diff options
author | Christoph Hellwig <hch@lst.de> | 2018-11-08 03:28:20 -0500 |
---|---|---|
committer | Martin K. Petersen <martin.petersen@oracle.com> | 2019-02-05 21:28:52 -0500 |
commit | 19fcae3d4f2dd513d472055fb694d802e9a21b91 (patch) | |
tree | 8bcd2155c5e073576dea32ce958b366f311bfbab /Documentation/scsi | |
parent | 80f2121380caa14895638b24b81800158c0844f2 (diff) |
scsi: remove the SCSI OSD library
Now that all the users are gone the SCSI OSD library can be removed as
well.
Signed-off-by: Christoph Hellwig <hch@lst.de>
Reviewed-by: Jens Axboe <axboe@kernel.dk>
Signed-off-by: Martin K. Petersen <martin.petersen@oracle.com>
Diffstat (limited to 'Documentation/scsi')
-rw-r--r-- | Documentation/scsi/osd.txt | 192 |
1 files changed, 0 insertions, 192 deletions
diff --git a/Documentation/scsi/osd.txt b/Documentation/scsi/osd.txt deleted file mode 100644 index 2bc2ab06b0c0..000000000000 --- a/Documentation/scsi/osd.txt +++ /dev/null | |||
@@ -1,192 +0,0 @@ | |||
1 | The OSD Standard | ||
2 | ================ | ||
3 | OSD (Object-Based Storage Device) is a T10 SCSI command set that is designed | ||
4 | to provide efficient operation of input/output logical units that manage the | ||
5 | allocation, placement, and accessing of variable-size data-storage containers, | ||
6 | called objects. Objects are intended to contain operating system and application | ||
7 | constructs. Each object has associated attributes attached to it, which are | ||
8 | integral part of the object and provide metadata about the object. The standard | ||
9 | defines some common obligatory attributes, but user attributes can be added as | ||
10 | needed. | ||
11 | |||
12 | See: http://www.t10.org/ftp/t10/drafts/osd2/ for the latest draft for OSD 2 | ||
13 | or search the web for "OSD SCSI" | ||
14 | |||
15 | OSD in the Linux Kernel | ||
16 | ======================= | ||
17 | osd-initiator: | ||
18 | The main component of OSD in Kernel is the osd-initiator library. Its main | ||
19 | user is intended to be the pNFS-over-objects layout driver, which uses objects | ||
20 | as its back-end data storage. Other clients are the other osd parts listed below. | ||
21 | |||
22 | osd-uld: | ||
23 | This is a SCSI ULD that registers for OSD type devices and provides a testing | ||
24 | platform, both for the in-kernel initiator as well as connected targets. It | ||
25 | currently has no useful user-mode API, though it could have if need be. | ||
26 | |||
27 | osd target: | ||
28 | There are no current plans for an OSD target implementation in kernel. For all | ||
29 | needs, a user-mode target that is based on the scsi tgt target framework is | ||
30 | available from Ohio Supercomputer Center (OSC) at: | ||
31 | http://www.open-osd.org/bin/view/Main/OscOsdProject | ||
32 | There are several other target implementations. See http://open-osd.org for more | ||
33 | links. | ||
34 | |||
35 | Files and Folders | ||
36 | ================= | ||
37 | This is the complete list of files included in this work: | ||
38 | include/scsi/ | ||
39 | osd_initiator.h Main API for the initiator library | ||
40 | osd_types.h Common OSD types | ||
41 | osd_sec.h Security Manager API | ||
42 | osd_protocol.h Wire definitions of the OSD standard protocol | ||
43 | osd_attributes.h Wire definitions of OSD attributes | ||
44 | |||
45 | drivers/scsi/osd/ | ||
46 | osd_initiator.c OSD-Initiator library implementation | ||
47 | osd_uld.c The OSD scsi ULD | ||
48 | osd_ktest.{h,c} In-kernel test suite (called by osd_uld) | ||
49 | osd_debug.h Some printk macros | ||
50 | Makefile For both in-tree and out-of-tree compilation | ||
51 | Kconfig Enables inclusion of the different pieces | ||
52 | osd_test.c User-mode application to call the kernel tests | ||
53 | |||
54 | The OSD-Initiator Library | ||
55 | ========================= | ||
56 | osd_initiator is a low level implementation of an osd initiator encoder. | ||
57 | But even though, it should be intuitive and easy to use. Perhaps over time an | ||
58 | higher lever will form that automates some of the more common recipes. | ||
59 | |||
60 | init/fini: | ||
61 | - osd_dev_init() associates a scsi_device with an osd_dev structure | ||
62 | and initializes some global pools. This should be done once per scsi_device | ||
63 | (OSD LUN). The osd_dev structure is needed for calling osd_start_request(). | ||
64 | |||
65 | - osd_dev_fini() cleans up before a osd_dev/scsi_device destruction. | ||
66 | |||
67 | OSD commands encoding, execution, and decoding of results: | ||
68 | |||
69 | struct osd_request's is used to iteratively encode an OSD command and carry | ||
70 | its state throughout execution. Each request goes through these stages: | ||
71 | |||
72 | a. osd_start_request() allocates the request. | ||
73 | |||
74 | b. Any of the osd_req_* methods is used to encode a request of the specified | ||
75 | type. | ||
76 | |||
77 | c. osd_req_add_{get,set}_attr_* may be called to add get/set attributes to the | ||
78 | CDB. "List" or "Page" mode can be used exclusively. The attribute-list API | ||
79 | can be called multiple times on the same request. However, only one | ||
80 | attribute-page can be read, as mandated by the OSD standard. | ||
81 | |||
82 | d. osd_finalize_request() computes offsets into the data-in and data-out buffers | ||
83 | and signs the request using the provided capability key and integrity- | ||
84 | check parameters. | ||
85 | |||
86 | e. osd_execute_request() may be called to execute the request via the block | ||
87 | layer and wait for its completion. The request can be executed | ||
88 | asynchronously by calling the block layer API directly. | ||
89 | |||
90 | f. After execution, osd_req_decode_sense() can be called to decode the request's | ||
91 | sense information. | ||
92 | |||
93 | g. osd_req_decode_get_attr() may be called to retrieve osd_add_get_attr_list() | ||
94 | values. | ||
95 | |||
96 | h. osd_end_request() must be called to deallocate the request and any resource | ||
97 | associated with it. Note that osd_end_request cleans up the request at any | ||
98 | stage and it must always be called after a successful osd_start_request(). | ||
99 | |||
100 | osd_request's structure: | ||
101 | |||
102 | The OSD standard defines a complex structure of IO segments pointed to by | ||
103 | members in the CDB. Up to 3 segments can be deployed in the IN-Buffer and up to | ||
104 | 4 in the OUT-Buffer. The ASCII illustration below depicts a secure-read with | ||
105 | associated get+set of attributes-lists. Other combinations very on the same | ||
106 | basic theme. From no-segments-used up to all-segments-used. | ||
107 | |||
108 | |________OSD-CDB__________| | ||
109 | | | | ||
110 | |read_len (offset=0) -|---------\ | ||
111 | | | | | ||
112 | |get_attrs_list_length | | | ||
113 | |get_attrs_list_offset -|----\ | | ||
114 | | | | | | ||
115 | |retrieved_attrs_alloc_len| | | | ||
116 | |retrieved_attrs_offset -|----|----|-\ | ||
117 | | | | | | | ||
118 | |set_attrs_list_length | | | | | ||
119 | |set_attrs_list_offset -|-\ | | | | ||
120 | | | | | | | | ||
121 | |in_data_integ_offset -|-|--|----|-|-\ | ||
122 | |out_data_integ_offset -|-|--|--\ | | | | ||
123 | \_________________________/ | | | | | | | ||
124 | | | | | | | | ||
125 | |_______OUT-BUFFER________| | | | | | | | ||
126 | | Set attr list |</ | | | | | | ||
127 | | | | | | | | | ||
128 | |-------------------------| | | | | | | ||
129 | | Get attr descriptors |<---/ | | | | | ||
130 | | | | | | | | ||
131 | |-------------------------| | | | | | ||
132 | | Out-data integrity |<------/ | | | | ||
133 | | | | | | | ||
134 | \_________________________/ | | | | ||
135 | | | | | ||
136 | |________IN-BUFFER________| | | | | ||
137 | | In-Data read |<--------/ | | | ||
138 | | | | | | ||
139 | |-------------------------| | | | ||
140 | | Get attr list |<----------/ | | ||
141 | | | | | ||
142 | |-------------------------| | | ||
143 | | In-data integrity |<------------/ | ||
144 | | | | ||
145 | \_________________________/ | ||
146 | |||
147 | A block device request can carry bidirectional payload by means of associating | ||
148 | a bidi_read request with a main write-request. Each in/out request is described | ||
149 | by a chain of BIOs associated with each request. | ||
150 | The CDB is of a SCSI VARLEN CDB format, as described by OSD standard. | ||
151 | The OSD standard also mandates alignment restrictions at start of each segment. | ||
152 | |||
153 | In the code, in struct osd_request, there are two _osd_io_info structures to | ||
154 | describe the IN/OUT buffers above, two BIOs for the data payload and up to five | ||
155 | _osd_req_data_segment structures to hold the different segments allocation and | ||
156 | information. | ||
157 | |||
158 | Important: We have chosen to disregard the assumption that a BIO-chain (and | ||
159 | the resulting sg-list) describes a linear memory buffer. Meaning only first and | ||
160 | last scatter chain can be incomplete and all the middle chains are of PAGE_SIZE. | ||
161 | For us, a scatter-gather-list, as its name implies and as used by the Networking | ||
162 | layer, is to describe a vector of buffers that will be transferred to/from the | ||
163 | wire. It works very well with current iSCSI transport. iSCSI is currently the | ||
164 | only deployed OSD transport. In the future we anticipate SAS and FC attached OSD | ||
165 | devices as well. | ||
166 | |||
167 | The OSD Testing ULD | ||
168 | =================== | ||
169 | TODO: More user-mode control on tests. | ||
170 | |||
171 | Authors, Mailing list | ||
172 | ===================== | ||
173 | Please communicate with us on any deployment of osd, whether using this code | ||
174 | or not. | ||
175 | |||
176 | Any problems, questions, bug reports, lonely OSD nights, please email: | ||
177 | OSD Dev List <osd-dev@open-osd.org> | ||
178 | |||
179 | More up-to-date information can be found on: | ||
180 | http://open-osd.org | ||
181 | |||
182 | Boaz Harrosh <ooo@electrozaur.com> | ||
183 | |||
184 | References | ||
185 | ========== | ||
186 | Weber, R., "SCSI Object-Based Storage Device Commands", | ||
187 | T10/1355-D ANSI/INCITS 400-2004, | ||
188 | http://www.t10.org/ftp/t10/drafts/osd/osd-r10.pdf | ||
189 | |||
190 | Weber, R., "SCSI Object-Based Storage Device Commands -2 (OSD-2)" | ||
191 | T10/1729-D, Working Draft, rev. 3 | ||
192 | http://www.t10.org/ftp/t10/drafts/osd2/osd2r03.pdf | ||