FreeBSD/Linux Kernel Cross Reference
sys/dev/isci/scil/scif_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 _SCIF_CONTROLLER_H_
    #define _SCIF_CONTROLLER_H_
    
    /**
     * @file
     *
     * @brief This file contains all of the interface methods that can be called
     *        by an SCIF user on a SCIF controller object.
     */
    
    #ifdef __cplusplus
    extern "C" {
    #endif // __cplusplus
    
    #include <dev/isci/scil/sci_types.h>
    #include <dev/isci/scil/sci_status.h>
    
    
    /**
     * @brief This method will attempt to construct a framework controller object
     *        utilizing the supplied parameter information.
     *
     * @param[in]  library This parameter specifies the handle to the framework
     *             library object associated with the controller being constructed.
     * @param[in]  controller This parameter specifies the framework 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
     *             framework 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_FAILURE_UNSUPPORTED_INIT_DATA_VERSION This value is returned
     *         if the controller does not support the supplied oem parameter
     *         data version.
     * @retval SCI_FAILURE_UNSUPPORTED_PORT_CONFIGURATION This value is returned
     *         if the controller doesn't support the port configuration scheme
     *         (APC or MPC).
     */
    SCI_STATUS scif_controller_construct(
       SCI_LIBRARY_HANDLE_T      library,
       SCI_CONTROLLER_HANDLE_T   controller,
      void *                    user_object
   );
   
   /**
    * @brief This method will initialize the SCI Framework controller object.
    *        This includes initialization of the associated core controller.
    *
    * @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 scif_controller_initialize(
      SCI_CONTROLLER_HANDLE_T  controller
   );
   
   /**
    * @brief This method returns the suggested scif_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 scif_controller_get_suggested_start_timeout(
      SCI_CONTROLLER_HANDLE_T  controller
   );
   
   /**
    * @brief This method will start the SCIF controller.  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 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.
    * @retval SCI_FAILURE_UNSUPPORTED_PORT_CONFIGURATION This value is
    *         returned if the phy to port allocation cannot be supported.
    *
    * @see For additional information please refer to: scic_controller_start()
    */
   SCI_STATUS scif_controller_start(
      SCI_CONTROLLER_HANDLE_T  controller,
      U32                      timeout
   );
   
   /**
    * @brief This method will stop an individual framework controller object. This
    *        includes quiescing IOs, releasing affiliations, and other shutdown
    *        related operations. 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 framework IO requests are quiesced
    *        and any additional framework operations are 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.
    *
    * @see For additional information please refer to: scic_controller_stop()
    */
   SCI_STATUS scif_controller_stop(
      SCI_CONTROLLER_HANDLE_T  controller,
      U32                      timeout
   );
   
   /**
    * @brief This method will reset the supplied framework controller regardless
    *        of the state of said controller.  This operation is considered
    *        destructive.  Outstanding IO requests are not aborted or completed
    *        at the actual remote device.  However, the framework will
    *        manufacture completion callbacks to the OS driver for the IO
    *        requests.
    *
    * @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.
    *
    * @see For additional information please refer to: scic_controller_reset()
    */
   SCI_STATUS scif_controller_reset(
      SCI_CONTROLLER_HANDLE_T  controller
   );
   
   /**
    * @brief This method returns the SCI Core controller handle associated
    *        with this controller.
    *
    * @param[in]  scif_controller the handle to the controller object for which
    *             to retrieve the core specific controller handle
    *
    * @return Return the SCI core controller handle associated with the supplied
    *         framework controller.
    */
   SCI_CONTROLLER_HANDLE_T scif_controller_get_scic_handle(
      SCI_CONTROLLER_HANDLE_T   scif_controller
   );
   
   /**
    * @brief This method is called by the SCIF user to send/start a framework
    *        IO request.
    *
    * @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.
    *
    * @see For additional information please refer to: scic_controller_start_io()
    *
    * @todo Determine the failure situations and return values.
    */
   SCI_IO_STATUS scif_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
   );
   
   /**
    * @brief This method is called by the SCIF user to send/start a framework
    *        task management 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.
    *
    * @see For additional information please refer to: scic_controller_start_task()
    *
    * @todo Determine the failure situations and return values.
    */
   SCI_TASK_STATUS scif_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 is called by the SCI user to complete a previously
    *        started 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).
    *
    * @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.
    *
    * @see For additional information please refer to:
    *      scic_controller_complete_io()
    */
   SCI_STATUS scif_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 will perform framework specific completion operations for
    *        a 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 scif_controller_complete_task(
      SCI_CONTROLLER_HANDLE_T     controller,
      SCI_REMOTE_DEVICE_HANDLE_T  remote_device,
      SCI_TASK_REQUEST_HANDLE_T   task_request
   );
   
   /**
    * @brief This method simply provides the user with a unique handle for a
    *        given SAS/SATA domain index.
    *
    * @param[in]  controller This parameter represents the handle to the
    *             controller object from which to retrieve a domain (SAS or
    *             SATA) handle.
    * @param[in]  port_index This parameter specifies the domain index in
    *             the controller for which to retrieve the domain handle.
    *             @note 0 <= port_index < maximum number of phys.
    * @param[out] domain_handle This parameter specifies the retrieved domain
    *             handle to be provided to the caller.
    *
    * @return Indicate if the retrieval of the domain 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 index is not invalid.
    */
   SCI_STATUS scif_controller_get_domain_handle(
      SCI_CONTROLLER_HANDLE_T   controller,
      U8                        port_index,
      SCI_DOMAIN_HANDLE_T     * domain_handle
   );
   
   /**
    * @brief This method allows the user to configure the SCI Framework
    *        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 scif_controller_set_mode(
      SCI_CONTROLLER_HANDLE_T   controller,
      SCI_CONTROLLER_MODE       mode
   );
   
   /**
    * @brief This method simply returns the T10 SCSI to ATA Translation (SAT)
    *        specification version to which this translator is compliant for
    *        supported commands.
    *
    * @return An integer value indicating the SAT version to which this
    *         translator complies.
    */
   U32 scif_controller_get_sat_compliance_version(
      void
   );
   
   /**
    * @brief This method simply returns the revision of the T10 SCSI to ATA
    *        Translation (SAT) specification version to which this translator
    *        is compliant for supported commands.
    *
    * @return An integer value indicating the revision of the SAT version
    *         to which this translator complies.
    */
   U32 scif_controller_get_sat_compliance_version_revision(
      void
   );
   
   /**
    * @brief This method is called by the SCI user to start internal io.
    */
   typedef void (*SCI_START_INTERNAL_IO_ROUTINE)(
      SCI_CONTROLLER_HANDLE_T controller
   );
   
   #if !defined(DISABLE_INTERRUPTS)
   /**
    * @brief This method allows the user to configure the interrupt coalescence.
    *           Please refer to the comment header for
    *           scic_controller_set_interrupt_coalescence() to find details.
    */
   SCI_STATUS scif_controller_set_interrupt_coalescence(
      SCI_CONTROLLER_HANDLE_T controller,
      U32                     coalesce_number,
      U32                     coalesce_timeout
   );
   
   /**
    * @brief This method retrieves the interrupt coalescence information.
    *           Please refer to the comment header for
    *           scic_controller_get_interrupt_coalescence() to find details.
    */
   void scif_controller_get_interrupt_coalescence(
      SCI_CONTROLLER_HANDLE_T controller,
      U32                   * coalesce_number,
      U32                   * coalesce_timeout
   );
   
   #else // !defined(DISABLE_INTERRUPTS)
   
   #define scif_controller_set_interrupt_coalescence(controller, num, timeout) \
           SCI_FAILURE
   #define scif_controller_get_interrupt_coalescence(controller, num, timeout)
   
   #endif // !defined(DISABLE_INTERRUPTS)
   
   #ifdef __cplusplus
   }
   #endif // __cplusplus
   
   #endif // _SCIF_CONTROLLER_H_
   

Cache object: e01bb6ab9803d65945adb8f2f6967163