drivers/scsi/isci/core/scic_controller.h

   1 /*
   2  * This file is provided under a dual BSD/GPLv2 license.  When using or
   3  * redistributing this file, you may do so under either license.
   4  *
   5  * GPL LICENSE SUMMARY
   6  *
   7  * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of version 2 of the GNU General Public License as
  11  * published by the Free Software Foundation.
  12  *
  13  * This program is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA.
  21  * The full GNU General Public License is included in this distribution
  22  * in the file called LICENSE.GPL.
  23  *
  24  * BSD LICENSE
  25  *
  26  * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
  27  * All rights reserved.
  28  *
  29  * Redistribution and use in source and binary forms, with or without
  30  * modification, are permitted provided that the following conditions
  31  * are met:
  32  *
  33  *   * Redistributions of source code must retain the above copyright
  34  *     notice, this list of conditions and the following disclaimer.
  35  *   * Redistributions in binary form must reproduce the above copyright
  36  *     notice, this list of conditions and the following disclaimer in
  37  *     the documentation and/or other materials provided with the
  38  *     distribution.
  39  *   * Neither the name of Intel Corporation nor the names of its
  40  *     contributors may be used to endorse or promote products derived
  41  *     from this software without specific prior written permission.
  42  *
  43  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  44  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  45  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  46  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  47  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  48  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  49  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  50  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  51  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  52  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  53  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  54  */
  55
  56 #ifndef _SCIC_CONTROLLER_H_
  57 #define _SCIC_CONTROLLER_H_
  58
  59 /**
  60  * This file contains all of the interface methods that can be called by an
  61  *    SCIC user on a controller object.
  62  *
  63  *
  64  */
  65
  66
  67 #include "sci_status.h"
  68 #include "sci_controller.h"
  69 #include "scic_config_parameters.h"
  70
  71 struct scic_sds_request;
  72 struct scic_sds_phy;
  73 struct scic_sds_port;
  74 struct scic_sds_remote_device;
  75
  76
  77 enum sci_controller_mode {
  78         SCI_MODE_SPEED,         /* Optimized for performance */
  79         SCI_MODE_SIZE           /* Optimized for memory use */
  80 };
  81
  82
  83 /**
  84  * scic_controller_construct() - This method will attempt to construct a
  85  *    controller object utilizing the supplied parameter information.
  86  * @c: This parameter specifies the controller to be constructed.
  87  * @scu_base: mapped base address of the scu registers
  88  * @smu_base: mapped base address of the smu registers
  89  *
  90  * Indicate if the controller was successfully constructed or if it failed in
  91  * some way. SCI_SUCCESS This value is returned if the controller was
  92  * successfully constructed. SCI_WARNING_TIMER_CONFLICT This value is returned
  93  * if the interrupt coalescence timer may cause SAS compliance issues for SMP
  94  * Target mode response processing. SCI_FAILURE_UNSUPPORTED_CONTROLLER_TYPE
  95  * This value is returned if the controller does not support the supplied type.
  96  * SCI_FAILURE_UNSUPPORTED_INIT_DATA_VERSION This value is returned if the
  97  * controller does not support the supplied initialization data version.
  98  */
  99 enum sci_status scic_controller_construct(struct scic_sds_controller *c,
 100                                           void __iomem *scu_base,
 101                                           void __iomem *smu_base);
 102
 103 /**
 104  * scic_controller_enable_interrupts() - This method will enable all controller
 105  *    interrupts.
 106  * @controller: This parameter specifies the controller for which to enable
 107  *    interrupts.
 108  *
 109  */
 110 void scic_controller_enable_interrupts(
 111         struct scic_sds_controller *controller);
 112
 113 /**
 114  * scic_controller_disable_interrupts() - This method will disable all
 115  *    controller interrupts.
 116  * @controller: This parameter specifies the controller for which to disable
 117  *    interrupts.
 118  *
 119  */
 120 void scic_controller_disable_interrupts(
 121         struct scic_sds_controller *controller);
 122
 123
 124 /**
 125  * scic_controller_initialize() - This method will initialize the controller
 126  *    hardware managed by the supplied core controller object.  This method
 127  *    will bring the physical controller hardware out of reset and enable the
 128  *    core to determine the capabilities of the hardware being managed.  Thus,
 129  *    the core controller can determine it's exact physical (DMA capable)
 130  *    memory requirements.
 131  * @controller: This parameter specifies the controller to be initialized.
 132  *
 133  * The SCI Core user must have called scic_controller_construct() on the
 134  * supplied controller object previously. Indicate if the controller was
 135  * successfully initialized or if it failed in some way. SCI_SUCCESS This value
 136  * is returned if the controller hardware was successfully initialized.
 137  */
 138 enum sci_status scic_controller_initialize(
 139         struct scic_sds_controller *controller);
 140
 141 /**
 142  * scic_controller_get_suggested_start_timeout() - This method returns the
 143  *    suggested scic_controller_start() timeout amount.  The user is free to
 144  *    use any timeout value, but this method provides the suggested minimum
 145  *    start timeout value.  The returned value is based upon empirical
 146  *    information determined as a result of interoperability testing.
 147  * @controller: the handle to the controller object for which to return the
 148  *    suggested start timeout.
 149  *
 150  * This method returns the number of milliseconds for the suggested start
 151  * operation timeout.
 152  */
 153 u32 scic_controller_get_suggested_start_timeout(
 154         struct scic_sds_controller *controller);
 155
 156 /**
 157  * scic_controller_start() - This method will start the supplied core
 158  *    controller.  This method will start the staggered spin up operation.  The
 159  *    SCI User completion callback is called when the following conditions are
 160  *    met: -# the return status of this method is SCI_SUCCESS. -# after all of
 161  *    the phys have successfully started or been given the opportunity to start.
 162  * @controller: the handle to the controller object to start.
 163  * @timeout: This parameter specifies the number of milliseconds in which the
 164  *    start operation should complete.
 165  *
 166  * The SCI Core user must have filled in the physical memory descriptor
 167  * structure via the sci_controller_get_memory_descriptor_list() method. The
 168  * SCI Core user must have invoked the scic_controller_initialize() method
 169  * prior to invoking this method. The controller must be in the INITIALIZED or
 170  * STARTED state. Indicate if the controller start method succeeded or failed
 171  * in some way. SCI_SUCCESS if the start operation succeeded.
 172  * SCI_WARNING_ALREADY_IN_STATE if the controller is already in the STARTED
 173  * state. SCI_FAILURE_INVALID_STATE if the controller is not either in the
 174  * INITIALIZED or STARTED states. SCI_FAILURE_INVALID_MEMORY_DESCRIPTOR if
 175  * there are inconsistent or invalid values in the supplied
 176  * struct sci_physical_memory_descriptor array.
 177  */
 178 enum sci_status scic_controller_start(
 179         struct scic_sds_controller *controller,
 180         u32 timeout);
 181
 182 /**
 183  * scic_controller_stop() - This method will stop an individual controller
 184  *    object.This method will invoke the associated user callback upon
 185  *    completion.  The completion callback is called when the following
 186  *    conditions are met: -# the method return status is SCI_SUCCESS. -# the
 187  *    controller has been quiesced. This method will ensure that all IO
 188  *    requests are quiesced, phys are stopped, and all additional operation by
 189  *    the hardware is halted.
 190  * @controller: the handle to the controller object to stop.
 191  * @timeout: This parameter specifies the number of milliseconds in which the
 192  *    stop operation should complete.
 193  *
 194  * The controller must be in the STARTED or STOPPED state. Indicate if the
 195  * controller stop method succeeded or failed in some way. SCI_SUCCESS if the
 196  * stop operation successfully began. SCI_WARNING_ALREADY_IN_STATE if the
 197  * controller is already in the STOPPED state. SCI_FAILURE_INVALID_STATE if the
 198  * controller is not either in the STARTED or STOPPED states.
 199  */
 200 enum sci_status scic_controller_stop(
 201         struct scic_sds_controller *controller,
 202         u32 timeout);
 203
 204 /**
 205  * scic_controller_reset() - This method will reset the supplied core
 206  *    controller regardless of the state of said controller.  This operation is
 207  *    considered destructive.  In other words, all current operations are wiped
 208  *    out.  No IO completions for outstanding devices occur.  Outstanding IO
 209  *    requests are not aborted or completed at the actual remote device.
 210  * @controller: the handle to the controller object to reset.
 211  *
 212  * Indicate if the controller reset method succeeded or failed in some way.
 213  * SCI_SUCCESS if the reset operation successfully started. SCI_FATAL_ERROR if
 214  * the controller reset operation is unable to complete.
 215  */
 216 enum sci_status scic_controller_reset(
 217         struct scic_sds_controller *controller);
 218
 219 /**
 220  * scic_controller_start_io() - This method is called by the SCI user to
 221  *    send/start an IO request. If the method invocation is successful, then
 222  *    the IO request has been queued to the hardware for processing.
 223  * @controller: the handle to the controller object for which to start an IO
 224  *    request.
 225  * @remote_device: the handle to the remote device object for which to start an
 226  *    IO request.
 227  * @io_request: the handle to the io request object to start.
 228  * @io_tag: This parameter specifies a previously allocated IO tag that the
 229  *    user desires to be utilized for this request. This parameter is optional.
 230  *     The user is allowed to supply SCI_CONTROLLER_INVALID_IO_TAG as the value
 231  *    for this parameter.
 232  *
 233  * - IO tags are a protected resource.  It is incumbent upon the SCI Core user
 234  * to ensure that each of the methods that may allocate or free available IO
 235  * tags are handled in a mutually exclusive manner.  This method is one of said
 236  * methods requiring proper critical code section protection (e.g. semaphore,
 237  * spin-lock, etc.). - For SATA, the user is required to manage NCQ tags.  As a
 238  * result, it is expected the user will have set the NCQ tag field in the host
 239  * to device register FIS prior to calling this method.  There is also a
 240  * requirement for the user to call scic_stp_io_set_ncq_tag() prior to invoking
 241  * the scic_controller_start_io() method. scic_controller_allocate_tag() for
 242  * more information on allocating a tag. Indicate if the controller
 243  * successfully started the IO request. SCI_IO_SUCCESS if the IO request was
 244  * successfully started. Determine the failure situations and return values.
 245  */
 246 enum sci_io_status scic_controller_start_io(
 247         struct scic_sds_controller *controller,
 248         struct scic_sds_remote_device *remote_device,
 249         struct scic_sds_request *io_request,
 250         u16 io_tag);
 251
 252
 253 /**
 254  * scic_controller_start_task() - This method is called by the SCIC user to
 255  *    send/start a framework task management request.
 256  * @controller: the handle to the controller object for which to start the task
 257  *    management request.
 258  * @remote_device: the handle to the remote device object for which to start
 259  *    the task management request.
 260  * @task_request: the handle to the task request object to start.
 261  * @io_tag: This parameter specifies a previously allocated IO tag that the
 262  *    user desires to be utilized for this request.  Note this not the io_tag
 263  *    of the request being managed.  It is to be utilized for the task request
 264  *    itself. This parameter is optional.  The user is allowed to supply
 265  *    SCI_CONTROLLER_INVALID_IO_TAG as the value for this parameter.
 266  *
 267  * - IO tags are a protected resource.  It is incumbent upon the SCI Core user
 268  * to ensure that each of the methods that may allocate or free available IO
 269  * tags are handled in a mutually exclusive manner.  This method is one of said
 270  * methods requiring proper critical code section protection (e.g. semaphore,
 271  * spin-lock, etc.). - The user must synchronize this task with completion
 272  * queue processing.  If they are not synchronized then it is possible for the
 273  * io requests that are being managed by the task request can complete before
 274  * starting the task request. scic_controller_allocate_tag() for more
 275  * information on allocating a tag. Indicate if the controller successfully
 276  * started the IO request. SCI_TASK_SUCCESS if the task request was
 277  * successfully started. SCI_TASK_FAILURE_REQUIRES_SCSI_ABORT This value is
 278  * returned if there is/are task(s) outstanding that require termination or
 279  * completion before this request can succeed.
 280  */
 281 enum sci_task_status scic_controller_start_task(
 282         struct scic_sds_controller *controller,
 283         struct scic_sds_remote_device *remote_device,
 284         struct scic_sds_request *task_request,
 285         u16 io_tag);
 286
 287 /**
 288  * scic_controller_complete_task() - This method will perform core specific
 289  *    completion operations for task management request. After this method is
 290  *    invoked, the user should consider the task request as invalid until it is
 291  *    properly reused (i.e. re-constructed).
 292  * @controller: The handle to the controller object for which to complete the
 293  *    task management request.
 294  * @remote_device: The handle to the remote device object for which to complete
 295  *    the task management request.
 296  * @task_request: the handle to the task management request object to complete.
 297  *
 298  * Indicate if the controller successfully completed the task management
 299  * request. SCI_SUCCESS if the completion process was successful.
 300  */
 301 enum sci_status scic_controller_complete_task(
 302         struct scic_sds_controller *controller,
 303         struct scic_sds_remote_device *remote_device,
 304         struct scic_sds_request *task_request);
 305
 306
 307 /**
 308  * scic_controller_terminate_request() - This method is called by the SCI Core
 309  *    user to terminate an ongoing (i.e. started) core IO request.  This does
 310  *    not abort the IO request at the target, but rather removes the IO request
 311  *    from the host controller.
 312  * @controller: the handle to the controller object for which to terminate a
 313  *    request.
 314  * @remote_device: the handle to the remote device object for which to
 315  *    terminate a request.
 316  * @request: the handle to the io or task management request object to
 317  *    terminate.
 318  *
 319  * Indicate if the controller successfully began the terminate process for the
 320  * IO request. SCI_SUCCESS if the terminate process was successfully started
 321  * for the request. Determine the failure situations and return values.
 322  */
 323 enum sci_status scic_controller_terminate_request(
 324         struct scic_sds_controller *controller,
 325         struct scic_sds_remote_device *remote_device,
 326         struct scic_sds_request *request);
 327
 328 /**
 329  * scic_controller_complete_io() - This method will perform core specific
 330  *    completion operations for an IO request.  After this method is invoked,
 331  *    the user should consider the IO request as invalid until it is properly
 332  *    reused (i.e. re-constructed).
 333  * @controller: The handle to the controller object for which to complete the
 334  *    IO request.
 335  * @remote_device: The handle to the remote device object for which to complete
 336  *    the IO request.
 337  * @io_request: the handle to the io request object to complete.
 338  *
 339  * - IO tags are a protected resource.  It is incumbent upon the SCI Core user
 340  * to ensure that each of the methods that may allocate or free available IO
 341  * tags are handled in a mutually exclusive manner.  This method is one of said
 342  * methods requiring proper critical code section protection (e.g. semaphore,
 343  * spin-lock, etc.). - If the IO tag for a request was allocated, by the SCI
 344  * Core user, using the scic_controller_allocate_io_tag() method, then it is
 345  * the responsibility of the caller to invoke the scic_controller_free_io_tag()
 346  * method to free the tag (i.e. this method will not free the IO tag). Indicate
 347  * if the controller successfully completed the IO request. SCI_SUCCESS if the
 348  * completion process was successful.
 349  */
 350 enum sci_status scic_controller_complete_io(
 351         struct scic_sds_controller *controller,
 352         struct scic_sds_remote_device *remote_device,
 353         struct scic_sds_request *io_request);
 354
 355
 356 /**
 357  * scic_controller_get_port_handle() - This method simply provides the user
 358  *    with a unique handle for a given SAS/SATA core port index.
 359  * @controller: This parameter represents the handle to the controller object
 360  *    from which to retrieve a port (SAS or SATA) handle.
 361  * @port_index: This parameter specifies the port index in the controller for
 362  *    which to retrieve the port handle. 0 <= port_index < maximum number of
 363  *    phys.
 364  * @port_handle: This parameter specifies the retrieved port handle to be
 365  *    provided to the caller.
 366  *
 367  * Indicate if the retrieval of the port handle was successful. SCI_SUCCESS
 368  * This value is returned if the retrieval was successful.
 369  * SCI_FAILURE_INVALID_PORT This value is returned if the supplied port id is
 370  * not in the supported range.
 371  */
 372 enum sci_status scic_controller_get_port_handle(
 373         struct scic_sds_controller *controller,
 374         u8 port_index,
 375         struct scic_sds_port **port_handle);
 376
 377 /**
 378  * scic_controller_get_phy_handle() - This method simply provides the user with
 379  *    a unique handle for a given SAS/SATA phy index/identifier.
 380  * @controller: This parameter represents the handle to the controller object
 381  *    from which to retrieve a phy (SAS or SATA) handle.
 382  * @phy_index: This parameter specifies the phy index in the controller for
 383  *    which to retrieve the phy handle. 0 <= phy_index < maximum number of phys.
 384  * @phy_handle: This parameter specifies the retrieved phy handle to be
 385  *    provided to the caller.
 386  *
 387  * Indicate if the retrieval of the phy handle was successful. SCI_SUCCESS This
 388  * value is returned if the retrieval was successful. SCI_FAILURE_INVALID_PHY
 389  * This value is returned if the supplied phy id is not in the supported range.
 390  */
 391 enum sci_status scic_controller_get_phy_handle(
 392         struct scic_sds_controller *controller,
 393         u8 phy_index,
 394         struct scic_sds_phy **phy_handle);
 395
 396 /**
 397  * scic_controller_allocate_io_tag() - This method will allocate a tag from the
 398  *    pool of free IO tags. Direct allocation of IO tags by the SCI Core user
 399  *    is optional. The scic_controller_start_io() method will allocate an IO
 400  *    tag if this method is not utilized and the tag is not supplied to the IO
 401  *    construct routine.  Direct allocation of IO tags may provide additional
 402  *    performance improvements in environments capable of supporting this usage
 403  *    model.  Additionally, direct allocation of IO tags also provides
 404  *    additional flexibility to the SCI Core user.  Specifically, the user may
 405  *    retain IO tags across the lives of multiple IO requests.
 406  * @controller: the handle to the controller object for which to allocate the
 407  *    tag.
 408  *
 409  * IO tags are a protected resource.  It is incumbent upon the SCI Core user to
 410  * ensure that each of the methods that may allocate or free available IO tags
 411  * are handled in a mutually exclusive manner.  This method is one of said
 412  * methods requiring proper critical code section protection (e.g. semaphore,
 413  * spin-lock, etc.). An unsigned integer representing an available IO tag.
 414  * SCI_CONTROLLER_INVALID_IO_TAG This value is returned if there are no
 415  * currently available tags to be allocated. All return other values indicate a
 416  * legitimate tag.
 417  */
 418 u16 scic_controller_allocate_io_tag(
 419         struct scic_sds_controller *controller);
 420
 421 /**
 422  * scic_controller_free_io_tag() - This method will free an IO tag to the pool
 423  *    of free IO tags. This method provides the SCI Core user more flexibility
 424  *    with regards to IO tags.  The user may desire to keep an IO tag after an
 425  *    IO request has completed, because they plan on re-using the tag for a
 426  *    subsequent IO request.  This method is only legal if the tag was
 427  *    allocated via scic_controller_allocate_io_tag().
 428  * @controller: This parameter specifies the handle to the controller object
 429  *    for which to free/return the tag.
 430  * @io_tag: This parameter represents the tag to be freed to the pool of
 431  *    available tags.
 432  *
 433  * - IO tags are a protected resource.  It is incumbent upon the SCI Core user
 434  * to ensure that each of the methods that may allocate or free available IO
 435  * tags are handled in a mutually exclusive manner.  This method is one of said
 436  * methods requiring proper critical code section protection (e.g. semaphore,
 437  * spin-lock, etc.). - If the IO tag for a request was allocated, by the SCI
 438  * Core user, using the scic_controller_allocate_io_tag() method, then it is
 439  * the responsibility of the caller to invoke this method to free the tag. This
 440  * method returns an indication of whether the tag was successfully put back
 441  * (freed) to the pool of available tags. SCI_SUCCESS This return value
 442  * indicates the tag was successfully placed into the pool of available IO
 443  * tags. SCI_FAILURE_INVALID_IO_TAG This value is returned if the supplied tag
 444  * is not a valid IO tag value.
 445  */
 446 enum sci_status scic_controller_free_io_tag(
 447         struct scic_sds_controller *controller,
 448         u16 io_tag);
 449
 450
 451
 452
 453 /**
 454  * scic_controller_set_mode() - This method allows the user to configure the
 455  *    SCI core into either a performance mode or a memory savings mode.
 456  * @controller: This parameter represents the handle to the controller object
 457  *    for which to update the operating mode.
 458  * @mode: This parameter specifies the new mode for the controller.
 459  *
 460  * Indicate if the user successfully change the operating mode of the
 461  * controller. SCI_SUCCESS The user successfully updated the mode.
 462  */
 463 enum sci_status scic_controller_set_mode(
 464         struct scic_sds_controller *controller,
 465         enum sci_controller_mode mode);
 466
 467
 468 /**
 469  * scic_controller_set_interrupt_coalescence() - This method allows the user to
 470  *    configure the interrupt coalescence.
 471  * @controller: This parameter represents the handle to the controller object
 472  *    for which its interrupt coalesce register is overridden.
 473  * @coalesce_number: Used to control the number of entries in the Completion
 474  *    Queue before an interrupt is generated. If the number of entries exceed
 475  *    this number, an interrupt will be generated. The valid range of the input
 476  *    is [0, 256]. A setting of 0 results in coalescing being disabled.
 477  * @coalesce_timeout: Timeout value in microseconds. The valid range of the
 478  *    input is [0, 2700000] . A setting of 0 is allowed and results in no
 479  *    interrupt coalescing timeout.
 480  *
 481  * Indicate if the user successfully set the interrupt coalesce parameters.
 482  * SCI_SUCCESS The user successfully updated the interrutp coalescence.
 483  * SCI_FAILURE_INVALID_PARAMETER_VALUE The user input value is out of range.
 484  */
 485 enum sci_status scic_controller_set_interrupt_coalescence(
 486         struct scic_sds_controller *controller,
 487         u32 coalesce_number,
 488         u32 coalesce_timeout);
 489
 490 struct device;
 491 struct scic_sds_controller *scic_controller_alloc(struct device *dev);
 492
 493
 494 #endif  /* _SCIC_CONTROLLER_H_ */
 495