sys/dev/isci/scil/scic_remote_device.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  *
  40  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  41  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  42  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  43  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  44  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  45  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  46  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  47  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  48  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  49  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  50  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  51  *
  52  * $FreeBSD$
  53  */
  54 #ifndef _SCIC_REMOTE_DEVICE_H_
  55 #define _SCIC_REMOTE_DEVICE_H_
  56
  57 /**
  58  * @file
  59  *
  60  * @brief This file contains all of the interface methods that can be called
  61  *        by an SCIC user on the device object.
  62  */
  63
  64 #ifdef __cplusplus
  65 extern "C" {
  66 #endif // __cplusplus
  67
  68 #include <dev/isci/scil/sci_types.h>
  69 #include <dev/isci/scil/sci_status.h>
  70 #include <dev/isci/scil/intel_sas.h>
  71
  72
  73 /**
  74  * @brief
  75  */
  76 typedef enum SCIC_REMOTE_DEVICE_NOT_READY_REASON_CODE
  77 {
  78    SCIC_REMOTE_DEVICE_NOT_READY_START_REQUESTED,
  79    SCIC_REMOTE_DEVICE_NOT_READY_STOP_REQUESTED,
  80    SCIC_REMOTE_DEVICE_NOT_READY_SATA_REQUEST_STARTED,
  81    SCIC_REMOTE_DEVICE_NOT_READY_SATA_SDB_ERROR_FIS_RECEIVED,
  82    SCIC_REMOTE_DEVICE_NOT_READY_SMP_REQUEST_STARTED,
  83
  84    SCIC_REMOTE_DEVICE_NOT_READY_REASON_CODE_MAX
  85
  86 } SCIC_REMOTE_DEVICE_NOT_READY_REASON_CODE_T;
  87
  88 /**
  89  * @brief This method simply returns the maximum memory space needed to
  90  *        store a remote device object.
  91  *
  92  * @return a positive integer value indicating the size (in bytes) of the
  93  *         remote device object.
  94  */
  95 U32 scic_remote_device_get_object_size(
  96    void
  97 );
  98
  99 /**
 100  * @brief This method will perform the construction common to all
 101  *        remote device objects.
 102  *
 103  * @note  It isn't necessary to call scic_remote_device_destruct() for
 104  *        device objects that have only called this method for construction.
 105  *        Once subsequent construction methods have been invoked (e.g.
 106  *        scic_remote_device_da_construct()), then destruction should occur.
 107  * @note
 108  *
 109  * @param[in]  port This parameter specifies the SAS/SATA Port handle
 110  *             corresponding to the port through which this device
 111  *             is to be accessed.
 112  * @param[in]  remote_device_memory This parameter specifies the memory
 113  *             location to be used by the SCIC implementation to store the
 114  *             SCIC REMOTE DEVICE.
 115  * @param[out] new_remote_device_handle An opaque remote device handle to
 116  *             be used by the SCIC user for all subsequent remote device
 117  *             operations.
 118  *
 119  * @return none
 120  */
 121 void scic_remote_device_construct(
 122    SCI_PORT_HANDLE_T            port,
 123    void                       * remote_device_memory,
 124    SCI_REMOTE_DEVICE_HANDLE_T * new_remote_device_handle
 125 );
 126
 127 /**
 128  * @brief This method will construct a SCIC_REMOTE_DEVICE object for a
 129  *        direct attached (da) device.  The information (e.g. IAF, Signature
 130  *        FIS, etc.) necessary to build the device is known to the SCI Core
 131  *        since it is contained in the scic_phy object.
 132  *
 133  * @pre The user must have previously called scic_remote_device_construct()
 134  *
 135  * @note  Remote device objects are a limited resource.  As such, they
 136  *        must be protected.  Thus calls to construct and destruct are
 137  *        mutually exclusive and non-reentrant.
 138  *
 139  * @param[in]  remote_device This parameter specifies the remote device to be
 140  *             destructed.
 141  *
 142  * @return Indicate if the remote device was successfully constructed.
 143  * @retval SCI_SUCCESS Returned if the device was successfully constructed.
 144  * @retval SCI_FAILURE_DEVICE_EXISTS Returned if the device has already
 145  *         been constructed.  If it's an additional phy for the target, then
 146  *         call scic_remote_device_da_add_phy().
 147  * @retval SCI_FAILURE_UNSUPPORTED_PROTOCOL Returned if the supplied
 148  *         parameters necessitate creation of a remote device for which
 149  *         the protocol is not supported by the underlying controller
 150  *         hardware.
 151  * @retval SCI_FAILURE_INSUFFICIENT_RESOURCES This value is returned if
 152  *         the core controller associated with the supplied parameters
 153  *         is unable to support additional remote devices.
 154  */
 155 SCI_STATUS scic_remote_device_da_construct(
 156    SCI_REMOTE_DEVICE_HANDLE_T  remote_device
 157 );
 158
 159 /**
 160  * @brief This method will construct an SCIC_REMOTE_DEVICE object for an
 161  *        expander attached (ea) device from an SMP Discover Response.
 162  *
 163  * @pre The user must have previously called scic_remote_device_construct()
 164  *
 165  * @note  Remote device objects are a limited resource.  As such, they
 166  *        must be protected.  Thus calls to construct and destruct are
 167  *        mutually exclusive and non-reentrant.
 168  *
 169  * @param[in]  remote_device This parameter specifies the remote device to be
 170  *             destructed.
 171  * @param[in]  discover_response This parameter specifies the SMP
 172  *             Discovery Response to be used in device creation.
 173  *
 174  * @return Indicate if the remote device was successfully constructed.
 175  * @retval SCI_SUCCESS Returned if the device was successfully constructed.
 176  * @retval SCI_FAILURE_DEVICE_EXISTS Returned if the device has already
 177  *         been constructed.  If it's an additional phy for the target, then
 178  *         call scic_ea_remote_device_add_phy().
 179  * @retval SCI_FAILURE_UNSUPPORTED_PROTOCOL Returned if the supplied
 180  *         parameters necessitate creation of a remote device for which
 181  *         the protocol is not supported by the underlying controller
 182  *         hardware.
 183  * @retval SCI_FAILURE_INSUFFICIENT_RESOURCES This value is returned if
 184  *         the core controller associated with the supplied parameters
 185  *         is unable to support additional remote devices.
 186  */
 187 SCI_STATUS scic_remote_device_ea_construct(
 188    SCI_REMOTE_DEVICE_HANDLE_T   remote_device,
 189    SMP_RESPONSE_DISCOVER_T    * discover_response
 190 );
 191
 192 /**
 193  * @brief This method is utilized to free up a core's remote device object.
 194  *
 195  * @note  Remote device objects are a limited resource.  As such, they
 196  *        must be protected.  Thus calls to construct and destruct are
 197  *        mutually exclusive and non-reentrant.
 198  *
 199  * @param[in]  remote_device This parameter specifies the remote device to be
 200  *             destructed.
 201  *
 202  * @return The return value shall indicate if the device was successfully
 203  *         destructed or if some failure occurred.
 204  * @retval SCI_STATUS This value is returned if the device is successfully
 205  *         destructed.
 206  * @retval SCI_FAILURE_INVALID_REMOTE_DEVICE This value is returned if the
 207  *         supplied device isn't valid (e.g. it's already been destoryed,
 208  *         the handle isn't valid, etc.).
 209  */
 210 SCI_STATUS scic_remote_device_destruct(
 211    SCI_REMOTE_DEVICE_HANDLE_T  remote_device
 212 );
 213
 214 #if !defined(DISABLE_WIDE_PORTED_TARGETS)
 215 /**
 216  * @brief This method will attempt to set port width for a remote device.
 217  *
 218  * @param[in]  remote_device This parameter specifies the remote device
 219  *             object for which to set new port width.
 220  * @param[in]  new_port_width The new port width to update.
 221  *
 222  * @return Indicate if the device port width was successfully updated.
 223  * @retval SCI_SUCCESS This value is returned when port width update was successful.
 224  * @retval SCI_FAILURE The port width update failed.
 225  */
 226 SCI_STATUS scic_remote_device_set_port_width(
 227    SCI_REMOTE_DEVICE_HANDLE_T  remote_device,
 228    U8                          new_port_width
 229 );
 230
 231 /**
 232  * @brief This method retrieve the SCIC's record of a remote device's port width.
 233  *
 234  * @param[in]  remote_device This parameter specifies the remote device
 235  *             object for which to retrieve the port width value.
 236  *
 237  * @return The SCIC's record of a remote device's port width
 238  */
 239 U8 scic_remote_device_get_port_width(
 240    SCI_REMOTE_DEVICE_HANDLE_T  remote_device
 241 );
 242
 243 #define scic_remote_device_da_add_phy(device, phy) SCI_FAILURE
 244 #define scic_remote_device_ea_add_phy(device, response) SCI_FAILURE
 245 #define scic_remote_device_remove_phy(device) SCI_FAILURE
 246
 247 #else // !defined(DISABLE_WIDE_PORTED_TARGETS)
 248
 249 #define scic_remote_device_set_port_width(device, port_width) SCI_FAILURE
 250 #define scic_remote_device_get_port_width(device) (1)
 251
 252 #define scic_remote_device_da_add_phy(device, phy) SCI_FAILURE
 253 #define scic_remote_device_ea_add_phy(device, response) SCI_FAILURE
 254 #define scic_remote_device_remove_phy(device) SCI_FAILURE
 255
 256 #endif // !defined(DISABLE_WIDE_PORTED_TARGETS)
 257
 258 /**
 259  * @brief This method will start the supplied remote device.  This method
 260  *        enables normal IO requests to flow through to the remote device.
 261  *
 262  * @param[in]  remote_device This parameter specifies the device to be
 263  *             started.
 264  * @param[in]  timeout This parameter specifies the number of milliseconds
 265  *             in which the start operation should complete.
 266  *
 267  * @return An indication of whether the device was successfully started.
 268  * @retval SCI_SUCCESS This value is returned if the device was successfully
 269  *         started.
 270  * @retval SCI_FAILURE_INVALID_PHY This value is returned if the user attempts
 271  *         to start the device when there have been no phys added to it.
 272  */
 273 SCI_STATUS scic_remote_device_start(
 274    SCI_REMOTE_DEVICE_HANDLE_T  remote_device,
 275    U32                         timeout
 276 );
 277
 278 /**
 279  * @brief This method will stop both transmission and reception of link
 280  *        activity for the supplied remote device.  This method disables
 281  *        normal IO requests from flowing through to the remote device.
 282  *
 283  * @param[in]  remote_device This parameter specifies the device to be
 284  *             stopped.
 285  * @param[in]  timeout This parameter specifies the number of milliseconds
 286  *             in which the stop operation should complete.
 287  *
 288  * @return An indication of whether the device was successfully stopped.
 289  * @retval SCI_SUCCESS This value is returned if the transmission and reception
 290  *         for the device was successfully stopped.
 291  */
 292 SCI_STATUS scic_remote_device_stop(
 293    SCI_REMOTE_DEVICE_HANDLE_T  remote_device,
 294    U32                         timeout
 295 );
 296
 297 /**
 298  * @brief This method will reset the device making it ready for operation.
 299  *        This method must be called anytime the device is reset either
 300  *        through a SMP phy control or a port hard reset request.
 301  *
 302  * @note This method does not actually cause the device hardware to be reset.
 303  *       This method resets the software object so that it will be operational
 304  *       after a device hardware reset completes.
 305  *
 306  * @param[in]  remote_device This parameter specifies the device to be
 307  *             reset.
 308  *
 309  * @return An indication of whether the device reset was accepted.
 310  * @retval SCI_SUCCESS This value is returned if the device reset is started.
 311  */
 312 SCI_STATUS scic_remote_device_reset(
 313    SCI_REMOTE_DEVICE_HANDLE_T  remote_device
 314 );
 315
 316 /**
 317  * @brief This method informs the device object that the reset operation is
 318  *        complete and the device can resume operation again.
 319  *
 320  * @param[in]  remote_device This parameter specifies the device which is to
 321  *             be informed of the reset complete operation.
 322  *
 323  * @return An indication that the device is resuming operation.
 324  * @retval SCI_SUCCESS the device is resuming operation.
 325  */
 326 SCI_STATUS scic_remote_device_reset_complete(
 327    SCI_REMOTE_DEVICE_HANDLE_T  remote_device
 328 );
 329
 330 /**
 331  * @brief This method returns the suggested target reset timeout.  SAS and
 332  *        SATA devices have different timeout values in milliseconds for
 333  *        target reset operations.
 334  *
 335  * @param[in]  remote_device This parameter specifies the device which is to
 336  *             be informed of the reset complete operation.
 337  *
 338  * @return The suggested reset timeout value for the specified target device
 339  *         in milliseconds.
 340  */
 341 U32 scic_remote_device_get_suggested_reset_timeout(
 342    SCI_REMOTE_DEVICE_HANDLE_T  remote_device
 343 );
 344
 345 /**
 346  * @brief This method will set the maximum link speed to be utilized
 347  *        when connections are established for the supplied remote device.
 348  *
 349  * @pre The remote device must previously have been stopped for this
 350  *      call to succeed.
 351  *
 352  * @param[in]  remote_device This parameter specifies the device for which
 353  *             to set the maximum connection rate.
 354  * @param[in]  connection_rate This parameter specifies the maximum link rate
 355  *             to be utilized for all connections to the supplied remote
 356  *             device.
 357  *
 358  * @return An indication as to whether the connection rate was successfully
 359  *         updated.
 360  * @retval SCI_SUCCESS This value is returned if the connection rate was
 361  *         successfully updated.
 362  * @retval SCI_FAILURE_INVALID_STATE This value is returned if the remote
 363  *         device is not in a stopped state or some other state that allows
 364  *         for a maximum connection rate change.
 365  */
 366 SCI_STATUS scic_remote_device_set_max_connection_rate(
 367    SCI_REMOTE_DEVICE_HANDLE_T  remote_device,
 368    SCI_SAS_LINK_RATE           connection_rate
 369 );
 370
 371 /**
 372  * @brief This method simply returns the link rate at which communications
 373  *        to the remote device occur.
 374  *
 375  * @param[in]  remote_device This parameter specifies the device for which
 376  *             to get the connection rate.
 377  *
 378  * @return Return the link rate at which we transfer for the supplied
 379  *         remote device.
 380  */
 381 SCI_SAS_LINK_RATE scic_remote_device_get_connection_rate(
 382    SCI_REMOTE_DEVICE_HANDLE_T  remote_device
 383 );
 384
 385 /**
 386  * @brief This method will indicate which protocols are supported by this
 387  *        remote device.
 388  *
 389  * @param[in]  remote_device This parameter specifies the device for which
 390  *             to return the protocol.
 391  * @param[out] protocols This parameter specifies the output values, from
 392  *             the remote device object, which indicate the protocols
 393  *             supported by the supplied remote_device.
 394  *
 395  * @return The type of protocols supported by this device.  The values are
 396  *         returned as part of a bit mask in order to allow for multi-protocol
 397  *         support.
 398  */
 399 void scic_remote_device_get_protocols(
 400    SCI_REMOTE_DEVICE_HANDLE_T          remote_device,
 401    SMP_DISCOVER_RESPONSE_PROTOCOLS_T * protocols
 402 );
 403
 404 /**
 405  * @brief This method will indicate the SAS address for the remote device.
 406  *
 407  * @param[in]  remote_device This parameter specifies the device for which
 408  *             to return the SAS address.
 409  * @param[out] sas_address This parameter specifies a pointer to a SAS
 410  *             address structure into which the core will copy the SAS
 411  *             address for the remote device.
 412  *
 413  * @return none
 414  */
 415 void scic_remote_device_get_sas_address(
 416    SCI_REMOTE_DEVICE_HANDLE_T   remote_device,
 417    SCI_SAS_ADDRESS_T          * sas_address
 418 );
 419
 420 #if !defined(DISABLE_ATAPI)
 421 /**
 422  * This method first decide whether a device is a stp target, then
 423  *    decode the signature fis of a DA STP device to tell whether it
 424  *    is a standard end disk or an ATAPI device.
 425  *
 426  * @param[in] this_device The device whose type is to be decided.
 427  *
 428  * @return BOOL Indicate a device is ATAPI device or not.
 429  */
 430 BOOL scic_remote_device_is_atapi(
 431    SCI_REMOTE_DEVICE_HANDLE_T device_handle
 432 );
 433 #else // !defined(DISABLE_ATAPI)
 434 #define scic_remote_device_is_atapi(device_handle) FALSE
 435 #endif // !defined(DISABLE_ATAPI)
 436
 437 #ifdef __cplusplus
 438 }
 439 #endif // __cplusplus
 440
 441 #endif // _SCIC_REMOTE_DEVICE_H_
 442