linux/Documentation/scsi/osd.txt
<<
>>
Prefs
   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
  27exofs:
  28  Is an OSD based Linux file system. It uses the osd-initiator and osd-uld,
  29to export a usable file system for users.
  30See Documentation/filesystems/exofs.txt for more details
  31
  32osd target:
  33  There are no current plans for an OSD target implementation in kernel. For all
  34needs, a user-mode target that is based on the scsi tgt target framework is
  35available from Ohio Supercomputer Center (OSC) at:
  36http://www.open-osd.org/bin/view/Main/OscOsdProject
  37There are several other target implementations. See http://open-osd.org for more
  38links.
  39
  40Files and Folders
  41=================
  42This is the complete list of files included in this work:
  43include/scsi/
  44        osd_initiator.h   Main API for the initiator library
  45        osd_types.h       Common OSD types
  46        osd_sec.h         Security Manager API
  47        osd_protocol.h    Wire definitions of the OSD standard protocol
  48        osd_attributes.h  Wire definitions of OSD attributes
  49
  50drivers/scsi/osd/
  51        osd_initiator.c   OSD-Initiator library implementation
  52        osd_uld.c         The OSD scsi ULD
  53        osd_ktest.{h,c}   In-kernel test suite (called by osd_uld)
  54        osd_debug.h       Some printk macros
  55        Makefile          For both in-tree and out-of-tree compilation
  56        Kconfig           Enables inclusion of the different pieces
  57        osd_test.c        User-mode application to call the kernel tests
  58
  59The OSD-Initiator Library
  60=========================
  61osd_initiator is a low level implementation of an osd initiator encoder.
  62But even though, it should be intuitive and easy to use. Perhaps over time an
  63higher lever will form that automates some of the more common recipes.
  64
  65init/fini:
  66- osd_dev_init() associates a scsi_device with an osd_dev structure
  67  and initializes some global pools. This should be done once per scsi_device
  68  (OSD LUN). The osd_dev structure is needed for calling osd_start_request().
  69
  70- osd_dev_fini() cleans up before a osd_dev/scsi_device destruction.
  71
  72OSD commands encoding, execution, and decoding of results:
  73
  74struct osd_request's is used to iteratively encode an OSD command and carry
  75its state throughout execution. Each request goes through these stages:
  76
  77a. osd_start_request() allocates the request.
  78
  79b. Any of the osd_req_* methods is used to encode a request of the specified
  80   type.
  81
  82c. osd_req_add_{get,set}_attr_* may be called to add get/set attributes to the
  83   CDB. "List" or "Page" mode can be used exclusively. The attribute-list API
  84   can be called multiple times on the same request. However, only one
  85   attribute-page can be read, as mandated by the OSD standard.
  86
  87d. osd_finalize_request() computes offsets into the data-in and data-out buffers
  88   and signs the request using the provided capability key and integrity-
  89   check parameters.
  90
  91e. osd_execute_request() may be called to execute the request via the block
  92   layer and wait for its completion.  The request can be executed
  93   asynchronously by calling the block layer API directly.
  94
  95f. After execution, osd_req_decode_sense() can be called to decode the request's
  96   sense information.
  97
  98g. osd_req_decode_get_attr() may be called to retrieve osd_add_get_attr_list()
  99   values.
 100
 101h. osd_end_request() must be called to deallocate the request and any resource
 102   associated with it. Note that osd_end_request cleans up the request at any
 103   stage and it must always be called after a successful osd_start_request().
 104
 105osd_request's structure:
 106
 107The OSD standard defines a complex structure of IO segments pointed to by
 108members in the CDB. Up to 3 segments can be deployed in the IN-Buffer and up to
 1094 in the OUT-Buffer. The ASCII illustration below depicts a secure-read with
 110associated get+set of attributes-lists. Other combinations very on the same
 111basic theme. From no-segments-used up to all-segments-used.
 112
 113|________OSD-CDB__________|
 114|                         |
 115|read_len (offset=0)     -|---------\
 116|                         |         |
 117|get_attrs_list_length    |         |
 118|get_attrs_list_offset   -|----\    |
 119|                         |    |    |
 120|retrieved_attrs_alloc_len|    |    |
 121|retrieved_attrs_offset  -|----|----|-\
 122|                         |    |    | |
 123|set_attrs_list_length    |    |    | |
 124|set_attrs_list_offset   -|-\  |    | |
 125|                         | |  |    | |
 126|in_data_integ_offset    -|-|--|----|-|-\
 127|out_data_integ_offset   -|-|--|--\ | | |
 128\_________________________/ |  |  | | | |
 129                            |  |  | | | |
 130|_______OUT-BUFFER________| |  |  | | | |
 131|      Set attr list      |</  |  | | | |
 132|                         |    |  | | | |
 133|-------------------------|    |  | | | |
 134|   Get attr descriptors  |<---/  | | | |
 135|                         |       | | | |
 136|-------------------------|       | | | |
 137|    Out-data integrity   |<------/ | | |
 138|                         |         | | |
 139\_________________________/         | | |
 140                                    | | |
 141|________IN-BUFFER________|         | | |
 142|      In-Data read       |<--------/ | |
 143|                         |           | |
 144|-------------------------|           | |
 145|      Get attr list      |<----------/ |
 146|                         |             |
 147|-------------------------|             |
 148|    In-data integrity    |<------------/
 149|                         |
 150\_________________________/
 151
 152A block device request can carry bidirectional payload by means of associating
 153a bidi_read request with a main write-request. Each in/out request is described
 154by a chain of BIOs associated with each request.
 155The CDB is of a SCSI VARLEN CDB format, as described by OSD standard.
 156The OSD standard also mandates alignment restrictions at start of each segment.
 157
 158In the code, in struct osd_request, there are two _osd_io_info structures to
 159describe the IN/OUT buffers above, two BIOs for the data payload and up to five
 160_osd_req_data_segment structures to hold the different segments allocation and
 161information.
 162
 163Important: We have chosen to disregard the assumption that a BIO-chain (and
 164the resulting sg-list) describes a linear memory buffer. Meaning only first and
 165last scatter chain can be incomplete and all the middle chains are of PAGE_SIZE.
 166For us, a scatter-so3att) API6"> 166For us, a scatter-so3att) AP4">  89   cht3s mandated cumentawe,/osd.i/osd.txt#L9" id="L9" class="line" name=s{losds2="liof the to fictly.,te lioinear memattvad er-  68  1(OSD 1UN). Twloaosd-isame
  69
<1a hre1="Docu
  70- 1osd_d1v_finiovides a ected umentation/scsi/osd.txt#L166" id="L166" lass="lin1e" name="L71">  71
<1a hre1="Documentation/scsi/osd.txt#L72" id="L72" c1lass="lin1e" name="L72">  72OS1D com172andard also T="DocuDocumentation/scsi/osd.txt#L53" id="L53" c1lass="lin1e" name="L73">  73
<1a hre1="Docu=====
  74st1ruct 1sd_reqTODO: Mscsiet that ising rola hreDocuumentation/scsi/osd.txt#L166" id="L166" llass="line" name="L75">  75it1s sta1e thromentation/scsi/osd.txt#L166" id="L166" llass="line" name="L76">  76
<1a hre1="DocuAuthoro3aMai laye>Formentation/scsi/osd.txt#L166" id="L166" lass="line"" name="L17">  17osd-f thetart_r=======
  78
<1a hre1="DocuPleases.
  79b.1 Any 1f the er-nocumentation/scsi/osd.txt#L157" id="L157" lass="lin1e" name="L80">  80  1 type18"Documentation/scsi/osd.txt#L101" id="L101" lass="lin1e" name="L81">  81
<1a hre1="Docu_reqproblemo3are twof eribuglisve cerilonOSD lso n">snd aeaseseueslumentation/scsi/osd.txt#L18" id="L18" claass="lin1e" name="L82">  82c.1 osd_18ated witlso Dev &quo --/
d="-ovi@or more
spanmentation/scsi/osd.txt#L18" id="L18" claass="lin1e" name="L83">  83  1 CDB.18"Documentation/scsi/osd.txt#L74" id="L74" c1lass="lin1e" name="L84">  84  1 can 1e callMscsiep-toy   
  85  1 attr1bute-pentation/d.org for more
osd.org for more
Documentation/scsi/osd.txt#L74" id="L74" c1llass="line" name="L86">  86
<1a hre1="Documentation/scsi/osd.txt#L87" id="L87" c1lass="lin1e" name="L87">  87d.1 osd_1inalizBoaz Harrosh --/
bharrosh@panasas..
  18  Th hre1igns tBenreqHalevy --/
bhalevy@panasas..
  89  1 chec18"Documentation/scsi/osd.txt#L70" id="L70" c1lass="lin1e" name="L90">  90
<1a hre1="DocuRes allocumentation/scsi/osd.txt#L57" id="L57" c1lass="lin1e" name="L91">  91e.1 osd_19========
  92  1 laye1 and wWeby.,tR.,ot; modB fortorage Device) is a T10 SCSpes
< exet; modumentation/scsi/osd.txt#L29" id="L29" c1lass="lin1e" name="L93">  93  1 asyn1hronouT10/1355-D ANSI/INCITS 400-2004umentation/scsi/osd.txt#L29" id="L29" c1lass="lin1e" name="L94">  94
<1a hre1="Docuentation/d.org fp/t10/drafts/osd2/ for the the-r/drpdf10.org/ftp/t10/drafts/osd2/ for the the-r/drpdfDocumentation/scsi/osd.txt#L70" id="L70" c1llass="line" name="L95">  95f.1 Afte19 thromentation/scsi/osd.txt#L166" id="L166" lass="lin1e" name="L96">  96  1 sens1 inforWeby.,tR.,ot; modB fortorage Device) is a T10 SCSpes
< exe -2e osd-2)="Documentation/scsi/osd.txt#L14" id="L14" cllass="lin1e" name="L97">  97
<1a hre1="DocuT10/1729-D, W/a> ma Da>fo,lisv. 3mentation/scsi/osd.txt#L14" id="L14" cllass="linee" name="L98">  98g.1 osd_1eq_decentation/d.org fp/t10/drafts/osd2/ for the2 the2r03rpdf10.org/ftp/t10/drafts/osd2/ for the2 the2r03rpdfthromentation/scsi/osd.txt#L166" id="L166" lass="line"" name="L19">  19userchec1s.

   

d="content">
ame="L1footer">
ructurigt()  LXR softwZE.
a>   chentation/d.org f="Docuhrege.net/prref="s/lxr">LXR .
 entation/ueslto:lxr@lem. .no">lxr@lem. .no

ame="L1subfooter">
lxr.lem. .no > mdul uos standaentation/d.org fp/t1redpill-lemprr.no">Redpillstemprr AS