FreeBSD/Linux Kernel Cross Reference
sys/dev/isci/scil/scic_controller.h

     /*-
      * SPDX-License-Identifier: BSD-2-Clause OR GPL-2.0
      *
      * This file is provided under a dual BSD/GPLv2 license.  When using or
      * redistributing this file, you may do so under either license.
      *
      * GPL LICENSE SUMMARY
      *
      * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
     *
     * This program is free software; you can redistribute it and/or modify
     * it under the terms of version 2 of the GNU General Public License as
     * published by the Free Software Foundation.
     *
     * This program is distributed in the hope that it will be useful, but
     * WITHOUT ANY WARRANTY; without even the implied warranty of
     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     * General Public License for more details.
     *
     * You should have received a copy of the GNU General Public License
     * along with this program; if not, write to the Free Software
     * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA.
     * The full GNU General Public License is included in this distribution
     * in the file called LICENSE.GPL.
     *
     * BSD LICENSE
     *
     * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
     * All rights reserved.
     *
     * Redistribution and use in source and binary forms, with or without
     * modification, are permitted provided that the following conditions
     * are met:
     *
     *   * Redistributions of source code must retain the above copyright
     *     notice, this list of conditions and the following disclaimer.
     *   * Redistributions in binary form must reproduce the above copyright
     *     notice, this list of conditions and the following disclaimer in
     *     the documentation and/or other materials provided with the
     *     distribution.
     *
     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
     * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
     * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
     * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
     * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
     * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
     * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
     * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
     * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
     * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     *
     * $FreeBSD$
     */
    #ifndef _SCIC_CONTROLLER_H_
    #define _SCIC_CONTROLLER_H_
    
    /**
     * @file
     *
     * @brief This file contains all of the interface methods that can be called
     *        by an SCIC user on a controller object.
     */
    
    #ifdef __cplusplus
    extern "C" {
    #endif // __cplusplus
    
    #include <dev/isci/scil/sci_types.h>
    #include <dev/isci/scil/sci_status.h>
    #include <dev/isci/scil/sci_controller.h>
    #include <dev/isci/scil/scic_config_parameters.h>
    
    /**
     * @enum
     *
     * Allowed PORT configuration modes
     *
     * APC Automatic PORT configuration mode is defined by the OEM configuration
     * parameters providing no PHY_MASK parameters for any PORT. i.e. There are
     * no phys assigned to any of the ports at start.
     *
     * MPC Manual PORT configuration mode is defined by the OEM configuration
     * parameters providing a PHY_MASK value for any PORT.  It is assumed that
     * any PORT with no PHY_MASK is an invalid port and not all PHYs must be
     * assigned. A PORT_PHY mask that assigns just a single PHY to a port and no
     * other PHYs being assigned is sufficient to declare manual PORT configuration.
     */
    enum SCIC_PORT_CONFIGURATION_MODE
    {
       SCIC_PORT_MANUAL_CONFIGURATION_MODE,
       SCIC_PORT_AUTOMATIC_CONFIGURATION_MODE
    };
    
    /**
     * @enum _SCIC_INTERRUPT_TYPE
     *
     * @brief This enumeration depicts the various types of interrupts that
    *        are potentially supported by a SCI Core implementation.
    */
   typedef enum _SCIC_INTERRUPT_TYPE
   {
      SCIC_LEGACY_LINE_INTERRUPT_TYPE,
      SCIC_MSIX_INTERRUPT_TYPE,
   
      /**
       * This enumeration value indicates the use of polling.
       */
      SCIC_NO_INTERRUPTS
   
   } SCIC_INTERRUPT_TYPE;
   
   /**
    * @typedef SCIC_CONTROLLER_INTERRUPT_HANDLER
    *
    * @brief This method is called by the SCI user in order to have the SCI
    *        implementation handle the interrupt.  This method performs
    *        minimal processing to allow for streamlined interrupt time usage.
    * @note
    *        TRUE: returned if there is an interrupt to process and it was
    *              processed.
    *        FALSE: returned if no interrupt was processed.
    *
    */
   typedef BOOL (*SCIC_CONTROLLER_INTERRUPT_HANDLER)(
      SCI_CONTROLLER_HANDLE_T  controller
   );
   
   /**
    * @brief This method is called by the SCI user to process completions
    *        generated as a result of a previously handled interrupt.  This
    *        method will result in the completion of IO requests and handling
    *        of other controller generated events.  This method should be
    *        called some time after the interrupt handler.
    *
    * @note  Most, if not all, of the user callback APIs are invoked from within
    *        this API.  As a result, the user should be cognizant of the operating
    *        level at which they invoke this API.
    *
    */
   typedef void (*SCIC_CONTROLLER_COMPLETION_HANDLER)(
      SCI_CONTROLLER_HANDLE_T  controller
   );
   
   /**
    * @struct SCIC_CONTROLLER_HANDLER_METHODS
    *
    * @brief This structure contains an interrupt handler and completion
    *        handler function pointers.
    */
   typedef struct SCIC_CONTROLLER_HANDLER_METHODS
   {
      SCIC_CONTROLLER_INTERRUPT_HANDLER  interrupt_handler;
      SCIC_CONTROLLER_COMPLETION_HANDLER completion_handler;
   
   } SCIC_CONTROLLER_HANDLER_METHODS_T;
   
   /**
    * @brief This method will attempt to construct a controller object
    *        utilizing the supplied parameter information.
    *
    * @param[in]  library This parameter specifies the handle to the library
    *             object associated with the controller being constructed.
    * @param[in]  controller This parameter specifies the controller to be
    *             constructed.
    * @param[in]  user_object This parameter is a reference to the SCIL users
    *             controller object and will be used to associate with the core
    *             controller.
    *
    * @return Indicate if the controller was successfully constructed or if
    *         it failed in some way.
    * @retval SCI_SUCCESS This value is returned if the controller was
    *         successfully constructed.
    * @retval SCI_WARNING_TIMER_CONFLICT This value is returned if the
    *         interrupt coalescence timer may cause SAS compliance issues
    *         for SMP Target mode response processing.
    * @retval SCI_FAILURE_UNSUPPORTED_CONTROLLER_TYPE This value is returned if
    *         the controller does not support the supplied type.
    * @retval SCI_FAILURE_UNSUPPORTED_INIT_DATA_VERSION This value is returned
    *         if the controller does not support the supplied initialization
    *         data version.
    */
   SCI_STATUS scic_controller_construct(
      SCI_LIBRARY_HANDLE_T      library,
      SCI_CONTROLLER_HANDLE_T   controller,
      void *                    user_object
   );
   
   /**
    * @brief This method will enable all controller interrupts.
    *
    * @param[in]  controller This parameter specifies the controller for which
    *             to enable interrupts.
    *
    * @return none
    */
   void scic_controller_enable_interrupts(
      SCI_CONTROLLER_HANDLE_T      controller
   );
   
   /**
    * @brief This method will disable all controller interrupts.
    *
    * @param[in]  controller This parameter specifies the controller for which
    *             to disable interrupts.
    *
    * @return none
    */
   void scic_controller_disable_interrupts(
      SCI_CONTROLLER_HANDLE_T      controller
   );
   
   /**
    * @brief This method will return provide function pointers for the
    *        interrupt handler and completion handler.  The interrupt handler
    *        is expected to be invoked at interrupt time.  The completion
    *        handler is scheduled to run as a result of the interrupt handler.
    *        The completion handler performs the bulk work for processing
    *        silicon events.
    *
    * @param[in]  interrupt_type This parameter informs the core which type
    *             of interrupt/completion methods are being requested. These
    *             are the types: SCIC_LEGACY_LINE_INTERRUPT_TYPE,
    *             SCIC_MSIX_INTERRUPT_TYPE, SCIC_NO_INTERRUPTS (POLLING)
    * @param[in]  message_count This parameter informs the core the
    *             number of MSI-X messages to be utilized.  This parameter must
    *             be 0 when requesting legacy line based handlers.
    * @param[in]  handler_methods The caller provides a pointer to a buffer of
    *             type SCIC_CONTROLLER_HANDLER_METHODS_T. The size depends on
    *             the combination of the interrupt_type and message_count input
    *             parameters:
    *             SCIC_LEGACY_LINE_INTERRUPT_TYPE:
    *             - size = sizeof(SCIC_CONTROLLER_HANDLER_METHODS_T)
    *             SCIC_MSIX_INTERRUPT_TYPE:
    *             - size = message_count*sizeof(SCIC_CONTROLLER_HANDLER_METHODS_T)
    * @param[out] handler_methods SCIC fills out the caller's buffer with the
    *             appropriate interrupt and completion handlers based on the info
    *             provided in the interrupt_type and message_count input
    *             parameters. For SCIC_LEGACY_LINE_INTERRUPT_TYPE, the buffer
    *             receives a single SCIC_CONTROLLER_HANDLER_METHODS_T element
    *             regardless that the message_count parameter is zero.
    *             For SCIC_MSIX_INTERRUPT_TYPE, the buffer receives an array of
    *             elements of type SCIC_CONTROLLER_HANDLER_METHODS_T where the
    *             array size is equivalent to the message_count parameter. The
    *             array is zero-relative where entry zero corresponds to
    *             message-vector zero, entry one corresponds to message-vector one,
    *             and so forth.
    *
    * @return Indicate if the handler retrieval operation was successful.
    * @retval SCI_SUCCESS This value is returned if retrieval succeeded.
    * @retval SCI_FAILURE_UNSUPPORTED_MESSAGE_COUNT This value is returned
    *         if the user supplied an unsupported number of MSI-X messages.
    *         For legacy line interrupts the only valid value is 0.
    */
   SCI_STATUS scic_controller_get_handler_methods(
      SCIC_INTERRUPT_TYPE                  interrupt_type,
      U16                                  message_count,
      SCIC_CONTROLLER_HANDLER_METHODS_T *  handler_methods
   );
   
   /**
    * @brief This method will initialize the controller hardware managed by
    *        the supplied core controller object.  This method will bring the
    *        physical controller hardware out of reset and enable the core to
    *        determine the capabilities of the hardware being managed.  Thus,
    *        the core controller can determine it's exact physical (DMA capable)
    *        memory requirements.
    *
    * @pre   The SCI Core user must have called scic_controller_construct()
    *        on the supplied controller object previously.
    *
    * @param[in]  controller This parameter specifies the controller to be
    *             initialized.
    *
    * @return Indicate if the controller was successfully initialized or if
    *         it failed in some way.
    * @retval SCI_SUCCESS This value is returned if the controller hardware
    *         was successfully initialized.
    */
   SCI_STATUS scic_controller_initialize(
      SCI_CONTROLLER_HANDLE_T   controller
   );
   
   /**
    * @brief This method returns the suggested scic_controller_start()
    *        timeout amount.  The user is free to use any timeout value,
    *        but this method provides the suggested minimum start timeout
    *        value.  The returned value is based upon empirical information
    *        determined as a result of interoperability testing.
    *
    * @param[in]  controller the handle to the controller object for which
    *             to return the suggested start timeout.
    *
    * @return  This method returns the number of milliseconds for the
    *          suggested start operation timeout.
    */
   U32 scic_controller_get_suggested_start_timeout(
      SCI_CONTROLLER_HANDLE_T  controller
   );
   
   /**
    * @brief This method will start the supplied core controller.  This method
    *        will start the staggered spin up operation.  The SCI User completion
    *        callback is called when the following conditions are met:
    *        -# the return status of this method is SCI_SUCCESS.
    *        -# after all of the phys have successfully started or been given
    *           the opportunity to start.
    *
    * @pre   The SCI Core user must have filled in the physical memory
    *        descriptor structure via the
    *        sci_controller_get_memory_descriptor_list() method.
    * @pre   The SCI Core user must have invoked the scic_controller_initialize()
    *        method prior to invoking this method.
    *
    * @pre   The controller must be in the INITIALIZED or STARTED state.
    *
    * @param[in]  controller the handle to the controller object to start.
    * @param[in]  timeout This parameter specifies the number of milliseconds
    *             in which the start operation should complete.
    *
    * @return Indicate if the controller start method succeeded or failed in
    *         some way.
    * @retval SCI_SUCCESS if the start operation succeeded.
    * @retval SCI_WARNING_ALREADY_IN_STATE if the controller is already in
    *         the STARTED state.
    * @retval SCI_FAILURE_INVALID_STATE if the controller is not either in
    *         the INITIALIZED or STARTED states.
    * @retval SCI_FAILURE_INVALID_MEMORY_DESCRIPTOR if there are
    *         inconsistent or invalid values in the supplied
    *         SCI_PHYSICAL_MEMORY_DESCRIPTOR array.
    */
   SCI_STATUS scic_controller_start(
      SCI_CONTROLLER_HANDLE_T  controller,
      U32                      timeout
   );
   
   /**
    * @brief This method will stop an individual controller object.This method
    *        will invoke the associated user callback upon completion.  The
    *        completion callback is called when the following conditions are met:
    *           -# the method return status is SCI_SUCCESS.
    *           -# the controller has been quiesced.
    *        This method will ensure that all IO requests are quiesced, phys
    *        are stopped, and all additional operation by the hardware is halted.
    *
    * @pre   The controller must be in the STARTED or STOPPED state.
    *
    * @param[in]  controller the handle to the controller object to stop.
    * @param[in]  timeout This parameter specifies the number of milliseconds
    *             in which the stop operation should complete.
    *
    * @return Indicate if the controller stop method succeeded or failed in
    *         some way.
    * @retval SCI_SUCCESS if the stop operation successfully began.
    * @retval SCI_WARNING_ALREADY_IN_STATE if the controller is already in
    *         the STOPPED state.
    * @retval SCI_FAILURE_INVALID_STATE if the controller is not either in
    *         the STARTED or STOPPED states.
    */
   SCI_STATUS scic_controller_stop(
      SCI_CONTROLLER_HANDLE_T  controller,
      U32                      timeout
   );
   
   /**
    * @brief This method will reset the supplied core controller regardless of
    *        the state of said controller.  This operation is considered
    *        destructive.  In other words, all current operations are wiped
    *        out.  No IO completions for outstanding devices occur.  Outstanding
    *        IO requests are not aborted or completed at the actual remote
    *        device.
    *
    * @param[in]  controller the handle to the controller object to reset.
    *
    * @return Indicate if the controller reset method succeeded or failed in
    *         some way.
    * @retval SCI_SUCCESS if the reset operation successfully started.
    * @retval SCI_FATAL_ERROR if the controller reset operation is unable to
    *         complete.
    */
   SCI_STATUS scic_controller_reset(
      SCI_CONTROLLER_HANDLE_T  controller
   );
   
   /**
    * @brief This method is called by the SCI user to send/start an IO request.
    *        If the method invocation is successful, then the IO request has
    *        been queued to the hardware for processing.
    *
    * @warning
    *         - IO tags are a protected resource.  It is incumbent upon the
    *           SCI Core user to ensure that each of the methods that may
    *           allocate or free available IO tags are handled in a mutually
    *           exclusive manner.  This method is one of said methods requiring
    *           proper critical code section protection (e.g. semaphore,
    *           spin-lock, etc.).
    *         - For SATA, the user is required to manage NCQ tags.  As a
    *           result, it is expected the user will have set the NCQ tag
    *           field in the host to device register FIS prior to calling
    *           this method.  There is also a requirement for the user
    *           to call scic_stp_io_set_ncq_tag() prior to invoking the
    *           scic_controller_start_io() method.
    *
    * @param[in]  controller the handle to the controller object for which
    *             to start an IO request.
    * @param[in]  remote_device the handle to the remote device object for which
    *             to start an IO request.
    * @param[in]  io_request the handle to the io request object to start.
    * @param[in]  io_tag This parameter specifies a previously allocated IO tag
    *             that the user desires to be utilized for this request.
    *             This parameter is optional.  The user is allowed to supply
    *             SCI_CONTROLLER_INVALID_IO_TAG as the value for this parameter.
    *             @see scic_controller_allocate_tag() for more information
    *             on allocating a tag.
    *
    * @return Indicate if the controller successfully started the IO request.
    * @retval SCI_IO_SUCCESS if the IO request was successfully started.
    *
    * @todo Determine the failure situations and return values.
    */
   SCI_IO_STATUS scic_controller_start_io(
      SCI_CONTROLLER_HANDLE_T     controller,
      SCI_REMOTE_DEVICE_HANDLE_T  remote_device,
      SCI_IO_REQUEST_HANDLE_T     io_request,
      U16                         io_tag
   );
   
   #if !defined(DISABLE_TASK_MANAGEMENT)
   
   /**
    * @brief This method is called by the SCIC user to send/start a framework
    *        task management request.
    *
    * @warning
    *         - IO tags are a protected resource.  It is incumbent upon the
    *           SCI Core user to ensure that each of the methods that may
    *           allocate or free available IO tags are handled in a mutually
    *           exclusive manner.  This method is one of said methods requiring
    *           proper critical code section protection (e.g. semaphore,
    *           spin-lock, etc.).
    *         - The user must synchronize this task with completion queue
    *           processing.  If they are not synchronized then it is possible
    *           for the io requests that are being managed by the task request
    *           can complete before starting the task request.
    *
    * @param[in]  controller the handle to the controller object for which
    *             to start the task management request.
    * @param[in]  remote_device the handle to the remote device object for which
    *             to start the task management request.
    * @param[in]  task_request the handle to the task request object to start.
    * @param[in]  io_tag This parameter specifies a previously allocated IO tag
    *             that the user desires to be utilized for this request.  Note
    *             this not the io_tag of the request being managed.  It is to
    *             be utilized for the task request itself.
    *             This parameter is optional.  The user is allowed to supply
    *             SCI_CONTROLLER_INVALID_IO_TAG as the value for this parameter.
    *             @see scic_controller_allocate_tag() for more information
    *             on allocating a tag.
    *
    * @return Indicate if the controller successfully started the IO request.
    * @retval SCI_TASK_SUCCESS if the task request was successfully started.
    * @retval SCI_TASK_FAILURE_REQUIRES_SCSI_ABORT This value is returned if
    *         there is/are task(s) outstanding that require termination or
    *         completion before this request can succeed.
    */
   SCI_TASK_STATUS scic_controller_start_task(
      SCI_CONTROLLER_HANDLE_T     controller,
      SCI_REMOTE_DEVICE_HANDLE_T  remote_device,
      SCI_TASK_REQUEST_HANDLE_T   task_request,
      U16                         io_tag
   );
   
   /**
    * @brief This method will perform core specific completion operations for
    *        task management request. After this method is invoked, the user should
    *        consider the task request as invalid until it is properly reused
    *        (i.e. re-constructed).
    *
    * @param[in]  controller The handle to the controller object for which
    *             to complete the task management request.
    * @param[in]  remote_device The handle to the remote device object for which
    *             to complete the task management request.
    * @param[in]  task_request the handle to the task management request object
    *             to complete.
    *
    * @return Indicate if the controller successfully completed the task
    *         management request.
    * @retval SCI_SUCCESS if the completion process was successful.
    */
   SCI_STATUS scic_controller_complete_task(
      SCI_CONTROLLER_HANDLE_T     controller,
      SCI_REMOTE_DEVICE_HANDLE_T  remote_device,
      SCI_TASK_REQUEST_HANDLE_T   task_request
   );
   
   #else // !defined(DISABLE_TASK_MANAGEMENT)
   
   #define scic_controller_start_task(controller, dev, task, tag) SCI_TASK_FAILURE
   #define scic_controller_complete_task(controller, dev, task) SCI_FAILURE
   
   #endif // !defined(DISABLE_TASK_MANAGEMENT)
   
   /**
    * @brief This method is called by the SCI Core user to terminate an ongoing
    *        (i.e. started) core IO request.  This does not abort the IO request
    *        at the target, but rather removes the IO request from the host
    *        controller.
    *
    * @param[in]  controller the handle to the controller object for which
    *             to terminate a request.
    * @param[in]  remote_device the handle to the remote device object for which
    *             to terminate a request.
    * @param[in]  request the handle to the io or task management request
    *             object to terminate.
    *
    * @return Indicate if the controller successfully began the terminate process
    *         for the IO request.
    * @retval SCI_SUCCESS if the terminate process was successfully started for
    *         the request.
    *
    * @todo Determine the failure situations and return values.
    */
   SCI_STATUS scic_controller_terminate_request(
      SCI_CONTROLLER_HANDLE_T     controller,
      SCI_REMOTE_DEVICE_HANDLE_T  remote_device,
      SCI_IO_REQUEST_HANDLE_T     request
   );
   
   /**
    * @brief This method will perform core specific completion operations for
    *        an IO request.  After this method is invoked, the user should
    *        consider the IO request as invalid until it is properly reused
    *        (i.e. re-constructed).
    *
    * @warning
    *        - IO tags are a protected resource.  It is incumbent upon the
    *          SCI Core user to ensure that each of the methods that may
    *          allocate or free available IO tags are handled in a mutually
    *          exclusive manner.  This method is one of said methods requiring
    *          proper critical code section protection (e.g. semaphore,
    *          spin-lock, etc.).
    *        - If the IO tag for a request was allocated, by the SCI Core user,
    *          using the scic_controller_allocate_io_tag() method, then it is
    *          the responsibility of the caller to invoke the
    *          scic_controller_free_io_tag() method to free the tag (i.e. this
    *          method will not free the IO tag).
    *
    * @param[in]  controller The handle to the controller object for which
    *             to complete the IO request.
    * @param[in]  remote_device The handle to the remote device object for which
    *             to complete the IO request.
    * @param[in]  io_request the handle to the io request object to complete.
    *
    * @return Indicate if the controller successfully completed the IO request.
    * @retval SCI_SUCCESS if the completion process was successful.
    */
   SCI_STATUS scic_controller_complete_io(
      SCI_CONTROLLER_HANDLE_T     controller,
      SCI_REMOTE_DEVICE_HANDLE_T  remote_device,
      SCI_IO_REQUEST_HANDLE_T     io_request
   );
   
   
   /**
    * @brief This method simply provides the user with a unique handle for a
    *        given SAS/SATA core port index.
    *
    * @param[in]  controller This parameter represents the handle to the
    *             controller object from which to retrieve a port (SAS or
    *             SATA) handle.
    * @param[in]  port_index This parameter specifies the port index in
    *             the controller for which to retrieve the port handle.
    *             0 <= port_index < maximum number of phys.
    * @param[out] port_handle This parameter specifies the retrieved port handle
    *             to be provided to the caller.
    *
    * @return Indicate if the retrieval of the port handle was successful.
    * @retval SCI_SUCCESS This value is returned if the retrieval was successful.
    * @retval SCI_FAILURE_INVALID_PORT This value is returned if the supplied
    *         port id is not in the supported range.
    */
   SCI_STATUS scic_controller_get_port_handle(
      SCI_CONTROLLER_HANDLE_T   controller,
      U8                        port_index,
      SCI_PORT_HANDLE_T       * port_handle
   );
   
   /**
    * @brief This method simply provides the user with a unique handle for a
    *        given SAS/SATA phy index/identifier.
    *
    * @param[in]  controller This parameter represents the handle to the
    *             controller object from which to retrieve a phy (SAS or
    *             SATA) handle.
    * @param[in]  phy_index This parameter specifies the phy index in
    *             the controller for which to retrieve the phy handle.
    *             0 <= phy_index < maximum number of phys.
    * @param[out] phy_handle This parameter specifies the retrieved phy handle
    *             to be provided to the caller.
    *
    * @return Indicate if the retrieval of the phy handle was successful.
    * @retval SCI_SUCCESS This value is returned if the retrieval was successful.
    * @retval SCI_FAILURE_INVALID_PHY This value is returned if the supplied phy
    *         id is not in the supported range.
    */
   SCI_STATUS scic_controller_get_phy_handle(
      SCI_CONTROLLER_HANDLE_T   controller,
      U8                        phy_index,
      SCI_PHY_HANDLE_T        * phy_handle
   );
   
   /**
    * @brief This method will allocate a tag from the pool of free IO tags.
    *        Direct allocation of IO tags by the SCI Core user is optional.
    *        The scic_controller_start_io() method will allocate an IO
    *        tag if this method is not utilized and the tag is not
    *        supplied to the IO construct routine.  Direct allocation of IO tags
    *        may provide additional performance improvements in environments
    *        capable of supporting this usage model.  Additionally, direct
    *        allocation of IO tags also provides additional flexibility to the
    *        SCI Core user.  Specifically, the user may retain IO tags across
    *        the lives of multiple IO requests.
    *
    * @warning IO tags are a protected resource.  It is incumbent upon the
    *          SCI Core user to ensure that each of the methods that may
    *          allocate or free available IO tags are handled in a mutually
    *          exclusive manner.  This method is one of said methods requiring
    *          proper critical code section protection (e.g. semaphore,
    *          spin-lock, etc.).
    *
    * @param[in]  controller the handle to the controller object for which to
    *             allocate the tag.
    *
    * @return An unsigned integer representing an available IO tag.
    * @retval SCI_CONTROLLER_INVALID_IO_TAG This value is returned if there
    *         are no currently available tags to be allocated.
    * @retval All return other values indicate a legitimate tag.
    */
   U16 scic_controller_allocate_io_tag(
      SCI_CONTROLLER_HANDLE_T  controller
   );
   
   /**
    * @brief This method will free an IO tag to the pool of free IO tags.
    *        This method provides the SCI Core user more flexibility with
    *        regards to IO tags.  The user may desire to keep an IO tag after
    *        an IO request has completed, because they plan on re-using the
    *        tag for a subsequent IO request.  This method is only legal if
    *        the tag was allocated via scic_controller_allocate_io_tag().
    *
    * @warning
    *        - IO tags are a protected resource.  It is incumbent upon the
    *          SCI Core user to ensure that each of the methods that may
    *          allocate or free available IO tags are handled in a mutually
    *          exclusive manner.  This method is one of said methods requiring
    *          proper critical code section protection (e.g. semaphore,
    *          spin-lock, etc.).
    *        - If the IO tag for a request was allocated, by the SCI Core user,
    *          using the scic_controller_allocate_io_tag() method, then it is
    *          the responsibility of the caller to invoke this method to free
    *          the tag.
    *
    * @param[in]  controller This parameter specifies the handle to the
    *             controller object for which to free/return the tag.
    * @param[in]  io_tag This parameter represents the tag to be freed to the
    *             pool of available tags.
    *
    * @return This method returns an indication of whether the tag was
    *         successfully put back (freed) to the pool of available tags.
    * @retval SCI_SUCCESS This return value indicates the tag was successfully
    *         placed into the pool of available IO tags.
    * @retval SCI_FAILURE_INVALID_IO_TAG This value is returned if the supplied
    *         tag is not a valid IO tag value.
    */
   SCI_STATUS scic_controller_free_io_tag(
      SCI_CONTROLLER_HANDLE_T  controller,
      U16                      io_tag
   );
   
   /**
    * @brief This method returns the size of the core's scratch RAM.
    *
    * @return Size of the scratch RAM in dwords.
    */
   U32 scic_controller_get_scratch_ram_size(
      SCI_CONTROLLER_HANDLE_T   controller
   );
   
   /**
    * @brief This method allows the user to read a U32 from the core's
    *        scratch RAM.
    *
    * @param[in]  controller This parameter represents the handle to the
    *             controller object for which to read scratch RAM.
    * @param[in]  offset The offset (in dwords) into the scratch RAM.
    * @param[out] value The location where the read value should be stored.
    *
    * @return Indicate if the user specified a valid offset into the
    *         scratch RAM.
    * @retval SCI_SUCCESS The scratch RAM was successfully read.
    * @retval SCI_FAILURE_INVALID_PARAMETER_VALUE The user specified an
    *          invalid offset.
    */
   SCI_STATUS scic_controller_read_scratch_ram_dword(
      SCI_CONTROLLER_HANDLE_T   controller,
      U32                       offset,
      U32                     * value
   );
   
   /**
    * @brief This method allows the user to write a U32 to the core's
    *        scratch RAM.
    *
    * @param[in]  controller This parameter represents the handle to the
    *             controller object for which to write scratch RAM.
    * @param[in]  offset The offset (in dwords) into the scratch RAM.
    * @param[out] value The value to be written to scratch RAM.
    *
    * @return Indicate if the user specified a valid offset into the
    *         scratch RAM.
    * @retval SCI_SUCCESS The scratch RAM was successfully written.
    * @retval SCI_FAILURE_INVALID_PARAMETER_VALUE The user specified an
    *          invalid offset.
    */
   SCI_STATUS scic_controller_write_scratch_ram_dword(
       SCI_CONTROLLER_HANDLE_T   controller,
       U32                       offset,
       U32                       value
   );
   
   /**
    * @brief This method allows the user to configure the SCI core into
    *        either a performance mode or a memory savings mode.
    *
    * @param[in]  controller This parameter represents the handle to the
    *             controller object for which to update the operating
    *             mode.
    * @param[in]  mode This parameter specifies the new mode for the
    *             controller.
    *
    * @return Indicate if the user successfully change the operating mode
    *         of the controller.
    * @retval SCI_SUCCESS The user successfully updated the mode.
    */
   SCI_STATUS scic_controller_set_mode(
      SCI_CONTROLLER_HANDLE_T   controller,
      SCI_CONTROLLER_MODE       mode
   );
   
   
   #if !defined(DISABLE_INTERRUPTS)
   /**
    * @brief This method allows the user to configure the interrupt coalescence.
    *
    * @param[in]  controller This parameter represents the handle to the
    *                controller object for which its interrupt coalesce register
    *                is overridden.
    *
    * @param[in]  coalesce_number Used to control the number of entries in the
    *                Completion Queue before an interrupt is generated. If the
    *                number of entries exceed this number, an interrupt will be
    *                generated. The valid range of the input is [0, 256].
    *                A setting of 0 results in coalescing being disabled.
    * @param[in]  coalesce_timeout Timeout value in microseconds. The valid range
    *                of the input is [0, 2700000] . A setting of 0 is allowed and
    *                results in no interrupt coalescing timeout.
    *
    * @return Indicate if the user successfully set the interrupt coalesce parameters.
    * @retval SCI_SUCCESS The user successfully updated the interrupt coalescence.
    * @retval SCI_FAILURE_INVALID_PARAMETER_VALUE The user input value is out of range.
    */
   SCI_STATUS scic_controller_set_interrupt_coalescence(
      SCI_CONTROLLER_HANDLE_T controller,
      U32                     coalesce_number,
      U32                     coalesce_timeout
   );
   
   /**
    * @brief This method retrieves the interrupt coalescing values
    *
    * @param[in] controller This parameter specifies the controller for
    *            which its interrupt coalescing number is read.
    *
    * @param[out] coalesce_number, interrupt coalescing number read from controller.
    *
    * @param[out] coalesce_timeout, timeout value in microseconds.
    *
    * @return None
    */
   void scic_controller_get_interrupt_coalescence(
      SCI_CONTROLLER_HANDLE_T   controller,
      U32                     * coalesce_number,
      U32                     * coalesce_timeout
   );
   #else // !defined(DISABLE_INTERRUPTS)
   #define scic_controller_set_interrupt_coalescence(controller, num, timeout) \
           SCI_FAILURE
   #define scic_controller_get_interrupt_coalescence(controller, num, timeout)
   #endif // !defined(DISABLE_INTERRUPTS)
   
   
   /**
    * @brief This method suspend the controller, reinitialize RAMs, then resume
    *           the controller.
    *
    * @param[in] controller This parameter specifies the controller which is transitioning.
    *
    * @param[in] restrict_completions This parameter specifies whether the controller should
    *               ignore completion processing for non-fastpath events.  This will cause
    *               the completions to be thrown away.
    *
    * @return SCI_STATUS The status of controller transition.
    */
   SCI_STATUS scic_controller_transition(
      SCI_CONTROLLER_HANDLE_T   controller,
      BOOL                      restrict_completions
   );
   
   
   /**
    * @brief This method suspends the controller.
    *
    * @param[in] controller This parameter specifies the controller which is to be suspended.
    *
    * @return SCI_STATUS The status of controller suspend.
    */
   SCI_STATUS scic_controller_suspend(
      SCI_CONTROLLER_HANDLE_T   controller
   );
   
   /**
    * @brief This method resumes the controller.
    *
    * @param[in] controller This parameter specifies the controller which is to be resumed.
    *
    * @return SCI_STATUS The status of controller resume.
    */
   SCI_STATUS scic_controller_resume(
      SCI_CONTROLLER_HANDLE_T   controller
   );
   
   SCI_STATUS scic_controller_get_max_ports(
      SCI_CONTROLLER_HANDLE_T   controller,
      U8                      * count
   );
   
   SCI_STATUS scic_controller_get_max_phys(
      SCI_CONTROLLER_HANDLE_T   controller,
      U8                      * count
   );
   
   #ifdef __cplusplus
   }
   #endif // __cplusplus
   
   #endif // _SCIC_CONTROLLER_H_
   

Cache object: ad7fcd392b6fa13fbdfb0f1fa0a92ee8