sys/dev/isci/scil/sati_design.h

   1 /*-
   2  * This file is provided under a dual BSD/GPLv2 license.  When using or
   3  * redistributing this file, you may do so under either license.
   4  *
   5  * GPL LICENSE SUMMARY
   6  *
   7  * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of version 2 of the GNU General Public License as
  11  * published by the Free Software Foundation.
  12  *
  13  * This program is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA.
  21  * The full GNU General Public License is included in this distribution
  22  * in the file called LICENSE.GPL.
  23  *
  24  * BSD LICENSE
  25  *
  26  * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
  27  * All rights reserved.
  28  *
  29  * Redistribution and use in source and binary forms, with or without
  30  * modification, are permitted provided that the following conditions
  31  * are met:
  32  *
  33  *   * Redistributions of source code must retain the above copyright
  34  *     notice, this list of conditions and the following disclaimer.
  35  *   * Redistributions in binary form must reproduce the above copyright
  36  *     notice, this list of conditions and the following disclaimer in
  37  *     the documentation and/or other materials provided with the
  38  *     distribution.
  39  *
  40  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  41  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  42  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  43  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  44  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  45  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  46  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  47  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  48  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  49  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  50  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  51  *
  52  * $FreeBSD$
  53  */
  54 #ifndef _SATI_DESIGN_H_
  55 #define _SATI_DESIGN_H_
  56
  57 /**
  58 @page sati_design_page SATI High Level Design
  59
  60 <b>Authors:</b>
  61 - Nathan Marushak
  62
  63 @section scif_sas_scope_and_audience Scope and Audience
  64
  65 This document provides design information relating to the SCSI to ATA
  66 Translation Implementation (SATI).  Driver developers are the primary
  67 audience for this document.  The reader is expected to have an understanding
  68 of SCSI (Simple Computer Storage Interface), ATA (Advanced Technology
  69 Attachment), and SAT (SCSI-to-ATA Translation).
  70
  71 Please refer to www.t10.org for specifications relating to SCSI and SAT.
  72 Please refer to www.t13.org for specifications relating to ATA.
  73
  74 @section overview Overview
  75
  76 SATI provides environment agnostic functionality for translating SCSI
  77 commands, data, and responses into ATA commands, data, and responses.  As
  78 a result, in some instances the user must fill out callbacks to set data.
  79 This ensures that user isn't forced to have to copy the data an additional
  80 time due to memory access restrictions.
  81
  82 SATI complies with the t10 SAT specification where possible.  In cases where
  83 there are variances the design and implementation will make note.
  84 Additionally, for parameters, pages, functionality, or commands for which
  85 SATI is unable to translate, SATI will return sense data indicating
  86 INVALID FIELD IN CDB.
  87
  88 SATI has two primary entry points from which the user can enter:
  89 - sati_translate_command()
  90 - sati_translate_response() (this method performs data translation).
  91
  92 Additionally, SATI provides a means through which the user can query to
  93 determine the t10 specification revision with which SATI is compliant.  For
  94 more information please refer to:
  95 - sati_get_sat_compliance_version()
  96 - sati_get_sat_compliance_version_revision()
  97
  98 @section sati_definitions Definitions
  99
 100 - scsi_io: The SCSI IO is considered to be the user's SCSI IO request object
 101 (e.g. the windows driver IO request object and SRB).  It is passed back to
 102 the user via callback methods to retrieve required SCSI information (e.g. CDB,
 103 response IU address, etc.).  The SCSI IO is just a cookie and can represent
 104 any value the caller desires, but the user must be able to utilize this value
 105 when it is passed back through callback methods during translation.
 106 - ata_io: The ATA IO is considered to be the user's ATA IO request object.  If
 107 you are utilizing the SCI Framework, then the SCI Framework is the ATA IO.
 108 The ATA IO is just a cookie and can represent any value the caller desires,
 109 but the user must be able to utilize this value when it is passed back
 110 through callback methods during translation.
 111
 112 @section sati_use_cases Use Cases
 113
 114 The SCSI Primary Command (SPC) set is comprised of commands that are valid
 115 for all device types defined in SCSI.  Some of these commands have
 116 sub-commands or parameter data defined in another specification (e.g. SBC, SAT).
 117 These separate sub-commands or parameter data are captured in the SPC use
 118 case diagram for simplicity.
 119
 120 @note
 121 - For simplicify the association between the actor and the use cases
 122 has not been drawn, but is assumed.
 123 - The use cases in green indicate the use case has been implemented in
 124   source.
 125
 126 @image html Use_Case_Diagram__SATI__SATI_-_SPC.jpg "SCSI Primary Command Translation Use Cases"
 127
 128 The SCSI Block Command (SBC) set is comprised of commands that are valid for
 129 block devices (e.g. disks).
 130
 131 @image html Use_Case_Diagram__SATI__SATI_-_SBC.jpg "SCSI Block Command Translation Use Cases"
 132
 133 The SCSI-to-ATA Translation (SAT) specification defines a few of it's own
 134 commands, parameter data, and log pages.  This use case diagram, however, only
 135 captures the SAT specific commands being translated.
 136
 137 @image html Use_Case_Diagram__SATI__SATI_-_SAT_Specific.jpg "SCSI-to-ATA Translation Specific Use Cases"
 138
 139 @section sati_class_hierarchy Class Hierarchy
 140
 141 @image html Class_Diagram__SATI__Class_Diagram.jpg "SATI Class Diagram"
 142
 143 @section sati_sequences Sequence Diagrams
 144
 145 @note These sequence diagrams are currently a little out of date.  An
 146       update is required.
 147
 148 This sequence diagram simply depicts the high-level translation sequence to
 149 be followed for command translations.
 150
 151 @image html Sequence_Diagram__General_Cmd_Translation_Sequence__General_Cmd_Translation_Sequence.jpg "General Command Translation Sequence"
 152
 153 This sequence diagram simply depicts the high-level translation sequence to
 154 be followed for reponse translations.
 155
 156 @image html Sequence_Diagram__General_Rsp_Translation_Sequence__General_Rsp_Translation_Sequence.jpg "General Response Translation Sequence"
 157
 158 This sequence diagram simply depicts the high-level translation sequence to
 159 be followed for data translations.  Some SCSI commands such as READ CAPACITY,
 160 INQUIRY, etc. have payload data associated with them.  As a result, it is
 161 necessary for the ATA payload data to be translated to meet the expected SCSI
 162 output.
 163
 164 @image html Sequence_Diagram__General_Data_Translation_Sequence__General_Data_Translation_Sequence.jpg "General Data Translation Sequence"
 165
 166 */
 167
 168 #endif // _SATI_DESIGN_H_
 169