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