sys/dev/isci/scil/scic_controller.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_CONTROLLER_H_
  55 #define _SCIC_CONTROLLER_H_
  56
  57 /**
  58  * @file
  59  *
  60  * @brief This file contains all of the interface methods that can be called
  61  *        by an SCIC user on a controller object.
  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 #include <dev/isci/scil/scic_config_parameters.h>
  72
  73 /**
  74  * @enum
  75  *
  76  * Allowed PORT configuration modes
  77  *
  78  * APC Automatic PORT configuration mode is defined by the OEM configuration
  79  * parameters providing no PHY_MASK parameters for any PORT. i.e. There are
  80  * no phys assigned to any of the ports at start.
  81  *
  82  * MPC Manual PORT configuration mode is defined by the OEM configuration
  83  * parameters providing a PHY_MASK value for any PORT.  It is assumed that
  84  * any PORT with no PHY_MASK is an invalid port and not all PHYs must be
  85  * assigned. A PORT_PHY mask that assigns just a single PHY to a port and no
  86  * other PHYs being assigned is sufficient to declare manual PORT configuration.
  87  */
  88 enum SCIC_PORT_CONFIGURATION_MODE
  89 {
  90    SCIC_PORT_MANUAL_CONFIGURATION_MODE,
  91    SCIC_PORT_AUTOMATIC_CONFIGURATION_MODE
  92 };
  93
  94 /**
  95  * @enum _SCIC_INTERRUPT_TYPE
  96  *
  97  * @brief This enumeration depicts the various types of interrupts that
  98  *        are potentially supported by a SCI Core implementation.
  99  */
 100 typedef enum _SCIC_INTERRUPT_TYPE
 101 {
 102    SCIC_LEGACY_LINE_INTERRUPT_TYPE,
 103    SCIC_MSIX_INTERRUPT_TYPE,
 104
 105    /**
 106     * This enumeration value indicates the use of polling.
 107     */
 108    SCIC_NO_INTERRUPTS
 109
 110 } SCIC_INTERRUPT_TYPE;
 111
 112 /**
 113  * @typedef SCIC_CONTROLLER_INTERRUPT_HANDLER
 114  *
 115  * @brief This method is called by the SCI user in order to have the SCI
 116  *        implementation handle the interrupt.  This method performs
 117  *        minimal processing to allow for streamlined interrupt time usage.
 118  * @note
 119  *        TRUE: returned if there is an interrupt to process and it was
 120  *              processed.
 121  *        FALSE: returned if no interrupt was processed.
 122  *
 123  */
 124 typedef BOOL (*SCIC_CONTROLLER_INTERRUPT_HANDLER)(
 125    SCI_CONTROLLER_HANDLE_T  controller
 126 );
 127
 128 /**
 129  * @brief This method is called by the SCI user to process completions
 130  *        generated as a result of a previously handled interrupt.  This
 131  *        method will result in the completion of IO requests and handling
 132  *        of other controller generated events.  This method should be
 133  *        called some time after the interrupt handler.
 134  *
 135  * @note  Most, if not all, of the user callback APIs are invoked from within
 136  *        this API.  As a result, the user should be cognizent of the operating
 137  *        level at which they invoke this API.
 138  *
 139  */
 140 typedef void (*SCIC_CONTROLLER_COMPLETION_HANDLER)(
 141    SCI_CONTROLLER_HANDLE_T  controller
 142 );
 143
 144 /**
 145  * @struct SCIC_CONTROLLER_HANDLER_METHODS
 146  *
 147  * @brief This structure contains an interrupt handler and completion
 148  *        handler function pointers.
 149  */
 150 typedef struct SCIC_CONTROLLER_HANDLER_METHODS
 151 {
 152    SCIC_CONTROLLER_INTERRUPT_HANDLER  interrupt_handler;
 153    SCIC_CONTROLLER_COMPLETION_HANDLER completion_handler;
 154
 155 } SCIC_CONTROLLER_HANDLER_METHODS_T;
 156
 157 /**
 158  * @brief This method will attempt to construct a controller object
 159  *        utilizing the supplied parameter information.
 160  *
 161  * @param[in]  library This parameter specifies the handle to the library
 162  *             object associated with the controller being constructed.
 163  * @param[in]  controller This parameter specifies the controller to be
 164  *             constructed.
 165  * @param[in]  user_object This parameter is a reference to the SCIL users
 166  *             controller object and will be used to associate with the core
 167  *             controller.
 168  *
 169  * @return Indicate if the controller was successfully constructed or if
 170  *         it failed in some way.
 171  * @retval SCI_SUCCESS This value is returned if the controller was
 172  *         successfully constructed.
 173  * @retval SCI_WARNING_TIMER_CONFLICT This value is returned if the
 174  *         interrupt coalescence timer may cause SAS compliance issues
 175  *         for SMP Target mode response processing.
 176  * @retval SCI_FAILURE_UNSUPPORTED_CONTROLLER_TYPE This value is returned if
 177  *         the controller does not support the supplied type.
 178  * @retval SCI_FAILURE_UNSUPPORTED_INIT_DATA_VERSION This value is returned
 179  *         if the controller does not support the supplied initialization
 180  *         data version.
 181  */
 182 SCI_STATUS scic_controller_construct(
 183    SCI_LIBRARY_HANDLE_T      library,
 184    SCI_CONTROLLER_HANDLE_T   controller,
 185    void *                    user_object
 186 );
 187
 188 /**
 189  * @brief This method will enable all controller interrupts.
 190  *
 191  * @param[in]  controller This parameter specifies the controller for which
 192  *             to enable interrupts.
 193  *
 194  * @return none
 195  */
 196 void scic_controller_enable_interrupts(
 197    SCI_CONTROLLER_HANDLE_T      controller
 198 );
 199
 200 /**
 201  * @brief This method will disable all controller interrupts.
 202  *
 203  * @param[in]  controller This parameter specifies the controller for which
 204  *             to disable interrupts.
 205  *
 206  * @return none
 207  */
 208 void scic_controller_disable_interrupts(
 209    SCI_CONTROLLER_HANDLE_T      controller
 210 );
 211
 212 /**
 213  * @brief This method will return provide function pointers for the
 214  *        interrupt handler and completion handler.  The interrupt handler
 215  *        is expected to be invoked at interrupt time.  The completion
 216  *        handler is scheduled to run as a result of the interrupt handler.
 217  *        The completion handler performs the bulk work for processing
 218  *        silicon events.
 219  *
 220  * @param[in]  interrupt_type This parameter informs the core which type
 221  *             of interrupt/completion methods are being requested. These
 222  *             are the types: SCIC_LEGACY_LINE_INTERRUPT_TYPE,
 223  *             SCIC_MSIX_INTERRUPT_TYPE, SCIC_NO_INTERRUPTS (POLLING)
 224  * @param[in]  message_count This parameter informs the core the
 225  *             number of MSI-X messages to be utilized.  This parameter must
 226  *             be 0 when requesting legacy line based handlers.
 227  * @param[in]  handler_methods The caller provides a pointer to a buffer of
 228  *             type SCIC_CONTROLLER_HANDLER_METHODS_T. The size depends on
 229  *             the combination of the interrupt_type and message_count input
 230  *             parameters:
 231  *             SCIC_LEGACY_LINE_INTERRUPT_TYPE:
 232  *             - size = sizeof(SCIC_CONTROLLER_HANDLER_METHODS_T)
 233  *             SCIC_MSIX_INTERRUPT_TYPE:
 234  *             - size = message_count*sizeof(SCIC_CONTROLLER_HANDLER_METHODS_T)
 235  * @param[out] handler_methods SCIC fills out the caller's buffer with the
 236  *             appropriate interrupt and completion handlers based on the info
 237  *             provided in the interrupt_type and message_count input
 238  *             parameters. For SCIC_LEGACY_LINE_INTERRUPT_TYPE, the buffer
 239  *             receives a single SCIC_CONTROLLER_HANDLER_METHODS_T element
 240  *             regardless that the message_count parameter is zero.
 241  *             For SCIC_MSIX_INTERRUPT_TYPE, the buffer receives an array of
 242  *             elements of type SCIC_CONTROLLER_HANDLER_METHODS_T where the
 243  *             array size is equivalent to the message_count parameter. The
 244  *             array is zero-relative where entry zero corresponds to
 245  *             message-vector zero, entry one corresponds to message-vector one,
 246  *             and so forth.
 247  *
 248  * @return Indicate if the handler retrieval operation was successful.
 249  * @retval SCI_SUCCESS This value is returned if retrieval succeeded.
 250  * @retval SCI_FAILURE_UNSUPPORTED_MESSAGE_COUNT This value is returned
 251  *         if the user supplied an unsupported number of MSI-X messages.
 252  *         For legacy line interrupts the only valid value is 0.
 253  */
 254 SCI_STATUS scic_controller_get_handler_methods(
 255    SCIC_INTERRUPT_TYPE                  interrupt_type,
 256    U16                                  message_count,
 257    SCIC_CONTROLLER_HANDLER_METHODS_T *  handler_methods
 258 );
 259
 260 /**
 261  * @brief This method will initialize the controller hardware managed by
 262  *        the supplied core controller object.  This method will bring the
 263  *        physical controller hardware out of reset and enable the core to
 264  *        determine the capabilities of the hardware being managed.  Thus,
 265  *        the core controller can determine it's exact physical (DMA capable)
 266  *        memory requirements.
 267  *
 268  * @pre   The SCI Core user must have called scic_controller_construct()
 269  *        on the supplied controller object previously.
 270  *
 271  * @param[in]  controller This parameter specifies the controller to be
 272  *             initialized.
 273  *
 274  * @return Indicate if the controller was successfully initialized or if
 275  *         it failed in some way.
 276  * @retval SCI_SUCCESS This value is returned if the controller hardware
 277  *         was successfully initialized.
 278  */
 279 SCI_STATUS scic_controller_initialize(
 280    SCI_CONTROLLER_HANDLE_T   controller
 281 );
 282
 283 /**
 284  * @brief This method returns the suggested scic_controller_start()
 285  *        timeout amount.  The user is free to use any timeout value,
 286  *        but this method provides the suggested minimum start timeout
 287  *        value.  The returned value is based upon empirical information
 288  *        determined as a result of interoperability testing.
 289  *
 290  * @param[in]  controller the handle to the controller object for which
 291  *             to return the suggested start timeout.
 292  *
 293  * @return  This method returns the number of milliseconds for the
 294  *          suggested start operation timeout.
 295  */
 296 U32 scic_controller_get_suggested_start_timeout(
 297    SCI_CONTROLLER_HANDLE_T  controller
 298 );
 299
 300 /**
 301  * @brief This method will start the supplied core controller.  This method
 302  *        will start the staggered spin up operation.  The SCI User completion
 303  *        callback is called when the following conditions are met:
 304  *        -# the return status of this method is SCI_SUCCESS.
 305  *        -# after all of the phys have successfully started or been given
 306  *           the opportunity to start.
 307  *
 308  * @pre   The SCI Core user must have filled in the physical memory
 309  *        descriptor structure via the
 310  *        sci_controller_get_memory_descriptor_list() method.
 311  * @pre   The SCI Core user must have invoked the scic_controller_initialize()
 312  *        method prior to invoking this method.
 313  *
 314  * @pre   The controller must be in the INITIALIZED or STARTED state.
 315  *
 316  * @param[in]  controller the handle to the controller object to start.
 317  * @param[in]  timeout This parameter specifies the number of milliseconds
 318  *             in which the start operation should complete.
 319  *
 320  * @return Indicate if the controller start method succeeded or failed in
 321  *         some way.
 322  * @retval SCI_SUCCESS if the start operation succeeded.
 323  * @retval SCI_WARNING_ALREADY_IN_STATE if the controller is already in
 324  *         the STARTED state.
 325  * @retval SCI_FAILURE_INVALID_STATE if the controller is not either in
 326  *         the INITIALIZED or STARTED states.
 327  * @retval SCI_FAILURE_INVALID_MEMORY_DESCRIPTOR if there are
 328  *         inconsistent or invalid values in the supplied
 329  *         SCI_PHYSICAL_MEMORY_DESCRIPTOR array.
 330  */
 331 SCI_STATUS scic_controller_start(
 332    SCI_CONTROLLER_HANDLE_T  controller,
 333    U32                      timeout
 334 );
 335
 336 /**
 337  * @brief This method will stop an individual controller object.This method
 338  *        will invoke the associated user callback upon completion.  The
 339  *        completion callback is called when the following conditions are met:
 340  *           -# the method return status is SCI_SUCCESS.
 341  *           -# the controller has been quiesced.
 342  *        This method will ensure that all IO requests are quiesced, phys
 343  *        are stopped, and all additional operation by the hardware is halted.
 344  *
 345  * @pre   The controller must be in the STARTED or STOPPED state.
 346  *
 347  * @param[in]  controller the handle to the controller object to stop.
 348  * @param[in]  timeout This parameter specifies the number of milliseconds
 349  *             in which the stop operation should complete.
 350  *
 351  * @return Indicate if the controller stop method succeeded or failed in
 352  *         some way.
 353  * @retval SCI_SUCCESS if the stop operation successfully began.
 354  * @retval SCI_WARNING_ALREADY_IN_STATE if the controller is already in
 355  *         the STOPPED state.
 356  * @retval SCI_FAILURE_INVALID_STATE if the controller is not either in
 357  *         the STARTED or STOPPED states.
 358  */
 359 SCI_STATUS scic_controller_stop(
 360    SCI_CONTROLLER_HANDLE_T  controller,
 361    U32                      timeout
 362 );
 363
 364 /**
 365  * @brief This method will reset the supplied core controller regardless of
 366  *        the state of said controller.  This operation is considered
 367  *        destructive.  In other words, all current operations are wiped
 368  *        out.  No IO completions for outstanding devices occur.  Outstanding
 369  *        IO requests are not aborted or completed at the actual remote
 370  *        device.
 371  *
 372  * @param[in]  controller the handle to the controller object to reset.
 373  *
 374  * @return Indicate if the controller reset method succeeded or failed in
 375  *         some way.
 376  * @retval SCI_SUCCESS if the reset operation successfully started.
 377  * @retval SCI_FATAL_ERROR if the controller reset operation is unable to
 378  *         complete.
 379  */
 380 SCI_STATUS scic_controller_reset(
 381    SCI_CONTROLLER_HANDLE_T  controller
 382 );
 383
 384 /**
 385  * @brief This method is called by the SCI user to send/start an IO request.
 386  *        If the method invocation is successful, then the IO request has
 387  *        been queued to the hardware for processing.
 388  *
 389  * @warning
 390  *         - IO tags are a protected resource.  It is incumbent upon the
 391  *           SCI Core user to ensure that each of the methods that may
 392  *           allocate or free available IO tags are handled in a mutually
 393  *           exclusive manner.  This method is one of said methods requiring
 394  *           proper critical code section protection (e.g. semaphore,
 395  *           spin-lock, etc.).
 396  *         - For SATA, the user is required to manage NCQ tags.  As a
 397  *           result, it is expected the user will have set the NCQ tag
 398  *           field in the host to device register FIS prior to calling
 399  *           this method.  There is also a requirement for the user
 400  *           to call scic_stp_io_set_ncq_tag() prior to invoking the
 401  *           scic_controller_start_io() method.
 402  *
 403  * @param[in]  controller the handle to the controller object for which
 404  *             to start an IO request.
 405  * @param[in]  remote_device the handle to the remote device object for which
 406  *             to start an IO request.
 407  * @param[in]  io_request the handle to the io request object to start.
 408  * @param[in]  io_tag This parameter specifies a previously allocated IO tag
 409  *             that the user desires to be utilized for this request.
 410  *             This parameter is optional.  The user is allowed to supply
 411  *             SCI_CONTROLLER_INVALID_IO_TAG as the value for this parameter.
 412  *             @see scic_controller_allocate_tag() for more information
 413  *             on allocating a tag.
 414  *
 415  * @return Indicate if the controller successfully started the IO request.
 416  * @retval SCI_IO_SUCCESS if the IO request was successfully started.
 417  *
 418  * @todo Determine the failure situations and return values.
 419  */
 420 SCI_IO_STATUS scic_controller_start_io(
 421    SCI_CONTROLLER_HANDLE_T     controller,
 422    SCI_REMOTE_DEVICE_HANDLE_T  remote_device,
 423    SCI_IO_REQUEST_HANDLE_T     io_request,
 424    U16                         io_tag
 425 );
 426
 427 #if !defined(DISABLE_TASK_MANAGEMENT)
 428
 429 /**
 430  * @brief This method is called by the SCIC user to send/start a framework
 431  *        task management request.
 432  *
 433  * @warning
 434  *         - IO tags are a protected resource.  It is incumbent upon the
 435  *           SCI Core user to ensure that each of the methods that may
 436  *           allocate or free available IO tags are handled in a mutually
 437  *           exclusive manner.  This method is one of said methods requiring
 438  *           proper critical code section protection (e.g. semaphore,
 439  *           spin-lock, etc.).
 440  *         - The user must synchronize this task with completion queue
 441  *           processing.  If they are not synchronized then it is possible
 442  *           for the io requests that are being managed by the task request
 443  *           can complete before starting the task request.
 444  *
 445  * @param[in]  controller the handle to the controller object for which
 446  *             to start the task management request.
 447  * @param[in]  remote_device the handle to the remote device object for which
 448  *             to start the task management request.
 449  * @param[in]  task_request the handle to the task request object to start.
 450  * @param[in]  io_tag This parameter specifies a previously allocated IO tag
 451  *             that the user desires to be utilized for this request.  Note
 452  *             this not the io_tag of the request being managed.  It is to
 453  *             be utilized for the task request itself.
 454  *             This parameter is optional.  The user is allowed to supply
 455  *             SCI_CONTROLLER_INVALID_IO_TAG as the value for this parameter.
 456  *             @see scic_controller_allocate_tag() for more information
 457  *             on allocating a tag.
 458  *
 459  * @return Indicate if the controller successfully started the IO request.
 460  * @retval SCI_TASK_SUCCESS if the task request was successfully started.
 461  * @retval SCI_TASK_FAILURE_REQUIRES_SCSI_ABORT This value is returned if
 462  *         there is/are task(s) outstanding that require termination or
 463  *         completion before this request can succeed.
 464  */
 465 SCI_TASK_STATUS scic_controller_start_task(
 466    SCI_CONTROLLER_HANDLE_T     controller,
 467    SCI_REMOTE_DEVICE_HANDLE_T  remote_device,
 468    SCI_TASK_REQUEST_HANDLE_T   task_request,
 469    U16                         io_tag
 470 );
 471
 472 /**
 473  * @brief This method will perform core specific completion operations for
 474  *        task management request. After this method is invoked, the user should
 475  *        consider the task request as invalid until it is properly reused
 476  *        (i.e. re-constructed).
 477  *
 478  * @param[in]  controller The handle to the controller object for which
 479  *             to complete the task management request.
 480  * @param[in]  remote_device The handle to the remote device object for which
 481  *             to complete the task management request.
 482  * @param[in]  task_request the handle to the task management request object
 483  *             to complete.
 484  *
 485  * @return Indicate if the controller successfully completed the task
 486  *         management request.
 487  * @retval SCI_SUCCESS if the completion process was successful.
 488  */
 489 SCI_STATUS scic_controller_complete_task(
 490    SCI_CONTROLLER_HANDLE_T     controller,
 491    SCI_REMOTE_DEVICE_HANDLE_T  remote_device,
 492    SCI_TASK_REQUEST_HANDLE_T   task_request
 493 );
 494
 495 #else // !defined(DISABLE_TASK_MANAGEMENT)
 496
 497 #define scic_controller_start_task(controller, dev, task, tag) SCI_TASK_FAILURE
 498 #define scic_controller_complete_task(controller, dev, task) SCI_FAILURE
 499
 500 #endif // !defined(DISABLE_TASK_MANAGEMENT)
 501
 502 /**
 503  * @brief This method is called by the SCI Core user to terminate an ongoing
 504  *        (i.e. started) core IO request.  This does not abort the IO request
 505  *        at the target, but rather removes the IO request from the host
 506  *        controller.
 507  *
 508  * @param[in]  controller the handle to the controller object for which
 509  *             to terminate a request.
 510  * @param[in]  remote_device the handle to the remote device object for which
 511  *             to terminate a request.
 512  * @param[in]  request the handle to the io or task management request
 513  *             object to terminate.
 514  *
 515  * @return Indicate if the controller successfully began the terminate process
 516  *         for the IO request.
 517  * @retval SCI_SUCCESS if the terminate process was successfully started for
 518  *         the request.
 519  *
 520  * @todo Determine the failure situations and return values.
 521  */
 522 SCI_STATUS scic_controller_terminate_request(
 523    SCI_CONTROLLER_HANDLE_T     controller,
 524    SCI_REMOTE_DEVICE_HANDLE_T  remote_device,
 525    SCI_IO_REQUEST_HANDLE_T     request
 526 );
 527
 528 /**
 529  * @brief This method will perform core specific completion operations for
 530  *        an IO request.  After this method is invoked, the user should
 531  *        consider the IO request as invalid until it is properly reused
 532  *        (i.e. re-constructed).
 533  *
 534  * @warning
 535  *        - IO tags are a protected resource.  It is incumbent upon the
 536  *          SCI Core user to ensure that each of the methods that may
 537  *          allocate or free available IO tags are handled in a mutually
 538  *          exclusive manner.  This method is one of said methods requiring
 539  *          proper critical code section protection (e.g. semaphore,
 540  *          spin-lock, etc.).
 541  *        - If the IO tag for a request was allocated, by the SCI Core user,
 542  *          using the scic_controller_allocate_io_tag() method, then it is
 543  *          the responsibility of the caller to invoke the
 544  *          scic_controller_free_io_tag() method to free the tag (i.e. this
 545  *          method will not free the IO tag).
 546  *
 547  * @param[in]  controller The handle to the controller object for which
 548  *             to complete the IO request.
 549  * @param[in]  remote_device The handle to the remote device object for which
 550  *             to complete the IO request.
 551  * @param[in]  io_request the handle to the io request object to complete.
 552  *
 553  * @return Indicate if the controller successfully completed the IO request.
 554  * @retval SCI_SUCCESS if the completion process was successful.
 555  */
 556 SCI_STATUS scic_controller_complete_io(
 557    SCI_CONTROLLER_HANDLE_T     controller,
 558    SCI_REMOTE_DEVICE_HANDLE_T  remote_device,
 559    SCI_IO_REQUEST_HANDLE_T     io_request
 560 );
 561
 562
 563 /**
 564  * @brief This method simply provides the user with a unique handle for a
 565  *        given SAS/SATA core port index.
 566  *
 567  * @param[in]  controller This parameter represents the handle to the
 568  *             controller object from which to retrieve a port (SAS or
 569  *             SATA) handle.
 570  * @param[in]  port_index This parameter specifies the port index in
 571  *             the controller for which to retrieve the port handle.
 572  *             0 <= port_index < maximum number of phys.
 573  * @param[out] port_handle This parameter specifies the retrieved port handle
 574  *             to be provided to the caller.
 575  *
 576  * @return Indicate if the retrieval of the port handle was successful.
 577  * @retval SCI_SUCCESS This value is returned if the retrieval was successful.
 578  * @retval SCI_FAILURE_INVALID_PORT This value is returned if the supplied
 579  *         port id is not in the supported range.
 580  */
 581 SCI_STATUS scic_controller_get_port_handle(
 582    SCI_CONTROLLER_HANDLE_T   controller,
 583    U8                        port_index,
 584    SCI_PORT_HANDLE_T       * port_handle
 585 );
 586
 587 /**
 588  * @brief This method simply provides the user with a unique handle for a
 589  *        given SAS/SATA phy index/identifier.
 590  *
 591  * @param[in]  controller This parameter represents the handle to the
 592  *             controller object from which to retrieve a phy (SAS or
 593  *             SATA) handle.
 594  * @param[in]  phy_index This parameter specifies the phy index in
 595  *             the controller for which to retrieve the phy handle.
 596  *             0 <= phy_index < maximum number of phys.
 597  * @param[out] phy_handle This parameter specifies the retrieved phy handle
 598  *             to be provided to the caller.
 599  *
 600  * @return Indicate if the retrieval of the phy handle was successful.
 601  * @retval SCI_SUCCESS This value is returned if the retrieval was successful.
 602  * @retval SCI_FAILURE_INVALID_PHY This value is returned if the supplied phy
 603  *         id is not in the supported range.
 604  */
 605 SCI_STATUS scic_controller_get_phy_handle(
 606    SCI_CONTROLLER_HANDLE_T   controller,
 607    U8                        phy_index,
 608    SCI_PHY_HANDLE_T        * phy_handle
 609 );
 610
 611 /**
 612  * @brief This method will allocate a tag from the pool of free IO tags.
 613  *        Direct allocation of IO tags by the SCI Core user is optional.
 614  *        The scic_controller_start_io() method will allocate an IO
 615  *        tag if this method is not utilized and the tag is not
 616  *        supplied to the IO construct routine.  Direct allocation of IO tags
 617  *        may provide additional performance improvements in environments
 618  *        capable of supporting this usage model.  Additionally, direct
 619  *        allocation of IO tags also provides additional flexibility to the
 620  *        SCI Core user.  Specifically, the user may retain IO tags across
 621  *        the lives of multiple IO requests.
 622  *
 623  * @warning IO tags are a protected resource.  It is incumbent upon the
 624  *          SCI Core user to ensure that each of the methods that may
 625  *          allocate or free available IO tags are handled in a mutually
 626  *          exclusive manner.  This method is one of said methods requiring
 627  *          proper critical code section protection (e.g. semaphore,
 628  *          spin-lock, etc.).
 629  *
 630  * @param[in]  controller the handle to the controller object for which to
 631  *             allocate the tag.
 632  *
 633  * @return An unsigned integer representing an available IO tag.
 634  * @retval SCI_CONTROLLER_INVALID_IO_TAG This value is returned if there
 635  *         are no currently available tags to be allocated.
 636  * @retval All return other values indicate a legitimate tag.
 637  */
 638 U16 scic_controller_allocate_io_tag(
 639    SCI_CONTROLLER_HANDLE_T  controller
 640 );
 641
 642 /**
 643  * @brief This method will free an IO tag to the pool of free IO tags.
 644  *        This method provides the SCI Core user more flexibility with
 645  *        regards to IO tags.  The user may desire to keep an IO tag after
 646  *        an IO request has completed, because they plan on re-using the
 647  *        tag for a subsequent IO request.  This method is only legal if
 648  *        the tag was allocated via scic_controller_allocate_io_tag().
 649  *
 650  * @warning
 651  *        - IO tags are a protected resource.  It is incumbent upon the
 652  *          SCI Core user to ensure that each of the methods that may
 653  *          allocate or free available IO tags are handled in a mutually
 654  *          exclusive manner.  This method is one of said methods requiring
 655  *          proper critical code section protection (e.g. semaphore,
 656  *          spin-lock, etc.).
 657  *        - If the IO tag for a request was allocated, by the SCI Core user,
 658  *          using the scic_controller_allocate_io_tag() method, then it is
 659  *          the responsibility of the caller to invoke this method to free
 660  *          the tag.
 661  *
 662  * @param[in]  controller This parameter specifies the handle to the
 663  *             controller object for which to free/return the tag.
 664  * @param[in]  io_tag This parameter represents the tag to be freed to the
 665  *             pool of available tags.
 666  *
 667  * @return This method returns an indication of whether the tag was
 668  *         successfully put back (freed) to the pool of available tags.
 669  * @retval SCI_SUCCESS This return value indicates the tag was successfully
 670  *         placed into the pool of available IO tags.
 671  * @retval SCI_FAILURE_INVALID_IO_TAG This value is returned if the supplied
 672  *         tag is not a valid IO tag value.
 673  */
 674 SCI_STATUS scic_controller_free_io_tag(
 675    SCI_CONTROLLER_HANDLE_T  controller,
 676    U16                      io_tag
 677 );
 678
 679 /**
 680  * @brief This method returns the size of the core's scratch RAM.
 681  *
 682  * @return Size of the scratch RAM in dwords.
 683  */
 684 U32 scic_controller_get_scratch_ram_size(
 685    SCI_CONTROLLER_HANDLE_T   controller
 686 );
 687
 688 /**
 689  * @brief This method allows the user to read a U32 from the core's
 690  *        scratch RAM.
 691  *
 692  * @param[in]  controller This parameter represents the handle to the
 693  *             controller object for which to read scratch RAM.
 694  * @param[in]  offset The offset (in dwords) into the scratch RAM.
 695  * @param[out] value The location where the read value should be stored.
 696  *
 697  * @return Indicate if the user specified a valid offset into the
 698  *         scratch RAM.
 699  * @retval SCI_SUCCESS The scratch RAM was successfully read.
 700  * @retval SCI_FAILURE_INVALID_PARAMETER_VALUE The user specified an
 701  *          invalid offset.
 702  */
 703 SCI_STATUS scic_controller_read_scratch_ram_dword(
 704    SCI_CONTROLLER_HANDLE_T   controller,
 705    U32                       offset,
 706    U32                     * value
 707 );
 708
 709 /**
 710  * @brief This method allows the user to write a U32 to the core's
 711  *        scratch RAM.
 712  *
 713  * @param[in]  controller This parameter represents the handle to the
 714  *             controller object for which to write scratch RAM.
 715  * @param[in]  offset The offset (in dwords) into the scratch RAM.
 716  * @param[out] value The value to be written to scratch RAM.
 717  *
 718  * @return Indicate if the user specified a valid offset into the
 719  *         scratch RAM.
 720  * @retval SCI_SUCCESS The scratch RAM was successfully written.
 721  * @retval SCI_FAILURE_INVALID_PARAMETER_VALUE The user specified an
 722  *          invalid offset.
 723  */
 724 SCI_STATUS scic_controller_write_scratch_ram_dword(
 725     SCI_CONTROLLER_HANDLE_T   controller,
 726     U32                       offset,
 727     U32                       value
 728 );
 729
 730 /**
 731  * @brief This method allows the user to configure the SCI core into
 732  *        either a performance mode or a memory savings mode.
 733  *
 734  * @param[in]  controller This parameter represents the handle to the
 735  *             controller object for which to update the operating
 736  *             mode.
 737  * @param[in]  mode This parameter specifies the new mode for the
 738  *             controller.
 739  *
 740  * @return Indicate if the user successfully change the operating mode
 741  *         of the controller.
 742  * @retval SCI_SUCCESS The user successfully updated the mode.
 743  */
 744 SCI_STATUS scic_controller_set_mode(
 745    SCI_CONTROLLER_HANDLE_T   controller,
 746    SCI_CONTROLLER_MODE       mode
 747 );
 748
 749
 750 #if !defined(DISABLE_INTERRUPTS)
 751 /**
 752  * @brief This method allows the user to configure the interrupt coalescence.
 753  *
 754  * @param[in]  controller This parameter represents the handle to the
 755  *                controller object for which its interrupt coalesce register
 756  *                is overridden.
 757  *
 758  * @param[in]  coalesce_number Used to control the number of entries in the
 759  *                Completion Queue before an interrupt is generated. If the
 760  *                number of entries exceed this number, an interrupt will be
 761  *                generated. The valid range of the input is [0, 256].
 762  *                A setting of 0 results in coalescing being disabled.
 763  * @param[in]  coalesce_timeout Timeout value in microseconds. The valid range
 764  *                of the input is [0, 2700000] . A setting of 0 is allowed and
 765  *                results in no interrupt coalescing timeout.
 766  *
 767  * @return Indicate if the user successfully set the interrupt coalesce parameters.
 768  * @retval SCI_SUCCESS The user successfully updated the interrutp coalescence.
 769  * @retval SCI_FAILURE_INVALID_PARAMETER_VALUE The user input value is out of range.
 770  */
 771 SCI_STATUS scic_controller_set_interrupt_coalescence(
 772    SCI_CONTROLLER_HANDLE_T controller,
 773    U32                     coalesce_number,
 774    U32                     coalesce_timeout
 775 );
 776
 777 /**
 778  * @brief This method retrieves the interrupt coalescing values
 779  *
 780  * @param[in] controller This parameter specifies the controller for
 781  *            which its interrupt coalescing number is read.
 782  *
 783  * @param[out] coalesce_number, interrupt coalescing number read from controller.
 784  *
 785  * @param[out] coalesce_timeout, timeout value in microseconds.
 786  *
 787  * @return None
 788  */
 789 void scic_controller_get_interrupt_coalescence(
 790    SCI_CONTROLLER_HANDLE_T   controller,
 791    U32                     * coalesce_number,
 792    U32                     * coalesce_timeout
 793 );
 794 #else // !defined(DISABLE_INTERRUPTS)
 795 #define scic_controller_set_interrupt_coalescence(controller, num, timeout) \
 796         SCI_FAILURE
 797 #define scic_controller_get_interrupt_coalescence(controller, num, timeout)
 798 #endif // !defined(DISABLE_INTERRUPTS)
 799
 800
 801 /**
 802  * @brief This method suspend the controller, reinitialize RAMs, then resume
 803  *           the controller.
 804  *
 805  * @param[in] controller This parameter specifies the controller which is transitioning.
 806  *
 807  * @param[in] restrict_completions This parameter specifies whether the controller should
 808  *               ignore completion processing for non-fastpath events.  This will cause
 809  *               the completions to be thrown away.
 810  *
 811  * @return SCI_STATUS The status of controller transition.
 812  */
 813 SCI_STATUS scic_controller_transition(
 814    SCI_CONTROLLER_HANDLE_T   controller,
 815    BOOL                      restrict_completions
 816 );
 817
 818
 819 /**
 820  * @brief This method suspends the controller.
 821  *
 822  * @param[in] controller This parameter specifies the controller which is to be suspended.
 823  *
 824  * @return SCI_STATUS The status of controller suspend.
 825  */
 826 SCI_STATUS scic_controller_suspend(
 827    SCI_CONTROLLER_HANDLE_T   controller
 828 );
 829
 830 /**
 831  * @brief This method resumes the controller.
 832  *
 833  * @param[in] controller This parameter specifies the controller which is to be resumed.
 834  *
 835  * @return SCI_STATUS The status of controller resume.
 836  */
 837 SCI_STATUS scic_controller_resume(
 838    SCI_CONTROLLER_HANDLE_T   controller
 839 );
 840
 841 SCI_STATUS scic_controller_get_max_ports(
 842    SCI_CONTROLLER_HANDLE_T   controller,
 843    U8                      * count
 844 );
 845
 846 SCI_STATUS scic_controller_get_max_phys(
 847    SCI_CONTROLLER_HANDLE_T   controller,
 848    U8                      * count
 849 );
 850
 851 #ifdef __cplusplus
 852 }
 853 #endif // __cplusplus
 854
 855 #endif // _SCIC_CONTROLLER_H_
 856