Documentation / target / tcm_mod_builder.rst


Based on kernel version 5.17. Page generated on 2022-03-28 08:42 EST.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149
=========================================
The TCM v4 fabric module script generator
=========================================

Greetings all,

This document is intended to be a mini-HOWTO for using the tcm_mod_builder.py
script to generate a brand new functional TCM v4 fabric .ko module of your very own,
that once built can be immediately be loaded to start access the new TCM/ConfigFS
fabric skeleton, by simply using::

	modprobe $TCM_NEW_MOD
	mkdir -p /sys/kernel/config/target/$TCM_NEW_MOD

This script will create a new drivers/target/$TCM_NEW_MOD/, and will do the following

	1) Generate new API callers for drivers/target/target_core_fabric_configs.c logic
	   ->make_tpg(), ->drop_tpg(), ->make_wwn(), ->drop_wwn().  These are created
	   into $TCM_NEW_MOD/$TCM_NEW_MOD_configfs.c
	2) Generate basic infrastructure for loading/unloading LKMs and TCM/ConfigFS fabric module
	   using a skeleton struct target_core_fabric_ops API template.
	3) Based on user defined T10 Proto_Ident for the new fabric module being built,
	   the TransportID / Initiator and Target WWPN related handlers for
	   SPC-3 persistent reservation are automatically generated in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
	   using drivers/target/target_core_fabric_lib.c logic.
	4) NOP API calls for all other Data I/O path and fabric dependent attribute logic
	   in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c

tcm_mod_builder.py depends upon the mandatory '-p $PROTO_IDENT' and '-m
$FABRIC_MOD_name' parameters, and actually running the script looks like::

  target:/mnt/sdb/lio-core-2.6.git/Documentation/target# python tcm_mod_builder.py -p iSCSI -m tcm_nab5000
  tcm_dir: /mnt/sdb/lio-core-2.6.git/Documentation/target/../../
  Set fabric_mod_name: tcm_nab5000
  Set fabric_mod_dir:
  /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
  Using proto_ident: iSCSI
  Creating fabric_mod_dir:
  /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
  Writing file:
  /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_base.h
  Using tcm_mod_scan_fabric_ops:
  /mnt/sdb/lio-core-2.6.git/Documentation/target/../../include/target/target_core_fabric_ops.h
  Writing file:
  /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.c
  Writing file:
  /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.h
  Writing file:
  /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_configfs.c
  Writing file:
  /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kbuild
  Writing file:
  /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kconfig
  Would you like to add tcm_nab5000to drivers/target/Kbuild..? [yes,no]: yes
  Would you like to add tcm_nab5000to drivers/target/Kconfig..? [yes,no]: yes

At the end of tcm_mod_builder.py. the script will ask to add the following
line to drivers/target/Kbuild::

	obj-$(CONFIG_TCM_NAB5000)       += tcm_nab5000/

and the same for drivers/target/Kconfig::

	source "drivers/target/tcm_nab5000/Kconfig"

#) Run 'make menuconfig' and select the new CONFIG_TCM_NAB5000 item::

	<M>   TCM_NAB5000 fabric module

#) Build using 'make modules', once completed you will have::

    target:/mnt/sdb/lio-core-2.6.git# ls -la drivers/target/tcm_nab5000/
    total 1348
    drwxr-xr-x 2 root root   4096 2010-10-05 03:23 .
    drwxr-xr-x 9 root root   4096 2010-10-05 03:22 ..
    -rw-r--r-- 1 root root    282 2010-10-05 03:22 Kbuild
    -rw-r--r-- 1 root root    171 2010-10-05 03:22 Kconfig
    -rw-r--r-- 1 root root     49 2010-10-05 03:23 modules.order
    -rw-r--r-- 1 root root    738 2010-10-05 03:22 tcm_nab5000_base.h
    -rw-r--r-- 1 root root   9096 2010-10-05 03:22 tcm_nab5000_configfs.c
    -rw-r--r-- 1 root root 191200 2010-10-05 03:23 tcm_nab5000_configfs.o
    -rw-r--r-- 1 root root  40504 2010-10-05 03:23 .tcm_nab5000_configfs.o.cmd
    -rw-r--r-- 1 root root   5414 2010-10-05 03:22 tcm_nab5000_fabric.c
    -rw-r--r-- 1 root root   2016 2010-10-05 03:22 tcm_nab5000_fabric.h
    -rw-r--r-- 1 root root 190932 2010-10-05 03:23 tcm_nab5000_fabric.o
    -rw-r--r-- 1 root root  40713 2010-10-05 03:23 .tcm_nab5000_fabric.o.cmd
    -rw-r--r-- 1 root root 401861 2010-10-05 03:23 tcm_nab5000.ko
    -rw-r--r-- 1 root root    265 2010-10-05 03:23 .tcm_nab5000.ko.cmd
    -rw-r--r-- 1 root root    459 2010-10-05 03:23 tcm_nab5000.mod.c
    -rw-r--r-- 1 root root  23896 2010-10-05 03:23 tcm_nab5000.mod.o
    -rw-r--r-- 1 root root  22655 2010-10-05 03:23 .tcm_nab5000.mod.o.cmd
    -rw-r--r-- 1 root root 379022 2010-10-05 03:23 tcm_nab5000.o
    -rw-r--r-- 1 root root    211 2010-10-05 03:23 .tcm_nab5000.o.cmd

#) Load the new module, create a lun_0 configfs group, and add new TCM Core
   IBLOCK backstore symlink to port::

    target:/mnt/sdb/lio-core-2.6.git# insmod drivers/target/tcm_nab5000.ko
    target:/mnt/sdb/lio-core-2.6.git# mkdir -p /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0
    target:/mnt/sdb/lio-core-2.6.git# cd /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0/
    target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# ln -s /sys/kernel/config/target/core/iblock_0/lvm_test0 nab5000_port

    target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# cd -
    target:/mnt/sdb/lio-core-2.6.git# tree /sys/kernel/config/target/nab5000/
    /sys/kernel/config/target/nab5000/
    |-- discovery_auth
    |-- iqn.foo
    |   `-- tpgt_1
    |       |-- acls
    |       |-- attrib
    |       |-- lun
    |       |   `-- lun_0
    |       |       |-- alua_tg_pt_gp
    |       |       |-- alua_tg_pt_offline
    |       |       |-- alua_tg_pt_status
    |       |       |-- alua_tg_pt_write_md
    |	|	`-- nab5000_port -> ../../../../../../target/core/iblock_0/lvm_test0
    |       |-- np
    |       `-- param
    `-- version

    target:/mnt/sdb/lio-core-2.6.git# lsmod
    Module                  Size  Used by
    tcm_nab5000             3935  4
    iscsi_target_mod      193211  0
    target_core_stgt        8090  0
    target_core_pscsi      11122  1
    target_core_file        9172  2
    target_core_iblock      9280  1
    target_core_mod       228575  31
    tcm_nab5000,iscsi_target_mod,target_core_stgt,target_core_pscsi,target_core_file,target_core_iblock
    libfc                  73681  0
    scsi_debug             56265  0
    scsi_tgt                8666  1 target_core_stgt
    configfs               20644  2 target_core_mod

----------------------------------------------------------------------

Future TODO items
=================

	1) Add more T10 proto_idents
	2) Make tcm_mod_dump_fabric_ops() smarter and generate function pointer
	   defs directly from include/target/target_core_fabric_ops.h:struct target_core_fabric_ops
	   structure members.

October 5th, 2010

Nicholas A. Bellinger <nab@linux-iscsi.org>