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.
7 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
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.
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.
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.
26 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
27 * All rights reserved.
29 * Redistribution and use in source and binary forms, with or without
30 * modification, are permitted provided that the following conditions
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
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.
54 #ifndef _SCIC_REMOTE_DEVICE_H_
55 #define _SCIC_REMOTE_DEVICE_H_
60 * @brief This file contains all of the interface methods that can be called
61 * by an SCIC user on the device object.
68 #include <dev/isci/scil/sci_types.h>
69 #include <dev/isci/scil/sci_status.h>
70 #include <dev/isci/scil/intel_sas.h>
76 typedef enum SCIC_REMOTE_DEVICE_NOT_READY_REASON_CODE
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,
84 SCIC_REMOTE_DEVICE_NOT_READY_REASON_CODE_MAX
86 } SCIC_REMOTE_DEVICE_NOT_READY_REASON_CODE_T;
89 * @brief This method simply returns the maximum memory space needed to
90 * store a remote device object.
92 * @return a positive integer value indicating the size (in bytes) of the
93 * remote device object.
95 U32 scic_remote_device_get_object_size(
100 * @brief This method will perform the construction common to all
101 * remote device objects.
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.
109 * @param[in] port This parameter specifies the SAS/SATA Port handle
110 * corresponding to the port through which this device
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
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
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.
133 * @pre The user must have previously called scic_remote_device_construct()
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.
139 * @param[in] remote_device This parameter specifies the remote device to be
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
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.
155 SCI_STATUS scic_remote_device_da_construct(
156 SCI_REMOTE_DEVICE_HANDLE_T remote_device
160 * @brief This method will construct an SCIC_REMOTE_DEVICE object for an
161 * expander attached (ea) device from an SMP Discover Response.
163 * @pre The user must have previously called scic_remote_device_construct()
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.
169 * @param[in] remote_device This parameter specifies the remote device to be
171 * @param[in] discover_response This parameter specifies the SMP
172 * Discovery Response to be used in device creation.
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
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.
187 SCI_STATUS scic_remote_device_ea_construct(
188 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
189 SMP_RESPONSE_DISCOVER_T * discover_response
193 * @brief This method is utilized to free up a core's remote device object.
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.
199 * @param[in] remote_device This parameter specifies the remote device to be
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
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.).
210 SCI_STATUS scic_remote_device_destruct(
211 SCI_REMOTE_DEVICE_HANDLE_T remote_device
214 #if !defined(DISABLE_WIDE_PORTED_TARGETS)
216 * @brief This method will attempt to set port width for a remote device.
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.
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.
226 SCI_STATUS scic_remote_device_set_port_width(
227 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
232 * @brief This method retrieve the SCIC's record of a remote device's port width.
234 * @param[in] remote_device This parameter specifies the remote device
235 * object for which to retrieve the port width value.
237 * @return The SCIC's record of a remote device's port width
239 U8 scic_remote_device_get_port_width(
240 SCI_REMOTE_DEVICE_HANDLE_T remote_device
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
247 #else // !defined(DISABLE_WIDE_PORTED_TARGETS)
249 #define scic_remote_device_set_port_width(device, port_width) SCI_FAILURE
250 #define scic_remote_device_get_port_width(device) (1)
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
256 #endif // !defined(DISABLE_WIDE_PORTED_TARGETS)
259 * @brief This method will start the supplied remote device. This method
260 * enables normal IO requests to flow through to the remote device.
262 * @param[in] remote_device This parameter specifies the device to be
264 * @param[in] timeout This parameter specifies the number of milliseconds
265 * in which the start operation should complete.
267 * @return An indication of whether the device was successfully started.
268 * @retval SCI_SUCCESS This value is returned if the device was successfully
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.
273 SCI_STATUS scic_remote_device_start(
274 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
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.
283 * @param[in] remote_device This parameter specifies the device to be
285 * @param[in] timeout This parameter specifies the number of milliseconds
286 * in which the stop operation should complete.
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.
292 SCI_STATUS scic_remote_device_stop(
293 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
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.
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.
306 * @param[in] remote_device This parameter specifies the device to be
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.
312 SCI_STATUS scic_remote_device_reset(
313 SCI_REMOTE_DEVICE_HANDLE_T remote_device
317 * @brief This method informs the device object that the reset operation is
318 * complete and the device can resume operation again.
320 * @param[in] remote_device This parameter specifies the device which is to
321 * be informed of the reset complete operation.
323 * @return An indication that the device is resuming operation.
324 * @retval SCI_SUCCESS the device is resuming operation.
326 SCI_STATUS scic_remote_device_reset_complete(
327 SCI_REMOTE_DEVICE_HANDLE_T remote_device
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.
335 * @param[in] remote_device This parameter specifies the device which is to
336 * be informed of the reset complete operation.
338 * @return The suggested reset timeout value for the specified target device
341 U32 scic_remote_device_get_suggested_reset_timeout(
342 SCI_REMOTE_DEVICE_HANDLE_T remote_device
346 * @brief This method will set the maximum link speed to be utilized
347 * when connections are established for the supplied remote device.
349 * @pre The remote device must previously have been stopped for this
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
358 * @return An indication as to whether the connection rate was successfully
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.
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
372 * @brief This method simply returns the link rate at which communications
373 * to the remote device occur.
375 * @param[in] remote_device This parameter specifies the device for which
376 * to get the connection rate.
378 * @return Return the link rate at which we transfer for the supplied
381 SCI_SAS_LINK_RATE scic_remote_device_get_connection_rate(
382 SCI_REMOTE_DEVICE_HANDLE_T remote_device
386 * @brief This method will indicate which protocols are supported by this
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.
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
399 void scic_remote_device_get_protocols(
400 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
401 SMP_DISCOVER_RESPONSE_PROTOCOLS_T * protocols
405 * @brief This method will indicate the SAS address for the remote device.
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.
415 void scic_remote_device_get_sas_address(
416 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
417 SCI_SAS_ADDRESS_T * sas_address
420 #if !defined(DISABLE_ATAPI)
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.
426 * @param[in] this_device The device whose type is to be decided.
428 * @return BOOL Indicate a device is ATAPI device or not.
430 BOOL scic_remote_device_is_atapi(
431 SCI_REMOTE_DEVICE_HANDLE_T device_handle
433 #else // !defined(DISABLE_ATAPI)
434 #define scic_remote_device_is_atapi(device_handle) FALSE
435 #endif // !defined(DISABLE_ATAPI)
439 #endif // __cplusplus
441 #endif // _SCIC_REMOTE_DEVICE_H_