diff options
Diffstat (limited to 'sys/dev/isci/scil/sati_design.h')
| -rw-r--r-- | sys/dev/isci/scil/sati_design.h | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/sys/dev/isci/scil/sati_design.h b/sys/dev/isci/scil/sati_design.h new file mode 100644 index 0000000..f4f2248 --- /dev/null +++ b/sys/dev/isci/scil/sati_design.h @@ -0,0 +1,169 @@ +/*- + * This file is provided under a dual BSD/GPLv2 license. When using or + * redistributing this file, you may do so under either license. + * + * GPL LICENSE SUMMARY + * + * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of version 2 of the GNU General Public License as + * published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. + * The full GNU General Public License is included in this distribution + * in the file called LICENSE.GPL. + * + * BSD LICENSE + * + * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * * Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + * $FreeBSD$ + */ +#ifndef _SATI_DESIGN_H_ +#define _SATI_DESIGN_H_ + +/** +@page sati_design_page SATI High Level Design + +<b>Authors:</b> +- Nathan Marushak + +@section scif_sas_scope_and_audience Scope and Audience + +This document provides design information relating to the SCSI to ATA +Translation Implementation (SATI). Driver developers are the primary +audience for this document. The reader is expected to have an understanding +of SCSI (Simple Computer Storage Interface), ATA (Advanced Technology +Attachment), and SAT (SCSI-to-ATA Translation). + +Please refer to www.t10.org for specifications relating to SCSI and SAT. +Please refer to www.t13.org for specifications relating to ATA. + +@section overview Overview + +SATI provides environment agnostic functionality for translating SCSI +commands, data, and responses into ATA commands, data, and responses. As +a result, in some instances the user must fill out callbacks to set data. +This ensures that user isn't forced to have to copy the data an additional +time due to memory access restrictions. + +SATI complies with the t10 SAT specification where possible. In cases where +there are variances the design and implementation will make note. +Additionally, for parameters, pages, functionality, or commands for which +SATI is unable to translate, SATI will return sense data indicating +INVALID FIELD IN CDB. + +SATI has two primary entry points from which the user can enter: +- sati_translate_command() +- sati_translate_response() (this method performs data translation). + +Additionally, SATI provides a means through which the user can query to +determine the t10 specification revision with which SATI is compliant. For +more information please refer to: +- sati_get_sat_compliance_version() +- sati_get_sat_compliance_version_revision() + +@section sati_definitions Definitions + +- scsi_io: The SCSI IO is considered to be the user's SCSI IO request object +(e.g. the windows driver IO request object and SRB). It is passed back to +the user via callback methods to retrieve required SCSI information (e.g. CDB, +response IU address, etc.). The SCSI IO is just a cookie and can represent +any value the caller desires, but the user must be able to utilize this value +when it is passed back through callback methods during translation. +- ata_io: The ATA IO is considered to be the user's ATA IO request object. If +you are utilizing the SCI Framework, then the SCI Framework is the ATA IO. +The ATA IO is just a cookie and can represent any value the caller desires, +but the user must be able to utilize this value when it is passed back +through callback methods during translation. + +@section sati_use_cases Use Cases + +The SCSI Primary Command (SPC) set is comprised of commands that are valid +for all device types defined in SCSI. Some of these commands have +sub-commands or parameter data defined in another specification (e.g. SBC, SAT). +These separate sub-commands or parameter data are captured in the SPC use +case diagram for simplicity. + +@note +- For simplicify the association between the actor and the use cases +has not been drawn, but is assumed. +- The use cases in green indicate the use case has been implemented in + source. + +@image html Use_Case_Diagram__SATI__SATI_-_SPC.jpg "SCSI Primary Command Translation Use Cases" + +The SCSI Block Command (SBC) set is comprised of commands that are valid for +block devices (e.g. disks). + +@image html Use_Case_Diagram__SATI__SATI_-_SBC.jpg "SCSI Block Command Translation Use Cases" + +The SCSI-to-ATA Translation (SAT) specification defines a few of it's own +commands, parameter data, and log pages. This use case diagram, however, only +captures the SAT specific commands being translated. + +@image html Use_Case_Diagram__SATI__SATI_-_SAT_Specific.jpg "SCSI-to-ATA Translation Specific Use Cases" + +@section sati_class_hierarchy Class Hierarchy + +@image html Class_Diagram__SATI__Class_Diagram.jpg "SATI Class Diagram" + +@section sati_sequences Sequence Diagrams + +@note These sequence diagrams are currently a little out of date. An + update is required. + +This sequence diagram simply depicts the high-level translation sequence to +be followed for command translations. + +@image html Sequence_Diagram__General_Cmd_Translation_Sequence__General_Cmd_Translation_Sequence.jpg "General Command Translation Sequence" + +This sequence diagram simply depicts the high-level translation sequence to +be followed for reponse translations. + +@image html Sequence_Diagram__General_Rsp_Translation_Sequence__General_Rsp_Translation_Sequence.jpg "General Response Translation Sequence" + +This sequence diagram simply depicts the high-level translation sequence to +be followed for data translations. Some SCSI commands such as READ CAPACITY, +INQUIRY, etc. have payload data associated with them. As a result, it is +necessary for the ATA payload data to be translated to meet the expected SCSI +output. + +@image html Sequence_Diagram__General_Data_Translation_Sequence__General_Data_Translation_Sequence.jpg "General Data Translation Sequence" + +*/ + +#endif // _SATI_DESIGN_H_ + |
