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 _SCIC_IO_REQUEST_H_ 55230557Sjimharris#define _SCIC_IO_REQUEST_H_ 56230557Sjimharris 57230557Sjimharris/** 58230557Sjimharris * @file 59230557Sjimharris * 60230557Sjimharris * @brief This file contains the structures and interface methods that 61230557Sjimharris * can be referenced and used by the SCI user for the SCI IO request 62230557Sjimharris * object. 63230557Sjimharris * 64230557Sjimharris * @todo Determine the failure situations and return values. 65230557Sjimharris */ 66230557Sjimharris 67230557Sjimharris#ifdef __cplusplus 68230557Sjimharrisextern "C" { 69230557Sjimharris#endif // __cplusplus 70230557Sjimharris 71230557Sjimharris#include <dev/isci/scil/sci_types.h> 72230557Sjimharris#include <dev/isci/scil/sci_status.h> 73230557Sjimharris#include <dev/isci/scil/intel_sas.h> 74230557Sjimharris 75230557Sjimharris/** 76230557Sjimharris * @struct SCIC_IO_SSP_PARAMETERS 77230557Sjimharris * @brief This structure contains additional optional parameters for SSP 78230557Sjimharris * IO requests. These parameters are utilized with the 79230557Sjimharris * scic_io_request_construct_advanced_ssp() method. 80230557Sjimharris * 81230557Sjimharris * @todo Add Block-guard/DIF, TLR 82230557Sjimharris */ 83230557Sjimharristypedef struct SCIC_IO_SSP_PARAMETERS 84230557Sjimharris{ 85230557Sjimharris /** 86230557Sjimharris * Data Integrity Format (DIF) is also known as protection information 87230557Sjimharris * or block-guard. This sub-structure contains DIF specific feature 88230557Sjimharris * information for SSP IO requests. 89230557Sjimharris */ 90230557Sjimharris struct 91230557Sjimharris { 92230557Sjimharris void * placeholder; 93230557Sjimharris } dif; 94230557Sjimharris 95230557Sjimharris /** 96230557Sjimharris * Transport Layer Retries (TLR) is an SSP protocol specific feature. 97230557Sjimharris * This sub-structure contains Transport Layer Retries (TLR) specific 98230557Sjimharris * feature information for SSP IO requests. 99230557Sjimharris */ 100230557Sjimharris struct 101230557Sjimharris { 102230557Sjimharris void * placeholder; 103230557Sjimharris } tlr; 104230557Sjimharris 105230557Sjimharris} SCIC_IO_SSP_PARAMETERS_T; 106230557Sjimharris 107230557Sjimharris/** 108230557Sjimharris * @struct SCIC_IO_PARAMETERS 109230557Sjimharris * @brief This structure contains additional optional parameters for 110230557Sjimharris * STP/SATA IO requests. These parameters are utilized with the 111230557Sjimharris * scic_io_request_construct_advanced_sata() method. 112230557Sjimharris */ 113230557Sjimharristypedef struct SCIC_IO_SATA_PARAMETERS 114230557Sjimharris{ 115230557Sjimharris /** 116230557Sjimharris * This field indicates whether or not to construct the Scatter-Gather 117230557Sjimharris * List elements for the SATA request. This is used in scenarios 118230557Sjimharris * where Scatter-gather-list processing/translation is done by the 119230557Sjimharris * user. 120230557Sjimharris */ 121230557Sjimharris BOOL do_translate_sgl; 122230557Sjimharris 123230557Sjimharris} SCIC_IO_SATA_PARAMETERS_T; 124230557Sjimharris 125230557Sjimharris/** 126230557Sjimharris * @struct SCIC_PASSTHRU_REQUEST_CALLBACKS 127230557Sjimharris * @brief This structure contains the pointer to the callback functions 128230557Sjimharris * for constructing the passthrough request common to SSP, SMP and STP. 129230557Sjimharris * This structure must be set by the win sci layer before the passthrough 130230557Sjimharris * build is called 131230557Sjimharris * 132230557Sjimharris */ 133230557Sjimharristypedef struct SCIC_PASSTHRU_REQUEST_CALLBACKS 134230557Sjimharris{ 135230557Sjimharris /** 136230557Sjimharris * Function pointer to get the phy identifier for passthrough request. 137230557Sjimharris */ 138230557Sjimharris U32 (*scic_cb_passthru_get_phy_identifier) ( void * , U8 *); 139230557Sjimharris /** 140230557Sjimharris * Function pointer to get the port identifier for passthrough request. 141230557Sjimharris */ 142230557Sjimharris U32 (*scic_cb_passthru_get_port_identifier) ( void * , U8 *); 143230557Sjimharris /** 144230557Sjimharris * Function pointer to get the connection rate for passthrough request. 145230557Sjimharris */ 146230557Sjimharris U32 (*scic_cb_passthru_get_connection_rate) ( void * , void *); 147230557Sjimharris /** 148230557Sjimharris * Function pointer to get the destination sas address for passthrough request. 149230557Sjimharris */ 150230557Sjimharris void (*scic_cb_passthru_get_destination_sas_address) (void *, U8 **); 151230557Sjimharris /** 152230557Sjimharris * Function pointer to get the transfer length for passthrough request. 153230557Sjimharris */ 154230557Sjimharris U32 (*scic_cb_passthru_get_transfer_length) (void *); 155230557Sjimharris /** 156230557Sjimharris * Function pointer to get the data direction for passthrough request. 157230557Sjimharris */ 158230557Sjimharris U32 (*scic_cb_passthru_get_data_direction) (void *); 159230557Sjimharris 160230557Sjimharris} SCIC_PASSTHRU_REQUEST_CALLBACKS_T; 161230557Sjimharris 162230557Sjimharris/** 163230557Sjimharris * @struct SCIC_SSP_PASSTHRU_REQUEST_CALLBACKS 164230557Sjimharris * @brief This structure contains the pointer to the callback functions 165230557Sjimharris * for constructing the passthrough request specific to SSP. 166230557Sjimharris * This structure must be set by the win sci layer before the passthrough 167230557Sjimharris * build is called 168230557Sjimharris * 169230557Sjimharris */ 170230557Sjimharristypedef struct SCIC_SSP_PASSTHRU_REQUEST_CALLBACKS 171230557Sjimharris{ 172230557Sjimharris /** 173230557Sjimharris * Common callbacks for all Passthru requests 174230557Sjimharris */ 175230557Sjimharris SCIC_PASSTHRU_REQUEST_CALLBACKS_T common_callbacks; 176230557Sjimharris /** 177230557Sjimharris * Function pointer to get the lun for passthrough request. 178230557Sjimharris */ 179230557Sjimharris void (* scic_cb_ssp_passthru_get_lun) (void *, U8 **); 180230557Sjimharris /** 181230557Sjimharris * Function pointer to get the cdb 182230557Sjimharris */ 183230557Sjimharris void (* scic_cb_ssp_passthru_get_cdb) ( void *, U32 *, U8 **, U32 *, U8 ** ); 184230557Sjimharris /** 185230557Sjimharris * Function pointer to get the task attribute for passthrough request. 186230557Sjimharris */ 187230557Sjimharris U32 (*scic_cb_ssp_passthru_get_task_attribute) (void *); 188230557Sjimharris} SCIC_SSP_PASSTHRU_REQUEST_CALLBACKS_T; 189230557Sjimharris 190230557Sjimharris/** 191230557Sjimharris * @struct SCIC_STP_PASSTHRU_REQUEST_CALLBACKS 192230557Sjimharris * @brief This structure contains the pointer to the callback functions 193230557Sjimharris * for constructing the passthrough request specific to STP. 194230557Sjimharris * This structure must be set by the win sci layer before the passthrough 195230557Sjimharris * build is called 196230557Sjimharris * 197230557Sjimharris */ 198230557Sjimharristypedef struct SCIC_STP_PASSTHRU_REQUEST_CALLBACKS 199230557Sjimharris{ 200230557Sjimharris /** 201230557Sjimharris * Common callbacks for all Passthru requests 202230557Sjimharris */ 203230557Sjimharris SCIC_PASSTHRU_REQUEST_CALLBACKS_T common_callbacks; 204230557Sjimharris /** 205230557Sjimharris * Function pointer to get the protocol for passthrough request. 206230557Sjimharris */ 207230557Sjimharris U8 (* scic_cb_stp_passthru_get_protocol) (void *); 208230557Sjimharris /** 209230557Sjimharris * Function pointer to get the resgister fis 210230557Sjimharris */ 211230557Sjimharris void (* scic_cb_stp_passthru_get_register_fis) ( void *, U8 ** ); 212230557Sjimharris /** 213230557Sjimharris * Function pointer to get the MULTIPLE_COUNT (bits 5,6,7 in Byte 1 in the SAT-specific SCSI extenstion in ATA Pass-through (0x85)) 214230557Sjimharris */ 215230557Sjimharris U8 (* scic_cb_stp_passthru_get_multiplecount) ( void *); 216230557Sjimharris /** 217230557Sjimharris * Function pointer to get the EXTEND (bit 0 in Byte 1 the SAT-specific SCSI extenstion in ATA Pass-through (0x85)) 218230557Sjimharris */ 219230557Sjimharris U8 (* scic_cb_stp_passthru_get_extend) ( void *); 220230557Sjimharris /** 221230557Sjimharris * Function pointer to get the CK_COND (bit 5 in Byte 2 the SAT-specific SCSI extenstion in ATA Pass-through (0x85)) 222230557Sjimharris */ 223230557Sjimharris U8 (* scic_cb_stp_passthru_get_ckcond) ( void *); 224230557Sjimharris /** 225230557Sjimharris * Function pointer to get the T_DIR (bit 3 in Byte 2 the SAT-specific SCSI extenstion in ATA Pass-through (0x85)) 226230557Sjimharris */ 227230557Sjimharris U8 (* scic_cb_stp_passthru_get_tdir) ( void *); 228230557Sjimharris /** 229230557Sjimharris * Function pointer to get the BYTE_BLOCK (bit 2 in Byte 2 the SAT-specific SCSI extenstion in ATA Pass-through (0x85)) 230230557Sjimharris */ 231230557Sjimharris U8 (* scic_cb_stp_passthru_get_byteblock) ( void *); 232230557Sjimharris /** 233230557Sjimharris * Function pointer to get the T_LENGTH (bits 0,1 in Byte 2 the SAT-specific SCSI extenstion in ATA Pass-through (0x85)) 234230557Sjimharris */ 235230557Sjimharris U8 (* scic_cb_stp_passthru_get_tlength) ( void *); 236230557Sjimharris 237230557Sjimharris} SCIC_STP_PASSTHRU_REQUEST_CALLBACKS_T; 238230557Sjimharris 239230557Sjimharris/** 240230557Sjimharris * @struct SCIC_SMP_PASSTHRU_REQUEST_CALLBACKS 241230557Sjimharris * @brief This structure contains the pointer to the callback functions 242230557Sjimharris * for constructing the passthrough request specific to SMP. 243230557Sjimharris * This structure must be set by the win sci layer before the passthrough 244230557Sjimharris * build is called 245230557Sjimharris * 246230557Sjimharris */ 247230557Sjimharristypedef struct SCIC_SMP_PASSTHRU_REQUEST_CALLBACKS 248230557Sjimharris{ 249230557Sjimharris /** 250230557Sjimharris * Common callbacks for all Passthru requests 251230557Sjimharris */ 252230557Sjimharris SCIC_PASSTHRU_REQUEST_CALLBACKS_T common_callbacks; 253230557Sjimharris 254230557Sjimharris /** 255230557Sjimharris * Function pointer to get the length of the smp request and its length 256230557Sjimharris */ 257230557Sjimharris U32 (* scic_cb_smp_passthru_get_request) ( void *, U8 ** ); 258230557Sjimharris /** 259230557Sjimharris * Function pointer to get the frame type of the smp request 260230557Sjimharris */ 261230557Sjimharris U8 (* scic_cb_smp_passthru_get_frame_type) ( void *); 262230557Sjimharris /** 263240518Seadler * Function pointer to get the function in the smp request 264230557Sjimharris */ 265230557Sjimharris U8 (* scic_cb_smp_passthru_get_function) ( void * ); 266230557Sjimharris 267230557Sjimharris /** 268240518Seadler * Function pointer to get the "allocated response length" in the smp request 269230557Sjimharris */ 270230557Sjimharris U8 (* scic_cb_smp_passthru_get_allocated_response_length) ( void * ); 271230557Sjimharris 272230557Sjimharris} SCIC_SMP_PASSTHRU_REQUEST_CALLBACKS_T; 273230557Sjimharris 274230557Sjimharris/** 275230557Sjimharris * @brief This enumeration specifies the transport protocol utilized 276230557Sjimharris * for the request. 277230557Sjimharris */ 278230557Sjimharristypedef enum 279230557Sjimharris{ 280230557Sjimharris /** 281230557Sjimharris * This enumeration constant indicates that no protocol has yet been 282230557Sjimharris * set. 283230557Sjimharris */ 284230557Sjimharris SCIC_NO_PROTOCOL, 285230557Sjimharris 286230557Sjimharris /** 287230557Sjimharris * This enumeration constant indicates that the protocol utilized 288230557Sjimharris * is the Serial Management Protocol. 289230557Sjimharris */ 290230557Sjimharris SCIC_SMP_PROTOCOL, 291230557Sjimharris 292230557Sjimharris /** 293230557Sjimharris * This enumeration constant indicates that the protocol utilized 294230557Sjimharris * is the Serial SCSI Protocol. 295230557Sjimharris */ 296230557Sjimharris SCIC_SSP_PROTOCOL, 297230557Sjimharris 298230557Sjimharris /** 299230557Sjimharris * This enumeration constant indicates that the protocol utilized 300230557Sjimharris * is the Serial-ATA Tunneling Protocol. 301230557Sjimharris */ 302230557Sjimharris SCIC_STP_PROTOCOL 303230557Sjimharris 304230557Sjimharris} SCIC_TRANSPORT_PROTOCOL; 305230557Sjimharris 306230557Sjimharris 307230557Sjimharris/** 308230557Sjimharris * @brief This method simply returns the size required to build an SCI 309230557Sjimharris * based IO request object. 310230557Sjimharris * 311230557Sjimharris * @return Return the size of the SCI IO request object. 312230557Sjimharris */ 313230557SjimharrisU32 scic_io_request_get_object_size( 314230557Sjimharris void 315230557Sjimharris); 316230557Sjimharris 317230557Sjimharris/** 318230557Sjimharris * @brief This method is called by the SCI user to construct all SCI Core 319230557Sjimharris * IO requests. Memory initialization and functionality common to 320230557Sjimharris * all IO request types is performed in this method. 321230557Sjimharris * 322230557Sjimharris * @note The SCI core implementation will create an association between 323230557Sjimharris * the user IO request object and the core IO request object. 324230557Sjimharris * 325230557Sjimharris * @param[in] scic_controller the handle to the core controller object 326230557Sjimharris * for which to build an IO request. 327230557Sjimharris * @param[in] scic_remote_device the handle to the core remote device 328230557Sjimharris * object for which to build an IO request. 329230557Sjimharris * @param[in] io_tag This parameter specifies the IO tag to be associated 330230557Sjimharris * with this request. If SCI_CONTROLLER_INVALID_IO_TAG is 331230557Sjimharris * passed, then a copy of the request is built internally. The 332230557Sjimharris * request will be copied into the actual controller request 333230557Sjimharris * memory when the IO tag is allocated internally during the 334230557Sjimharris * scic_controller_start_io() method. 335230557Sjimharris * @param[in] user_io_request_object This parameter specifies the user 336230557Sjimharris * IO request to be utilized during IO construction. This IO 337230557Sjimharris * pointer will become the associated object for the core 338230557Sjimharris * IO request object. 339230557Sjimharris * @param[in] scic_io_request_memory This parameter specifies the memory 340230557Sjimharris * location to be utilized when building the core request. 341230557Sjimharris * @param[out] new_scic_io_request_handle This parameter specifies a 342230557Sjimharris * pointer to the handle the core will expect in further 343230557Sjimharris * interactions with the core IO request object. 344230557Sjimharris * 345230557Sjimharris * @return Indicate if the controller successfully built the IO request. 346230557Sjimharris * @retval SCI_SUCCESS This value is returned if the IO request was 347230557Sjimharris * successfully built. 348230557Sjimharris */ 349230557SjimharrisSCI_STATUS scic_io_request_construct( 350230557Sjimharris SCI_CONTROLLER_HANDLE_T scic_controller, 351230557Sjimharris SCI_REMOTE_DEVICE_HANDLE_T scic_remote_device, 352230557Sjimharris U16 io_tag, 353230557Sjimharris void * user_io_request_object, 354230557Sjimharris void * scic_io_request_memory, 355230557Sjimharris SCI_IO_REQUEST_HANDLE_T * new_scic_io_request_handle 356230557Sjimharris); 357230557Sjimharris 358230557Sjimharris/** 359230557Sjimharris * @brief This method is called by the SCI user to build an SSP 360230557Sjimharris * IO request. 361230557Sjimharris * 362230557Sjimharris * @pre 363230557Sjimharris * - The user must have previously called scic_io_request_construct() 364230557Sjimharris * on the supplied IO request. 365230557Sjimharris * 366230557Sjimharris * @param[in] scic_io_request This parameter specifies the handle to the 367230557Sjimharris * io request object to be built. 368230557Sjimharris * 369230557Sjimharris * @return Indicate if the controller successfully built the IO request. 370230557Sjimharris * @retval SCI_SUCCESS This value is returned if the IO request was 371230557Sjimharris * successfully built. 372230557Sjimharris * @retval SCI_FAILURE_UNSUPPORTED_PROTOCOL This value is returned if the 373230557Sjimharris * remote_device does not support the SSP protocol. 374230557Sjimharris * @retval SCI_FAILURE_INVALID_ASSOCIATION This value is returned if the 375230557Sjimharris * user did not properly set the association between the SCIC IO 376230557Sjimharris * request and the user's IO request. Please refer to the 377230557Sjimharris * sci_object_set_association() routine for more 378230557Sjimharris * information. 379230557Sjimharris */ 380230557SjimharrisSCI_STATUS scic_io_request_construct_basic_ssp( 381230557Sjimharris SCI_IO_REQUEST_HANDLE_T scic_io_request 382230557Sjimharris); 383230557Sjimharris 384230557Sjimharris/** 385230557Sjimharris * @brief This method is called by the SCI user to build an SSP 386230557Sjimharris * IO request with additional parameters that provide additional 387230557Sjimharris * flexibility from the standard scic_io_request_construct_basic_ssp() 388230557Sjimharris * method. 389230557Sjimharris * 390230557Sjimharris * @pre 391230557Sjimharris * - The user must have previously called scic_io_request_construct() 392230557Sjimharris * on the supplied IO request. 393230557Sjimharris * 394230557Sjimharris * @param[in] scic_io_request This parameter specifies the handle to the 395230557Sjimharris * io request object to be built. 396230557Sjimharris * @param[in] io_parameters the additional parameter information to 397230557Sjimharris * be added to the outgoing IO request. 398230557Sjimharris * 399230557Sjimharris * @return Indicate if the controller successfully built the IO request. 400230557Sjimharris * @retval SCI_SUCCESS This value is returned if the IO request was 401230557Sjimharris * successfully built. 402230557Sjimharris * @retval SCI_FAILURE_UNSUPPORTED_PROTOCOL This value is returned if the 403230557Sjimharris * remote_device does not support the SSP protocol. 404230557Sjimharris * @retval SCI_FAILURE_INVALID_ASSOCIATION This value is returned if the 405230557Sjimharris * user did not properly set the association between the SCIC IO 406230557Sjimharris * request and the user's IO request. Please refer to the 407230557Sjimharris * sci_object_set_association() routine for more 408230557Sjimharris * information. 409230557Sjimharris * 410230557Sjimharris * @todo Determine the failure situations and return values. 411230557Sjimharris */ 412230557SjimharrisSCI_STATUS scic_io_request_construct_advanced_ssp( 413230557Sjimharris SCI_IO_REQUEST_HANDLE_T scic_io_request, 414230557Sjimharris SCIC_IO_SSP_PARAMETERS_T * io_parameters 415230557Sjimharris); 416230557Sjimharris 417230557Sjimharris#if !defined(DISABLE_PASS_THROUGH) 418230557Sjimharris 419230557Sjimharris/** 420230557Sjimharris * @brief This method will build an IO request based on the user information 421230557Sjimharris * supplied in the pass-through IO request object. 422230557Sjimharris * 423230557Sjimharris * @param[in] scic_io_request This parameter specifies the handle to the 424230557Sjimharris * io request object to be built. 425230557Sjimharris * 426230557Sjimharris * @param[in] ssp_passthru_cb This parameter specifies the pointer to 427230557Sjimharris * the structure containing the callback to the function 428230557Sjimharris * pointers to get the needed fields from the pass-through 429230557Sjimharris * reqiest instead of SRB 430230557Sjimharris * 431230557Sjimharris * @return Indicate if the controller successfully built the IO request. 432230557Sjimharris * @retval SCI_SUCCESS This value is returned if the IO request was 433230557Sjimharris * successfully built. 434230557Sjimharris * @retval SCI_FAILURE_INVALID_ASSOCIATION This value is returned if the 435230557Sjimharris * user did not properly set the association between the SCIC IO 436230557Sjimharris * request and the user's IO request. Please refer to the 437230557Sjimharris * sci_object_set_association() routine for more 438230557Sjimharris * information. 439230557Sjimharris */ 440230557SjimharrisSCI_STATUS scic_io_request_construct_ssp_pass_through( 441230557Sjimharris void * scic_io_request_memory, 442230557Sjimharris SCIC_SSP_PASSTHRU_REQUEST_CALLBACKS_T *ssp_passthru_cb 443230557Sjimharris); 444230557Sjimharris 445230557Sjimharris#else // !defined(DISABLE_PASS_THROUGH) 446230557Sjimharris 447230557Sjimharris#define scic_io_request_construct_ssp_pass_through(memory, cb) SCI_FAILURE 448230557Sjimharris 449230557Sjimharris#endif // !defined(DISABLE_PASS_THROUGH) 450230557Sjimharris 451230557Sjimharris/** 452230557Sjimharris * @brief This method is called by the SCI Core user to build an STP 453230557Sjimharris * IO request. 454230557Sjimharris * 455230557Sjimharris * @pre 456230557Sjimharris * - The user must have previously called scic_io_request_construct() 457230557Sjimharris * on the supplied IO request. 458230557Sjimharris * 459230557Sjimharris * @param[in] scic_io_request This parameter specifies the handle to the 460230557Sjimharris * io request object to be built. 461230557Sjimharris * 462230557Sjimharris * @return Indicate if the controller successfully built the IO request. 463230557Sjimharris * @retval SCI_SUCCESS This value is returned if the IO request was 464230557Sjimharris * successfully built. 465230557Sjimharris * @retval SCI_FAILURE_UNSUPPORTED_PROTOCOL This value is returned if the 466230557Sjimharris * remote_device does not support the STP protocol. 467230557Sjimharris * @retval SCI_FAILURE_INVALID_ASSOCIATION This value is returned if the 468230557Sjimharris * user did not properly set the association between the SCIC IO 469230557Sjimharris * request and the user's IO request. Please refer to the 470230557Sjimharris * sci_object_set_association() routine for more 471230557Sjimharris * information. 472230557Sjimharris */ 473230557SjimharrisSCI_STATUS scic_io_request_construct_basic_sata( 474230557Sjimharris SCI_IO_REQUEST_HANDLE_T scic_io_request 475230557Sjimharris); 476230557Sjimharris 477230557Sjimharris/** 478230557Sjimharris * @brief This method is called by the SCI Core user to build an STP 479230557Sjimharris * IO request. 480230557Sjimharris * 481230557Sjimharris * @pre 482230557Sjimharris * - The user must have previously called scic_io_request_construct() 483230557Sjimharris * on the supplied IO request. 484230557Sjimharris * 485230557Sjimharris * @param[in] scic_io_request This parameter specifies the handle to the 486230557Sjimharris * io request object to be built. 487230557Sjimharris * 488230557Sjimharris * @return Indicate if the controller successfully built the IO request. 489230557Sjimharris * @retval SCI_SUCCESS This value is returned if the IO request was 490230557Sjimharris * successfully built. 491230557Sjimharris * @retval SCI_FAILURE_UNSUPPORTED_PROTOCOL This value is returned if the 492230557Sjimharris * remote_device does not support the STP protocol. 493230557Sjimharris * @retval SCI_FAILURE_INVALID_ASSOCIATION This value is returned if the 494230557Sjimharris * user did not properly set the association between the SCIC IO 495230557Sjimharris * request and the user's IO request. Please refer to the 496230557Sjimharris * sci_object_set_association() routine for more 497230557Sjimharris * information. 498230557Sjimharris */ 499230557SjimharrisSCI_STATUS scic_io_request_construct_advanced_sata( 500230557Sjimharris SCI_IO_REQUEST_HANDLE_T scic_io_request, 501230557Sjimharris SCIC_IO_SATA_PARAMETERS_T * io_parameters 502230557Sjimharris); 503230557Sjimharris 504230557Sjimharris#if !defined(DISABLE_PASS_THROUGH) 505230557Sjimharris 506230557Sjimharris/** 507230557Sjimharris * @brief This method is called by the SCI user to build an STP pass-through 508230557Sjimharris * IO request. 509230557Sjimharris * 510230557Sjimharris * @pre 511230557Sjimharris * - The user must have previously called scic_io_request_construct() 512230557Sjimharris * on the supplied IO request. 513230557Sjimharris * 514230557Sjimharris * @param[in] scic_io_request This parameter specifies the handle to the 515230557Sjimharris * io request object to be built. 516230557Sjimharris * 517230557Sjimharris * @param[in] passthru_cb This parameter specifies the pointer to the callback 518230557Sjimharris * structure that contains the function pointers 519230557Sjimharris * 520230557Sjimharris * @return Indicate if the controller successfully built the IO request. 521230557Sjimharris */ 522230557SjimharrisSCI_STATUS scic_io_request_construct_sata_pass_through( 523230557Sjimharris SCI_IO_REQUEST_HANDLE_T scic_io_request, 524230557Sjimharris SCIC_STP_PASSTHRU_REQUEST_CALLBACKS_T *passthru_cb 525230557Sjimharris 526230557Sjimharris); 527230557Sjimharris 528230557Sjimharris#else // !defined(DISABLE_PASS_THROUGH) 529230557Sjimharris 530230557Sjimharris#define scic_io_request_construct_sata_pass_through(io, cb) SCI_FAILURE 531230557Sjimharris 532230557Sjimharris#endif // !defined(DISABLE_PASS_THROUGH) 533230557Sjimharris 534230557Sjimharris/** 535230557Sjimharris * @brief This method is called by the SCI user to build an SMP 536230557Sjimharris * IO request. 537230557Sjimharris * 538230557Sjimharris * @pre 539230557Sjimharris * - The user must have previously called scic_io_request_construct() 540230557Sjimharris * on the supplied IO request. 541230557Sjimharris * 542230557Sjimharris * @param[in] scic_io_request This parameter specifies the handle to the 543230557Sjimharris * io request object to be built. 544230557Sjimharris * 545230557Sjimharris * @return Indicate if the controller successfully built the IO request. 546230557Sjimharris * @retval SCI_SUCCESS This value is returned if the IO request was 547230557Sjimharris * successfully built. 548230557Sjimharris * @retval SCI_FAILURE_UNSUPPORTED_PROTOCOL This value is returned if the 549230557Sjimharris * remote_device does not support the SMP protocol. 550230557Sjimharris * @retval SCI_FAILURE_INVALID_ASSOCIATION This value is returned if the 551230557Sjimharris * user did not properly set the association between the SCIC IO 552230557Sjimharris * request and the user's IO request. Please refer to the 553230557Sjimharris * sci_object_set_association() routine for more 554230557Sjimharris * information. 555230557Sjimharris */ 556230557SjimharrisSCI_STATUS scic_io_request_construct_smp( 557230557Sjimharris SCI_IO_REQUEST_HANDLE_T scic_io_request 558230557Sjimharris); 559230557Sjimharris 560230557Sjimharris 561230557Sjimharris/** 562230557Sjimharris * @brief This method is called by the SCI user to build an SMP pass-through 563230557Sjimharris * IO request. 564230557Sjimharris * 565230557Sjimharris * @pre 566230557Sjimharris * - The user must have previously called scic_io_request_construct() 567230557Sjimharris * on the supplied IO request. 568230557Sjimharris * 569230557Sjimharris * @param[in] scic_smp_request This parameter specifies the handle to the 570230557Sjimharris * io request object to be built. 571230557Sjimharris * 572230557Sjimharris * @param[in] passthru_cb This parameter specifies the pointer to the callback 573230557Sjimharris * structure that contains the function pointers 574230557Sjimharris * 575230557Sjimharris * @return Indicate if the controller successfully built the IO request. 576230557Sjimharris */ 577230557SjimharrisSCI_STATUS scic_io_request_construct_smp_pass_through( 578230557Sjimharris SCI_IO_REQUEST_HANDLE_T scic_smp_request, 579230557Sjimharris SCIC_SMP_PASSTHRU_REQUEST_CALLBACKS_T *passthru_cb 580230557Sjimharris); 581230557Sjimharris 582230557Sjimharris/** 583230557Sjimharris * @brief This method returns the controller specific IO/Task request status. 584230557Sjimharris * These status values are unique to the specific controller being 585230557Sjimharris * managed by the SCIC. 586230557Sjimharris * 587230557Sjimharris * @param[in] io_request the handle to the IO or task management request 588230557Sjimharris * object for which to retrieve the status. 589230557Sjimharris * 590230557Sjimharris * @return This method returns a value indicating the controller specific 591230557Sjimharris * request status. 592230557Sjimharris */ 593230557SjimharrisU32 scic_request_get_controller_status( 594230557Sjimharris SCI_IO_REQUEST_HANDLE_T io_request 595230557Sjimharris); 596230557Sjimharris 597230557Sjimharris/** 598230557Sjimharris * @brief This method returns the user specific IO/Task request status. 599230557Sjimharris * 600230557Sjimharris * @param[in] io_request the handle to the IO or task management request 601230557Sjimharris * object for which to retrieve the status. 602230557Sjimharris * 603230557Sjimharris * @return This method returns a value indicating the user specific 604230557Sjimharris * request status. 605230557Sjimharris */ 606230557SjimharrisU32 scic_request_get_sci_status( 607230557Sjimharris SCI_IO_REQUEST_HANDLE_T io_request 608230557Sjimharris); 609230557Sjimharris 610230557Sjimharris 611230557Sjimharris/** 612230557Sjimharris * @brief This method will return the address to the command information 613230557Sjimharris * unit. 614230557Sjimharris * 615230557Sjimharris * @param[in] scic_io_request This parameter specifies the handle to the 616230557Sjimharris * io request object to be built. 617230557Sjimharris * 618230557Sjimharris * @return The address of the SSP/SMP command information unit. 619230557Sjimharris */ 620230557Sjimharrisvoid * scic_io_request_get_command_iu_address( 621230557Sjimharris SCI_IO_REQUEST_HANDLE_T scic_io_request 622230557Sjimharris); 623230557Sjimharris 624230557Sjimharris/** 625230557Sjimharris * @brief This method will return the address to the response information 626230557Sjimharris * unit. For an SSP request this buffer is only valid if the IO 627230557Sjimharris * request is completed with the status SCI_FAILURE_IO_RESPONSE_VALID. 628230557Sjimharris * 629230557Sjimharris * @param[in] scic_io_request This parameter specifies the handle to the 630230557Sjimharris * io request object to be built. 631230557Sjimharris * 632230557Sjimharris * @return The address of the SSP/SMP response information unit. 633230557Sjimharris */ 634230557Sjimharrisvoid * scic_io_request_get_response_iu_address( 635230557Sjimharris SCI_IO_REQUEST_HANDLE_T scic_io_request 636230557Sjimharris); 637230557Sjimharris 638230557Sjimharris/** 639230557Sjimharris * @brief This method will return the IO tag utilized by the IO request. 640230557Sjimharris * 641230557Sjimharris * @param[in] scic_io_request This parameter specifies the handle to the 642230557Sjimharris * io request object for which to return the IO tag. 643230557Sjimharris * 644230557Sjimharris * @return An unsigned integer representing the IO tag being utilized. 645230557Sjimharris * @retval SCI_CONTROLLER_INVALID_IO_TAG This value is returned if the IO 646230557Sjimharris * does not currently have an IO tag allocated to it. 647230557Sjimharris * @retval All return other values indicate a legitimate tag. 648230557Sjimharris */ 649230557SjimharrisU16 scic_io_request_get_io_tag( 650230557Sjimharris SCI_IO_REQUEST_HANDLE_T scic_io_request 651230557Sjimharris); 652230557Sjimharris 653230557Sjimharris/** 654230557Sjimharris * @brief This method will inform the user of the protocol with which 655230557Sjimharris * the supplied IO request was created. 656230557Sjimharris * 657230557Sjimharris * @param[in] scic_io_request This parameter specifies the IO request 658230557Sjimharris * for which to retrieve the protocol. 659230557Sjimharris * 660230557Sjimharris * @return This method returns the transport protocol utilized for the 661230557Sjimharris * the supplied request. Please refer to SCIC_TRANSPORT_PROTOCOL 662230557Sjimharris * for more information. 663230557Sjimharris */ 664230557SjimharrisSCIC_TRANSPORT_PROTOCOL scic_io_request_get_protocol( 665230557Sjimharris SCI_IO_REQUEST_HANDLE_T scic_io_request 666230557Sjimharris); 667230557Sjimharris 668230557Sjimharris/** 669230557Sjimharris * @brief This method will assign an NCQ tag to the io request object. The 670230557Sjimharris * caller of this function must make sure that only valid NCQ tags are 671230557Sjimharris * assigned to the io request object. 672230557Sjimharris * 673230557Sjimharris * @param[in] scic_io_request This parameter specifies the handle to the 674230557Sjimharris * io request object to which to assign the ncq tag. 675230557Sjimharris * @param[in] ncq_tag This parameter specifies the NCQ tag to be utilized 676230557Sjimharris * for the supplied core IO request. It is up to the user to make 677230557Sjimharris * sure that this is a valid NCQ tag. 678230557Sjimharris * 679230557Sjimharris * @return none 680230557Sjimharris * 681230557Sjimharris * @note This function is only valid for SATA NCQ requests. 682230557Sjimharris */ 683230557Sjimharrisvoid scic_stp_io_request_set_ncq_tag( 684230557Sjimharris SCI_IO_REQUEST_HANDLE_T scic_io_request, 685230557Sjimharris U16 ncq_tag 686230557Sjimharris); 687230557Sjimharris 688230557Sjimharris/** 689230557Sjimharris * @brief This method will return the address of the host to device register 690230557Sjimharris * fis region for the io request object. 691230557Sjimharris * 692230557Sjimharris * @param[in] scic_io_request This parameter specifies the handle to the io 693230557Sjimharris * request object from which to get the host to device register fis 694230557Sjimharris * buffer. 695230557Sjimharris * 696230557Sjimharris * @return The address of the host to device register fis buffer in the io 697230557Sjimharris * request object. 698230557Sjimharris * 699230557Sjimharris * @note This function is only valid for SATA requests. 700230557Sjimharris */ 701230557Sjimharrisvoid * scic_stp_io_request_get_h2d_reg_address( 702230557Sjimharris SCI_IO_REQUEST_HANDLE_T scic_io_request 703230557Sjimharris); 704230557Sjimharris 705230557Sjimharris/** 706230557Sjimharris * @brief This method will return the address of the device to host register 707230557Sjimharris * fis region for the io request object. 708230557Sjimharris * 709240520Seadler * @param[in] scic_io_request This parameter specifies the handle to the io 710230557Sjimharris * request object from which to get the device to host register fis 711230557Sjimharris * buffer. 712230557Sjimharris * 713230557Sjimharris * @return The address fo the device to host register fis ending the io 714230557Sjimharris * request. 715230557Sjimharris * 716230557Sjimharris * @note This function is only valid for SATA requests. 717230557Sjimharris */ 718230557Sjimharrisvoid * scic_stp_io_request_get_d2h_reg_address( 719230557Sjimharris SCI_IO_REQUEST_HANDLE_T scic_io_request 720230557Sjimharris); 721230557Sjimharris 722230557Sjimharris/** 723230557Sjimharris * @brief This method will return the rx frame for the io request object that 724230557Sjimharris * contains the given offset. 725230557Sjimharris * 726230557Sjimharris * @param[in] scic_io_request This parameter specifies the handle to the io 727230557Sjimharris * request object which has received the frame data. 728230557Sjimharris * @param[in] offset This parameter specifies which frame is being requested. 729230557Sjimharris * 730230557Sjimharris * @return The return is a pointer to the frame buffer data. 731230557Sjimharris * 732230557Sjimharris * @note Frame buffers are only 1024 bytes in size. Reading past the end of a 733230557Sjimharris * frame will have unexpected results. 734230557Sjimharris */ 735230557Sjimharrisvoid * scic_io_request_get_rx_frame( 736230557Sjimharris SCI_IO_REQUEST_HANDLE_T scic_io_request, 737230557Sjimharris U32 offset 738230557Sjimharris); 739230557Sjimharris 740230557Sjimharris/** 741230557Sjimharris * @brief This method will return the number of bytes transferred from the SCU 742230557Sjimharris * 743230557Sjimharris * @param[in] scic_io_request This parameter specifies the handle to the io request 744230557Sjimharris * whose data length was not eqaul to the data length specified in the request. 745230557Sjimharris * When the driver gets an early io completion status from the hardware, 746230557Sjimharris * this routine should be called to get the actual number of bytes transferred 747230557Sjimharris * 748230557Sjimharris * @return The return is the number of bytes transferred when the data legth is not equal to 749230557Sjimharris * the specified length in the io request 750230557Sjimharris * 751230557Sjimharris */ 752230557SjimharrisU32 scic_io_request_get_number_of_bytes_transferred ( 753230557Sjimharris SCI_IO_REQUEST_HANDLE_T scic_io_request 754230557Sjimharris); 755230557Sjimharris 756230557Sjimharris#ifdef __cplusplus 757230557Sjimharris} 758230557Sjimharris#endif // __cplusplus 759230557Sjimharris 760230557Sjimharris#endif // _SCIC_IO_REQUEST_H_ 761230557Sjimharris 762