/*- * 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. */ #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 #include /** * @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_