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