drivers/scsi/isci/core/scic_io_request.h

   1 /*
   2  * This file is provided under a dual BSD/GPLv2 license.  When using or
   3  * redistributing this file, you may do so under either license.
   4  *
   5  * GPL LICENSE SUMMARY
   6  *
   7  * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of version 2 of the GNU General Public License as
  11  * published by the Free Software Foundation.
  12  *
  13  * This program is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA.
  21  * The full GNU General Public License is included in this distribution
  22  * in the file called LICENSE.GPL.
  23  *
  24  * BSD LICENSE
  25  *
  26  * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
  27  * All rights reserved.
  28  *
  29  * Redistribution and use in source and binary forms, with or without
  30  * modification, are permitted provided that the following conditions
  31  * are met:
  32  *
  33  *   * Redistributions of source code must retain the above copyright
  34  *     notice, this list of conditions and the following disclaimer.
  35  *   * Redistributions in binary form must reproduce the above copyright
  36  *     notice, this list of conditions and the following disclaimer in
  37  *     the documentation and/or other materials provided with the
  38  *     distribution.
  39  *   * Neither the name of Intel Corporation nor the names of its
  40  *     contributors may be used to endorse or promote products derived
  41  *     from this software without specific prior written permission.
  42  *
  43  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  44  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  45  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  46  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  47  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  48  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  49  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  50  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  51  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  52  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  53  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  54  */
  55
  56 #ifndef _SCIC_IO_REQUEST_H_
  57 #define _SCIC_IO_REQUEST_H_
  58
  59 /**
  60  * This file contains the structures and interface methods that can be
  61  *    referenced and used by the SCI user for the SCI IO request object.
  62  *
  63  * Determine the failure situations and return values.
  64  */
  65
  66
  67 #include "sci_types.h"
  68 #include "sci_status.h"
  69 #include "intel_sas.h"
  70
  71 struct scic_sds_request;
  72 struct scic_sds_remote_device;
  73 struct scic_sds_controller;
  74
  75 /**
  76  * struct scic_io_parameters - This structure contains additional optional
  77  *    parameters for SSP IO requests.  These parameters are utilized with the
  78  *    scic_io_request_construct_advanced_ssp() method.
  79  *
  80  * Add Block-guard/DIF, TLR
  81  */
  82 struct scic_io_parameters {
  83         /**
  84          * This sub-structure contains SCSI specific features (for use with SSP
  85          * IO requests).
  86          */
  87         struct {
  88                 /**
  89                  * Data Integrity Format (DIF) is also known as protection information
  90                  * or block-guard.  This sub-structure contains DIF specific feature
  91                  * information for SSP IO requests.
  92                  */
  93                 struct {
  94                         void *placeholder;
  95                 } dif;
  96
  97                 /**
  98                  * Transport Layer Retries (TLR) is an SSP protocol specific feature.
  99                  * This sub-structure contains Transport Layer Retries (TLR) specific
 100                  * feature information for SSP IO requests.
 101                  */
 102                 struct {
 103                         void *placeholder;
 104                 } tlr;
 105
 106         } scsi;
 107
 108 };
 109
 110 /**
 111  * struct scic_passthru_request_callbacks - This structure contains the pointer
 112  *    to the callback functions for constructing the passthrough request common
 113  *    to SSP, SMP and STP. This structure must be set by the win sci layer
 114  *    before the passthrough build is called
 115  *
 116  *
 117  */
 118 struct scic_passthru_request_callbacks {
 119         /**
 120          * Function pointer to get the phy identifier for passthrough request.
 121          */
 122         u32 (*scic_cb_passthru_get_phy_identifier)(void *, u8 *);
 123         /**
 124          * Function pointer to get the port identifier for passthrough request.
 125          */
 126         u32 (*scic_cb_passthru_get_port_identifier)(void *, u8 *);
 127         /**
 128          * Function pointer to get the connection rate for passthrough request.
 129          */
 130         u32 (*scic_cb_passthru_get_connection_rate)(void *, void *);
 131         /**
 132          * Function pointer to get the destination sas address for passthrough request.
 133          */
 134         void (*scic_cb_passthru_get_destination_sas_address)(void *, u8 **);
 135         /**
 136          * Function pointer to get the transfer length for passthrough request.
 137          */
 138         u32 (*scic_cb_passthru_get_transfer_length)(void *);
 139         /**
 140          * Function pointer to get the data direction for passthrough request.
 141          */
 142         u32 (*scic_cb_passthru_get_data_direction)(void *);
 143
 144 };
 145
 146 /**
 147  * struct scic_ssp_passthru_request_callbacks - This structure contains the
 148  *    pointer to the callback functions for constructing the passthrough
 149  *    request specific to SSP. This structure must be set by the win sci layer
 150  *    before the passthrough build is called
 151  *
 152  *
 153  */
 154 struct scic_ssp_passthru_request_callbacks {
 155         /**
 156          * Common callbacks for all Passthru requests
 157          */
 158         struct scic_passthru_request_callbacks common_callbacks;
 159         /**
 160          * Function pointer to get the lun for passthrough request.
 161          */
 162         void (*scic_cb_ssp_passthru_get_lun)(void *, u8 **);
 163         /**
 164          * Function pointer to get the cdb
 165          */
 166         void (*scic_cb_ssp_passthru_get_cdb)(void *, u32 *, u8 **, u32 *, u8 **);
 167         /**
 168          * Function pointer to get the task attribute for passthrough request.
 169          */
 170         u32 (*scic_cb_ssp_passthru_get_task_attribute)(void *);
 171 };
 172
 173 /**
 174  * struct scic_stp_passthru_request_callbacks - This structure contains the
 175  *    pointer to the callback functions for constructing the passthrough
 176  *    request specific to STP. This structure must be set by the win sci layer
 177  *    before the passthrough build is called
 178  *
 179  *
 180  */
 181 struct scic_stp_passthru_request_callbacks {
 182         /**
 183          * Common callbacks for all Passthru requests
 184          */
 185         struct scic_passthru_request_callbacks common_callbacks;
 186         /**
 187          * Function pointer to get the protocol for passthrough request.
 188          */
 189         u8 (*scic_cb_stp_passthru_get_protocol)(void *);
 190         /**
 191          * Function pointer to get the resgister fis
 192          */
 193         void (*scic_cb_stp_passthru_get_register_fis)(void *, u8 **);
 194         /**
 195          * 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))
 196          */
 197         u8 (*scic_cb_stp_passthru_get_multiplecount)(void *);
 198         /**
 199          * Function pointer to get the EXTEND (bit 0 in Byte 1 the SAT-specific SCSI extenstion in ATA Pass-through (0x85))
 200          */
 201         u8 (*scic_cb_stp_passthru_get_extend)(void *);
 202         /**
 203          * Function pointer to get the CK_COND (bit 5 in Byte 2 the SAT-specific SCSI extenstion in ATA Pass-through (0x85))
 204          */
 205         u8 (*scic_cb_stp_passthru_get_ckcond)(void *);
 206         /**
 207          * Function pointer to get the T_DIR (bit 3 in Byte 2 the SAT-specific SCSI extenstion in ATA Pass-through (0x85))
 208          */
 209         u8 (*scic_cb_stp_passthru_get_tdir)(void *);
 210         /**
 211          * Function pointer to get the BYTE_BLOCK (bit 2 in Byte 2 the SAT-specific SCSI extenstion in ATA Pass-through (0x85))
 212          */
 213         u8 (*scic_cb_stp_passthru_get_byteblock)(void *);
 214         /**
 215          * Function pointer to get the T_LENGTH (bits 0,1 in Byte 2 the SAT-specific SCSI extenstion in ATA Pass-through (0x85))
 216          */
 217         u8 (*scic_cb_stp_passthru_get_tlength)(void *);
 218
 219 };
 220
 221 /**
 222  * struct scic_smp_passthru_request_callbacks - This structure contains the
 223  *    pointer to the callback functions for constructing the passthrough
 224  *    request specific to SMP. This structure must be set by the win sci layer
 225  *    before the passthrough build is called
 226  *
 227  *
 228  */
 229 struct scic_smp_passthru_request_callbacks {
 230         /**
 231          * Common callbacks for all Passthru requests
 232          */
 233         struct scic_passthru_request_callbacks common_callbacks;
 234
 235         /**
 236          * Function pointer to get the length of the smp request and its length
 237          */
 238         u32 (*scic_cb_smp_passthru_get_request)(void *, u8 **);
 239         /**
 240          * Function pointer to get the frame type of the smp request
 241          */
 242         u8 (*scic_cb_smp_passthru_get_frame_type)(void *);
 243         /**
 244          * Function pointer to get the function in the the smp request
 245          */
 246         u8 (*scic_cb_smp_passthru_get_function)(void *);
 247
 248         /**
 249          * Function pointer to get the "allocated response length" in the the smp request
 250          */
 251         u8 (*scic_cb_smp_passthru_get_allocated_response_length)(void *);
 252
 253 };
 254
 255 /**
 256  * This enumeration specifies the transport protocol utilized for the request.
 257  *
 258  *
 259  */
 260 typedef enum {
 261         /**
 262          * This enumeration constant indicates that no protocol has yet been
 263          * set.
 264          */
 265         SCIC_NO_PROTOCOL,
 266
 267         /**
 268          * This enumeration constant indicates that the protocol utilized
 269          * is the Serial Management Protocol.
 270          */
 271         SCIC_SMP_PROTOCOL,
 272
 273         /**
 274          * This enumeration constant indicates that the protocol utilized
 275          * is the Serial SCSI Protocol.
 276          */
 277         SCIC_SSP_PROTOCOL,
 278
 279         /**
 280          * This enumeration constant indicates that the protocol utilized
 281          * is the Serial-ATA Tunneling Protocol.
 282          */
 283         SCIC_STP_PROTOCOL
 284
 285 } SCIC_TRANSPORT_PROTOCOL;
 286
 287
 288 /**
 289  * scic_io_request_get_object_size() - This method simply returns the size
 290  *    required to build an SCI based IO request object.
 291  *
 292  * Return the size of the SCI IO request object.
 293  */
 294 u32 scic_io_request_get_object_size(
 295         void);
 296
 297 /**
 298  * scic_io_request_construct() - This method is called by the SCI user to
 299  *    construct all SCI Core IO requests.  Memory initialization and
 300  *    functionality common to all IO request types is performed in this method.
 301  * @scic_controller: the handle to the core controller object for which to
 302  *    build an IO request.
 303  * @scic_remote_device: the handle to the core remote device object for which
 304  *    to build an IO request.
 305  * @io_tag: This parameter specifies the IO tag to be associated with this
 306  *    request.  If SCI_CONTROLLER_INVALID_IO_TAG is passed, then a copy of the
 307  *    request is built internally.  The request will be copied into the actual
 308  *    controller request memory when the IO tag is allocated internally during
 309  *    the scic_controller_start_io() method.
 310  * @user_io_request_object: This parameter specifies the user IO request to be
 311  *    utilized during IO construction.  This IO pointer will become the
 312  *    associated object for the core IO request object.
 313  * @scic_io_request_memory: This parameter specifies the memory location to be
 314  *    utilized when building the core request.
 315  * @new_scic_io_request_handle: This parameter specifies a pointer to the
 316  *    handle the core will expect in further interactions with the core IO
 317  *    request object.
 318  *
 319  * The SCI core implementation will create an association between the user IO
 320  * request object and the core IO request object. Indicate if the controller
 321  * successfully built the IO request. SCI_SUCCESS This value is returned if the
 322  * IO request was successfully built.
 323  */
 324 enum sci_status scic_io_request_construct(
 325         struct scic_sds_controller *scic_controller,
 326         struct scic_sds_remote_device *scic_remote_device,
 327         u16 io_tag,
 328         void *user_io_request_object,
 329         void *scic_io_request_memory,
 330         struct scic_sds_request **new_scic_io_request_handle);
 331
 332 /**
 333  * scic_io_request_construct_basic_ssp() - This method is called by the SCI
 334  *    user to build an SSP IO request.
 335  * @scic_io_request: This parameter specifies the handle to the io request
 336  *    object to be built.
 337  *
 338  * - The user must have previously called scic_io_request_construct() on the
 339  * supplied IO request. Indicate if the controller successfully built the IO
 340  * request. SCI_SUCCESS This value is returned if the IO request was
 341  * successfully built. SCI_FAILURE_UNSUPPORTED_PROTOCOL This value is returned
 342  * if the remote_device does not support the SSP protocol.
 343  * SCI_FAILURE_INVALID_ASSOCIATION This value is returned if the user did not
 344  * properly set the association between the SCIC IO request and the user's IO
 345  * request.  Please refer to the sci_object_set_association() routine for more
 346  * information.
 347  */
 348 enum sci_status scic_io_request_construct_basic_ssp(
 349         struct scic_sds_request *scic_io_request);
 350
 351
 352
 353
 354
 355 /**
 356  * scic_io_request_construct_basic_sata() - This method is called by the SCI
 357  *    Core user to build an STP IO request.
 358  * @scic_io_request: This parameter specifies the handle to the io request
 359  *    object to be built.
 360  *
 361  * - The user must have previously called scic_io_request_construct() on the
 362  * supplied IO request. Indicate if the controller successfully built the IO
 363  * request. SCI_SUCCESS This value is returned if the IO request was
 364  * successfully built. SCI_FAILURE_UNSUPPORTED_PROTOCOL This value is returned
 365  * if the remote_device does not support the STP protocol.
 366  * SCI_FAILURE_INVALID_ASSOCIATION This value is returned if the user did not
 367  * properly set the association between the SCIC IO request and the user's IO
 368  * request.  Please refer to the sci_object_set_association() routine for more
 369  * information.
 370  */
 371 enum sci_status scic_io_request_construct_basic_sata(
 372         struct scic_sds_request *scic_io_request);
 373
 374
 375
 376
 377 /**
 378  * scic_io_request_construct_smp() - This method is called by the SCI user to
 379  *    build an SMP IO request.
 380  * @scic_io_request: This parameter specifies the handle to the io request
 381  *    object to be built.
 382  *
 383  * - The user must have previously called scic_io_request_construct() on the
 384  * supplied IO request. Indicate if the controller successfully built the IO
 385  * request. SCI_SUCCESS This value is returned if the IO request was
 386  * successfully built. SCI_FAILURE_UNSUPPORTED_PROTOCOL This value is returned
 387  * if the remote_device does not support the SMP protocol.
 388  * SCI_FAILURE_INVALID_ASSOCIATION This value is returned if the user did not
 389  * properly set the association between the SCIC IO request and the user's IO
 390  * request.  Please refer to the sci_object_set_association() routine for more
 391  * information.
 392  */
 393 enum sci_status scic_io_request_construct_smp(
 394         struct scic_sds_request *scic_io_request);
 395
 396
 397
 398 /**
 399  * scic_request_get_controller_status() - This method returns the controller
 400  *    specific IO/Task request status. These status values are unique to the
 401  *    specific controller being managed by the SCIC.
 402  * @io_request: the handle to the IO or task management request object for
 403  *    which to retrieve the status.
 404  *
 405  * This method returns a value indicating the controller specific request
 406  * status.
 407  */
 408 u32 scic_request_get_controller_status(
 409         struct scic_sds_request *io_request);
 410
 411
 412
 413 /**
 414  * scic_io_request_get_command_iu_address() - This method will return the
 415  *    address to the command information unit.
 416  * @scic_io_request: This parameter specifies the handle to the io request
 417  *    object to be built.
 418  *
 419  * The address of the SSP/SMP command information unit.
 420  */
 421 void *scic_io_request_get_command_iu_address(
 422         struct scic_sds_request *scic_io_request);
 423
 424 /**
 425  * scic_io_request_get_response_iu_address() - This method will return the
 426  *    address to the response information unit.  For an SSP request this buffer
 427  *    is only valid if the IO request is completed with the status
 428  *    SCI_FAILURE_IO_RESPONSE_VALID.
 429  * @scic_io_request: This parameter specifies the handle to the io request
 430  *    object to be built.
 431  *
 432  * The address of the SSP/SMP response information unit.
 433  */
 434 void *scic_io_request_get_response_iu_address(
 435         struct scic_sds_request *scic_io_request);
 436
 437 /**
 438  * scic_io_request_get_io_tag() - This method will return the IO tag utilized
 439  *    by the IO request.
 440  * @scic_io_request: This parameter specifies the handle to the io request
 441  *    object for which to return the IO tag.
 442  *
 443  * An unsigned integer representing the IO tag being utilized.
 444  * SCI_CONTROLLER_INVALID_IO_TAG This value is returned if the IO does not
 445  * currently have an IO tag allocated to it. All return other values indicate a
 446  * legitimate tag.
 447  */
 448 u16 scic_io_request_get_io_tag(
 449         struct scic_sds_request *scic_io_request);
 450
 451
 452 /**
 453  * scic_stp_io_request_set_ncq_tag() - This method will assign an NCQ tag to
 454  *    the io request object.  The caller of this function must make sure that
 455  *    only valid NCQ tags are assigned to the io request object.
 456  * @scic_io_request: This parameter specifies the handle to the io request
 457  *    object to which to assign the ncq tag.
 458  * @ncq_tag: This parameter specifies the NCQ tag to be utilized for the
 459  *    supplied core IO request.  It is up to the user to make sure that this is
 460  *    a valid NCQ tag.
 461  *
 462  * none This function is only valid for SATA NCQ requests.
 463  */
 464 void scic_stp_io_request_set_ncq_tag(
 465         struct scic_sds_request *scic_io_request,
 466         u16 ncq_tag);
 467
 468 /**
 469  * scic_stp_io_request_get_h2d_reg_address() - This method will return the
 470  *    address of the host to device register fis region for the io request
 471  *    object.
 472  * @scic_io_request: This parameter specifies the handle to the io request
 473  *    object from which to get the host to device register fis buffer.
 474  *
 475  * The address of the host to device register fis buffer in the io request
 476  * object. This function is only valid for SATA requests.
 477  */
 478 void *scic_stp_io_request_get_h2d_reg_address(
 479         struct scic_sds_request *scic_io_request);
 480
 481 /**
 482  * scic_stp_io_request_get_d2h_reg_address() - This method will return the
 483  *    address of the device to host register fis region for the io request
 484  *    object.
 485  * @scic_io_request: This parameter specifies teh handle to the io request
 486  *    object from which to get the device to host register fis buffer.
 487  *
 488  * The address fo the device to host register fis ending the io request. This
 489  * function is only valid for SATA requests.
 490  */
 491 void *scic_stp_io_request_get_d2h_reg_address(
 492         struct scic_sds_request *scic_io_request);
 493
 494
 495 /**
 496  * scic_io_request_get_number_of_bytes_transferred() - This method will return
 497  *    the number of bytes transferred from the SCU
 498  * @scic_io_request: This parameter specifies the handle to the io request
 499  *    whose data length was not eqaul to the data length specified in the
 500  *    request. When the driver gets an early io completion status from the
 501  *    hardware, this routine should be called to get the actual number of bytes
 502  *    transferred
 503  *
 504  * The return is the number of bytes transferred when the data legth is not
 505  * equal to the specified length in the io request
 506  */
 507 u32 scic_io_request_get_number_of_bytes_transferred(
 508         struct scic_sds_request *scic_io_request);
 509
 510
 511 #endif  /* _SCIC_IO_REQUEST_H_ */
 512