sati_design.h revision 230557
1163516Simp/*- 2163516Simp * This file is provided under a dual BSD/GPLv2 license. When using or 3163516Simp * redistributing this file, you may do so under either license. 4163516Simp * 5163516Simp * GPL LICENSE SUMMARY 6163516Simp * 7163516Simp * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 8163516Simp * 9163516Simp * This program is free software; you can redistribute it and/or modify 10163516Simp * it under the terms of version 2 of the GNU General Public License as 11163516Simp * published by the Free Software Foundation. 12163516Simp * 13163516Simp * This program is distributed in the hope that it will be useful, but 14163516Simp * WITHOUT ANY WARRANTY; without even the implied warranty of 15163516Simp * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16163516Simp * General Public License for more details. 17163516Simp * 18163516Simp * You should have received a copy of the GNU General Public License 19163516Simp * along with this program; if not, write to the Free Software 20163516Simp * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. 21163516Simp * The full GNU General Public License is included in this distribution 22163516Simp * in the file called LICENSE.GPL. 23163516Simp * 24170002Simp * BSD LICENSE 25170002Simp * 26170002Simp * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 27170002Simp * All rights reserved. 28170002Simp * 29170002Simp * Redistribution and use in source and binary forms, with or without 30170002Simp * modification, are permitted provided that the following conditions 31170002Simp * are met: 32170002Simp * 33170002Simp * * Redistributions of source code must retain the above copyright 34170002Simp * notice, this list of conditions and the following disclaimer. 35170002Simp * * Redistributions in binary form must reproduce the above copyright 36170002Simp * notice, this list of conditions and the following disclaimer in 37170002Simp * the documentation and/or other materials provided with the 38170002Simp * distribution. 39170002Simp * 40170002Simp * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 41170002Simp * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 42170002Simp * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 43170002Simp * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 44170002Simp * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45170002Simp * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 46170002Simp * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 47170002Simp * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 48170002Simp * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 49170002Simp * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 50170002Simp * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 51163516Simp * 52163516Simp * $FreeBSD$ 53163516Simp */ 54163516Simp#ifndef _SATI_DESIGN_H_ 55163516Simp#define _SATI_DESIGN_H_ 56163516Simp 57163516Simp/** 58163516Simp@page sati_design_page SATI High Level Design 59163516Simp 60163516Simp<b>Authors:</b> 61163516Simp- Nathan Marushak 62163516Simp 63163516Simp@section scif_sas_scope_and_audience Scope and Audience 64183704Smav 65187875SmavThis document provides design information relating to the SCSI to ATA 66163516SimpTranslation Implementation (SATI). Driver developers are the primary 67163516Simpaudience for this document. The reader is expected to have an understanding 68163516Simpof SCSI (Simple Computer Storage Interface), ATA (Advanced Technology 69163516SimpAttachment), and SAT (SCSI-to-ATA Translation). 70163516Simp 71163516SimpPlease refer to www.t10.org for specifications relating to SCSI and SAT. 72163516SimpPlease refer to www.t13.org for specifications relating to ATA. 73163516Simp 74163516Simp@section overview Overview 75163516Simp 76163516SimpSATI provides environment agnostic functionality for translating SCSI 77163516Simpcommands, data, and responses into ATA commands, data, and responses. As 78163516Simpa result, in some instances the user must fill out callbacks to set data. 79163516SimpThis ensures that user isn't forced to have to copy the data an additional 80163516Simptime due to memory access restrictions. 81163516Simp 82163516SimpSATI complies with the t10 SAT specification where possible. In cases where 83163516Simpthere are variances the design and implementation will make note. 84163516SimpAdditionally, for parameters, pages, functionality, or commands for which 85163516SimpSATI is unable to translate, SATI will return sense data indicating 86163516SimpINVALID FIELD IN CDB. 87183704Smav 88183704SmavSATI has two primary entry points from which the user can enter: 89184033Smav- sati_translate_command() 90163516Simp- sati_translate_response() (this method performs data translation). 91163516Simp 92163516SimpAdditionally, SATI provides a means through which the user can query to 93163516Simpdetermine the t10 specification revision with which SATI is compliant. For 94183704Smavmore information please refer to: 95184033Smav- sati_get_sat_compliance_version() 96183447Simp- sati_get_sat_compliance_version_revision() 97183704Smav 98183704Smav@section sati_definitions Definitions 99183731Smav 100183731Smav- scsi_io: The SCSI IO is considered to be the user's SCSI IO request object 101183704Smav(e.g. the windows driver IO request object and SRB). It is passed back to 102183704Smavthe user via callback methods to retrieve required SCSI information (e.g. CDB, 103184033Smavresponse IU address, etc.). The SCSI IO is just a cookie and can represent 104234524Smariusany value the caller desires, but the user must be able to utilize this value 105163516Simpwhen it is passed back through callback methods during translation. 106163516Simp- ata_io: The ATA IO is considered to be the user's ATA IO request object. If 107163516Simpyou are utilizing the SCI Framework, then the SCI Framework is the ATA IO. 108163516SimpThe ATA IO is just a cookie and can represent any value the caller desires, 109254716Sianbut the user must be able to utilize this value when it is passed back 110254427Sianthrough callback methods during translation. 111227309Sed 112187875Smav@section sati_use_cases Use Cases 113188044Simp 114187875SmavThe SCSI Primary Command (SPC) set is comprised of commands that are valid 115187875Smavfor all device types defined in SCSI. Some of these commands have 116163516Simpsub-commands or parameter data defined in another specification (e.g. SBC, SAT). 117236491SmariusThese separate sub-commands or parameter data are captured in the SPC use 118163516Simpcase diagram for simplicity. 119236491Smarius 120236491Smarius@note 121163516Simp- For simplicify the association between the actor and the use cases 122236491Smariushas not been drawn, but is assumed. 123236491Smarius- The use cases in green indicate the use case has been implemented in 124236491Smarius source. 125236491Smarius 126236491Smarius@image html Use_Case_Diagram__SATI__SATI_-_SPC.jpg "SCSI Primary Command Translation Use Cases" 127185721Smav 128236491SmariusThe SCSI Block Command (SBC) set is comprised of commands that are valid for 129236491Smariusblock devices (e.g. disks). 130236491Smarius 131236491Smarius@image html Use_Case_Diagram__SATI__SATI_-_SBC.jpg "SCSI Block Command Translation Use Cases" 132163516Simp 133163516SimpThe SCSI-to-ATA Translation (SAT) specification defines a few of it's own 134163516Simpcommands, parameter data, and log pages. This use case diagram, however, only 135183444Simpcaptures the SAT specific commands being translated. 136183444Simp 137163516Simp@image html Use_Case_Diagram__SATI__SATI_-_SAT_Specific.jpg "SCSI-to-ATA Translation Specific Use Cases" 138163516Simp 139163516Simp@section sati_class_hierarchy Class Hierarchy 140163516Simp 141163516Simp@image html Class_Diagram__SATI__Class_Diagram.jpg "SATI Class Diagram" 142236491Smarius 143236491Smarius@section sati_sequences Sequence Diagrams 144236491Smarius 145236491Smarius@note These sequence diagrams are currently a little out of date. An 146236491Smarius update is required. 147236491Smarius 148236491SmariusThis sequence diagram simply depicts the high-level translation sequence to 149236491Smariusbe followed for command translations. 150183763Smav 151236491Smarius@image html Sequence_Diagram__General_Cmd_Translation_Sequence__General_Cmd_Translation_Sequence.jpg "General Command Translation Sequence" 152236491Smarius 153236491SmariusThis sequence diagram simply depicts the high-level translation sequence to 154236491Smariusbe followed for reponse translations. 155236491Smarius 156236491Smarius@image html Sequence_Diagram__General_Rsp_Translation_Sequence__General_Rsp_Translation_Sequence.jpg "General Response Translation Sequence" 157236491Smarius 158236491SmariusThis sequence diagram simply depicts the high-level translation sequence to 159236491Smariusbe followed for data translations. Some SCSI commands such as READ CAPACITY, 160236491SmariusINQUIRY, etc. have payload data associated with them. As a result, it is 161236491Smariusnecessary for the ATA payload data to be translated to meet the expected SCSI 162236491Smariusoutput. 163236491Smarius 164236491Smarius@image html Sequence_Diagram__General_Data_Translation_Sequence__General_Data_Translation_Sequence.jpg "General Data Translation Sequence" 165236491Smarius 166183449Simp*/ 167236491Smarius 168236491Smarius#endif // _SATI_DESIGN_H_ 169236491Smarius 170236491Smarius