1 /*- 2 * SPDX-License-Identifier: BSD-2-Clause OR GPL-2.0 3 * 4 * This file is provided under a dual BSD/GPLv2 license. When using or 5 * redistributing this file, you may do so under either license. 6 * 7 * GPL LICENSE SUMMARY 8 * 9 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 10 * 11 * This program is free software; you can redistribute it and/or modify 12 * it under the terms of version 2 of the GNU General Public License as 13 * published by the Free Software Foundation. 14 * 15 * This program is distributed in the hope that it will be useful, but 16 * WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 18 * General Public License for more details. 19 * 20 * You should have received a copy of the GNU General Public License 21 * along with this program; if not, write to the Free Software 22 * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. 23 * The full GNU General Public License is included in this distribution 24 * in the file called LICENSE.GPL. 25 * 26 * BSD LICENSE 27 * 28 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 29 * All rights reserved. 30 * 31 * Redistribution and use in source and binary forms, with or without 32 * modification, are permitted provided that the following conditions 33 * are met: 34 * 35 * * Redistributions of source code must retain the above copyright 36 * notice, this list of conditions and the following disclaimer. 37 * * Redistributions in binary form must reproduce the above copyright 38 * notice, this list of conditions and the following disclaimer in 39 * the documentation and/or other materials provided with the 40 * distribution. 41 * 42 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 43 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 44 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 45 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 46 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 47 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 48 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 49 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 50 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 51 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 52 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 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 443