sati.h revision 230557
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_H_ 55230557Sjimharris#define _SATI_H_ 56230557Sjimharris 57230557Sjimharris/** 58230557Sjimharris * @file 59230557Sjimharris * @brief This file contains all of the interface methods, macros, structures 60230557Sjimharris * that can be utilized by a user to perform SCSI-to-ATA Translation. 61230557Sjimharris * SATI adheres to the www.t10.org SAT specification. 62230557Sjimharris * 63230557Sjimharris * For specific compliance information please refer to: 64230557Sjimharris * - sati_get_sat_compliance_version() and 65230557Sjimharris * - sati_get_sat_compliance_version_revision() 66230557Sjimharris * 67230557Sjimharris * For situations where compliance is not observed, the SATI will 68230557Sjimharris * return an error indication (most likely INVALID FIELD IN CDB sense). 69230557Sjimharris */ 70230557Sjimharris 71230557Sjimharris#include <dev/isci/scil/sati_types.h> 72230557Sjimharris#include <dev/isci/scil/sati_translator_sequence.h> 73230557Sjimharris 74230557Sjimharris/** 75230557Sjimharris * @brief This method will be called by the core to indicate the start of a 76230557Sjimharris * new translation sequence. Set up the initial sequence state. 77230557Sjimharris * 78230557Sjimharris * @return None 79230557Sjimharris */ 80230557Sjimharrisvoid sati_sequence_construct( 81230557Sjimharris SATI_TRANSLATOR_SEQUENCE_T * sequence 82230557Sjimharris); 83230557Sjimharris 84230557Sjimharris/** 85230557Sjimharris * @brief This method will be called by the core to request the current translation 86230557Sjimharris * sequence be terminated. 87230557Sjimharris * 88230557Sjimharris * @param[in] sequence This parameter specifies the sequence 89230557Sjimharris * data associated with the translation. 90230557Sjimharris * @param[in,out] scsi_io This parameter specifies the user's SCSI IO request 91230557Sjimharris * object. SATI expects that the user can access the SCSI CDB, 92230557Sjimharris * response, and data from this pointer. For example, if there 93230557Sjimharris * is a failure in translation resulting in sense data, then 94230557Sjimharris * SATI will call sati_cb_set_status() and pass the scsi_io 95230557Sjimharris * pointer as a parameter. 96230557Sjimharris * @param[out] ata_io This parameter specifies the location of the 97230557Sjimharris * ATA register FIS into which the translator can write the 98230557Sjimharris * resultant ATA command if translation is successful. This 99230557Sjimharris * parameter is passed back to the user through the 100230557Sjimharris * SATI_SATA_CALLBACKS when it is necessary to write fields 101230557Sjimharris * in the ata_io. 102230557Sjimharris * 103230557Sjimharris * @return None 104230557Sjimharris */ 105230557Sjimharrisvoid sati_sequence_terminate( 106230557Sjimharris SATI_TRANSLATOR_SEQUENCE_T * sequence, 107230557Sjimharris void * scsi_io, 108230557Sjimharris void * ata_io 109230557Sjimharris); 110230557Sjimharris 111230557Sjimharris/** 112230557Sjimharris * @brief This method translates the supplied SCSI command into a 113230557Sjimharris * corresponding ATA command. 114230557Sjimharris * 115230557Sjimharris * @param[in] sequence This parameter specifies the sequence 116230557Sjimharris * data associated with the translation. 117230557Sjimharris * @param[in] sati_device This parameter specifies the remote device 118230557Sjimharris * for which the translated request is destined. 119230557Sjimharris * @param[in,out] scsi_io This parameter specifies the user's SCSI IO request 120230557Sjimharris * object. SATI expects that the user can access the SCSI CDB, 121230557Sjimharris * response, and data from this pointer. For example, if there 122230557Sjimharris * is a failure in translation resulting in sense data, then 123230557Sjimharris * SATI will call sati_cb_set_status() and pass the scsi_io 124230557Sjimharris * pointer as a parameter. 125230557Sjimharris * @param[out] ata_io This parameter specifies the location of the 126230557Sjimharris * ATA register FIS into which the translator can write the 127230557Sjimharris * resultant ATA command if translation is successful. This 128230557Sjimharris * parameter is passed back to the user through the 129230557Sjimharris * SATI_SATA_CALLBACKS when it is necessary to write fields 130230557Sjimharris * in the ata_io. 131230557Sjimharris * 132230557Sjimharris * @return Indicate if the translation was successful. 133230557Sjimharris * @retval SATI_SUCCESS 134230557Sjimharris * @retval SATI_FAILURE_CHECK_RESPONSE_DATA 135230557Sjimharris */ 136230557SjimharrisSATI_STATUS sati_translate_command( 137230557Sjimharris SATI_TRANSLATOR_SEQUENCE_T * sequence, 138230557Sjimharris SATI_DEVICE_T * sati_device, 139230557Sjimharris void * scsi_io, 140230557Sjimharris void * ata_io 141230557Sjimharris); 142230557Sjimharris 143230557Sjimharris/** 144230557Sjimharris * @brief This method translates the supplied SCSI task management request 145230557Sjimharris * into a corresponding ATA command/control FIS. 146230557Sjimharris * 147230557Sjimharris * @param[in] sequence This parameter specifies the sequence 148230557Sjimharris * data associated with the translation. 149230557Sjimharris * @param[in] sati_device This parameter specifies the remote device 150230557Sjimharris * for which the translated request is destined. 151230557Sjimharris * @param[in,out] scsi_io This parameter specifies the user's SCSI IO request 152230557Sjimharris * object. SATI expects that the user can access the SCSI CDB, 153230557Sjimharris * response, and data from this pointer. For example, if there 154230557Sjimharris * is a failure in translation resulting in sense data, then 155230557Sjimharris * SATI will call sati_cb_set_status() and pass the scsi_io 156230557Sjimharris * pointer as a parameter. 157230557Sjimharris * @param[out] ata_io This parameter specifies the location of the 158230557Sjimharris * ATA register FIS into which the translator can write the 159230557Sjimharris * resultant ATA command if translation is successful. This 160230557Sjimharris * parameter is passed back to the user through the 161230557Sjimharris * SATI_SATA_CALLBACKS when it is necessary to write fields 162230557Sjimharris * in the ata_io. 163230557Sjimharris * 164230557Sjimharris * @return Indicate if the translation was successful. 165230557Sjimharris * @retval SATI_SUCCESS 166230557Sjimharris * @retval SATI_FAILURE_CHECK_RESPONSE_DATA 167230557Sjimharris */ 168230557SjimharrisSATI_STATUS sati_translate_task_management( 169230557Sjimharris SATI_TRANSLATOR_SEQUENCE_T * sequence, 170230557Sjimharris SATI_DEVICE_T * sati_device, 171230557Sjimharris void * scsi_task, 172230557Sjimharris void * ata_io 173230557Sjimharris); 174230557Sjimharris 175230557Sjimharris/** 176230557Sjimharris * @brief This method translates the supplied ATA response into the 177230557Sjimharris * corresponding SCSI command response. 178230557Sjimharris * 179230557Sjimharris * @param[in] sequence This parameter specifies the sequence 180230557Sjimharris * data associated with the translation. 181230557Sjimharris * @param[out] scsi_io This parameter specifies the user's SCSI IO request 182230557Sjimharris * object. SATI expects that the user can access the SCSI CDB, 183230557Sjimharris * response, and data from this pointer. For example, if there 184230557Sjimharris * is a failure in translation resulting in sense data, then 185230557Sjimharris * SATI will call sati_cb_set_status() and pass the scsi_io 186230557Sjimharris * pointer as a parameter. 187230557Sjimharris * @param[out] ata_io This parameter specifies the location of the 188230557Sjimharris * ATA IO request (e.g. register FIS, PIO Setup etc.) from which 189230557Sjimharris * the translator can read the received ATA status and error 190230557Sjimharris * fields. 191230557Sjimharris * 192230557Sjimharris * @return Indicate if the translation was successful. 193230557Sjimharris * @retval SATI_SUCCESS 194230557Sjimharris * @retval SATI_FAILURE_CHECK_RESPONSE_DATA 195230557Sjimharris */ 196230557SjimharrisSATI_STATUS sati_translate_command_response( 197230557Sjimharris SATI_TRANSLATOR_SEQUENCE_T * sequence, 198230557Sjimharris void * scsi_io, 199230557Sjimharris void * ata_io 200230557Sjimharris); 201230557Sjimharris 202230557Sjimharris/** 203230557Sjimharris * @brief This method translates the supplied ATA response into the 204230557Sjimharris * corresponding SCSI task response. 205230557Sjimharris * 206230557Sjimharris * @param[in] sequence This parameter specifies the sequence 207230557Sjimharris * data associated with the translation. 208230557Sjimharris * @param[out] scsi_io This parameter specifies the user's SCSI IO request 209230557Sjimharris * object. SATI expects that the user can access the SCSI CDB, 210230557Sjimharris * response, and data from this pointer. For example, if there 211230557Sjimharris * is a failure in translation resulting in sense data, then 212230557Sjimharris * SATI will call sati_cb_set_status() and pass the scsi_io 213230557Sjimharris * pointer as a parameter. 214230557Sjimharris * @param[out] ata_io This parameter specifies the location of the 215230557Sjimharris * ATA IO request (e.g. register FIS, PIO Setup etc.) from which 216230557Sjimharris * the translator can read the received ATA status and error 217230557Sjimharris * fields. 218230557Sjimharris * 219230557Sjimharris * @return Indicate if the translation was successful. 220230557Sjimharris * @retval SATI_FAILURE_CHECK_RESPONSE_DATA 221230557Sjimharris */ 222230557SjimharrisSATI_STATUS sati_translate_task_response( 223230557Sjimharris SATI_TRANSLATOR_SEQUENCE_T * sequence, 224230557Sjimharris void * scsi_io, 225230557Sjimharris void * ata_io 226230557Sjimharris); 227230557Sjimharris 228230557Sjimharris/** 229230557Sjimharris * @brief This method simply returns the SAT major compliance version number 230230557Sjimharris * for which the implementation is compliant. 231230557Sjimharris * 232230557Sjimharris * @return Return the specification identifier with which this translator 233230557Sjimharris * is compliant. 234230557Sjimharris */ 235230557SjimharrisU32 sati_get_sat_compliance_version( 236230557Sjimharris void 237230557Sjimharris); 238230557Sjimharris 239230557Sjimharris/** 240230557Sjimharris * @brief This method simply returns the SAT version revision identifier 241230557Sjimharris * for which the implementation is compliant. 242230557Sjimharris * 243230557Sjimharris * @return Return the specification revision identifier with which this 244230557Sjimharris * translator is compliant. 245230557Sjimharris */ 246230557SjimharrisU32 sati_get_sat_compliance_version_revision( 247230557Sjimharris void 248230557Sjimharris); 249230557Sjimharris 250230557Sjimharris/** 251230557Sjimharris* @brief This method returns the number of data bytes written 252230557Sjimharris* by the translation sequence. 253230557Sjimharris* 254230557Sjimharris* @param[in] sequence This parameter specifies the sequence data 255230557Sjimharris* associated with the translation. 256230557Sjimharris* 257230557Sjimharris* @return Return the U16 number_data_bytes_set in the 258230557Sjimharris* SATI_TRANSLATOR_SEQUENCE. 259230557Sjimharris*/ 260230557SjimharrisU16 sati_get_number_data_bytes_set( 261230557Sjimharris SATI_TRANSLATOR_SEQUENCE_T * sequence 262230557Sjimharris); 263230557Sjimharris 264230557Sjimharrisvoid sati_translate_error( 265230557Sjimharris SATI_TRANSLATOR_SEQUENCE_T * sequence, 266230557Sjimharris void * scsi_io, 267230557Sjimharris U8 error 268230557Sjimharris); 269230557Sjimharris 270230557Sjimharris#endif // _SATI_H_ 271230557Sjimharris 272