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 _SCIF_SAS_REMOTE_DEVICE_H_
57 #define _SCIF_SAS_REMOTE_DEVICE_H_
62 * @brief This file contains the protected interface structures, constants,
63 * and methods for the SCIF_SAS_REMOTE_DEVICE object.
70 #include <dev/isci/scil/scif_remote_device.h>
72 #include <dev/isci/scil/sci_base_remote_device.h>
73 #include <dev/isci/scil/sci_base_request.h>
74 #include <dev/isci/scil/sci_base_state_machine_logger.h>
75 #include <dev/isci/scil/scif_sas_stp_remote_device.h>
76 #include <dev/isci/scil/scif_sas_smp_remote_device.h>
79 struct SCIF_SAS_DOMAIN;
80 struct SCIF_SAS_REMOTE_DEVICE;
81 struct SCIF_SAS_REQUEST;
84 * This constant indicates the number of milliseconds to wait for the core
85 * to start/stop it's remote device object.
87 #define SCIF_SAS_REMOTE_DEVICE_CORE_OP_TIMEOUT 1000
90 * @enum _SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATES
92 * @brief This enumeration depicts all the substates for the remote device's
93 * starting substate machine.
95 typedef enum _SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATES
98 * This state indicates that the framework is waiting for the core to
99 * issue a scic_cb_remote_device_start_complete() notification.
101 SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATE_AWAIT_COMPLETE,
104 * This state indicates that the core has received the core's
105 * scic_cb_remote_device_start_complete() notification.
107 SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATE_AWAIT_READY,
109 SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATE_MAX_STATES
111 } SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATES;
114 * @enum _SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATES
116 * @brief This enumeration depicts all of the substates for the remote
117 * device READY substate machine.
119 typedef enum _SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATES
122 * The Operational sub-state indicates that the remote device object
123 * is capable of receiving and handling all request types.
125 SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATE_OPERATIONAL,
128 * This substate indicates that core remote device is not ready.
129 * As a result, no new IO or Task Management requests are allowed.
131 SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATE_SUSPENDED,
134 * This substate indicates that task management to this device is
135 * ongoing and new IO requests are not allowed.
137 SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATE_TASK_MGMT,
140 * This substate indicates that core remote device is not ready due
141 * to an NCQ error. As a result, no new IO requests are allowed.
143 SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATE_NCQ_ERROR,
145 SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATE_MAX_STATES
147 } SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATES;
149 struct SCIF_SAS_REMOTE_DEVICE;
150 typedef void (*SCIF_SAS_REMOTE_DEVICE_COMPLETION_HANDLER_T)(
151 struct SCIF_SAS_REMOTE_DEVICE *,
155 typedef void (*SCIF_SAS_REMOTE_DEVICE_HANDLER_T)(
156 struct SCIF_SAS_REMOTE_DEVICE *
159 typedef void (*SCIF_SAS_REMOTE_DEVICE_NOT_READY_HANDLER_T)(
160 struct SCIF_SAS_REMOTE_DEVICE *,
165 * @struct SCIF_SAS_REMOTE_DEVICE_STATE_HANDLER
167 * @brief This structure defines the state handler methods for states and
168 * substates applicable for the framework remote device object.
170 typedef struct SCIF_SAS_REMOTE_DEVICE_STATE_HANDLER
172 SCI_BASE_REMOTE_DEVICE_STATE_HANDLER_T parent;
173 SCIF_SAS_REMOTE_DEVICE_COMPLETION_HANDLER_T start_complete_handler;
174 SCIF_SAS_REMOTE_DEVICE_COMPLETION_HANDLER_T stop_complete_handler;
175 SCIF_SAS_REMOTE_DEVICE_HANDLER_T ready_handler;
176 SCIF_SAS_REMOTE_DEVICE_NOT_READY_HANDLER_T not_ready_handler;
177 SCI_BASE_REMOTE_DEVICE_REQUEST_HANDLER_T start_high_priority_io_handler;
178 SCI_BASE_REMOTE_DEVICE_HIGH_PRIORITY_REQUEST_COMPLETE_HANDLER_T complete_high_priority_io_handler;
179 } SCIF_SAS_REMOTE_DEVICE_STATE_HANDLER_T;
182 * @struct SCIF_SAS_REMOTE_DEVICE
184 * @brief The SCI SAS Framework remote device object abstracts the SAS remote
185 * device level behavior for the framework component. Additionally,
186 * it provides a higher level of abstraction for the core remote
189 typedef struct SCIF_SAS_REMOTE_DEVICE
192 * The SCI_BASE_REMOTE_DEVICE is the parent object for the
193 * SCIF_SAS_REMOTE_DEVICE object.
195 SCI_BASE_REMOTE_DEVICE_T parent;
198 * This field contains the handle for the SCI Core remote device object
199 * that is managed by this framework controller.
201 SCI_REMOTE_DEVICE_HANDLE_T core_object;
204 * This field references the list of state specific handler methods to
205 * be utilized for this remote device instance.
207 SCIF_SAS_REMOTE_DEVICE_STATE_HANDLER_T * state_handlers;
210 * This field specifies the state machine utilized to manage the
211 * starting remote device substate machine.
213 SCI_BASE_STATE_MACHINE_T starting_substate_machine;
216 * This field specifies the state machine utilized to manage the
217 * starting remote device substate machine.
219 SCI_BASE_STATE_MACHINE_T ready_substate_machine;
224 * This field specifies the information specific to SATA/STP device
225 * instances. This field is not utilized for SSP/SMP.
227 SCIF_SAS_STP_REMOTE_DEVICE_T stp_device;
230 * This field specifies the information specific to SMP device instances.
231 * This field is not utilized for SSP/SATA/STP.
233 SCIF_SAS_SMP_REMOTE_DEVICE_T smp_device;
238 * This field indicates the domain object containing this remote device.
240 struct SCIF_SAS_DOMAIN * domain;
243 * This field counts the number of requests (IO and task management)
244 * that are currently outstanding for this device.
249 * This field counts the number of only task management request that are
250 * currently outstanding for this device.
252 U32 task_request_count;
255 * This field is utilize to store the status value of various operations
256 * the can be executed on this remote device instance.
258 SCI_STATUS operation_status;
261 * This field is utilize to indicate that the remote device should be
262 * destructed when it finally reaches the stopped state. This will
263 * include destructing the core remote device as well.
265 BOOL destruct_when_stopped;
268 * This field marks a device state of being discovered or not, majorly used
269 * during re-discover procedure.
271 BOOL is_currently_discovered;
274 * This filed stores the expander device this device connected to, only if this
275 * device is behind expander. So this field also served as a flag to tell if a
276 * device is a EA one.
278 struct SCIF_SAS_REMOTE_DEVICE * containing_device;
281 * This field stores the expander phy identifier for an expander attached
282 * device. This field is only used by expander attached device.
284 U8 expander_phy_identifier;
287 * This field stores the port width for a device. Most devices are narrow port
288 * device, their port width is 1. If a device is a wide port device, their
289 * port width is larger than 1.
291 U8 device_port_width;
294 * This field stores the destination state for a remote device in UPDATING
295 * PORT WIDTH state. The possible destination states for a remote device in
296 * UPDATING_PORT_WIDTH state are READY or STOPPING.
298 U16 destination_state;
301 * This field stores the scheduled/delayed EA target reset request.
303 struct SCIF_SAS_REQUEST * ea_target_reset_request_scheduled;
307 * This field is the observer of the base state machine for this device
310 SCI_BASE_OBSERVER_T base_state_machine_observer;
313 * This field is the state machine logger of the startig substate machine for
314 * this device object.
316 SCI_BASE_STATE_MACHINE_LOGGER_T starting_substate_machine_logger;
319 * This field is the state machine logger of the ready substate machine for
320 * this device object.
322 SCI_BASE_STATE_MACHINE_LOGGER_T ready_substate_machine_logger;
323 #endif // SCI_LOGGING
325 } SCIF_SAS_REMOTE_DEVICE_T;
327 extern SCI_BASE_STATE_T scif_sas_remote_device_state_table[];
328 extern SCIF_SAS_REMOTE_DEVICE_STATE_HANDLER_T
329 scif_sas_remote_device_state_handler_table[];
331 extern SCI_BASE_STATE_T scif_sas_remote_device_starting_substate_table[];
332 extern SCIF_SAS_REMOTE_DEVICE_STATE_HANDLER_T
333 scif_sas_remote_device_starting_substate_handler_table[];
335 extern SCI_BASE_STATE_T scif_sas_remote_device_ready_substate_table[];
336 extern SCIF_SAS_REMOTE_DEVICE_STATE_HANDLER_T
337 scif_sas_remote_device_ready_substate_handler_table[];
342 * This enumeration is used to define the end destination state for the
343 * framework remote device.
345 enum SCIF_SAS_REMOTE_DEVICE_DESTINATION_STATE
347 SCIF_SAS_REMOTE_DEVICE_DESTINATION_STATE_UNSPECIFIED,
348 SCIF_SAS_REMOTE_DEVICE_DESTINATION_STATE_READY,
349 SCIF_SAS_REMOTE_DEVICE_DESTINATION_STATE_STOPPING,
350 SCIF_SAS_REMOTE_DEVICE_DESTINATION_STATE_UPDATING_PORT_WIDTH
353 //******************************************************************************
354 //* P R O T E C T E D M E T H O D S
355 //******************************************************************************
356 void scif_sas_remote_device_save_report_phy_sata_information(
357 SMP_RESPONSE_REPORT_PHY_SATA_T * report_phy_sata_response
360 void scif_sas_remote_device_target_reset(
361 SCIF_SAS_REMOTE_DEVICE_T * fw_device,
362 struct SCIF_SAS_REQUEST * fw_request
365 void scif_sas_remote_device_target_reset_complete(
366 SCIF_SAS_REMOTE_DEVICE_T * fw_device,
367 struct SCIF_SAS_REQUEST * fw_request,
368 SCI_STATUS completion_status
372 void scif_sas_remote_device_initialize_state_logging(
373 SCIF_SAS_REMOTE_DEVICE_T * remote_device
376 void scif_sas_remote_device_deinitialize_state_logging(
377 SCIF_SAS_REMOTE_DEVICE_T * remote_device
380 #define scif_sas_remote_device_initialize_state_logging(x)
381 #define scif_sas_remote_device_deinitialize_state_logging(x)
382 #endif // SCI_LOGGING
384 //******************************************************************************
385 //* 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
386 //******************************************************************************
388 SCI_STATUS scif_sas_remote_device_ready_operational_complete_io_handler(
389 SCI_BASE_REMOTE_DEVICE_T * remote_device,
390 SCI_BASE_REQUEST_T * io_request
393 SCI_STATUS scif_sas_remote_device_ready_operational_complete_task_handler(
394 SCI_BASE_REMOTE_DEVICE_T * remote_device,
395 SCI_BASE_REQUEST_T * task_request
398 SCI_STATUS scif_sas_remote_device_ready_task_management_complete_task_handler(
399 SCI_BASE_REMOTE_DEVICE_T * remote_device,
400 SCI_BASE_REQUEST_T * task_request
403 //******************************************************************************
404 //* D E F A U L T S T A T E H A N D L E R S
405 //******************************************************************************
407 SCI_STATUS scif_sas_remote_device_default_start_handler(
408 SCI_BASE_REMOTE_DEVICE_T * remote_device
411 SCI_STATUS scif_sas_remote_device_default_stop_handler(
412 SCI_BASE_REMOTE_DEVICE_T * remote_device
415 SCI_STATUS scif_sas_remote_device_default_reset_handler(
416 SCI_BASE_REMOTE_DEVICE_T * remote_device
419 SCI_STATUS scif_sas_remote_device_default_reset_complete_handler(
420 SCI_BASE_REMOTE_DEVICE_T * remote_device
423 SCI_STATUS scif_sas_remote_device_default_start_io_handler(
424 SCI_BASE_REMOTE_DEVICE_T * remote_device,
425 SCI_BASE_REQUEST_T * io_request
428 void scif_sas_remote_device_default_start_complete_handler(
429 SCIF_SAS_REMOTE_DEVICE_T * fw_device,
430 SCI_STATUS completion_status
433 void scif_sas_remote_device_default_stop_complete_handler(
434 SCIF_SAS_REMOTE_DEVICE_T * fw_device,
435 SCI_STATUS completion_status
438 SCI_STATUS scif_sas_remote_device_default_destruct_handler(
439 SCI_BASE_REMOTE_DEVICE_T * remote_device
442 SCI_STATUS scif_sas_remote_device_default_complete_io_handler(
443 SCI_BASE_REMOTE_DEVICE_T * remote_device,
444 SCI_BASE_REQUEST_T * io_request
447 SCI_STATUS scif_sas_remote_device_default_complete_high_priority_io_handler(
448 SCI_BASE_REMOTE_DEVICE_T * remote_device,
449 SCI_BASE_REQUEST_T * io_request,
450 void * response_data,
451 SCI_IO_STATUS completion_status
454 SCI_STATUS scif_sas_remote_device_default_continue_io_handler(
455 SCI_BASE_REMOTE_DEVICE_T * remote_device,
456 SCI_BASE_REQUEST_T * io_request
459 SCI_STATUS scif_sas_remote_device_default_start_task_handler(
460 SCI_BASE_REMOTE_DEVICE_T * remote_device,
461 SCI_BASE_REQUEST_T * task_request
464 SCI_STATUS scif_sas_remote_device_default_complete_task_handler(
465 SCI_BASE_REMOTE_DEVICE_T * remote_device,
466 SCI_BASE_REQUEST_T * task_request
469 void scif_sas_remote_device_default_ready_handler(
470 SCIF_SAS_REMOTE_DEVICE_T * fw_device
473 void scif_sas_remote_device_default_not_ready_handler(
474 SCIF_SAS_REMOTE_DEVICE_T * fw_device,
478 SCI_STATUS scif_sas_remote_device_ready_task_management_start_high_priority_io_handler(
479 SCI_BASE_REMOTE_DEVICE_T * remote_device,
480 SCI_BASE_REQUEST_T * io_request
483 SCI_STATUS scif_sas_remote_device_ready_task_management_complete_high_priority_io_handler(
484 SCI_BASE_REMOTE_DEVICE_T * remote_device,
485 SCI_BASE_REQUEST_T * io_request,
486 void * response_data,
487 SCI_IO_STATUS completion_status
490 #if !defined(DISABLE_WIDE_PORTED_TARGETS)
491 SCI_STATUS scif_sas_remote_device_update_port_width(
492 SCIF_SAS_REMOTE_DEVICE_T * fw_device,
495 #else // !defined(DISABLE_WIDE_PORTED_TARGETS)
496 #define scif_sas_remote_device_update_port_width(device) SCI_FAILURE
497 #endif //#if !defined(DISABLE_WIDE_PORTED_TARGETS)
501 #endif // __cplusplus
503 #endif // _SCIF_SAS_REMOTE_DEVICE_H_