aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/scsi
diff options
context:
space:
mode:
authorChristoph Hellwig <hch@lst.de>2018-11-08 03:28:20 -0500
committerMartin K. Petersen <martin.petersen@oracle.com>2019-02-05 21:28:52 -0500
commit19fcae3d4f2dd513d472055fb694d802e9a21b91 (patch)
tree8bcd2155c5e073576dea32ce958b366f311bfbab /Documentation/scsi
parent80f2121380caa14895638b24b81800158c0844f2 (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.txt192
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 @@
1The OSD Standard
2================
3OSD (Object-Based Storage Device) is a T10 SCSI command set that is designed
4to provide efficient operation of input/output logical units that manage the
5allocation, placement, and accessing of variable-size data-storage containers,
6called objects. Objects are intended to contain operating system and application
7constructs. Each object has associated attributes attached to it, which are
8integral part of the object and provide metadata about the object. The standard
9defines some common obligatory attributes, but user attributes can be added as
10needed.
11
12See: http://www.t10.org/ftp/t10/drafts/osd2/ for the latest draft for OSD 2
13or search the web for "OSD SCSI"
14
15OSD in the Linux Kernel
16=======================
17osd-initiator:
18 The main component of OSD in Kernel is the osd-initiator library. Its main
19user is intended to be the pNFS-over-objects layout driver, which uses objects
20as its back-end data storage. Other clients are the other osd parts listed below.
21
22osd-uld:
23 This is a SCSI ULD that registers for OSD type devices and provides a testing
24platform, both for the in-kernel initiator as well as connected targets. It
25currently has no useful user-mode API, though it could have if need be.
26
27osd target:
28 There are no current plans for an OSD target implementation in kernel. For all
29needs, a user-mode target that is based on the scsi tgt target framework is
30available from Ohio Supercomputer Center (OSC) at:
31http://www.open-osd.org/bin/view/Main/OscOsdProject
32There are several other target implementations. See http://open-osd.org for more
33links.
34
35Files and Folders
36=================
37This is the complete list of files included in this work:
38include/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
45drivers/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
54The OSD-Initiator Library
55=========================
56osd_initiator is a low level implementation of an osd initiator encoder.
57But even though, it should be intuitive and easy to use. Perhaps over time an
58higher lever will form that automates some of the more common recipes.
59
60init/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
67OSD commands encoding, execution, and decoding of results:
68
69struct osd_request's is used to iteratively encode an OSD command and carry
70its state throughout execution. Each request goes through these stages:
71
72a. osd_start_request() allocates the request.
73
74b. Any of the osd_req_* methods is used to encode a request of the specified
75 type.
76
77c. 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
82d. 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
86e. 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
90f. After execution, osd_req_decode_sense() can be called to decode the request's
91 sense information.
92
93g. osd_req_decode_get_attr() may be called to retrieve osd_add_get_attr_list()
94 values.
95
96h. 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
100osd_request's structure:
101
102The OSD standard defines a complex structure of IO segments pointed to by
103members in the CDB. Up to 3 segments can be deployed in the IN-Buffer and up to
1044 in the OUT-Buffer. The ASCII illustration below depicts a secure-read with
105associated get+set of attributes-lists. Other combinations very on the same
106basic 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
147A block device request can carry bidirectional payload by means of associating
148a bidi_read request with a main write-request. Each in/out request is described
149by a chain of BIOs associated with each request.
150The CDB is of a SCSI VARLEN CDB format, as described by OSD standard.
151The OSD standard also mandates alignment restrictions at start of each segment.
152
153In the code, in struct osd_request, there are two _osd_io_info structures to
154describe 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
156information.
157
158Important: We have chosen to disregard the assumption that a BIO-chain (and
159the resulting sg-list) describes a linear memory buffer. Meaning only first and
160last scatter chain can be incomplete and all the middle chains are of PAGE_SIZE.
161For us, a scatter-gather-list, as its name implies and as used by the Networking
162layer, is to describe a vector of buffers that will be transferred to/from the
163wire. It works very well with current iSCSI transport. iSCSI is currently the
164only deployed OSD transport. In the future we anticipate SAS and FC attached OSD
165devices as well.
166
167The OSD Testing ULD
168===================
169TODO: More user-mode control on tests.
170
171Authors, Mailing list
172=====================
173Please communicate with us on any deployment of osd, whether using this code
174or not.
175
176Any problems, questions, bug reports, lonely OSD nights, please email:
177 OSD Dev List <osd-dev@open-osd.org>
178
179More up-to-date information can be found on:
180http://open-osd.org
181
182Boaz Harrosh <ooo@electrozaur.com>
183
184References
185==========
186Weber, R., "SCSI Object-Based Storage Device Commands",
187T10/1355-D ANSI/INCITS 400-2004,
188http://www.t10.org/ftp/t10/drafts/osd/osd-r10.pdf
189
190Weber, R., "SCSI Object-Based Storage Device Commands -2 (OSD-2)"
191T10/1729-D, Working Draft, rev. 3
192http://www.t10.org/ftp/t10/drafts/osd2/osd2r03.pdf