1230557Sjimharris/*- 2230557Sjimharris * This file is provided under a dual BSD/GPLv2 license. When using or 3230557Sjimharris * redistributing this file, you may do so under either license. 4230557Sjimharris * 5230557Sjimharris * GPL LICENSE SUMMARY 6230557Sjimharris * 7230557Sjimharris * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 8230557Sjimharris * 9230557Sjimharris * This program is free software; you can redistribute it and/or modify 10230557Sjimharris * it under the terms of version 2 of the GNU General Public License as 11230557Sjimharris * published by the Free Software Foundation. 12230557Sjimharris * 13230557Sjimharris * This program is distributed in the hope that it will be useful, but 14230557Sjimharris * WITHOUT ANY WARRANTY; without even the implied warranty of 15230557Sjimharris * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16230557Sjimharris * General Public License for more details. 17230557Sjimharris * 18230557Sjimharris * You should have received a copy of the GNU General Public License 19230557Sjimharris * along with this program; if not, write to the Free Software 20230557Sjimharris * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. 21230557Sjimharris * The full GNU General Public License is included in this distribution 22230557Sjimharris * in the file called LICENSE.GPL. 23230557Sjimharris * 24230557Sjimharris * BSD LICENSE 25230557Sjimharris * 26230557Sjimharris * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 27230557Sjimharris * All rights reserved. 28230557Sjimharris * 29230557Sjimharris * Redistribution and use in source and binary forms, with or without 30230557Sjimharris * modification, are permitted provided that the following conditions 31230557Sjimharris * are met: 32230557Sjimharris * 33230557Sjimharris * * Redistributions of source code must retain the above copyright 34230557Sjimharris * notice, this list of conditions and the following disclaimer. 35230557Sjimharris * * Redistributions in binary form must reproduce the above copyright 36230557Sjimharris * notice, this list of conditions and the following disclaimer in 37230557Sjimharris * the documentation and/or other materials provided with the 38230557Sjimharris * distribution. 39230557Sjimharris * 40230557Sjimharris * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 41230557Sjimharris * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 42230557Sjimharris * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 43230557Sjimharris * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 44230557Sjimharris * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45230557Sjimharris * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 46230557Sjimharris * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 47230557Sjimharris * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 48230557Sjimharris * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 49230557Sjimharris * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 50230557Sjimharris * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 51230557Sjimharris * 52230557Sjimharris * $FreeBSD$ 53230557Sjimharris */ 54230557Sjimharris#ifndef _SATI_DESIGN_H_ 55230557Sjimharris#define _SATI_DESIGN_H_ 56230557Sjimharris 57230557Sjimharris/** 58230557Sjimharris@page sati_design_page SATI High Level Design 59230557Sjimharris 60230557Sjimharris<b>Authors:</b> 61230557Sjimharris- Nathan Marushak 62230557Sjimharris 63230557Sjimharris@section scif_sas_scope_and_audience Scope and Audience 64230557Sjimharris 65230557SjimharrisThis document provides design information relating to the SCSI to ATA 66230557SjimharrisTranslation Implementation (SATI). Driver developers are the primary 67230557Sjimharrisaudience for this document. The reader is expected to have an understanding 68230557Sjimharrisof SCSI (Simple Computer Storage Interface), ATA (Advanced Technology 69230557SjimharrisAttachment), and SAT (SCSI-to-ATA Translation). 70230557Sjimharris 71230557SjimharrisPlease refer to www.t10.org for specifications relating to SCSI and SAT. 72230557SjimharrisPlease refer to www.t13.org for specifications relating to ATA. 73230557Sjimharris 74230557Sjimharris@section overview Overview 75230557Sjimharris 76230557SjimharrisSATI provides environment agnostic functionality for translating SCSI 77230557Sjimharriscommands, data, and responses into ATA commands, data, and responses. As 78230557Sjimharrisa result, in some instances the user must fill out callbacks to set data. 79230557SjimharrisThis ensures that user isn't forced to have to copy the data an additional 80230557Sjimharristime due to memory access restrictions. 81230557Sjimharris 82230557SjimharrisSATI complies with the t10 SAT specification where possible. In cases where 83230557Sjimharristhere are variances the design and implementation will make note. 84230557SjimharrisAdditionally, for parameters, pages, functionality, or commands for which 85230557SjimharrisSATI is unable to translate, SATI will return sense data indicating 86230557SjimharrisINVALID FIELD IN CDB. 87230557Sjimharris 88230557SjimharrisSATI has two primary entry points from which the user can enter: 89230557Sjimharris- sati_translate_command() 90230557Sjimharris- sati_translate_response() (this method performs data translation). 91230557Sjimharris 92230557SjimharrisAdditionally, SATI provides a means through which the user can query to 93230557Sjimharrisdetermine the t10 specification revision with which SATI is compliant. For 94230557Sjimharrismore information please refer to: 95230557Sjimharris- sati_get_sat_compliance_version() 96230557Sjimharris- sati_get_sat_compliance_version_revision() 97230557Sjimharris 98230557Sjimharris@section sati_definitions Definitions 99230557Sjimharris 100230557Sjimharris- scsi_io: The SCSI IO is considered to be the user's SCSI IO request object 101230557Sjimharris(e.g. the windows driver IO request object and SRB). It is passed back to 102230557Sjimharristhe user via callback methods to retrieve required SCSI information (e.g. CDB, 103230557Sjimharrisresponse IU address, etc.). The SCSI IO is just a cookie and can represent 104230557Sjimharrisany value the caller desires, but the user must be able to utilize this value 105230557Sjimharriswhen it is passed back through callback methods during translation. 106230557Sjimharris- ata_io: The ATA IO is considered to be the user's ATA IO request object. If 107230557Sjimharrisyou are utilizing the SCI Framework, then the SCI Framework is the ATA IO. 108230557SjimharrisThe ATA IO is just a cookie and can represent any value the caller desires, 109230557Sjimharrisbut the user must be able to utilize this value when it is passed back 110230557Sjimharristhrough callback methods during translation. 111230557Sjimharris 112230557Sjimharris@section sati_use_cases Use Cases 113230557Sjimharris 114230557SjimharrisThe SCSI Primary Command (SPC) set is comprised of commands that are valid 115230557Sjimharrisfor all device types defined in SCSI. Some of these commands have 116230557Sjimharrissub-commands or parameter data defined in another specification (e.g. SBC, SAT). 117230557SjimharrisThese separate sub-commands or parameter data are captured in the SPC use 118230557Sjimharriscase diagram for simplicity. 119230557Sjimharris 120230557Sjimharris@note 121230557Sjimharris- For simplicify the association between the actor and the use cases 122230557Sjimharrishas not been drawn, but is assumed. 123230557Sjimharris- The use cases in green indicate the use case has been implemented in 124230557Sjimharris source. 125230557Sjimharris 126230557Sjimharris@image html Use_Case_Diagram__SATI__SATI_-_SPC.jpg "SCSI Primary Command Translation Use Cases" 127230557Sjimharris 128230557SjimharrisThe SCSI Block Command (SBC) set is comprised of commands that are valid for 129230557Sjimharrisblock devices (e.g. disks). 130230557Sjimharris 131230557Sjimharris@image html Use_Case_Diagram__SATI__SATI_-_SBC.jpg "SCSI Block Command Translation Use Cases" 132230557Sjimharris 133230557SjimharrisThe SCSI-to-ATA Translation (SAT) specification defines a few of it's own 134230557Sjimharriscommands, parameter data, and log pages. This use case diagram, however, only 135230557Sjimharriscaptures the SAT specific commands being translated. 136230557Sjimharris 137230557Sjimharris@image html Use_Case_Diagram__SATI__SATI_-_SAT_Specific.jpg "SCSI-to-ATA Translation Specific Use Cases" 138230557Sjimharris 139230557Sjimharris@section sati_class_hierarchy Class Hierarchy 140230557Sjimharris 141230557Sjimharris@image html Class_Diagram__SATI__Class_Diagram.jpg "SATI Class Diagram" 142230557Sjimharris 143230557Sjimharris@section sati_sequences Sequence Diagrams 144230557Sjimharris 145230557Sjimharris@note These sequence diagrams are currently a little out of date. An 146230557Sjimharris update is required. 147230557Sjimharris 148230557SjimharrisThis sequence diagram simply depicts the high-level translation sequence to 149230557Sjimharrisbe followed for command translations. 150230557Sjimharris 151230557Sjimharris@image html Sequence_Diagram__General_Cmd_Translation_Sequence__General_Cmd_Translation_Sequence.jpg "General Command Translation Sequence" 152230557Sjimharris 153230557SjimharrisThis sequence diagram simply depicts the high-level translation sequence to 154230557Sjimharrisbe followed for reponse translations. 155230557Sjimharris 156230557Sjimharris@image html Sequence_Diagram__General_Rsp_Translation_Sequence__General_Rsp_Translation_Sequence.jpg "General Response Translation Sequence" 157230557Sjimharris 158230557SjimharrisThis sequence diagram simply depicts the high-level translation sequence to 159230557Sjimharrisbe followed for data translations. Some SCSI commands such as READ CAPACITY, 160230557SjimharrisINQUIRY, etc. have payload data associated with them. As a result, it is 161230557Sjimharrisnecessary for the ATA payload data to be translated to meet the expected SCSI 162230557Sjimharrisoutput. 163230557Sjimharris 164230557Sjimharris@image html Sequence_Diagram__General_Data_Translation_Sequence__General_Data_Translation_Sequence.jpg "General Data Translation Sequence" 165230557Sjimharris 166230557Sjimharris*/ 167230557Sjimharris 168230557Sjimharris#endif // _SATI_DESIGN_H_ 169230557Sjimharris 170