forked from mirrors/linux
[SCSI] osd: Documentation for OSD library
Add osd.txt to Documentation/scsi/ Signed-off-by: Boaz Harrosh <bharrosh@panasas.com> Reviewed-by: Benny Halevy <bhalevy@panasas.com> Signed-off-by: James Bottomley <James.Bottomley@HansenPartnership.com>
This commit is contained in:
Boaz Harrosh
James Bottomley
parent
98f3aea2bd
commit
78e0c621de
1 changed files with 198 additions and 0 deletions
198
Documentation/scsi/osd.txt
Normal file
198
Documentation/scsi/osd.txt
Normal file
|
|
@ -0,0 +1,198 @@
|
||||||
|
The OSD Standard
|
||||||
|
================
|
||||||
|
OSD (Object-Based Storage Device) is a T10 SCSI command set that is designed
|
||||||
|
to provide efficient operation of input/output logical units that manage the
|
||||||
|
allocation, placement, and accessing of variable-size data-storage containers,
|
||||||
|
called objects. Objects are intended to contain operating system and application
|
||||||
|
constructs. Each object has associated attributes attached to it, which are
|
||||||
|
integral part of the object and provide metadata about the object. The standard
|
||||||
|
defines some common obligatory attributes, but user attributes can be added as
|
||||||
|
needed.
|
||||||
|
|
||||||
|
See: http://www.t10.org/ftp/t10/drafts/osd2/ for the latest draft for OSD 2
|
||||||
|
or search the web for "OSD SCSI"
|
||||||
|
|
||||||
|
OSD in the Linux Kernel
|
||||||
|
=======================
|
||||||
|
osd-initiator:
|
||||||
|
The main component of OSD in Kernel is the osd-initiator library. Its main
|
||||||
|
user is intended to be the pNFS-over-objects layout driver, which uses objects
|
||||||
|
as its back-end data storage. Other clients are the other osd parts listed below.
|
||||||
|
|
||||||
|
osd-uld:
|
||||||
|
This is a SCSI ULD that registers for OSD type devices and provides a testing
|
||||||
|
platform, both for the in-kernel initiator as well as connected targets. It
|
||||||
|
currently has no useful user-mode API, though it could have if need be.
|
||||||
|
|
||||||
|
exofs:
|
||||||
|
Is an OSD based Linux file system. It uses the osd-initiator and osd-uld,
|
||||||
|
to export a usable file system for users.
|
||||||
|
See Documentation/filesystems/exofs.txt for more details
|
||||||
|
|
||||||
|
osd target:
|
||||||
|
There are no current plans for an OSD target implementation in kernel. For all
|
||||||
|
needs, a user-mode target that is based on the scsi tgt target framework is
|
||||||
|
available from Ohio Supercomputer Center (OSC) at:
|
||||||
|
http://www.open-osd.org/bin/view/Main/OscOsdProject
|
||||||
|
There are several other target implementations. See http://open-osd.org for more
|
||||||
|
links.
|
||||||
|
|
||||||
|
Files and Folders
|
||||||
|
=================
|
||||||
|
This is the complete list of files included in this work:
|
||||||
|
include/scsi/
|
||||||
|
osd_initiator.h Main API for the initiator library
|
||||||
|
osd_types.h Common OSD types
|
||||||
|
osd_sec.h Security Manager API
|
||||||
|
osd_protocol.h Wire definitions of the OSD standard protocol
|
||||||
|
osd_attributes.h Wire definitions of OSD attributes
|
||||||
|
|
||||||
|
drivers/scsi/osd/
|
||||||
|
osd_initiator.c OSD-Initiator library implementation
|
||||||
|
osd_uld.c The OSD scsi ULD
|
||||||
|
osd_ktest.{h,c} In-kernel test suite (called by osd_uld)
|
||||||
|
osd_debug.h Some printk macros
|
||||||
|
Makefile For both in-tree and out-of-tree compilation
|
||||||
|
Kconfig Enables inclusion of the different pieces
|
||||||
|
osd_test.c User-mode application to call the kernel tests
|
||||||
|
|
||||||
|
The OSD-Initiator Library
|
||||||
|
=========================
|
||||||
|
osd_initiator is a low level implementation of an osd initiator encoder.
|
||||||
|
But even though, it should be intuitive and easy to use. Perhaps over time an
|
||||||
|
higher lever will form that automates some of the more common recipes.
|
||||||
|
|
||||||
|
init/fini:
|
||||||
|
- osd_dev_init() associates a scsi_device with an osd_dev structure
|
||||||
|
and initializes some global pools. This should be done once per scsi_device
|
||||||
|
(OSD LUN). The osd_dev structure is needed for calling osd_start_request().
|
||||||
|
|
||||||
|
- osd_dev_fini() cleans up before a osd_dev/scsi_device destruction.
|
||||||
|
|
||||||
|
OSD commands encoding, execution, and decoding of results:
|
||||||
|
|
||||||
|
struct osd_request's is used to iteratively encode an OSD command and carry
|
||||||
|
its state throughout execution. Each request goes through these stages:
|
||||||
|
|
||||||
|
a. osd_start_request() allocates the request.
|
||||||
|
|
||||||
|
b. Any of the osd_req_* methods is used to encode a request of the specified
|
||||||
|
type.
|
||||||
|
|
||||||
|
c. osd_req_add_{get,set}_attr_* may be called to add get/set attributes to the
|
||||||
|
CDB. "List" or "Page" mode can be used exclusively. The attribute-list API
|
||||||
|
can be called multiple times on the same request. However, only one
|
||||||
|
attribute-page can be read, as mandated by the OSD standard.
|
||||||
|
|
||||||
|
d. osd_finalize_request() computes offsets into the data-in and data-out buffers
|
||||||
|
and signs the request using the provided capability key and integrity-
|
||||||
|
check parameters.
|
||||||
|
|
||||||
|
e. osd_execute_request() may be called to execute the request via the block
|
||||||
|
layer and wait for its completion. The request can be executed
|
||||||
|
asynchronously by calling the block layer API directly.
|
||||||
|
|
||||||
|
f. After execution, osd_req_decode_sense() can be called to decode the request's
|
||||||
|
sense information.
|
||||||
|
|
||||||
|
g. osd_req_decode_get_attr() may be called to retrieve osd_add_get_attr_list()
|
||||||
|
values.
|
||||||
|
|
||||||
|
h. osd_end_request() must be called to deallocate the request and any resource
|
||||||
|
associated with it. Note that osd_end_request cleans up the request at any
|
||||||
|
stage and it must always be called after a successful osd_start_request().
|
||||||
|
|
||||||
|
osd_request's structure:
|
||||||
|
|
||||||
|
The OSD standard defines a complex structure of IO segments pointed to by
|
||||||
|
members in the CDB. Up to 3 segments can be deployed in the IN-Buffer and up to
|
||||||
|
4 in the OUT-Buffer. The ASCII illustration below depicts a secure-read with
|
||||||
|
associated get+set of attributes-lists. Other combinations very on the same
|
||||||
|
basic theme. From no-segments-used up to all-segments-used.
|
||||||
|
|
||||||
|
|________OSD-CDB__________|
|
||||||
|
| |
|
||||||
|
|read_len (offset=0) -|---------\
|
||||||
|
| | |
|
||||||
|
|get_attrs_list_length | |
|
||||||
|
|get_attrs_list_offset -|----\ |
|
||||||
|
| | | |
|
||||||
|
|retrieved_attrs_alloc_len| | |
|
||||||
|
|retrieved_attrs_offset -|----|----|-\
|
||||||
|
| | | | |
|
||||||
|
|set_attrs_list_length | | | |
|
||||||
|
|set_attrs_list_offset -|-\ | | |
|
||||||
|
| | | | | |
|
||||||
|
|in_data_integ_offset -|-|--|----|-|-\
|
||||||
|
|out_data_integ_offset -|-|--|--\ | | |
|
||||||
|
\_________________________/ | | | | | |
|
||||||
|
| | | | | |
|
||||||
|
|_______OUT-BUFFER________| | | | | | |
|
||||||
|
| Set attr list |</ | | | | |
|
||||||
|
| | | | | | |
|
||||||
|
|-------------------------| | | | | |
|
||||||
|
| Get attr descriptors |<---/ | | | |
|
||||||
|
| | | | | |
|
||||||
|
|-------------------------| | | | |
|
||||||
|
| Out-data integrity |<------/ | | |
|
||||||
|
| | | | |
|
||||||
|
\_________________________/ | | |
|
||||||
|
| | |
|
||||||
|
|________IN-BUFFER________| | | |
|
||||||
|
| In-Data read |<--------/ | |
|
||||||
|
| | | |
|
||||||
|
|-------------------------| | |
|
||||||
|
| Get attr list |<----------/ |
|
||||||
|
| | |
|
||||||
|
|-------------------------| |
|
||||||
|
| In-data integrity |<------------/
|
||||||
|
| |
|
||||||
|
\_________________________/
|
||||||
|
|
||||||
|
A block device request can carry bidirectional payload by means of associating
|
||||||
|
a bidi_read request with a main write-request. Each in/out request is described
|
||||||
|
by a chain of BIOs associated with each request.
|
||||||
|
The CDB is of a SCSI VARLEN CDB format, as described by OSD standard.
|
||||||
|
The OSD standard also mandates alignment restrictions at start of each segment.
|
||||||
|
|
||||||
|
In the code, in struct osd_request, there are two _osd_io_info structures to
|
||||||
|
describe the IN/OUT buffers above, two BIOs for the data payload and up to five
|
||||||
|
_osd_req_data_segment structures to hold the different segments allocation and
|
||||||
|
information.
|
||||||
|
|
||||||
|
Important: We have chosen to disregard the assumption that a BIO-chain (and
|
||||||
|
the resulting sg-list) describes a linear memory buffer. Meaning only first and
|
||||||
|
last scatter chain can be incomplete and all the middle chains are of PAGE_SIZE.
|
||||||
|
For us, a scatter-gather-list, as its name implies and as used by the Networking
|
||||||
|
layer, is to describe a vector of buffers that will be transferred to/from the
|
||||||
|
wire. It works very well with current iSCSI transport. iSCSI is currently the
|
||||||
|
only deployed OSD transport. In the future we anticipate SAS and FC attached OSD
|
||||||
|
devices as well.
|
||||||
|
|
||||||
|
The OSD Testing ULD
|
||||||
|
===================
|
||||||
|
TODO: More user-mode control on tests.
|
||||||
|
|
||||||
|
Authors, Mailing list
|
||||||
|
=====================
|
||||||
|
Please communicate with us on any deployment of osd, whether using this code
|
||||||
|
or not.
|
||||||
|
|
||||||
|
Any problems, questions, bug reports, lonely OSD nights, please email:
|
||||||
|
OSD Dev List <osd-dev@open-osd.org>
|
||||||
|
|
||||||
|
More up-to-date information can be found on:
|
||||||
|
http://open-osd.org
|
||||||
|
|
||||||
|
Boaz Harrosh <bharrosh@panasas.com>
|
||||||
|
Benny Halevy <bhalevy@panasas.com>
|
||||||
|
|
||||||
|
References
|
||||||
|
==========
|
||||||
|
Weber, R., "SCSI Object-Based Storage Device Commands",
|
||||||
|
T10/1355-D ANSI/INCITS 400-2004,
|
||||||
|
http://www.t10.org/ftp/t10/drafts/osd/osd-r10.pdf
|
||||||
|
|
||||||
|
Weber, R., "SCSI Object-Based Storage Device Commands -2 (OSD-2)"
|
||||||
|
T10/1729-D, Working Draft, rev. 3
|
||||||
|
http://www.t10.org/ftp/t10/drafts/osd2/osd2r03.pdf
|
||||||
Loading…
Reference in a new issue