sys/dev/isci/scil/scic_user_callback.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  *
  40  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  41  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  42  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  43  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  44  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  45  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  46  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  47  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  48  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  49  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  50  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  51  *
  52  * $FreeBSD$
  53  */
  54 #ifndef _SCIC_USER_CALLBACK_H_
  55 #define _SCIC_USER_CALLBACK_H_
  56
  57 /**
  58  * @file
  59  *
  60  * @brief This file contains all of the interface methods/macros that must
  61  *        be implemented by an SCI Core user.
  62  */
  63
  64 #ifdef __cplusplus
  65 extern "C" {
  66 #endif // __cplusplus
  67
  68 #include <dev/isci/scil/sci_types.h>
  69 #include <dev/isci/scil/sci_status.h>
  70 #include <dev/isci/scil/sci_controller.h>
  71
  72 /**
  73  * @brief This callback method asks the user to create a timer and provide
  74  *        a handle for this timer for use in further timer interactions.
  75  *
  76  * @warning The "timer_callback" method should be executed in a mutually
  77  *          exlusive manner from the controller completion handler
  78  *          handler (refer to scic_controller_get_handler_methods()).
  79  *
  80  * @param[in]  controller This parameter specifies the controller with
  81  *             which this timer is to be associated.
  82  * @param[in]  timer_callback This parameter specifies the callback method
  83  *             to be invoked whenever the timer expires.
  84  * @param[in]  cookie This parameter specifies a piece of information that
  85  *             the user must retain.  This cookie is to be supplied by the
  86  *             user anytime a timeout occurs for the created timer.
  87  *
  88  * @return This method returns a handle to a timer object created by the
  89  *         user.  The handle will be utilized for all further interactions
  90  *         relating to this timer.
  91  */
  92 void * scic_cb_timer_create(
  93    SCI_CONTROLLER_HANDLE_T   controller,
  94    SCI_TIMER_CALLBACK_T      timer_callback,
  95    void                    * cookie
  96 );
  97
  98 /**
  99  * @brief This callback method asks the user to destory the supplied timer.
 100  *
 101  * @param[in]  controller This parameter specifies the controller with
 102  *             which this timer is to associated.
 103  * @param[in]  timer This parameter specifies the timer to be destroyed.
 104  *
 105  * @return none
 106  */
 107 void scic_cb_timer_destroy(
 108    SCI_CONTROLLER_HANDLE_T   controller,
 109    void                    * timer
 110 );
 111
 112 /**
 113  * @brief This callback method asks the user to start the supplied timer.
 114  *
 115  * @warning All timers in the system started by the SCI Core are one shot
 116  *          timers.  Therefore, the SCI user should make sure that it
 117  *          removes the timer from it's list when a timer actually fires.
 118  *          Additionally, SCI Core user's should be able to handle
 119  *          calls from the SCI Core to stop a timer that may already
 120  *          be stopped.
 121  *
 122  * @param[in]  controller This parameter specifies the controller with
 123  *             which this timer is to associated.
 124  * @param[in]  timer This parameter specifies the timer to be started.
 125  * @param[in]  milliseconds This parameter specifies the number of
 126  *             milliseconds for which to stall.  The operating system driver
 127  *             is allowed to round this value up where necessary.
 128  *
 129  * @return none
 130  */
 131 void scic_cb_timer_start(
 132    SCI_CONTROLLER_HANDLE_T   controller,
 133    void                    * timer,
 134    U32                       milliseconds
 135 );
 136
 137 /**
 138  * @brief This callback method asks the user to stop the supplied timer.
 139  *
 140  * @param[in]  controller This parameter specifies the controller with
 141  *             which this timer is to associated.
 142  * @param[in]  timer This parameter specifies the timer to be stopped.
 143  *
 144  * @return none
 145  */
 146 void scic_cb_timer_stop(
 147    SCI_CONTROLLER_HANDLE_T   controller,
 148    void                    * timer
 149 );
 150
 151 /**
 152  * @brief This method is called when the core requires the OS driver
 153  *        to stall execution.  This method is utilized during initialization
 154  *        or non-performance paths only.
 155  *
 156  * @param[in]  microseconds This parameter specifies the number of
 157  *             microseconds for which to stall.  The operating system driver
 158  *             is allowed to round this value up where necessary.
 159  *
 160  * @return none.
 161  */
 162 void scic_cb_stall_execution(
 163    U32  microseconds
 164 );
 165
 166 /**
 167  * @brief This user callback will inform the user that the controller has
 168  *        finished the start process.
 169  *
 170  * @param[in]  controller This parameter specifies the controller that was
 171  *             started.
 172  * @param[in]  completion_status This parameter specifies the results of
 173  *             the start operation.  SCI_SUCCESS indicates successful
 174  *             completion.
 175  *
 176  * @return none
 177  */
 178 void scic_cb_controller_start_complete(
 179    SCI_CONTROLLER_HANDLE_T  controller,
 180    SCI_STATUS               completion_status
 181 );
 182
 183 /**
 184  * @brief This user callback will inform the user that the controller has
 185  *        finished the stop process.
 186  *
 187  * @param[in]  controller This parameter specifies the controller that was
 188  *             stopped.
 189  * @param[in]  completion_status This parameter specifies the results of
 190  *             the stop operation.  SCI_SUCCESS indicates successful
 191  *             completion.
 192  *
 193  * @return none
 194  */
 195 void scic_cb_controller_stop_complete(
 196    SCI_CONTROLLER_HANDLE_T  controller,
 197    SCI_STATUS               completion_status
 198 );
 199
 200 /**
 201  * @brief This user callback will inform the user that an IO request has
 202  *        completed.
 203  *
 204  * @param[in]  controller This parameter specifies the controller on
 205  *             which the IO is completing.
 206  * @param[in]  remote_device This parameter specifies the remote device on
 207  *             which this IO request is completing.
 208  * @param[in]  io_request This parameter specifies the IO request that has
 209  *             completed.
 210  * @param[in]  completion_status This parameter specifies the results of
 211  *             the IO request operation.  SCI_SUCCESS indicates successful
 212  *             completion.
 213  *
 214  * @return none
 215  */
 216 void scic_cb_io_request_complete(
 217    SCI_CONTROLLER_HANDLE_T     controller,
 218    SCI_REMOTE_DEVICE_HANDLE_T  remote_device,
 219    SCI_IO_REQUEST_HANDLE_T     io_request,
 220    SCI_IO_STATUS               completion_status
 221 );
 222
 223 /**
 224  * @brief This method simply returns the virtual address associated
 225  *        with the scsi_io and byte_offset supplied parameters.
 226  *
 227  * @note This callback is not utilized in the fast path.  The expectation
 228  *       is that this method is utilized for items such as SCSI to ATA
 229  *       translation for commands like INQUIRY, READ CAPACITY, etc.
 230  *
 231  * @param[in] scic_user_io_request This parameter points to the user's
 232  *            IO request object.  It is a cookie that allows the user to
 233  *            provide the necessary information for this callback.
 234  * @param[in] byte_offset This parameter specifies the offset into the data
 235  *            buffers pointed to by the SGL.  The byte offset starts at 0
 236  *            and continues until the last byte pointed to be the last SGL
 237  *            element.
 238  *
 239  * @return A virtual address pointer to the location specified by the
 240  *         parameters.
 241  */
 242 U8 *scic_cb_io_request_get_virtual_address_from_sgl(
 243    void * scic_user_io_request,
 244    U32    byte_offset
 245 );
 246
 247 /**
 248  * @brief This user callback will inform the user that a task management
 249  *        request completed.
 250  *
 251  * @param[in]  controller This parameter specifies the controller on
 252  *             which the task management request is completing.
 253  * @param[in]  remote_device This parameter specifies the remote device on
 254  *             which this task management request is completing.
 255  * @param[in]  task_request This parameter specifies the task management
 256  *             request that has completed.
 257  * @param[in]  completion_status This parameter specifies the results of
 258  *             the IO request operation.  SCI_SUCCESS indicates successful
 259  *             completion.
 260  *
 261  * @return none
 262  */
 263 void scic_cb_task_request_complete(
 264    SCI_CONTROLLER_HANDLE_T     controller,
 265    SCI_REMOTE_DEVICE_HANDLE_T  remote_device,
 266    SCI_TASK_REQUEST_HANDLE_T   task_request,
 267    SCI_TASK_STATUS             completion_status
 268 );
 269
 270 #ifndef SCI_GET_PHYSICAL_ADDRESS_OPTIMIZATION_ENABLED
 271 /**
 272  * @brief This callback method asks the user to provide the physical
 273  *        address for the supplied virtual address when building an
 274  *        io request object.
 275  *
 276  * @param[in] controller This parameter is the core controller object
 277  *            handle.
 278  * @param[in] io_request This parameter is the io request object handle
 279  *            for which the physical address is being requested.
 280  * @param[in] virtual_address This paramter is the virtual address which
 281  *            is to be returned as a physical address.
 282  * @param[out] physical_address The physical address for the supplied virtual
 283  *        address.
 284  *
 285  * @return None.
 286  */
 287 void scic_cb_io_request_get_physical_address(
 288    SCI_CONTROLLER_HANDLE_T   controller,
 289    SCI_IO_REQUEST_HANDLE_T   io_request,
 290    void                    * virtual_address,
 291    SCI_PHYSICAL_ADDRESS    * physical_address
 292 );
 293 #endif // SCI_GET_PHYSICAL_ADDRESS_OPTIMIZATION_ENABLED
 294
 295 /**
 296  * @brief This callback method asks the user to provide the number of
 297  *        bytes to be transfered as part of this request.
 298  *
 299  * @param[in] scic_user_io_request This parameter points to the user's
 300  *            IO request object.  It is a cookie that allows the user to
 301  *            provide the necessary information for this callback.
 302  *
 303  * @return This method returns the number of payload data bytes to be
 304  *         transfered for this IO request.
 305  */
 306 U32 scic_cb_io_request_get_transfer_length(
 307    void * scic_user_io_request
 308 );
 309
 310 /**
 311  * @brief This callback method asks the user to provide the data direction
 312  *        for this request.
 313  *
 314  * @param[in] scic_user_io_request This parameter points to the user's
 315  *            IO request object.  It is a cookie that allows the user to
 316  *            provide the necessary information for this callback.
 317  *
 318  * @return This method returns the value of SCI_IO_REQUEST_DATA_OUT or
 319  *         SCI_IO_REQUEST_DATA_IN, or SCI_IO_REQUEST_NO_DATA.
 320  */
 321 SCI_IO_REQUEST_DATA_DIRECTION scic_cb_io_request_get_data_direction(
 322    void * scic_user_io_request
 323 );
 324
 325 #ifdef ENABLE_OSSL_COPY_BUFFER
 326 /**
 327  * @brief This method is presently utilized in the PIO path,
 328  *        copies from UF buffer to the SGL buffer. This method
 329  *        can be served for other OS related copies.
 330  *
 331  * @param[in] scic_user_io_request. This parameter points to the user's
 332  *            IO request object.  It is a cookie that allows the user to
 333  *            provide the necessary information for this callback.
 334  * @param[in] source addr. Address of UF buffer.
 335  * @param[in] offset. This parameter specifies the offset into the data
 336  *            buffers pointed to by the SGL.  The byte offset starts at 0
 337  *            and continues until the last byte pointed to be the last SGL
 338  *            element.
 339  * @param[in] length. data length
 340  *
 341  * @return    None
 342  */
 343 void scic_cb_io_request_copy_buffer(
 344    void * scic_user_io_request,
 345    U8   *source_addr,
 346    U32   offset,
 347    U32   length
 348 );
 349 #endif
 350
 351 #ifndef SCI_SGL_OPTIMIZATION_ENABLED
 352 /**
 353  * @brief This callback method asks the user to provide the address
 354  *        to where the next Scatter-Gather Element is located.
 355  *
 356  * Details regarding usage:
 357  *   - Regarding the first SGE: the user should initialize an index,
 358  *     or a pointer, prior to construction of the request that will
 359  *     reference the very first scatter-gather element.  This is
 360  *     important since this method is called for every scatter-gather
 361  *     element, including the first element.
 362  *   - Regarding the last SGE: the user should return NULL from this
 363  *     method when this method is called and the SGL has exhausted
 364  *     all elements.
 365  *
 366  * @param[in] scic_user_io_request This parameter points to the user's
 367  *            IO request object.  It is a cookie that allows the user to
 368  *            provide the necessary information for this callback.
 369  * @param[in] current_sge_address This parameter specifies the address for
 370  *            the current SGE (i.e. the one that has just processed).
 371  * @param[out] next_sge An address specifying the location for the next
 372  *            scatter gather element to be processed.
 373  *
 374  * @return None
 375  */
 376 void scic_cb_io_request_get_next_sge(
 377    void * scic_user_io_request,
 378    void * current_sge_address,
 379    void ** next_sge
 380 );
 381 #endif // SCI_SGL_OPTIMIZATION_ENABLED
 382
 383 /**
 384  * @brief This callback method asks the user to provide the contents of the
 385  *        "address" field in the Scatter-Gather Element.
 386  *
 387  * @param[in] scic_user_io_request This parameter points to the user's
 388  *            IO request object.  It is a cookie that allows the user to
 389  *            provide the necessary information for this callback.
 390  * @param[in] sge_address This parameter specifies the address for the
 391  *            SGE from which to retrieve the address field.
 392  *
 393  * @return A physical address specifying the contents of the SGE's address
 394  *         field.
 395  */
 396 SCI_PHYSICAL_ADDRESS scic_cb_sge_get_address_field(
 397    void * scic_user_io_request,
 398    void * sge_address
 399 );
 400
 401 /**
 402  * @brief This callback method asks the user to provide the contents of the
 403  *        "length" field in the Scatter-Gather Element.
 404  *
 405  * @param[in] scic_user_io_request This parameter points to the user's
 406  *            IO request object.  It is a cookie that allows the user to
 407  *            provide the necessary information for this callback.
 408  * @param[in] sge_address This parameter specifies the address for the
 409  *            SGE from which to retrieve the address field.
 410  *
 411  * @return This method returns the length field specified inside the SGE
 412  *         referenced by the sge_address parameter.
 413  */
 414 U32 scic_cb_sge_get_length_field(
 415    void * scic_user_io_request,
 416    void * sge_address
 417 );
 418
 419 /**
 420  * @brief This callback method asks the user to provide the address for
 421  *        the command descriptor block (CDB) associated with this IO request.
 422  *
 423  * @param[in] scic_user_io_request This parameter points to the user's
 424  *            IO request object.  It is a cookie that allows the user to
 425  *            provide the necessary information for this callback.
 426  *
 427  * @return This method returns the virtual address of the CDB.
 428  */
 429 void * scic_cb_ssp_io_request_get_cdb_address(
 430    void * scic_user_io_request
 431 );
 432
 433 /**
 434  * @brief This callback method asks the user to provide the length of
 435  *        the command descriptor block (CDB) associated with this IO request.
 436  *
 437  * @param[in] scic_user_io_request This parameter points to the user's
 438  *            IO request object.  It is a cookie that allows the user to
 439  *            provide the necessary information for this callback.
 440  *
 441  * @return This method returns the length of the CDB.
 442  */
 443 U32 scic_cb_ssp_io_request_get_cdb_length(
 444    void * scic_user_io_request
 445 );
 446
 447 /**
 448  * @brief This callback method asks the user to provide the Logical Unit (LUN)
 449  *        associated with this IO request.
 450  *
 451  * @note The contents of the value returned from this callback are defined
 452  *       by the protocol standard (e.g. T10 SAS specification).  Please
 453  *       refer to the transport command information unit description
 454  *       in the associated standard.
 455  *
 456  * @param[in] scic_user_io_request This parameter points to the user's
 457  *            IO request object.  It is a cookie that allows the user to
 458  *            provide the necessary information for this callback.
 459  *
 460  * @return This method returns the LUN associated with this request.
 461  * @todo This should be U64?
 462  */
 463 U32 scic_cb_ssp_io_request_get_lun(
 464    void * scic_user_io_request
 465 );
 466
 467 /**
 468  * @brief This callback method asks the user to provide the task attribute
 469  *        associated with this IO request.
 470  *
 471  * @note The contents of the value returned from this callback are defined
 472  *       by the protocol standard (e.g. T10 SAS specification).  Please
 473  *       refer to the transport command information unit description
 474  *       in the associated standard.
 475  *
 476  * @param[in] scic_user_io_request This parameter points to the user's
 477  *            IO request object.  It is a cookie that allows the user to
 478  *            provide the necessary information for this callback.
 479  *
 480  * @return This method returns the task attribute associated with this
 481  *         IO request.
 482  */
 483 U32 scic_cb_ssp_io_request_get_task_attribute(
 484    void * scic_user_io_request
 485 );
 486
 487 /**
 488  * @brief This callback method asks the user to provide the command priority
 489  *        associated with this IO request.
 490  *
 491  * @note The contents of the value returned from this callback are defined
 492  *       by the protocol standard (e.g. T10 SAS specification).  Please
 493  *       refer to the transport command information unit description
 494  *       in the associated standard.
 495  *
 496  * @param[in] scic_user_io_request This parameter points to the user's
 497  *            IO request object.  It is a cookie that allows the user to
 498  *            provide the necessary information for this callback.
 499  *
 500  * @return This method returns the command priority associated with this
 501  *         IO request.
 502  */
 503 U32 scic_cb_ssp_io_request_get_command_priority(
 504    void * scic_user_io_request
 505 );
 506
 507 /**
 508  * @brief This callback method asks the user if the received RX frame data is
 509  *        to be copied to the SGL or should be stored by the SCI core to be
 510  *        retrieved later with the scic_io_request_get_rx_frame().
 511  *
 512  * @param[in] scic_user_io_request This parameter points to the user's IO
 513  *       request object.  It is a cookie that allows the user to provide the
 514  *       necessary information for this callback.
 515  *
 516  * @return This method returns TRUE if the SCI core should copy the received
 517  *         frame data to the SGL location or FALSE if the SCI user wants to
 518  *         retrieve the frame data at a later time.
 519  */
 520 BOOL scic_cb_io_request_do_copy_rx_frames(
 521    void * scic_user_io_request
 522 );
 523
 524 /**
 525  * @brief This callback method asks the user to return the SAT protocol
 526  *        definition for this IO request.  This method is only called by the
 527  *        SCI core if the request type constructed is SATA.
 528  *
 529  * @param[in] scic_user_io_request This parameter points to the user's IO
 530  *       request object.  It is a cookie that allows the user to provide the
 531  *       necessary information for this callback.
 532  *
 533  * @return This method returns one of the sat.h defined protocols for the
 534  *         given io request.
 535  */
 536 U8 scic_cb_request_get_sat_protocol(
 537    void * scic_user_io_request
 538 );
 539
 540 /**
 541  * @brief This callback method asks the user to indicate if the IO is initially
 542  *           constructed or is reconstructed using the recycled memory.
 543  *
 544  * @param[in] scic_user_io_request This parameter points to the user's IO
 545  *       request object.  It is a cookie that allows the user to provide the
 546  *       necessary information for this callback.
 547  *
 548  * @return This method returns TRUE if the request is initial constructed.
 549  *         This method returns FALSE if the request is constructed using recycled
 550  *         memory. For many scic user, this method mostly always returns TRUE.
 551  */
 552 BOOL scic_cb_request_is_initial_construction(
 553    void * scic_user_io_request
 554 );
 555
 556 /**
 557  * @brief This method returns the Logical Unit to be utilized for this
 558  *        task management request.
 559  *
 560  * @note The contents of the value returned from this callback are defined
 561  *       by the protocol standard (e.g. T10 SAS specification).  Please
 562  *       refer to the transport task information unit description
 563  *       in the associated standard.
 564  *
 565  * @param[in] scic_user_task_request This parameter points to the user's
 566  *            task request object.  It is a cookie that allows the user to
 567  *            provide the necessary information for this callback.
 568  *
 569  * @return This method returns the LUN associated with this request.
 570  * @todo This should be U64?
 571  */
 572 U32 scic_cb_ssp_task_request_get_lun(
 573    void * scic_user_task_request
 574 );
 575
 576 /**
 577  * @brief This method returns the task management function to be utilized
 578  *        for this task request.
 579  *
 580  * @note The contents of the value returned from this callback are defined
 581  *       by the protocol standard (e.g. T10 SAS specification).  Please
 582  *       refer to the transport task information unit description
 583  *       in the associated standard.
 584  *
 585  * @param[in] scic_user_task_request This parameter points to the user's
 586  *            task request object.  It is a cookie that allows the user to
 587  *            provide the necessary information for this callback.
 588  *
 589  * @return This method returns an unsigned byte representing the task
 590  *         management function to be performed.
 591  */
 592 U8 scic_cb_ssp_task_request_get_function(
 593    void * scic_user_task_request
 594 );
 595
 596 /**
 597  * @brief This method returns the task management IO tag to be managed.
 598  *        Depending upon the task management function the value returned
 599  *        from this method may be ignored.
 600  *
 601  * @param[in] scic_user_task_request This parameter points to the user's
 602  *            task request object.  It is a cookie that allows the user to
 603  *            provide the necessary information for this callback.
 604  *
 605  * @return This method returns an unsigned 16-bit word depicting the IO
 606  *         tag to be managed.
 607  */
 608 U16 scic_cb_ssp_task_request_get_io_tag_to_manage(
 609    void * scic_user_task_request
 610 );
 611
 612 /**
 613  * @brief This callback method asks the user to provide the virtual
 614  *        address of the response data buffer for the supplied IO request.
 615  *
 616  * @param[in] scic_user_task_request This parameter points to the user's
 617  *            task request object.  It is a cookie that allows the user to
 618  *            provide the necessary information for this callback.
 619  *
 620  * @return This method returns the virtual address for the response data buffer
 621  *         associated with this IO request.
 622  */
 623 void * scic_cb_ssp_task_request_get_response_data_address(
 624    void * scic_user_task_request
 625 );
 626
 627 /**
 628  * @brief This callback method asks the user to provide the length of the
 629  *        response data buffer for the supplied IO request.
 630  *
 631  * @param[in] scic_user_task_request This parameter points to the user's
 632  *            task request object.  It is a cookie that allows the user to
 633  *            provide the necessary information for this callback.
 634  *
 635  * @return This method returns the length of the response buffer data
 636  *         associated with this IO request.
 637  */
 638 U32 scic_cb_ssp_task_request_get_response_data_length(
 639    void * scic_user_task_request
 640 );
 641
 642 /**
 643  * @brief In this method the user is expected to log the supplied
 644  *        error information.  The user must be capable of handling variable
 645  *        length argument lists and should consider prepending the fact
 646  *        that this is an error from the core.
 647  *
 648  * @param[in]  logger_object This parameter specifies the logger object
 649  *             associated with this message.
 650  * @param[in]  log_object_mask This parameter specifies the log objects
 651  *             for which this message is being generated.
 652  * @param[in]  log_message This parameter specifies the message to be logged.
 653  *
 654  * @return none
 655  */
 656 void scic_cb_logger_log_error(
 657    SCI_LOGGER_HANDLE_T   logger_object,
 658    U32                   log_object_mask,
 659    char                * log_message,
 660    ...
 661 );
 662
 663
 664 /**
 665  * @brief In this method the user is expected to log the supplied warning
 666  *        information.  The user must be capable of handling variable
 667  *        length argument lists and should consider prepending the fact
 668  *        that this is a warning from the core.
 669  *
 670  * @param[in]  logger_object This parameter specifies the logger object
 671  *             associated with this message.
 672  * @param[in]  log_object_mask This parameter specifies the log objects
 673  *             for which this message is being generated.
 674  * @param[in]  log_message This parameter specifies the message to be logged.
 675  *
 676  * @return none
 677  */
 678 void scic_cb_logger_log_warning(
 679    SCI_LOGGER_HANDLE_T   logger_object,
 680    U32                   log_object_mask,
 681    char                * log_message,
 682    ...
 683 );
 684
 685
 686 /**
 687  * @brief In this method the user is expected to log the supplied debug
 688  *        information.  The user must be capable of handling variable
 689  *        length argument lists and should consider prepending the fact
 690  *        that this is a debug message from the core.
 691  *
 692  * @param[in]  logger_object This parameter specifies the logger object
 693  *             associated with this message.
 694  * @param[in]  log_object_mask This parameter specifies the log objects
 695  *             for which this message is being generated.
 696  * @param[in]  log_message This parameter specifies the message to be logged.
 697  *
 698  * @return none
 699  */
 700 void scic_cb_logger_log_info(
 701    SCI_LOGGER_HANDLE_T   logger_object,
 702    U32                   log_object_mask,
 703    char                * log_message,
 704    ...
 705 );
 706
 707
 708 /**
 709  * @brief In this method the user is expected to log the supplied function
 710  *        trace information.  The user must be capable of handling variable
 711  *        length argument lists and should consider prepending the fact
 712  *        that this is a function trace (i.e. entry/exit) message from the
 713  *        core.
 714  *
 715  * @param[in]  logger_object This parameter specifies the logger object
 716  *             associated with this message.
 717  * @param[in]  log_object_mask This parameter specifies the log objects
 718  *             for which this message is being generated.
 719  * @param[in]  log_message This parameter specifies the message to be logged.
 720  *
 721  * @return none
 722  */
 723 void scic_cb_logger_log_trace(
 724    SCI_LOGGER_HANDLE_T   logger_object,
 725    U32                   log_object_mask,
 726    char                * log_message,
 727    ...
 728 );
 729
 730
 731 /**
 732  * @brief In this method the user is expected to log the supplied state
 733  *        transition information. The user must be capable of handling
 734  *        variable length argument lists and should consider prepending the
 735  *        fact that this is a warning from the core.
 736  *
 737  * @param[in]  logger_object This parameter specifies the logger object
 738  *             associated with this message.
 739  * @param[in]  log_object_mask This parameter specifies the log objects
 740  *             for which this message is being generated.
 741  * @param[in]  log_message This parameter specifies the message to be logged.
 742  *
 743  * @return none
 744  */
 745 void scic_cb_logger_log_states(
 746    SCI_LOGGER_HANDLE_T   logger_object,
 747    U32                   log_object_mask,
 748    char                * log_message,
 749    ...
 750 );
 751
 752
 753 /**
 754  * @brief In this method the user must return the base address register (BAR)
 755  *        value for the supplied base address register number.
 756  *
 757  * @param[in] controller The controller for which to retrieve the bar number.
 758  * @param[in] bar_number This parameter depicts the BAR index/number to be read.
 759  *
 760  * @return Return a pointer value indicating the contents of the BAR.
 761  * @retval NULL indicates an invalid BAR index/number was specified.
 762  * @retval All other values indicate a valid VIRTUAL address from the BAR.
 763  */
 764 void * scic_cb_pci_get_bar(
 765    SCI_CONTROLLER_HANDLE_T  controller,
 766    U16                      bar_number
 767 );
 768
 769 /**
 770  * @brief In this method the user must read from PCI memory via access.
 771  *        This method is used for access to memory space and IO space.
 772  *
 773  * @param[in]  controller The controller for which to read a DWORD.
 774  * @param[in]  address This parameter depicts the address from
 775  *             which to read.
 776  *
 777  * @return The value being returned from the PCI memory location.
 778  *
 779  * @todo This PCI memory access calls likely need to be optimized into macro?
 780  */
 781 U32 scic_cb_pci_read_dword(
 782    SCI_CONTROLLER_HANDLE_T   controller,
 783    void                    * address
 784 );
 785
 786 /**
 787  * @brief In this method the user must write to PCI memory via access.
 788  *        This method is used for access to memory space and IO space.
 789  *
 790  * @param[in]  controller The controller for which to read a DWORD.
 791  * @param[in]  address This parameter depicts the address into
 792  *             which to write.
 793  * @param[out] write_value This parameter depicts the value being written
 794  *             into the PCI memory location.
 795  *
 796  * @todo This PCI memory access calls likely need to be optimized into macro?
 797  */
 798 void scic_cb_pci_write_dword(
 799    SCI_CONTROLLER_HANDLE_T   controller,
 800    void                    * address,
 801    U32                       write_value
 802 );
 803
 804 /**
 805  * @brief This method informs the user when a stop operation on the port
 806  *        has completed.
 807  *
 808  * @param[in] controller This parameter represents the controller which
 809  *            contains the port.
 810  * @param[in] port This parameter specifies the SCI port object for which
 811  *            the callback is being invoked.
 812  * @param[in] completion_status This parameter specifies the status for
 813  *            the operation being completed.
 814  *
 815  * @return none
 816  */
 817 void scic_cb_port_stop_complete(
 818    SCI_CONTROLLER_HANDLE_T  controller,
 819    SCI_PORT_HANDLE_T        port,
 820    SCI_STATUS               completion_status
 821 );
 822
 823 /**
 824  * @brief This method informs the user when a hard reset on the port
 825  *        has completed.  This hard reset could have been initiated by the
 826  *        user or by the remote port.
 827  *
 828  * @param[in] controller This parameter represents the controller which
 829  *            contains the port.
 830  * @param[in] port This parameter specifies the SCI port object for which
 831  *            the callback is being invoked.
 832  * @param[in] completion_status This parameter specifies the status for
 833  *            the operation being completed.
 834  *
 835  * @return none
 836  */
 837 void scic_cb_port_hard_reset_complete(
 838    SCI_CONTROLLER_HANDLE_T  controller,
 839    SCI_PORT_HANDLE_T        port,
 840    SCI_STATUS               completion_status
 841 );
 842
 843 /**
 844  * @brief This method informs the user that the port is now in a ready
 845  *        state and can be utilized to issue IOs.
 846  *
 847  * @param[in] controller This parameter represents the controller which
 848  *            contains the port.
 849  * @param[in] port This parameter specifies the SCI port object for which
 850  *            the callback is being invoked.
 851  *
 852  * @return none
 853  */
 854 void scic_cb_port_ready(
 855    SCI_CONTROLLER_HANDLE_T  controller,
 856    SCI_PORT_HANDLE_T        port
 857 );
 858
 859 /**
 860  * @brief This method informs the user that the port is now not in a ready
 861  *        (i.e. busy) state and can't be utilized to issue IOs.
 862  *
 863  * @param[in] controller This parameter represents the controller which
 864  *            contains the port.
 865  * @param[in] port This parameter specifies the SCI port object for which
 866  *            the callback is being invoked.
 867  * @param[in] reason_code This parameter specifies the reason for the port
 868  *            not ready callback.
 869  *
 870  * @return none
 871  */
 872 void scic_cb_port_not_ready(
 873    SCI_CONTROLLER_HANDLE_T  controller,
 874    SCI_PORT_HANDLE_T        port,
 875    U32                      reason_code
 876 );
 877
 878 /**
 879  * @brief This method informs the SCI Core user that a phy/link became
 880  *        ready, but the phy is not allowed in the port.  In some
 881  *        situations the underlying hardware only allows for certain phy
 882  *        to port mappings.  If these mappings are violated, then this
 883  *        API is invoked.
 884  *
 885  * @param[in] controller This parameter represents the controller which
 886  *            contains the port.
 887  * @param[in] port This parameter specifies the SCI port object for which
 888  *            the callback is being invoked.
 889  * @param[in] phy This parameter specifies the phy that came ready, but the
 890  *            phy can't be a valid member of the port.
 891  *
 892  * @return none
 893  */
 894 void scic_cb_port_invalid_link_up(
 895    SCI_CONTROLLER_HANDLE_T  controller,
 896    SCI_PORT_HANDLE_T        port,
 897    SCI_PHY_HANDLE_T         phy
 898 );
 899
 900 /**
 901  * @brief This callback method informs the user that a broadcast change
 902  *        primitive was received.
 903  *
 904  * @param[in] controller This parameter represents the controller which
 905  *            contains the port.
 906  * @param[in] port This parameter specifies the SCI port object for which
 907  *            the callback is being invoked.  For instances where the phy
 908  *            on which the primitive was received is not part of a port, this
 909  *            parameter will be SCI_INVALID_HANDLE_T.
 910  * @param[in] phy This parameter specifies the phy on which the primitive
 911  *            was received.
 912  *
 913  * @return none
 914  */
 915 void scic_cb_port_bc_change_primitive_recieved(
 916    SCI_CONTROLLER_HANDLE_T  controller,
 917    SCI_PORT_HANDLE_T        port,
 918    SCI_PHY_HANDLE_T         phy
 919 );
 920
 921 /**
 922  * @brief This callback method informs the user that a broadcast SES
 923  *        primitive was received.
 924  *
 925  * @param[in] controller This parameter represents the controller which
 926  *            contains the port.
 927  * @param[in] port This parameter specifies the SCI port object for which
 928  *            the callback is being invoked.  For instances where the phy
 929  *            on which the primitive was received is not part of a port, this
 930  *            parameter will be SCI_INVALID_HANDLE_T.
 931  * @param[in] phy This parameter specifies the phy on which the primitive
 932  *            was received.
 933  *
 934  * @return none
 935  */
 936 void scic_cb_port_bc_ses_primitive_recieved(
 937    SCI_CONTROLLER_HANDLE_T  controller,
 938    SCI_PORT_HANDLE_T        port,
 939    SCI_PHY_HANDLE_T         phy
 940 );
 941
 942 /**
 943  * @brief This callback method informs the user that a broadcast EXPANDER
 944  *        primitive was received.
 945  *
 946  * @param[in] controller This parameter represents the controller which
 947  *            contains the port.
 948  * @param[in] port This parameter specifies the SCI port object for which
 949  *            the callback is being invoked.  For instances where the phy
 950  *            on which the primitive was received is not part of a port, this
 951  *            parameter will be SCI_INVALID_HANDLE_T.
 952  * @param[in] phy This parameter specifies the phy on which the primitive
 953  *            was received.
 954  *
 955  * @return none
 956  */
 957 void scic_cb_port_bc_expander_primitive_recieved(
 958    SCI_CONTROLLER_HANDLE_T  controller,
 959    SCI_PORT_HANDLE_T        port,
 960    SCI_PHY_HANDLE_T         phy
 961 );
 962
 963 /**
 964  * @brief This callback method informs the user that a broadcast ASYNCHRONOUS
 965  *        EVENT (AEN) primitive was received.
 966  *
 967  * @param[in] controller This parameter represents the controller which
 968  *            contains the port.
 969  * @param[in] port This parameter specifies the SCI port object for which
 970  *            the callback is being invoked.  For instances where the phy
 971  *            on which the primitive was received is not part of a port, this
 972  *            parameter will be SCI_INVALID_HANDLE_T.
 973  * @param[in] phy This parameter specifies the phy on which the primitive
 974  *            was received.
 975  *
 976  * @return none
 977  */
 978 void scic_cb_port_bc_aen_primitive_recieved(
 979    SCI_CONTROLLER_HANDLE_T  controller,
 980    SCI_PORT_HANDLE_T        port,
 981    SCI_PHY_HANDLE_T         phy
 982 );
 983
 984 /**
 985  * @brief This callback method informs the user that a phy has become
 986  *        operational and is capable of communicating with the remote end
 987  *        point.
 988  *
 989  * @param[in] controller This parameter represents the controller
 990  *            associated with the phy.
 991  * @param[in] port This parameter specifies the port object for which the
 992  *            user callback is being invoked.  There may be conditions where
 993  *            this parameter can be SCI_INVALID_HANDLE
 994  * @param[in] phy This parameter specifies the phy object for which the
 995  *            user callback is being invoked.
 996  *
 997  * @return none
 998  */
 999 void scic_cb_port_link_up(
1000    SCI_CONTROLLER_HANDLE_T  controller,
1001    SCI_PORT_HANDLE_T        port,
1002    SCI_PHY_HANDLE_T         phy
1003 );
1004
1005 /**
1006  * @brief This callback method informs the user that a phy is no longer
1007  *        operational and is not capable of communicating with the remote end
1008  *        point.
1009  *
1010  * @param[in] controller This parameter represents the controller
1011  *            associated with the phy.
1012  * @param[in] port This parameter specifies the port object for which the
1013  *            user callback is being invoked.  There may be conditions where
1014  *            this parameter can be SCI_INVALID_HANDLE
1015  * @param[in] phy This parameter specifies the phy object for which the
1016  *            user callback is being invoked.
1017  *
1018  * @return none
1019  */
1020 void scic_cb_port_link_down(
1021    SCI_CONTROLLER_HANDLE_T  controller,
1022    SCI_PORT_HANDLE_T        port,
1023    SCI_PHY_HANDLE_T         phy
1024 );
1025
1026 /**
1027  * @brief This user callback method will inform the user that a start
1028  *        operation has completed.
1029  *
1030  * @param[in] controller This parameter specifies the core controller
1031  *            associated with the completion callback.
1032  * @param[in] remote_device This parameter specifies the remote device
1033  *            associated with the completion callback.
1034  * @param[in] completion_status This parameter specifies the completion
1035  *            status for the operation.
1036  *
1037  * @return none
1038  */
1039 void scic_cb_remote_device_start_complete(
1040    SCI_CONTROLLER_HANDLE_T    controller,
1041    SCI_REMOTE_DEVICE_HANDLE_T remote_device,
1042    SCI_STATUS                 completion_status
1043 );
1044
1045 /**
1046  * @brief This user callback method will inform the user that a stop
1047  *        operation has completed.
1048  *
1049  * @param[in] controller This parameter specifies the core controller
1050  *            associated with the completion callback.
1051  * @param[in] remote_device This parameter specifies the remote device
1052  *            associated with the completion callback.
1053  * @param[in] completion_status This parameter specifies the completion
1054  *            status for the operation.
1055  *
1056  * @return none
1057  */
1058 void scic_cb_remote_device_stop_complete(
1059    SCI_CONTROLLER_HANDLE_T    controller,
1060    SCI_REMOTE_DEVICE_HANDLE_T remote_device,
1061    SCI_STATUS                 completion_status
1062 );
1063
1064 /**
1065  * @brief This user callback method will inform the user that a remote
1066  *        device is now capable of handling IO requests.
1067  *
1068  * @param[in] controller This parameter specifies the core controller
1069  *            associated with the completion callback.
1070  * @param[in] remote_device This parameter specifies the remote device
1071  *            associated with the callback.
1072  *
1073  * @return none
1074  */
1075 void scic_cb_remote_device_ready(
1076    SCI_CONTROLLER_HANDLE_T     controller,
1077    SCI_REMOTE_DEVICE_HANDLE_T  remote_device
1078 );
1079
1080 /**
1081  * @brief This user callback method will inform the user that a remote
1082  *        device is no longer capable of handling IO requests (until a
1083  *        ready callback is invoked).
1084  *
1085  * @param[in] controller This parameter specifies the core controller
1086  *            associated with the completion callback.
1087  * @param[in] remote_device This parameter specifies the remote device
1088  *            associated with the callback.
1089  * @param[in] reason_code This paramete specifies the reason the remote
1090  *            device is not ready.
1091  *
1092  * @return none
1093  */
1094 void scic_cb_remote_device_not_ready(
1095    SCI_CONTROLLER_HANDLE_T     controller,
1096    SCI_REMOTE_DEVICE_HANDLE_T  remote_device,
1097    U32                         reason_code
1098 );
1099
1100
1101 /**
1102  * @brief This user callback method will inform the user that this controller
1103  *        is having unexpected error. The user can choose to reset the controller.
1104  * @param[in] controller The controller that is failed at the moment.
1105  *
1106  * @return none
1107  */
1108 void scic_cb_controller_error(
1109    SCI_CONTROLLER_HANDLE_T     controller,
1110    SCI_CONTROLLER_ERROR        error
1111 );
1112
1113
1114 #if !defined(DISABLE_ATAPI)
1115 /**
1116  * @brief This user callback gets from stp packet io's user request
1117  *           the CDB address.
1118  * @param[in] scic_user_io_request
1119  *
1120  * @return The cdb adress.
1121  */
1122 void * scic_cb_stp_packet_io_request_get_cdb_address(
1123    void * scic_user_io_request
1124 );
1125
1126 /**
1127  * @brief This user callback gets from stp packet io's user request
1128  *           the CDB length.
1129  * @param[in] scic_user_io_request
1130  *
1131  * @return The cdb length.
1132  */
1133 U32 scic_cb_stp_packet_io_request_get_cdb_length(
1134    void * scic_user_io_request
1135 );
1136 #else //!defined(DISABLE_ATAPI)
1137 #define scic_cb_stp_packet_io_request_get_cdb_address(scic_user_io_request) NULL
1138 #define scic_cb_stp_packet_io_request_get_cdb_length(scic_user_io_request) 0
1139 #endif //!defined(DISABLE_ATAPI)
1140
1141 #ifdef __cplusplus
1142 }
1143 #endif // __cplusplus
1144
1145 #endif // _SCIC_USER_CALLBACK_H_
1146