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