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