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 #ifndef _SATI_H_ 55 #define _SATI_H_ 56 57 /** 58 * @file 59 * @brief This file contains all of the interface methods, macros, structures 60 * that can be utilized by a user to perform SCSI-to-ATA Translation. 61 * SATI adheres to the www.t10.org SAT specification. 62 * 63 * For specific compliance information please refer to: 64 * - sati_get_sat_compliance_version() and 65 * - sati_get_sat_compliance_version_revision() 66 * 67 * For situations where compliance is not observed, the SATI will 68 * return an error indication (most likely INVALID FIELD IN CDB sense). 69 */ 70 71 #include <dev/isci/scil/sati_types.h> 72 #include <dev/isci/scil/sati_translator_sequence.h> 73 74 /** 75 * @brief This method will be called by the core to indicate the start of a 76 * new translation sequence. Set up the initial sequence state. 77 * 78 * @return None 79 */ 80 void sati_sequence_construct( 81 SATI_TRANSLATOR_SEQUENCE_T * sequence 82 ); 83 84 /** 85 * @brief This method will be called by the core to request the current translation 86 * sequence be terminated. 87 * 88 * @param[in] sequence This parameter specifies the sequence 89 * data associated with the translation. 90 * @param[in,out] scsi_io This parameter specifies the user's SCSI IO request 91 * object. SATI expects that the user can access the SCSI CDB, 92 * response, and data from this pointer. For example, if there 93 * is a failure in translation resulting in sense data, then 94 * SATI will call sati_cb_set_status() and pass the scsi_io 95 * pointer as a parameter. 96 * @param[out] ata_io This parameter specifies the location of the 97 * ATA register FIS into which the translator can write the 98 * resultant ATA command if translation is successful. This 99 * parameter is passed back to the user through the 100 * SATI_SATA_CALLBACKS when it is necessary to write fields 101 * in the ata_io. 102 * 103 * @return None 104 */ 105 void sati_sequence_terminate( 106 SATI_TRANSLATOR_SEQUENCE_T * sequence, 107 void * scsi_io, 108 void * ata_io 109 ); 110 111 /** 112 * @brief This method translates the supplied SCSI command into a 113 * corresponding ATA command. 114 * 115 * @param[in] sequence This parameter specifies the sequence 116 * data associated with the translation. 117 * @param[in] sati_device This parameter specifies the remote device 118 * for which the translated request is destined. 119 * @param[in,out] scsi_io This parameter specifies the user's SCSI IO request 120 * object. SATI expects that the user can access the SCSI CDB, 121 * response, and data from this pointer. For example, if there 122 * is a failure in translation resulting in sense data, then 123 * SATI will call sati_cb_set_status() and pass the scsi_io 124 * pointer as a parameter. 125 * @param[out] ata_io This parameter specifies the location of the 126 * ATA register FIS into which the translator can write the 127 * resultant ATA command if translation is successful. This 128 * parameter is passed back to the user through the 129 * SATI_SATA_CALLBACKS when it is necessary to write fields 130 * in the ata_io. 131 * 132 * @return Indicate if the translation was successful. 133 * @retval SATI_SUCCESS 134 * @retval SATI_FAILURE_CHECK_RESPONSE_DATA 135 */ 136 SATI_STATUS sati_translate_command( 137 SATI_TRANSLATOR_SEQUENCE_T * sequence, 138 SATI_DEVICE_T * sati_device, 139 void * scsi_io, 140 void * ata_io 141 ); 142 143 /** 144 * @brief This method translates the supplied SCSI task management request 145 * into a corresponding ATA command/control FIS. 146 * 147 * @param[in] sequence This parameter specifies the sequence 148 * data associated with the translation. 149 * @param[in] sati_device This parameter specifies the remote device 150 * for which the translated request is destined. 151 * @param[in,out] scsi_io This parameter specifies the user's SCSI IO request 152 * object. SATI expects that the user can access the SCSI CDB, 153 * response, and data from this pointer. For example, if there 154 * is a failure in translation resulting in sense data, then 155 * SATI will call sati_cb_set_status() and pass the scsi_io 156 * pointer as a parameter. 157 * @param[out] ata_io This parameter specifies the location of the 158 * ATA register FIS into which the translator can write the 159 * resultant ATA command if translation is successful. This 160 * parameter is passed back to the user through the 161 * SATI_SATA_CALLBACKS when it is necessary to write fields 162 * in the ata_io. 163 * 164 * @return Indicate if the translation was successful. 165 * @retval SATI_SUCCESS 166 * @retval SATI_FAILURE_CHECK_RESPONSE_DATA 167 */ 168 SATI_STATUS sati_translate_task_management( 169 SATI_TRANSLATOR_SEQUENCE_T * sequence, 170 SATI_DEVICE_T * sati_device, 171 void * scsi_task, 172 void * ata_io 173 ); 174 175 /** 176 * @brief This method translates the supplied ATA response into the 177 * corresponding SCSI command response. 178 * 179 * @param[in] sequence This parameter specifies the sequence 180 * data associated with the translation. 181 * @param[out] scsi_io This parameter specifies the user's SCSI IO request 182 * object. SATI expects that the user can access the SCSI CDB, 183 * response, and data from this pointer. For example, if there 184 * is a failure in translation resulting in sense data, then 185 * SATI will call sati_cb_set_status() and pass the scsi_io 186 * pointer as a parameter. 187 * @param[out] ata_io This parameter specifies the location of the 188 * ATA IO request (e.g. register FIS, PIO Setup etc.) from which 189 * the translator can read the received ATA status and error 190 * fields. 191 * 192 * @return Indicate if the translation was successful. 193 * @retval SATI_SUCCESS 194 * @retval SATI_FAILURE_CHECK_RESPONSE_DATA 195 */ 196 SATI_STATUS sati_translate_command_response( 197 SATI_TRANSLATOR_SEQUENCE_T * sequence, 198 void * scsi_io, 199 void * ata_io 200 ); 201 202 /** 203 * @brief This method translates the supplied ATA response into the 204 * corresponding SCSI task response. 205 * 206 * @param[in] sequence This parameter specifies the sequence 207 * data associated with the translation. 208 * @param[out] scsi_io This parameter specifies the user's SCSI IO request 209 * object. SATI expects that the user can access the SCSI CDB, 210 * response, and data from this pointer. For example, if there 211 * is a failure in translation resulting in sense data, then 212 * SATI will call sati_cb_set_status() and pass the scsi_io 213 * pointer as a parameter. 214 * @param[out] ata_io This parameter specifies the location of the 215 * ATA IO request (e.g. register FIS, PIO Setup etc.) from which 216 * the translator can read the received ATA status and error 217 * fields. 218 * 219 * @return Indicate if the translation was successful. 220 * @retval SATI_FAILURE_CHECK_RESPONSE_DATA 221 */ 222 SATI_STATUS sati_translate_task_response( 223 SATI_TRANSLATOR_SEQUENCE_T * sequence, 224 void * scsi_io, 225 void * ata_io 226 ); 227 228 /** 229 * @brief This method simply returns the SAT major compliance version number 230 * for which the implementation is compliant. 231 * 232 * @return Return the specification identifier with which this translator 233 * is compliant. 234 */ 235 U32 sati_get_sat_compliance_version( 236 void 237 ); 238 239 /** 240 * @brief This method simply returns the SAT version revision identifier 241 * for which the implementation is compliant. 242 * 243 * @return Return the specification revision identifier with which this 244 * translator is compliant. 245 */ 246 U32 sati_get_sat_compliance_version_revision( 247 void 248 ); 249 250 /** 251 * @brief This method returns the number of data bytes written 252 * by the translation sequence. 253 * 254 * @param[in] sequence This parameter specifies the sequence data 255 * associated with the translation. 256 * 257 * @return Return the U16 number_data_bytes_set in the 258 * SATI_TRANSLATOR_SEQUENCE. 259 */ 260 U16 sati_get_number_data_bytes_set( 261 SATI_TRANSLATOR_SEQUENCE_T * sequence 262 ); 263 264 void sati_translate_error( 265 SATI_TRANSLATOR_SEQUENCE_T * sequence, 266 void * scsi_io, 267 U8 error 268 ); 269 270 #endif // _SATI_H_ 271 272