2 * SPDX-License-Identifier: BSD-2-Clause OR GPL-2.0
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.
9 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
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.
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.
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.
28 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
29 * All rights reserved.
31 * Redistribution and use in source and binary forms, with or without
32 * modification, are permitted provided that the following conditions
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
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.
56 #ifndef _SCIC_REMOTE_DEVICE_H_
57 #define _SCIC_REMOTE_DEVICE_H_
62 * @brief This file contains all of the interface methods that can be called
63 * by an SCIC user on the device object.
70 #include <dev/isci/scil/sci_types.h>
71 #include <dev/isci/scil/sci_status.h>
72 #include <dev/isci/scil/intel_sas.h>
78 typedef enum SCIC_REMOTE_DEVICE_NOT_READY_REASON_CODE
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,
86 SCIC_REMOTE_DEVICE_NOT_READY_REASON_CODE_MAX
88 } SCIC_REMOTE_DEVICE_NOT_READY_REASON_CODE_T;
91 * @brief This method simply returns the maximum memory space needed to
92 * store a remote device object.
94 * @return a positive integer value indicating the size (in bytes) of the
95 * remote device object.
97 U32 scic_remote_device_get_object_size(
102 * @brief This method will perform the construction common to all
103 * remote device objects.
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.
111 * @param[in] port This parameter specifies the SAS/SATA Port handle
112 * corresponding to the port through which this device
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
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
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.
135 * @pre The user must have previously called scic_remote_device_construct()
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.
141 * @param[in] remote_device This parameter specifies the remote device to be
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
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.
157 SCI_STATUS scic_remote_device_da_construct(
158 SCI_REMOTE_DEVICE_HANDLE_T remote_device
162 * @brief This method will construct an SCIC_REMOTE_DEVICE object for an
163 * expander attached (ea) device from an SMP Discover Response.
165 * @pre The user must have previously called scic_remote_device_construct()
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.
171 * @param[in] remote_device This parameter specifies the remote device to be
173 * @param[in] discover_response This parameter specifies the SMP
174 * Discovery Response to be used in device creation.
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
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.
189 SCI_STATUS scic_remote_device_ea_construct(
190 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
191 SMP_RESPONSE_DISCOVER_T * discover_response
195 * @brief This method is utilized to free up a core's remote device object.
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.
201 * @param[in] remote_device This parameter specifies the remote device to be
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
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.).
212 SCI_STATUS scic_remote_device_destruct(
213 SCI_REMOTE_DEVICE_HANDLE_T remote_device
216 #if !defined(DISABLE_WIDE_PORTED_TARGETS)
218 * @brief This method will attempt to set port width for a remote device.
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.
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.
228 SCI_STATUS scic_remote_device_set_port_width(
229 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
234 * @brief This method retrieve the SCIC's record of a remote device's port width.
236 * @param[in] remote_device This parameter specifies the remote device
237 * object for which to retrieve the port width value.
239 * @return The SCIC's record of a remote device's port width
241 U8 scic_remote_device_get_port_width(
242 SCI_REMOTE_DEVICE_HANDLE_T remote_device
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
249 #else // !defined(DISABLE_WIDE_PORTED_TARGETS)
251 #define scic_remote_device_set_port_width(device, port_width) SCI_FAILURE
252 #define scic_remote_device_get_port_width(device) (1)
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
258 #endif // !defined(DISABLE_WIDE_PORTED_TARGETS)
261 * @brief This method will start the supplied remote device. This method
262 * enables normal IO requests to flow through to the remote device.
264 * @param[in] remote_device This parameter specifies the device to be
266 * @param[in] timeout This parameter specifies the number of milliseconds
267 * in which the start operation should complete.
269 * @return An indication of whether the device was successfully started.
270 * @retval SCI_SUCCESS This value is returned if the device was successfully
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.
275 SCI_STATUS scic_remote_device_start(
276 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
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.
285 * @param[in] remote_device This parameter specifies the device to be
287 * @param[in] timeout This parameter specifies the number of milliseconds
288 * in which the stop operation should complete.
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.
294 SCI_STATUS scic_remote_device_stop(
295 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
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.
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.
308 * @param[in] remote_device This parameter specifies the device to be
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.
314 SCI_STATUS scic_remote_device_reset(
315 SCI_REMOTE_DEVICE_HANDLE_T remote_device
319 * @brief This method informs the device object that the reset operation is
320 * complete and the device can resume operation again.
322 * @param[in] remote_device This parameter specifies the device which is to
323 * be informed of the reset complete operation.
325 * @return An indication that the device is resuming operation.
326 * @retval SCI_SUCCESS the device is resuming operation.
328 SCI_STATUS scic_remote_device_reset_complete(
329 SCI_REMOTE_DEVICE_HANDLE_T remote_device
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.
337 * @param[in] remote_device This parameter specifies the device which is to
338 * be informed of the reset complete operation.
340 * @return The suggested reset timeout value for the specified target device
343 U32 scic_remote_device_get_suggested_reset_timeout(
344 SCI_REMOTE_DEVICE_HANDLE_T remote_device
348 * @brief This method will set the maximum link speed to be utilized
349 * when connections are established for the supplied remote device.
351 * @pre The remote device must previously have been stopped for this
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
360 * @return An indication as to whether the connection rate was successfully
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.
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
374 * @brief This method simply returns the link rate at which communications
375 * to the remote device occur.
377 * @param[in] remote_device This parameter specifies the device for which
378 * to get the connection rate.
380 * @return Return the link rate at which we transfer for the supplied
383 SCI_SAS_LINK_RATE scic_remote_device_get_connection_rate(
384 SCI_REMOTE_DEVICE_HANDLE_T remote_device
388 * @brief This method will indicate which protocols are supported by this
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.
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
401 void scic_remote_device_get_protocols(
402 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
403 SMP_DISCOVER_RESPONSE_PROTOCOLS_T * protocols
407 * @brief This method will indicate the SAS address for the remote device.
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.
417 void scic_remote_device_get_sas_address(
418 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
419 SCI_SAS_ADDRESS_T * sas_address
422 #if !defined(DISABLE_ATAPI)
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.
428 * @param[in] this_device The device whose type is to be decided.
430 * @return BOOL Indicate a device is ATAPI device or not.
432 BOOL scic_remote_device_is_atapi(
433 SCI_REMOTE_DEVICE_HANDLE_T device_handle
435 #else // !defined(DISABLE_ATAPI)
436 #define scic_remote_device_is_atapi(device_handle) FALSE
437 #endif // !defined(DISABLE_ATAPI)
441 #endif // __cplusplus
443 #endif // _SCIC_REMOTE_DEVICE_H_