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 _SCIF_SAS_REMOTE_DEVICE_H_
55 #define _SCIF_SAS_REMOTE_DEVICE_H_
60 * @brief This file contains the protected interface structures, constants,
61 * and methods for the SCIF_SAS_REMOTE_DEVICE object.
68 #include <dev/isci/scil/scif_remote_device.h>
70 #include <dev/isci/scil/sci_base_remote_device.h>
71 #include <dev/isci/scil/sci_base_request.h>
72 #include <dev/isci/scil/sci_base_state_machine_logger.h>
73 #include <dev/isci/scil/scif_sas_stp_remote_device.h>
74 #include <dev/isci/scil/scif_sas_smp_remote_device.h>
77 struct SCIF_SAS_DOMAIN;
78 struct SCIF_SAS_REMOTE_DEVICE;
79 struct SCIF_SAS_REQUEST;
82 * This constant indicates the number of milliseconds to wait for the core
83 * to start/stop it's remote device object.
85 #define SCIF_SAS_REMOTE_DEVICE_CORE_OP_TIMEOUT 1000
88 * @enum _SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATES
90 * @brief This enumeration depicts all the substates for the remote device's
91 * starting substate machine.
93 typedef enum _SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATES
96 * This state indicates that the framework is waiting for the core to
97 * issue a scic_cb_remote_device_start_complete() notification.
99 SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATE_AWAIT_COMPLETE,
102 * This state indicates that the core has received the core's
103 * scic_cb_remote_device_start_complete() notification.
105 SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATE_AWAIT_READY,
107 SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATE_MAX_STATES
109 } SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATES;
112 * @enum _SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATES
114 * @brief This enumeration depicts all of the substates for the remote
115 * device READY substate machine.
117 typedef enum _SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATES
120 * The Operational sub-state indicates that the remote device object
121 * is capable of receiving and handling all request types.
123 SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATE_OPERATIONAL,
126 * This substate indicates that core remote device is not ready.
127 * As a result, no new IO or Task Management requests are allowed.
129 SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATE_SUSPENDED,
132 * This substate indicates that task management to this device is
133 * ongoing and new IO requests are not allowed.
135 SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATE_TASK_MGMT,
138 * This substate indicates that core remote device is not ready due
139 * to an NCQ error. As a result, no new IO requests are allowed.
141 SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATE_NCQ_ERROR,
143 SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATE_MAX_STATES
145 } SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATES;
147 struct SCIF_SAS_REMOTE_DEVICE;
148 typedef void (*SCIF_SAS_REMOTE_DEVICE_COMPLETION_HANDLER_T)(
149 struct SCIF_SAS_REMOTE_DEVICE *,
153 typedef void (*SCIF_SAS_REMOTE_DEVICE_HANDLER_T)(
154 struct SCIF_SAS_REMOTE_DEVICE *
157 typedef void (*SCIF_SAS_REMOTE_DEVICE_NOT_READY_HANDLER_T)(
158 struct SCIF_SAS_REMOTE_DEVICE *,
163 * @struct SCIF_SAS_REMOTE_DEVICE_STATE_HANDLER
165 * @brief This structure defines the state handler methods for states and
166 * substates applicable for the framework remote device object.
168 typedef struct SCIF_SAS_REMOTE_DEVICE_STATE_HANDLER
170 SCI_BASE_REMOTE_DEVICE_STATE_HANDLER_T parent;
171 SCIF_SAS_REMOTE_DEVICE_COMPLETION_HANDLER_T start_complete_handler;
172 SCIF_SAS_REMOTE_DEVICE_COMPLETION_HANDLER_T stop_complete_handler;
173 SCIF_SAS_REMOTE_DEVICE_HANDLER_T ready_handler;
174 SCIF_SAS_REMOTE_DEVICE_NOT_READY_HANDLER_T not_ready_handler;
175 SCI_BASE_REMOTE_DEVICE_REQUEST_HANDLER_T start_high_priority_io_handler;
176 SCI_BASE_REMOTE_DEVICE_HIGH_PRIORITY_REQUEST_COMPLETE_HANDLER_T complete_high_priority_io_handler;
177 } SCIF_SAS_REMOTE_DEVICE_STATE_HANDLER_T;
180 * @struct SCIF_SAS_REMOTE_DEVICE
182 * @brief The SCI SAS Framework remote device object abstracts the SAS remote
183 * device level behavior for the framework component. Additionally,
184 * it provides a higher level of abstraction for the core remote
187 typedef struct SCIF_SAS_REMOTE_DEVICE
190 * The SCI_BASE_REMOTE_DEVICE is the parent object for the
191 * SCIF_SAS_REMOTE_DEVICE object.
193 SCI_BASE_REMOTE_DEVICE_T parent;
196 * This field contains the handle for the SCI Core remote device object
197 * that is managed by this framework controller.
199 SCI_REMOTE_DEVICE_HANDLE_T core_object;
202 * This field references the list of state specific handler methods to
203 * be utilized for this remote device instance.
205 SCIF_SAS_REMOTE_DEVICE_STATE_HANDLER_T * state_handlers;
208 * This field specifies the state machine utilized to manage the
209 * starting remote device substate machine.
211 SCI_BASE_STATE_MACHINE_T starting_substate_machine;
214 * This field specifies the state machine utilized to manage the
215 * starting remote device substate machine.
217 SCI_BASE_STATE_MACHINE_T ready_substate_machine;
222 * This field specifies the information specific to SATA/STP device
223 * instances. This field is not utilized for SSP/SMP.
225 SCIF_SAS_STP_REMOTE_DEVICE_T stp_device;
228 * This field specifies the information specific to SMP device instances.
229 * This field is not utilized for SSP/SATA/STP.
231 SCIF_SAS_SMP_REMOTE_DEVICE_T smp_device;
236 * This field indicates the domain object containing this remote device.
238 struct SCIF_SAS_DOMAIN * domain;
241 * This field counts the number of requests (IO and task management)
242 * that are currently outstanding for this device.
247 * This field counts the number of only task management request that are
248 * currently outstanding for this device.
250 U32 task_request_count;
253 * This field is utilize to store the status value of various operations
254 * the can be executed on this remote device instance.
256 SCI_STATUS operation_status;
259 * This field is utilize to indicate that the remote device should be
260 * destructed when it finally reaches the stopped state. This will
261 * include destructing the core remote device as well.
263 BOOL destruct_when_stopped;
266 * This field marks a device state of being discovered or not, majorly used
267 * during re-discover procedure.
269 BOOL is_currently_discovered;
272 * This filed stores the expander device this device connected to, only if this
273 * device is behind expander. So this field also served as a flag to tell if a
274 * device is a EA one.
276 struct SCIF_SAS_REMOTE_DEVICE * containing_device;
279 * This field stores the expander phy identifier for an expander attached
280 * device. This field is only used by expander attached device.
282 U8 expander_phy_identifier;
285 * This field stores the port width for a device. Most devices are narrow port
286 * device, their port width is 1. If a device is a wide port device, their
287 * port width is larger than 1.
289 U8 device_port_width;
292 * This field stores the destination state for a remote device in UPDATING
293 * PORT WIDTH state. The possible destination states for a remote device in
294 * UPDATING_PORT_WIDTH state are READY or STOPPING.
296 U16 destination_state;
299 * This field stores the scheduled/delayed EA target reset request.
301 struct SCIF_SAS_REQUEST * ea_target_reset_request_scheduled;
305 * This field is the observer of the base state machine for this device
308 SCI_BASE_OBSERVER_T base_state_machine_observer;
311 * This field is the state machine logger of the startig substate machine for
312 * this device object.
314 SCI_BASE_STATE_MACHINE_LOGGER_T starting_substate_machine_logger;
317 * This field is the state machine logger of the ready substate machine for
318 * this device object.
320 SCI_BASE_STATE_MACHINE_LOGGER_T ready_substate_machine_logger;
321 #endif // SCI_LOGGING
323 } SCIF_SAS_REMOTE_DEVICE_T;
325 extern SCI_BASE_STATE_T scif_sas_remote_device_state_table[];
326 extern SCIF_SAS_REMOTE_DEVICE_STATE_HANDLER_T
327 scif_sas_remote_device_state_handler_table[];
329 extern SCI_BASE_STATE_T scif_sas_remote_device_starting_substate_table[];
330 extern SCIF_SAS_REMOTE_DEVICE_STATE_HANDLER_T
331 scif_sas_remote_device_starting_substate_handler_table[];
333 extern SCI_BASE_STATE_T scif_sas_remote_device_ready_substate_table[];
334 extern SCIF_SAS_REMOTE_DEVICE_STATE_HANDLER_T
335 scif_sas_remote_device_ready_substate_handler_table[];
340 * This enumeration is used to define the end destination state for the
341 * framework remote device.
343 enum SCIF_SAS_REMOTE_DEVICE_DESTINATION_STATE
345 SCIF_SAS_REMOTE_DEVICE_DESTINATION_STATE_UNSPECIFIED,
346 SCIF_SAS_REMOTE_DEVICE_DESTINATION_STATE_READY,
347 SCIF_SAS_REMOTE_DEVICE_DESTINATION_STATE_STOPPING,
348 SCIF_SAS_REMOTE_DEVICE_DESTINATION_STATE_UPDATING_PORT_WIDTH
351 //******************************************************************************
352 //* P R O T E C T E D M E T H O D S
353 //******************************************************************************
354 void scif_sas_remote_device_save_report_phy_sata_information(
355 SMP_RESPONSE_REPORT_PHY_SATA_T * report_phy_sata_response
358 void scif_sas_remote_device_target_reset(
359 SCIF_SAS_REMOTE_DEVICE_T * fw_device,
360 struct SCIF_SAS_REQUEST * fw_request
363 void scif_sas_remote_device_target_reset_complete(
364 SCIF_SAS_REMOTE_DEVICE_T * fw_device,
365 struct SCIF_SAS_REQUEST * fw_request,
366 SCI_STATUS completion_status
370 void scif_sas_remote_device_initialize_state_logging(
371 SCIF_SAS_REMOTE_DEVICE_T * remote_device
374 void scif_sas_remote_device_deinitialize_state_logging(
375 SCIF_SAS_REMOTE_DEVICE_T * remote_device
378 #define scif_sas_remote_device_initialize_state_logging(x)
379 #define scif_sas_remote_device_deinitialize_state_logging(x)
380 #endif // SCI_LOGGING
382 //******************************************************************************
383 //* R E A D Y O P E R A T I O N A L S T A T E H A N D L E R S
384 //******************************************************************************
386 SCI_STATUS scif_sas_remote_device_ready_operational_complete_io_handler(
387 SCI_BASE_REMOTE_DEVICE_T * remote_device,
388 SCI_BASE_REQUEST_T * io_request
391 SCI_STATUS scif_sas_remote_device_ready_operational_complete_task_handler(
392 SCI_BASE_REMOTE_DEVICE_T * remote_device,
393 SCI_BASE_REQUEST_T * task_request
396 SCI_STATUS scif_sas_remote_device_ready_task_management_complete_task_handler(
397 SCI_BASE_REMOTE_DEVICE_T * remote_device,
398 SCI_BASE_REQUEST_T * task_request
401 //******************************************************************************
402 //* D E F A U L T S T A T E H A N D L E R S
403 //******************************************************************************
405 SCI_STATUS scif_sas_remote_device_default_start_handler(
406 SCI_BASE_REMOTE_DEVICE_T * remote_device
409 SCI_STATUS scif_sas_remote_device_default_stop_handler(
410 SCI_BASE_REMOTE_DEVICE_T * remote_device
413 SCI_STATUS scif_sas_remote_device_default_reset_handler(
414 SCI_BASE_REMOTE_DEVICE_T * remote_device
417 SCI_STATUS scif_sas_remote_device_default_reset_complete_handler(
418 SCI_BASE_REMOTE_DEVICE_T * remote_device
421 SCI_STATUS scif_sas_remote_device_default_start_io_handler(
422 SCI_BASE_REMOTE_DEVICE_T * remote_device,
423 SCI_BASE_REQUEST_T * io_request
426 void scif_sas_remote_device_default_start_complete_handler(
427 SCIF_SAS_REMOTE_DEVICE_T * fw_device,
428 SCI_STATUS completion_status
431 void scif_sas_remote_device_default_stop_complete_handler(
432 SCIF_SAS_REMOTE_DEVICE_T * fw_device,
433 SCI_STATUS completion_status
436 SCI_STATUS scif_sas_remote_device_default_destruct_handler(
437 SCI_BASE_REMOTE_DEVICE_T * remote_device
440 SCI_STATUS scif_sas_remote_device_default_complete_io_handler(
441 SCI_BASE_REMOTE_DEVICE_T * remote_device,
442 SCI_BASE_REQUEST_T * io_request
445 SCI_STATUS scif_sas_remote_device_default_complete_high_priority_io_handler(
446 SCI_BASE_REMOTE_DEVICE_T * remote_device,
447 SCI_BASE_REQUEST_T * io_request,
448 void * response_data,
449 SCI_IO_STATUS completion_status
452 SCI_STATUS scif_sas_remote_device_default_continue_io_handler(
453 SCI_BASE_REMOTE_DEVICE_T * remote_device,
454 SCI_BASE_REQUEST_T * io_request
457 SCI_STATUS scif_sas_remote_device_default_start_task_handler(
458 SCI_BASE_REMOTE_DEVICE_T * remote_device,
459 SCI_BASE_REQUEST_T * task_request
462 SCI_STATUS scif_sas_remote_device_default_complete_task_handler(
463 SCI_BASE_REMOTE_DEVICE_T * remote_device,
464 SCI_BASE_REQUEST_T * task_request
467 void scif_sas_remote_device_default_ready_handler(
468 SCIF_SAS_REMOTE_DEVICE_T * fw_device
471 void scif_sas_remote_device_default_not_ready_handler(
472 SCIF_SAS_REMOTE_DEVICE_T * fw_device,
476 SCI_STATUS scif_sas_remote_device_ready_task_management_start_high_priority_io_handler(
477 SCI_BASE_REMOTE_DEVICE_T * remote_device,
478 SCI_BASE_REQUEST_T * io_request
481 SCI_STATUS scif_sas_remote_device_ready_task_management_complete_high_priority_io_handler(
482 SCI_BASE_REMOTE_DEVICE_T * remote_device,
483 SCI_BASE_REQUEST_T * io_request,
484 void * response_data,
485 SCI_IO_STATUS completion_status
488 #if !defined(DISABLE_WIDE_PORTED_TARGETS)
489 SCI_STATUS scif_sas_remote_device_update_port_width(
490 SCIF_SAS_REMOTE_DEVICE_T * fw_device,
493 #else // !defined(DISABLE_WIDE_PORTED_TARGETS)
494 #define scif_sas_remote_device_update_port_width(device) SCI_FAILURE
495 #endif //#if !defined(DISABLE_WIDE_PORTED_TARGETS)
499 #endif // __cplusplus
501 #endif // _SCIF_SAS_REMOTE_DEVICE_H_