Documentation/scsi/osd.txt

   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