diff options
Diffstat (limited to 'drivers/scsi/isci/core/scic_controller.h')
| -rw-r--r-- | drivers/scsi/isci/core/scic_controller.h | 586 |
1 files changed, 586 insertions, 0 deletions
diff --git a/drivers/scsi/isci/core/scic_controller.h b/drivers/scsi/isci/core/scic_controller.h new file mode 100644 index 000000000000..756b14fcd9a4 --- /dev/null +++ b/drivers/scsi/isci/core/scic_controller.h @@ -0,0 +1,586 @@ +/* + * 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. + * * Neither the name of Intel Corporation nor the names of its + * contributors may be used to endorse or promote products derived + * from this software without specific prior written permission. + * + * 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 _SCIC_CONTROLLER_H_ +#define _SCIC_CONTROLLER_H_ + +/** + * This file contains all of the interface methods that can be called by an + * SCIC user on a controller object. + * + * + */ + + +#include "sci_types.h" +#include "sci_status.h" +#include "sci_controller.h" +#include "scic_config_parameters.h" + +struct scic_sds_request; +struct scic_sds_phy; +struct scic_sds_port; +struct scic_sds_remote_device; + +/** + * enum _SCIC_INTERRUPT_TYPE - This enumeration depicts the various types of + * interrupts that are potentially supported by a SCI Core implementation. + * + * + */ +enum scic_interrupt_type { + SCIC_LEGACY_LINE_INTERRUPT_TYPE, + SCIC_MSIX_INTERRUPT_TYPE, + + /** + * This enumeration value indicates the use of polling. + */ + SCIC_NO_INTERRUPTS + +}; + +/** + * 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. + * + * SCIC_CONTROLLER_INTERRUPT_HANDLER 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)( + struct scic_sds_controller *controller + ); + +/** + * 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. + * + * 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)( + struct scic_sds_controller *controller + ); + +/** + * struct scic_controller_handler_methods - This structure contains an + * interrupt handler and completion handler function pointers. + * + * + */ +struct scic_controller_handler_methods { + SCIC_CONTROLLER_INTERRUPT_HANDLER interrupt_handler; + SCIC_CONTROLLER_COMPLETION_HANDLER completion_handler; + +}; + +/** + * scic_controller_construct() - This method will attempt to construct a + * controller object utilizing the supplied parameter information. + * @c: This parameter specifies the controller to be constructed. + * @scu_base: mapped base address of the scu registers + * @smu_base: mapped base address of the smu registers + * + * Indicate if the controller was successfully constructed or if it failed in + * some way. SCI_SUCCESS This value is returned if the controller was + * successfully constructed. SCI_WARNING_TIMER_CONFLICT This value is returned + * if the interrupt coalescence timer may cause SAS compliance issues for SMP + * Target mode response processing. SCI_FAILURE_UNSUPPORTED_CONTROLLER_TYPE + * This value is returned if the controller does not support the supplied type. + * SCI_FAILURE_UNSUPPORTED_INIT_DATA_VERSION This value is returned if the + * controller does not support the supplied initialization data version. + */ +enum sci_status scic_controller_construct(struct scic_sds_controller *c, + void __iomem *scu_base, + void __iomem *smu_base); + +/** + * scic_controller_enable_interrupts() - This method will enable all controller + * interrupts. + * @controller: This parameter specifies the controller for which to enable + * interrupts. + * + */ +void scic_controller_enable_interrupts( + struct scic_sds_controller *controller); + +/** + * scic_controller_disable_interrupts() - This method will disable all + * controller interrupts. + * @controller: This parameter specifies the controller for which to disable + * interrupts. + * + */ +void scic_controller_disable_interrupts( + struct scic_sds_controller *controller); + +/** + * scic_controller_get_handler_methods() - 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. + * @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) + * @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. + * @handler_methods: The caller provides a pointer to a buffer of type + * struct scic_controller_handler_methods. The size depends on the combination of + * the interrupt_type and message_count input parameters: + * SCIC_LEGACY_LINE_INTERRUPT_TYPE: - size = + * sizeof(struct scic_controller_handler_methods) SCIC_MSIX_INTERRUPT_TYPE: + * sizeof(struct scic_controller_handler_methods) + * @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 + * struct scic_controller_handler_methods element regardless that the + * message_count parameter is zero. For SCIC_MSIX_INTERRUPT_TYPE, the buffer + * receives an array of elements of type struct scic_controller_handler_methods + * 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. + * + * Indicate if the handler retrieval operation was successful. SCI_SUCCESS This + * value is returned if retrieval succeeded. + * 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. + */ +enum sci_status scic_controller_get_handler_methods( + enum scic_interrupt_type interrupt_type, + u16 message_count, + struct scic_controller_handler_methods *handler_methods); + +/** + * scic_controller_initialize() - 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. + * @controller: This parameter specifies the controller to be initialized. + * + * The SCI Core user must have called scic_controller_construct() on the + * supplied controller object previously. Indicate if the controller was + * successfully initialized or if it failed in some way. SCI_SUCCESS This value + * is returned if the controller hardware was successfully initialized. + */ +enum sci_status scic_controller_initialize( + struct scic_sds_controller *controller); + +/** + * scic_controller_get_suggested_start_timeout() - 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. + * @controller: the handle to the controller object for which to return the + * suggested start timeout. + * + * This method returns the number of milliseconds for the suggested start + * operation timeout. + */ +u32 scic_controller_get_suggested_start_timeout( + struct scic_sds_controller *controller); + +/** + * scic_controller_start() - 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. + * @controller: the handle to the controller object to start. + * @timeout: This parameter specifies the number of milliseconds in which the + * start operation should complete. + * + * The SCI Core user must have filled in the physical memory descriptor + * structure via the sci_controller_get_memory_descriptor_list() method. The + * SCI Core user must have invoked the scic_controller_initialize() method + * prior to invoking this method. The controller must be in the INITIALIZED or + * STARTED state. Indicate if the controller start method succeeded or failed + * in some way. SCI_SUCCESS if the start operation succeeded. + * SCI_WARNING_ALREADY_IN_STATE if the controller is already in the STARTED + * state. SCI_FAILURE_INVALID_STATE if the controller is not either in the + * INITIALIZED or STARTED states. SCI_FAILURE_INVALID_MEMORY_DESCRIPTOR if + * there are inconsistent or invalid values in the supplied + * struct sci_physical_memory_descriptor array. + */ +enum sci_status scic_controller_start( + struct scic_sds_controller *controller, + u32 timeout); + +/** + * scic_controller_stop() - 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. + * @controller: the handle to the controller object to stop. + * @timeout: This parameter specifies the number of milliseconds in which the + * stop operation should complete. + * + * The controller must be in the STARTED or STOPPED state. Indicate if the + * controller stop method succeeded or failed in some way. SCI_SUCCESS if the + * stop operation successfully began. SCI_WARNING_ALREADY_IN_STATE if the + * controller is already in the STOPPED state. SCI_FAILURE_INVALID_STATE if the + * controller is not either in the STARTED or STOPPED states. + */ +enum sci_status scic_controller_stop( + struct scic_sds_controller *controller, + u32 timeout); + +/** + * scic_controller_reset() - 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. + * @controller: the handle to the controller object to reset. + * + * Indicate if the controller reset method succeeded or failed in some way. + * SCI_SUCCESS if the reset operation successfully started. SCI_FATAL_ERROR if + * the controller reset operation is unable to complete. + */ +enum sci_status scic_controller_reset( + struct scic_sds_controller *controller); + +/** + * scic_controller_start_io() - 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. + * @controller: the handle to the controller object for which to start an IO + * request. + * @remote_device: the handle to the remote device object for which to start an + * IO request. + * @io_request: the handle to the io request object to start. + * @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. + * + * - 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. scic_controller_allocate_tag() for + * more information on allocating a tag. Indicate if the controller + * successfully started the IO request. SCI_IO_SUCCESS if the IO request was + * successfully started. Determine the failure situations and return values. + */ +enum sci_io_status scic_controller_start_io( + struct scic_sds_controller *controller, + struct scic_sds_remote_device *remote_device, + struct scic_sds_request *io_request, + u16 io_tag); + + +/** + * scic_controller_start_task() - This method is called by the SCIC user to + * send/start a framework task management request. + * @controller: the handle to the controller object for which to start the task + * management request. + * @remote_device: the handle to the remote device object for which to start + * the task management request. + * @task_request: the handle to the task request object to start. + * @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. + * + * - 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. scic_controller_allocate_tag() for more + * information on allocating a tag. Indicate if the controller successfully + * started the IO request. SCI_TASK_SUCCESS if the task request was + * successfully started. 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. + */ +enum sci_task_status scic_controller_start_task( + struct scic_sds_controller *controller, + struct scic_sds_remote_device *remote_device, + struct scic_sds_request *task_request, + u16 io_tag); + +/** + * scic_controller_complete_task() - 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). + * @controller: The handle to the controller object for which to complete the + * task management request. + * @remote_device: The handle to the remote device object for which to complete + * the task management request. + * @task_request: the handle to the task management request object to complete. + * + * Indicate if the controller successfully completed the task management + * request. SCI_SUCCESS if the completion process was successful. + */ +enum sci_status scic_controller_complete_task( + struct scic_sds_controller *controller, + struct scic_sds_remote_device *remote_device, + struct scic_sds_request *task_request); + + +/** + * scic_controller_terminate_request() - 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. + * @controller: the handle to the controller object for which to terminate a + * request. + * @remote_device: the handle to the remote device object for which to + * terminate a request. + * @request: the handle to the io or task management request object to + * terminate. + * + * Indicate if the controller successfully began the terminate process for the + * IO request. SCI_SUCCESS if the terminate process was successfully started + * for the request. Determine the failure situations and return values. + */ +enum sci_status scic_controller_terminate_request( + struct scic_sds_controller *controller, + struct scic_sds_remote_device *remote_device, + struct scic_sds_request *request); + +/** + * scic_controller_complete_io() - 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). + * @controller: The handle to the controller object for which to complete the + * IO request. + * @remote_device: The handle to the remote device object for which to complete + * the IO request. + * @io_request: the handle to the io request object to complete. + * + * - 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). Indicate + * if the controller successfully completed the IO request. SCI_SUCCESS if the + * completion process was successful. + */ +enum sci_status scic_controller_complete_io( + struct scic_sds_controller *controller, + struct scic_sds_remote_device *remote_device, + struct scic_sds_request *io_request); + + +/** + * scic_controller_get_port_handle() - This method simply provides the user + * with a unique handle for a given SAS/SATA core port index. + * @controller: This parameter represents the handle to the controller object + * from which to retrieve a port (SAS or SATA) handle. + * @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. + * @port_handle: This parameter specifies the retrieved port handle to be + * provided to the caller. + * + * Indicate if the retrieval of the port handle was successful. SCI_SUCCESS + * This value is returned if the retrieval was successful. + * SCI_FAILURE_INVALID_PORT This value is returned if the supplied port id is + * not in the supported range. + */ +enum sci_status scic_controller_get_port_handle( + struct scic_sds_controller *controller, + u8 port_index, + struct scic_sds_port **port_handle); + +/** + * scic_controller_get_phy_handle() - This method simply provides the user with + * a unique handle for a given SAS/SATA phy index/identifier. + * @controller: This parameter represents the handle to the controller object + * from which to retrieve a phy (SAS or SATA) handle. + * @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. + * @phy_handle: This parameter specifies the retrieved phy handle to be + * provided to the caller. + * + * Indicate if the retrieval of the phy handle was successful. SCI_SUCCESS This + * value is returned if the retrieval was successful. SCI_FAILURE_INVALID_PHY + * This value is returned if the supplied phy id is not in the supported range. + */ +enum sci_status scic_controller_get_phy_handle( + struct scic_sds_controller *controller, + u8 phy_index, + struct scic_sds_phy **phy_handle); + +/** + * scic_controller_allocate_io_tag() - 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. + * @controller: the handle to the controller object for which to allocate the + * tag. + * + * 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.). An unsigned integer representing an available IO tag. + * SCI_CONTROLLER_INVALID_IO_TAG This value is returned if there are no + * currently available tags to be allocated. All return other values indicate a + * legitimate tag. + */ +u16 scic_controller_allocate_io_tag( + struct scic_sds_controller *controller); + +/** + * scic_controller_free_io_tag() - 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(). + * @controller: This parameter specifies the handle to the controller object + * for which to free/return the tag. + * @io_tag: This parameter represents the tag to be freed to the pool of + * available tags. + * + * - 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. This + * method returns an indication of whether the tag was successfully put back + * (freed) to the pool of available tags. SCI_SUCCESS This return value + * indicates the tag was successfully placed into the pool of available IO + * tags. SCI_FAILURE_INVALID_IO_TAG This value is returned if the supplied tag + * is not a valid IO tag value. + */ +enum sci_status scic_controller_free_io_tag( + struct scic_sds_controller *controller, + u16 io_tag); + + + + +/** + * scic_controller_set_mode() - This method allows the user to configure the + * SCI core into either a performance mode or a memory savings mode. + * @controller: This parameter represents the handle to the controller object + * for which to update the operating mode. + * @mode: This parameter specifies the new mode for the controller. + * + * Indicate if the user successfully change the operating mode of the + * controller. SCI_SUCCESS The user successfully updated the mode. + */ +enum sci_status scic_controller_set_mode( + struct scic_sds_controller *controller, + enum sci_controller_mode mode); + + +/** + * scic_controller_set_interrupt_coalescence() - This method allows the user to + * configure the interrupt coalescence. + * @controller: This parameter represents the handle to the controller object + * for which its interrupt coalesce register is overridden. + * @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. + * @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. + * + * Indicate if the user successfully set the interrupt coalesce parameters. + * SCI_SUCCESS The user successfully updated the interrutp coalescence. + * SCI_FAILURE_INVALID_PARAMETER_VALUE The user input value is out of range. + */ +enum sci_status scic_controller_set_interrupt_coalescence( + struct scic_sds_controller *controller, + u32 coalesce_number, + u32 coalesce_timeout); + +struct device; +struct scic_sds_controller *scic_controller_alloc(struct device *dev); + + +#endif /* _SCIC_CONTROLLER_H_ */ + |