tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: target: convert docs to ReST and rename to *.rst
Convert the TCM docs to ReST format and add them to the
bookset.
This has a mix of userspace-faced and Kernelspace faced
docs. Still, it sounds a better candidate to be added at
the kernel API set of docs.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
authored by
Mauro Carvalho Chehab
and committed by
Jonathan Corbet
4ca9bc22
bdf3a950
+325
-267
+19
Documentation/target/index.rst
+19
Documentation/target/index.rst
+11
Documentation/target/scripts.rst
+11
Documentation/target/scripts.rst
+149
Documentation/target/tcm_mod_builder.rst
+149
Documentation/target/tcm_mod_builder.rst
···
1
+
=========================================
2
+
The TCM v4 fabric module script generator
3
+
=========================================
4
+
5
+
Greetings all,
6
+
7
+
This document is intended to be a mini-HOWTO for using the tcm_mod_builder.py
8
+
script to generate a brand new functional TCM v4 fabric .ko module of your very own,
9
+
that once built can be immediately be loaded to start access the new TCM/ConfigFS
10
+
fabric skeleton, by simply using::
11
+
12
+
modprobe $TCM_NEW_MOD
13
+
mkdir -p /sys/kernel/config/target/$TCM_NEW_MOD
14
+
15
+
This script will create a new drivers/target/$TCM_NEW_MOD/, and will do the following
16
+
17
+
1) Generate new API callers for drivers/target/target_core_fabric_configs.c logic
18
+
->make_tpg(), ->drop_tpg(), ->make_wwn(), ->drop_wwn(). These are created
19
+
into $TCM_NEW_MOD/$TCM_NEW_MOD_configfs.c
20
+
2) Generate basic infrastructure for loading/unloading LKMs and TCM/ConfigFS fabric module
21
+
using a skeleton struct target_core_fabric_ops API template.
22
+
3) Based on user defined T10 Proto_Ident for the new fabric module being built,
23
+
the TransportID / Initiator and Target WWPN related handlers for
24
+
SPC-3 persistent reservation are automatically generated in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
25
+
using drivers/target/target_core_fabric_lib.c logic.
26
+
4) NOP API calls for all other Data I/O path and fabric dependent attribute logic
27
+
in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
28
+
29
+
tcm_mod_builder.py depends upon the mandatory '-p $PROTO_IDENT' and '-m
30
+
$FABRIC_MOD_name' parameters, and actually running the script looks like::
31
+
32
+
target:/mnt/sdb/lio-core-2.6.git/Documentation/target# python tcm_mod_builder.py -p iSCSI -m tcm_nab5000
33
+
tcm_dir: /mnt/sdb/lio-core-2.6.git/Documentation/target/../../
34
+
Set fabric_mod_name: tcm_nab5000
35
+
Set fabric_mod_dir:
36
+
/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
37
+
Using proto_ident: iSCSI
38
+
Creating fabric_mod_dir:
39
+
/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
40
+
Writing file:
41
+
/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_base.h
42
+
Using tcm_mod_scan_fabric_ops:
43
+
/mnt/sdb/lio-core-2.6.git/Documentation/target/../../include/target/target_core_fabric_ops.h
44
+
Writing file:
45
+
/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.c
46
+
Writing file:
47
+
/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.h
48
+
Writing file:
49
+
/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_configfs.c
50
+
Writing file:
51
+
/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kbuild
52
+
Writing file:
53
+
/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kconfig
54
+
Would you like to add tcm_nab5000to drivers/target/Kbuild..? [yes,no]: yes
55
+
Would you like to add tcm_nab5000to drivers/target/Kconfig..? [yes,no]: yes
56
+
57
+
At the end of tcm_mod_builder.py. the script will ask to add the following
58
+
line to drivers/target/Kbuild::
59
+
60
+
obj-$(CONFIG_TCM_NAB5000) += tcm_nab5000/
61
+
62
+
and the same for drivers/target/Kconfig::
63
+
64
+
source "drivers/target/tcm_nab5000/Kconfig"
65
+
66
+
#) Run 'make menuconfig' and select the new CONFIG_TCM_NAB5000 item::
67
+
68
+
<M> TCM_NAB5000 fabric module
69
+
70
+
#) Build using 'make modules', once completed you will have::
71
+
72
+
target:/mnt/sdb/lio-core-2.6.git# ls -la drivers/target/tcm_nab5000/
73
+
total 1348
74
+
drwxr-xr-x 2 root root 4096 2010-10-05 03:23 .
75
+
drwxr-xr-x 9 root root 4096 2010-10-05 03:22 ..
76
+
-rw-r--r-- 1 root root 282 2010-10-05 03:22 Kbuild
77
+
-rw-r--r-- 1 root root 171 2010-10-05 03:22 Kconfig
78
+
-rw-r--r-- 1 root root 49 2010-10-05 03:23 modules.order
79
+
-rw-r--r-- 1 root root 738 2010-10-05 03:22 tcm_nab5000_base.h
80
+
-rw-r--r-- 1 root root 9096 2010-10-05 03:22 tcm_nab5000_configfs.c
81
+
-rw-r--r-- 1 root root 191200 2010-10-05 03:23 tcm_nab5000_configfs.o
82
+
-rw-r--r-- 1 root root 40504 2010-10-05 03:23 .tcm_nab5000_configfs.o.cmd
83
+
-rw-r--r-- 1 root root 5414 2010-10-05 03:22 tcm_nab5000_fabric.c
84
+
-rw-r--r-- 1 root root 2016 2010-10-05 03:22 tcm_nab5000_fabric.h
85
+
-rw-r--r-- 1 root root 190932 2010-10-05 03:23 tcm_nab5000_fabric.o
86
+
-rw-r--r-- 1 root root 40713 2010-10-05 03:23 .tcm_nab5000_fabric.o.cmd
87
+
-rw-r--r-- 1 root root 401861 2010-10-05 03:23 tcm_nab5000.ko
88
+
-rw-r--r-- 1 root root 265 2010-10-05 03:23 .tcm_nab5000.ko.cmd
89
+
-rw-r--r-- 1 root root 459 2010-10-05 03:23 tcm_nab5000.mod.c
90
+
-rw-r--r-- 1 root root 23896 2010-10-05 03:23 tcm_nab5000.mod.o
91
+
-rw-r--r-- 1 root root 22655 2010-10-05 03:23 .tcm_nab5000.mod.o.cmd
92
+
-rw-r--r-- 1 root root 379022 2010-10-05 03:23 tcm_nab5000.o
93
+
-rw-r--r-- 1 root root 211 2010-10-05 03:23 .tcm_nab5000.o.cmd
94
+
95
+
#) Load the new module, create a lun_0 configfs group, and add new TCM Core
96
+
IBLOCK backstore symlink to port::
97
+
98
+
target:/mnt/sdb/lio-core-2.6.git# insmod drivers/target/tcm_nab5000.ko
99
+
target:/mnt/sdb/lio-core-2.6.git# mkdir -p /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0
100
+
target:/mnt/sdb/lio-core-2.6.git# cd /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0/
101
+
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
102
+
103
+
target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# cd -
104
+
target:/mnt/sdb/lio-core-2.6.git# tree /sys/kernel/config/target/nab5000/
105
+
/sys/kernel/config/target/nab5000/
106
+
|-- discovery_auth
107
+
|-- iqn.foo
108
+
| `-- tpgt_1
109
+
| |-- acls
110
+
| |-- attrib
111
+
| |-- lun
112
+
| | `-- lun_0
113
+
| | |-- alua_tg_pt_gp
114
+
| | |-- alua_tg_pt_offline
115
+
| | |-- alua_tg_pt_status
116
+
| | |-- alua_tg_pt_write_md
117
+
| | `-- nab5000_port -> ../../../../../../target/core/iblock_0/lvm_test0
118
+
| |-- np
119
+
| `-- param
120
+
`-- version
121
+
122
+
target:/mnt/sdb/lio-core-2.6.git# lsmod
123
+
Module Size Used by
124
+
tcm_nab5000 3935 4
125
+
iscsi_target_mod 193211 0
126
+
target_core_stgt 8090 0
127
+
target_core_pscsi 11122 1
128
+
target_core_file 9172 2
129
+
target_core_iblock 9280 1
130
+
target_core_mod 228575 31
131
+
tcm_nab5000,iscsi_target_mod,target_core_stgt,target_core_pscsi,target_core_file,target_core_iblock
132
+
libfc 73681 0
133
+
scsi_debug 56265 0
134
+
scsi_tgt 8666 1 target_core_stgt
135
+
configfs 20644 2 target_core_mod
136
+
137
+
----------------------------------------------------------------------
138
+
139
+
Future TODO items
140
+
=================
141
+
142
+
1) Add more T10 proto_idents
143
+
2) Make tcm_mod_dump_fabric_ops() smarter and generate function pointer
144
+
defs directly from include/target/target_core_fabric_ops.h:struct target_core_fabric_ops
145
+
structure members.
146
+
147
+
October 5th, 2010
148
+
149
+
Nicholas A. Bellinger <nab@linux-iscsi.org>
-145
Documentation/target/tcm_mod_builder.txt
-145
Documentation/target/tcm_mod_builder.txt
···
1
-
>>>>>>>>>> The TCM v4 fabric module script generator <<<<<<<<<<
2
-
3
-
Greetings all,
4
-
5
-
This document is intended to be a mini-HOWTO for using the tcm_mod_builder.py
6
-
script to generate a brand new functional TCM v4 fabric .ko module of your very own,
7
-
that once built can be immediately be loaded to start access the new TCM/ConfigFS
8
-
fabric skeleton, by simply using:
9
-
10
-
modprobe $TCM_NEW_MOD
11
-
mkdir -p /sys/kernel/config/target/$TCM_NEW_MOD
12
-
13
-
This script will create a new drivers/target/$TCM_NEW_MOD/, and will do the following
14
-
15
-
*) Generate new API callers for drivers/target/target_core_fabric_configs.c logic
16
-
->make_tpg(), ->drop_tpg(), ->make_wwn(), ->drop_wwn(). These are created
17
-
into $TCM_NEW_MOD/$TCM_NEW_MOD_configfs.c
18
-
*) Generate basic infrastructure for loading/unloading LKMs and TCM/ConfigFS fabric module
19
-
using a skeleton struct target_core_fabric_ops API template.
20
-
*) Based on user defined T10 Proto_Ident for the new fabric module being built,
21
-
the TransportID / Initiator and Target WWPN related handlers for
22
-
SPC-3 persistent reservation are automatically generated in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
23
-
using drivers/target/target_core_fabric_lib.c logic.
24
-
*) NOP API calls for all other Data I/O path and fabric dependent attribute logic
25
-
in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
26
-
27
-
tcm_mod_builder.py depends upon the mandatory '-p $PROTO_IDENT' and '-m
28
-
$FABRIC_MOD_name' parameters, and actually running the script looks like:
29
-
30
-
target:/mnt/sdb/lio-core-2.6.git/Documentation/target# python tcm_mod_builder.py -p iSCSI -m tcm_nab5000
31
-
tcm_dir: /mnt/sdb/lio-core-2.6.git/Documentation/target/../../
32
-
Set fabric_mod_name: tcm_nab5000
33
-
Set fabric_mod_dir:
34
-
/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
35
-
Using proto_ident: iSCSI
36
-
Creating fabric_mod_dir:
37
-
/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
38
-
Writing file:
39
-
/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_base.h
40
-
Using tcm_mod_scan_fabric_ops:
41
-
/mnt/sdb/lio-core-2.6.git/Documentation/target/../../include/target/target_core_fabric_ops.h
42
-
Writing file:
43
-
/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.c
44
-
Writing file:
45
-
/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.h
46
-
Writing file:
47
-
/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_configfs.c
48
-
Writing file:
49
-
/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kbuild
50
-
Writing file:
51
-
/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kconfig
52
-
Would you like to add tcm_nab5000to drivers/target/Kbuild..? [yes,no]: yes
53
-
Would you like to add tcm_nab5000to drivers/target/Kconfig..? [yes,no]: yes
54
-
55
-
At the end of tcm_mod_builder.py. the script will ask to add the following
56
-
line to drivers/target/Kbuild:
57
-
58
-
obj-$(CONFIG_TCM_NAB5000) += tcm_nab5000/
59
-
60
-
and the same for drivers/target/Kconfig:
61
-
62
-
source "drivers/target/tcm_nab5000/Kconfig"
63
-
64
-
*) Run 'make menuconfig' and select the new CONFIG_TCM_NAB5000 item:
65
-
66
-
<M> TCM_NAB5000 fabric module
67
-
68
-
*) Build using 'make modules', once completed you will have:
69
-
70
-
target:/mnt/sdb/lio-core-2.6.git# ls -la drivers/target/tcm_nab5000/
71
-
total 1348
72
-
drwxr-xr-x 2 root root 4096 2010-10-05 03:23 .
73
-
drwxr-xr-x 9 root root 4096 2010-10-05 03:22 ..
74
-
-rw-r--r-- 1 root root 282 2010-10-05 03:22 Kbuild
75
-
-rw-r--r-- 1 root root 171 2010-10-05 03:22 Kconfig
76
-
-rw-r--r-- 1 root root 49 2010-10-05 03:23 modules.order
77
-
-rw-r--r-- 1 root root 738 2010-10-05 03:22 tcm_nab5000_base.h
78
-
-rw-r--r-- 1 root root 9096 2010-10-05 03:22 tcm_nab5000_configfs.c
79
-
-rw-r--r-- 1 root root 191200 2010-10-05 03:23 tcm_nab5000_configfs.o
80
-
-rw-r--r-- 1 root root 40504 2010-10-05 03:23 .tcm_nab5000_configfs.o.cmd
81
-
-rw-r--r-- 1 root root 5414 2010-10-05 03:22 tcm_nab5000_fabric.c
82
-
-rw-r--r-- 1 root root 2016 2010-10-05 03:22 tcm_nab5000_fabric.h
83
-
-rw-r--r-- 1 root root 190932 2010-10-05 03:23 tcm_nab5000_fabric.o
84
-
-rw-r--r-- 1 root root 40713 2010-10-05 03:23 .tcm_nab5000_fabric.o.cmd
85
-
-rw-r--r-- 1 root root 401861 2010-10-05 03:23 tcm_nab5000.ko
86
-
-rw-r--r-- 1 root root 265 2010-10-05 03:23 .tcm_nab5000.ko.cmd
87
-
-rw-r--r-- 1 root root 459 2010-10-05 03:23 tcm_nab5000.mod.c
88
-
-rw-r--r-- 1 root root 23896 2010-10-05 03:23 tcm_nab5000.mod.o
89
-
-rw-r--r-- 1 root root 22655 2010-10-05 03:23 .tcm_nab5000.mod.o.cmd
90
-
-rw-r--r-- 1 root root 379022 2010-10-05 03:23 tcm_nab5000.o
91
-
-rw-r--r-- 1 root root 211 2010-10-05 03:23 .tcm_nab5000.o.cmd
92
-
93
-
*) Load the new module, create a lun_0 configfs group, and add new TCM Core
94
-
IBLOCK backstore symlink to port:
95
-
96
-
target:/mnt/sdb/lio-core-2.6.git# insmod drivers/target/tcm_nab5000.ko
97
-
target:/mnt/sdb/lio-core-2.6.git# mkdir -p /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0
98
-
target:/mnt/sdb/lio-core-2.6.git# cd /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0/
99
-
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
100
-
101
-
target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# cd -
102
-
target:/mnt/sdb/lio-core-2.6.git# tree /sys/kernel/config/target/nab5000/
103
-
/sys/kernel/config/target/nab5000/
104
-
|-- discovery_auth
105
-
|-- iqn.foo
106
-
| `-- tpgt_1
107
-
| |-- acls
108
-
| |-- attrib
109
-
| |-- lun
110
-
| | `-- lun_0
111
-
| | |-- alua_tg_pt_gp
112
-
| | |-- alua_tg_pt_offline
113
-
| | |-- alua_tg_pt_status
114
-
| | |-- alua_tg_pt_write_md
115
-
| | `-- nab5000_port -> ../../../../../../target/core/iblock_0/lvm_test0
116
-
| |-- np
117
-
| `-- param
118
-
`-- version
119
-
120
-
target:/mnt/sdb/lio-core-2.6.git# lsmod
121
-
Module Size Used by
122
-
tcm_nab5000 3935 4
123
-
iscsi_target_mod 193211 0
124
-
target_core_stgt 8090 0
125
-
target_core_pscsi 11122 1
126
-
target_core_file 9172 2
127
-
target_core_iblock 9280 1
128
-
target_core_mod 228575 31
129
-
tcm_nab5000,iscsi_target_mod,target_core_stgt,target_core_pscsi,target_core_file,target_core_iblock
130
-
libfc 73681 0
131
-
scsi_debug 56265 0
132
-
scsi_tgt 8666 1 target_core_stgt
133
-
configfs 20644 2 target_core_mod
134
-
135
-
----------------------------------------------------------------------
136
-
137
-
Future TODO items:
138
-
139
-
*) Add more T10 proto_idents
140
-
*) Make tcm_mod_dump_fabric_ops() smarter and generate function pointer
141
-
defs directly from include/target/target_core_fabric_ops.h:struct target_core_fabric_ops
142
-
structure members.
143
-
144
-
October 5th, 2010
145
-
Nicholas A. Bellinger <nab@linux-iscsi.org>
+145
-121
Documentation/target/tcmu-design.txt
Documentation/target/tcmu-design.rst
+145
-121
Documentation/target/tcmu-design.txt
Documentation/target/tcmu-design.rst
···
1
-
Contents:
1
+
====================
2
+
TCM Userspace Design
3
+
====================
2
4
3
-
1) TCM Userspace Design
4
-
a) Background
5
-
b) Benefits
6
-
c) Design constraints
7
-
d) Implementation overview
8
-
i. Mailbox
9
-
ii. Command ring
10
-
iii. Data Area
11
-
e) Device discovery
12
-
f) Device events
13
-
g) Other contingencies
14
-
2) Writing a user pass-through handler
15
-
a) Discovering and configuring TCMU uio devices
16
-
b) Waiting for events on the device(s)
17
-
c) Managing the command ring
18
-
3) A final note
5
+
6
+
.. Contents:
7
+
8
+
1) TCM Userspace Design
9
+
a) Background
10
+
b) Benefits
11
+
c) Design constraints
12
+
d) Implementation overview
13
+
i. Mailbox
14
+
ii. Command ring
15
+
iii. Data Area
16
+
e) Device discovery
17
+
f) Device events
18
+
g) Other contingencies
19
+
2) Writing a user pass-through handler
20
+
a) Discovering and configuring TCMU uio devices
21
+
b) Waiting for events on the device(s)
22
+
c) Managing the command ring
23
+
3) A final note
19
24
20
25
21
26
TCM Userspace Design
22
-
--------------------
27
+
====================
23
28
24
29
TCM is another name for LIO, an in-kernel iSCSI target (server).
25
30
Existing TCM targets run in the kernel. TCMU (TCM in Userspace)
···
37
32
storage. These are called "backstores" or "storage engines". These
38
33
built-in modules are implemented entirely as kernel code.
39
34
40
-
Background:
35
+
Background
36
+
----------
41
37
42
38
In addition to modularizing the transport protocol used for carrying
43
39
SCSI commands ("fabrics"), the Linux kernel target, LIO, also modularizes
···
66
60
backstore for LIO, "TCMU".
67
61
68
62
69
-
Benefits:
63
+
Benefits
64
+
--------
70
65
71
66
In addition to allowing relatively easy support for RBD and GLFS, TCMU
72
67
will also allow easier development of new backstores. TCMU combines
···
79
72
potentially to malfunction. This is unavoidable, but hopefully not
80
73
fatal if we're careful to keep things as simple as possible.
81
74
82
-
Design constraints:
75
+
Design constraints
76
+
------------------
83
77
84
78
- Good performance: high throughput, low latency
85
79
- Cleanly handle if userspace:
80
+
86
81
1) never attaches
87
82
2) hangs
88
83
3) dies
89
84
4) misbehaves
85
+
90
86
- Allow future flexibility in user & kernel implementations
91
87
- Be reasonably memory-efficient
92
88
- Simple to configure & run
93
89
- Simple to write a userspace backend
94
90
95
91
96
-
Implementation overview:
92
+
Implementation overview
93
+
-----------------------
97
94
98
95
The core of the TCMU interface is a memory region that is shared
99
96
between kernel and userspace. Within this region is: a control area
···
119
108
120
109
See target_core_user.h for the struct definitions.
121
110
122
-
The Mailbox:
111
+
The Mailbox
112
+
-----------
123
113
124
114
The mailbox is always at the start of the shared memory region, and
125
115
contains a version, details about the starting offset and size of the
···
129
117
when the commands are completed.
130
118
131
119
version - 1 (userspace should abort if otherwise)
132
-
flags:
133
-
- TCMU_MAILBOX_FLAG_CAP_OOOC: indicates out-of-order completion is
134
-
supported. See "The Command Ring" for details.
135
-
cmdr_off - The offset of the start of the command ring from the start
136
-
of the memory region, to account for the mailbox size.
137
-
cmdr_size - The size of the command ring. This does *not* need to be a
138
-
power of two.
139
-
cmd_head - Modified by the kernel to indicate when a command has been
140
-
placed on the ring.
141
-
cmd_tail - Modified by userspace to indicate when it has completed
142
-
processing of a command.
143
120
144
-
The Command Ring:
121
+
flags:
122
+
- TCMU_MAILBOX_FLAG_CAP_OOOC:
123
+
indicates out-of-order completion is supported.
124
+
See "The Command Ring" for details.
125
+
126
+
cmdr_off
127
+
The offset of the start of the command ring from the start
128
+
of the memory region, to account for the mailbox size.
129
+
cmdr_size
130
+
The size of the command ring. This does *not* need to be a
131
+
power of two.
132
+
cmd_head
133
+
Modified by the kernel to indicate when a command has been
134
+
placed on the ring.
135
+
cmd_tail
136
+
Modified by userspace to indicate when it has completed
137
+
processing of a command.
138
+
139
+
The Command Ring
140
+
----------------
145
141
146
142
Commands are placed on the ring by the kernel incrementing
147
143
mailbox.cmd_head by the size of the command, modulo cmdr_size, and
···
200
180
hdr.uflags, update cmd_tail, and proceed with processing additional
201
181
commands, if any.
202
182
203
-
The Data Area:
183
+
The Data Area
184
+
-------------
204
185
205
186
This is shared-memory space after the command ring. The organization
206
187
of this area is not defined in the TCMU interface, and userspace
207
188
should access only the parts referenced by pending iovs.
208
189
209
190
210
-
Device Discovery:
191
+
Device Discovery
192
+
----------------
211
193
212
194
Other devices may be using UIO besides TCMU. Unrelated user processes
213
195
may also be handling different sets of TCMU devices. TCMU userspace
214
196
processes must find their devices by scanning sysfs
215
197
class/uio/uio*/name. For TCMU devices, these names will be of the
216
-
format:
198
+
format::
217
199
218
-
tcm-user/<hba_num>/<device_name>/<subtype>/<path>
200
+
tcm-user/<hba_num>/<device_name>/<subtype>/<path>
219
201
220
202
where "tcm-user" is common for all TCMU-backed UIO devices. <hba_num>
221
203
and <device_name> allow userspace to find the device's path in the
222
204
kernel target's configfs tree. Assuming the usual mount point, it is
223
-
found at:
205
+
found at::
224
206
225
-
/sys/kernel/config/target/core/user_<hba_num>/<device_name>
207
+
/sys/kernel/config/target/core/user_<hba_num>/<device_name>
226
208
227
209
This location contains attributes such as "hw_block_size", that
228
210
userspace needs to know for correct operation.
···
236
214
LIO limitations.
237
215
238
216
For all devices so discovered, the user handler opens /dev/uioX and
239
-
calls mmap():
217
+
calls mmap()::
240
218
241
-
mmap(NULL, size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0)
219
+
mmap(NULL, size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0)
242
220
243
221
where size must be equal to the value read from
244
222
/sys/class/uio/uioX/maps/map0/size.
245
223
246
224
247
-
Device Events:
225
+
Device Events
226
+
-------------
248
227
249
228
If a new device is added or removed, a notification will be broadcast
250
229
over netlink, using a generic netlink family name of "TCM-USER" and a
···
256
233
(based on subtype) it can take the appropriate action.
257
234
258
235
259
-
Other contingencies:
236
+
Other contingencies
237
+
-------------------
260
238
261
239
Userspace handler process never attaches:
262
240
···
282
258
283
259
284
260
Writing a user pass-through handler (with example code)
285
-
-------------------------------------------------------
261
+
=======================================================
286
262
287
263
A user process handing a TCMU device must support the following:
288
264
···
301
277
devices separately. All handlers should make sure to only open their
302
278
devices, based opon a known subtype string.
303
279
304
-
a) Discovering and configuring TCMU UIO devices:
280
+
a) Discovering and configuring TCMU UIO devices::
305
281
306
-
(error checking omitted for brevity)
282
+
/* error checking omitted for brevity */
307
283
308
-
int fd, dev_fd;
309
-
char buf[256];
310
-
unsigned long long map_len;
311
-
void *map;
284
+
int fd, dev_fd;
285
+
char buf[256];
286
+
unsigned long long map_len;
287
+
void *map;
312
288
313
-
fd = open("/sys/class/uio/uio0/name", O_RDONLY);
314
-
ret = read(fd, buf, sizeof(buf));
315
-
close(fd);
316
-
buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
289
+
fd = open("/sys/class/uio/uio0/name", O_RDONLY);
290
+
ret = read(fd, buf, sizeof(buf));
291
+
close(fd);
292
+
buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
317
293
318
-
/* we only want uio devices whose name is a format we expect */
319
-
if (strncmp(buf, "tcm-user", 8))
294
+
/* we only want uio devices whose name is a format we expect */
295
+
if (strncmp(buf, "tcm-user", 8))
320
296
exit(-1);
321
297
322
-
/* Further checking for subtype also needed here */
298
+
/* Further checking for subtype also needed here */
323
299
324
-
fd = open(/sys/class/uio/%s/maps/map0/size, O_RDONLY);
325
-
ret = read(fd, buf, sizeof(buf));
326
-
close(fd);
327
-
str_buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
300
+
fd = open(/sys/class/uio/%s/maps/map0/size, O_RDONLY);
301
+
ret = read(fd, buf, sizeof(buf));
302
+
close(fd);
303
+
str_buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
328
304
329
-
map_len = strtoull(buf, NULL, 0);
305
+
map_len = strtoull(buf, NULL, 0);
330
306
331
-
dev_fd = open("/dev/uio0", O_RDWR);
332
-
map = mmap(NULL, map_len, PROT_READ|PROT_WRITE, MAP_SHARED, dev_fd, 0);
333
-
334
-
335
-
b) Waiting for events on the device(s)
336
-
337
-
while (1) {
338
-
char buf[4];
339
-
340
-
int ret = read(dev_fd, buf, 4); /* will block */
341
-
342
-
handle_device_events(dev_fd, map);
343
-
}
307
+
dev_fd = open("/dev/uio0", O_RDWR);
308
+
map = mmap(NULL, map_len, PROT_READ|PROT_WRITE, MAP_SHARED, dev_fd, 0);
344
309
345
310
346
-
c) Managing the command ring
311
+
b) Waiting for events on the device(s)
347
312
348
-
#include <linux/target_core_user.h>
313
+
while (1) {
314
+
char buf[4];
349
315
350
-
int handle_device_events(int fd, void *map)
351
-
{
352
-
struct tcmu_mailbox *mb = map;
353
-
struct tcmu_cmd_entry *ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
354
-
int did_some_work = 0;
316
+
int ret = read(dev_fd, buf, 4); /* will block */
355
317
356
-
/* Process events from cmd ring until we catch up with cmd_head */
357
-
while (ent != (void *)mb + mb->cmdr_off + mb->cmd_head) {
358
-
359
-
if (tcmu_hdr_get_op(ent->hdr.len_op) == TCMU_OP_CMD) {
360
-
uint8_t *cdb = (void *)mb + ent->req.cdb_off;
361
-
bool success = true;
362
-
363
-
/* Handle command here. */
364
-
printf("SCSI opcode: 0x%x\n", cdb[0]);
365
-
366
-
/* Set response fields */
367
-
if (success)
368
-
ent->rsp.scsi_status = SCSI_NO_SENSE;
369
-
else {
370
-
/* Also fill in rsp->sense_buffer here */
371
-
ent->rsp.scsi_status = SCSI_CHECK_CONDITION;
318
+
handle_device_events(dev_fd, map);
372
319
}
373
-
}
374
-
else if (tcmu_hdr_get_op(ent->hdr.len_op) != TCMU_OP_PAD) {
375
-
/* Tell the kernel we didn't handle unknown opcodes */
376
-
ent->hdr.uflags |= TCMU_UFLAG_UNKNOWN_OP;
377
-
}
378
-
else {
379
-
/* Do nothing for PAD entries except update cmd_tail */
380
-
}
381
320
382
-
/* update cmd_tail */
383
-
mb->cmd_tail = (mb->cmd_tail + tcmu_hdr_get_len(&ent->hdr)) % mb->cmdr_size;
384
-
ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
385
-
did_some_work = 1;
386
-
}
387
321
388
-
/* Notify the kernel that work has been finished */
389
-
if (did_some_work) {
390
-
uint32_t buf = 0;
322
+
c) Managing the command ring::
391
323
392
-
write(fd, &buf, 4);
393
-
}
324
+
#include <linux/target_core_user.h>
394
325
395
-
return 0;
396
-
}
326
+
int handle_device_events(int fd, void *map)
327
+
{
328
+
struct tcmu_mailbox *mb = map;
329
+
struct tcmu_cmd_entry *ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
330
+
int did_some_work = 0;
331
+
332
+
/* Process events from cmd ring until we catch up with cmd_head */
333
+
while (ent != (void *)mb + mb->cmdr_off + mb->cmd_head) {
334
+
335
+
if (tcmu_hdr_get_op(ent->hdr.len_op) == TCMU_OP_CMD) {
336
+
uint8_t *cdb = (void *)mb + ent->req.cdb_off;
337
+
bool success = true;
338
+
339
+
/* Handle command here. */
340
+
printf("SCSI opcode: 0x%x\n", cdb[0]);
341
+
342
+
/* Set response fields */
343
+
if (success)
344
+
ent->rsp.scsi_status = SCSI_NO_SENSE;
345
+
else {
346
+
/* Also fill in rsp->sense_buffer here */
347
+
ent->rsp.scsi_status = SCSI_CHECK_CONDITION;
348
+
}
349
+
}
350
+
else if (tcmu_hdr_get_op(ent->hdr.len_op) != TCMU_OP_PAD) {
351
+
/* Tell the kernel we didn't handle unknown opcodes */
352
+
ent->hdr.uflags |= TCMU_UFLAG_UNKNOWN_OP;
353
+
}
354
+
else {
355
+
/* Do nothing for PAD entries except update cmd_tail */
356
+
}
357
+
358
+
/* update cmd_tail */
359
+
mb->cmd_tail = (mb->cmd_tail + tcmu_hdr_get_len(&ent->hdr)) % mb->cmdr_size;
360
+
ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
361
+
did_some_work = 1;
362
+
}
363
+
364
+
/* Notify the kernel that work has been finished */
365
+
if (did_some_work) {
366
+
uint32_t buf = 0;
367
+
368
+
write(fd, &buf, 4);
369
+
}
370
+
371
+
return 0;
372
+
}
397
373
398
374
399
375
A final note
400
-
------------
376
+
============
401
377
402
378
Please be careful to return codes as defined by the SCSI
403
379
specifications. These are different than some values defined in the
+1
-1
scripts/documentation-file-ref-check
+1
-1
scripts/documentation-file-ref-check
···
124
124
# Remove sched-pelt false-positive
125
125
next if ($fulref =~ m,^Documentation/scheduler/sched-pelt$,);
126
126
127
-
# Discard some build examples from Documentation/target/tcm_mod_builder.txt
127
+
# Discard some build examples from Documentation/target/tcm_mod_builder.rst
128
128
next if ($fulref =~ m,mnt/sdb/lio-core-2.6.git/Documentation/target,);
129
129
130
130
# Check if exists, evaluating wildcards