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
39 * * Neither the name of Intel Corporation nor the names of its
40 * contributors may be used to endorse or promote products derived
41 * from this software without specific prior written permission.
43 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
44 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
45 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
46 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
47 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
48 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
49 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
50 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
51 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
52 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
53 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
56 #ifndef _SCIC_REMOTE_DEVICE_H_
57 #define _SCIC_REMOTE_DEVICE_H_
60 * This file contains all of the interface methods that can be called by an
61 * SCIC user on the device object.
67 #include "sci_types.h"
68 #include "sci_status.h"
69 #include "intel_sas.h"
72 struct scic_sds_remote_device;
79 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
91 * scic_remote_device_get_object_size() - This method simply returns the
92 * maximum memory space needed to store a remote device object.
94 * a positive integer value indicating the size (in bytes) of the remote device
97 u32 scic_remote_device_get_object_size(
100 struct scic_sds_port;
101 struct scic_sds_remote_device;
103 * scic_remote_device_construct() - This method will perform the construction
104 * common to all remote device objects.
105 * @sci_port: SAS/SATA port through which this device is accessed.
106 * @sci_dev: remote device to construct
108 * It isn't necessary to call scic_remote_device_destruct() for device objects
109 * that have only called this method for construction. Once subsequent
110 * construction methods have been invoked (e.g.
111 * scic_remote_device_da_construct()), then destruction should occur. none
113 void scic_remote_device_construct(struct scic_sds_port *sci_port,
114 struct scic_sds_remote_device *sci_dev);
117 * scic_remote_device_da_construct() - This method will construct a
118 * SCIC_REMOTE_DEVICE object for a direct attached (da) device. The
119 * information (e.g. IAF, Signature FIS, etc.) necessary to build the device
120 * is known to the SCI Core since it is contained in the scic_phy object.
121 * @remote_device: This parameter specifies the remote device to be destructed.
123 * The user must have previously called scic_remote_device_construct() Remote
124 * device objects are a limited resource. As such, they must be protected.
125 * Thus calls to construct and destruct are mutually exclusive and
126 * non-reentrant. Indicate if the remote device was successfully constructed.
127 * SCI_SUCCESS Returned if the device was successfully constructed.
128 * SCI_FAILURE_DEVICE_EXISTS Returned if the device has already been
129 * constructed. If it's an additional phy for the target, then call
130 * scic_remote_device_da_add_phy(). SCI_FAILURE_UNSUPPORTED_PROTOCOL Returned
131 * if the supplied parameters necessitate creation of a remote device for which
132 * the protocol is not supported by the underlying controller hardware.
133 * SCI_FAILURE_INSUFFICIENT_RESOURCES This value is returned if the core
134 * controller associated with the supplied parameters is unable to support
135 * additional remote devices.
137 enum sci_status scic_remote_device_da_construct(
138 struct scic_sds_remote_device *remote_device);
141 * scic_remote_device_ea_construct() - This method will construct an
142 * SCIC_REMOTE_DEVICE object for an expander attached (ea) device from an
143 * SMP Discover Response.
144 * @remote_device: This parameter specifies the remote device to be destructed.
145 * @discover_response: This parameter specifies the SMP Discovery Response to
146 * be used in device creation.
148 * The user must have previously called scic_remote_device_construct() Remote
149 * device objects are a limited resource. As such, they must be protected.
150 * Thus calls to construct and destruct are mutually exclusive and
151 * non-reentrant. Indicate if the remote device was successfully constructed.
152 * SCI_SUCCESS Returned if the device was successfully constructed.
153 * SCI_FAILURE_DEVICE_EXISTS Returned if the device has already been
154 * constructed. If it's an additional phy for the target, then call
155 * scic_ea_remote_device_add_phy(). SCI_FAILURE_UNSUPPORTED_PROTOCOL Returned
156 * if the supplied parameters necessitate creation of a remote device for which
157 * the protocol is not supported by the underlying controller hardware.
158 * SCI_FAILURE_INSUFFICIENT_RESOURCES This value is returned if the core
159 * controller associated with the supplied parameters is unable to support
160 * additional remote devices.
162 enum sci_status scic_remote_device_ea_construct(
163 struct scic_sds_remote_device *remote_device,
164 struct smp_response_discover *discover_response);
167 * scic_remote_device_destruct() - This method is utilized to free up a core's
168 * remote device object.
169 * @remote_device: This parameter specifies the remote device to be destructed.
171 * Remote device objects are a limited resource. As such, they must be
172 * protected. Thus calls to construct and destruct are mutually exclusive and
173 * non-reentrant. The return value shall indicate if the device was
174 * successfully destructed or if some failure occurred. enum sci_status This value
175 * is returned if the device is successfully destructed.
176 * SCI_FAILURE_INVALID_REMOTE_DEVICE This value is returned if the supplied
177 * device isn't valid (e.g. it's already been destoryed, the handle isn't
180 enum sci_status scic_remote_device_destruct(
181 struct scic_sds_remote_device *remote_device);
188 * scic_remote_device_start() - This method will start the supplied remote
189 * device. This method enables normal IO requests to flow through to the
191 * @remote_device: This parameter specifies the device to be started.
192 * @timeout: This parameter specifies the number of milliseconds in which the
193 * start operation should complete.
195 * An indication of whether the device was successfully started. SCI_SUCCESS
196 * This value is returned if the device was successfully started.
197 * SCI_FAILURE_INVALID_PHY This value is returned if the user attempts to start
198 * the device when there have been no phys added to it.
200 enum sci_status scic_remote_device_start(
201 struct scic_sds_remote_device *remote_device,
205 * scic_remote_device_stop() - This method will stop both transmission and
206 * reception of link activity for the supplied remote device. This method
207 * disables normal IO requests from flowing through to the remote device.
208 * @remote_device: This parameter specifies the device to be stopped.
209 * @timeout: This parameter specifies the number of milliseconds in which the
210 * stop operation should complete.
212 * An indication of whether the device was successfully stopped. SCI_SUCCESS
213 * This value is returned if the transmission and reception for the device was
214 * successfully stopped.
216 enum sci_status scic_remote_device_stop(
217 struct scic_sds_remote_device *remote_device,
221 * scic_remote_device_reset() - This method will reset the device making it
222 * ready for operation. This method must be called anytime the device is
223 * reset either through a SMP phy control or a port hard reset request.
224 * @remote_device: This parameter specifies the device to be reset.
226 * This method does not actually cause the device hardware to be reset. This
227 * method resets the software object so that it will be operational after a
228 * device hardware reset completes. An indication of whether the device reset
229 * was accepted. SCI_SUCCESS This value is returned if the device reset is
232 enum sci_status scic_remote_device_reset(
233 struct scic_sds_remote_device *remote_device);
236 * scic_remote_device_reset_complete() - This method informs the device object
237 * that the reset operation is complete and the device can resume operation
239 * @remote_device: This parameter specifies the device which is to be informed
240 * of the reset complete operation.
242 * An indication that the device is resuming operation. SCI_SUCCESS the device
243 * is resuming operation.
245 enum sci_status scic_remote_device_reset_complete(
246 struct scic_sds_remote_device *remote_device);
251 * scic_remote_device_get_connection_rate() - This method simply returns the
252 * link rate at which communications to the remote device occur.
253 * @remote_device: This parameter specifies the device for which to get the
256 * Return the link rate at which we transfer for the supplied remote device.
258 enum sci_sas_link_rate scic_remote_device_get_connection_rate(
259 struct scic_sds_remote_device *remote_device);
262 * scic_remote_device_get_protocols() - This method will indicate which
263 * protocols are supported by this remote device.
264 * @remote_device: This parameter specifies the device for which to return the
266 * @protocols: This parameter specifies the output values, from the remote
267 * device object, which indicate the protocols supported by the supplied
270 * The type of protocols supported by this device. The values are returned as
271 * part of a bit mask in order to allow for multi-protocol support.
273 void scic_remote_device_get_protocols(
274 struct scic_sds_remote_device *remote_device,
275 struct smp_discover_response_protocols *protocols);
278 #if !defined(DISABLE_ATAPI)
280 * scic_remote_device_is_atapi() -
281 * @this_device: The device whose type is to be decided.
283 * This method first decide whether a device is a stp target, then decode the
284 * signature fis of a DA STP device to tell whether it is a standard end disk
285 * or an ATAPI device. bool Indicate a device is ATAPI device or not.
287 bool scic_remote_device_is_atapi(
288 struct scic_sds_remote_device *device_handle);
289 #else /* !defined(DISABLE_ATAPI) */
290 #define scic_remote_device_is_atapi(device_handle) false
291 #endif /* !defined(DISABLE_ATAPI) */
294 #endif /* _SCIC_REMOTE_DEVICE_H_ */