xref: /freebsd/sys/dev/isci/scil/scif_sas_design.h (revision 0957b409)
1 /*-
2  * SPDX-License-Identifier: BSD-2-Clause OR GPL-2.0
3  *
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.
6  *
7  * GPL LICENSE SUMMARY
8  *
9  * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
10  *
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.
14  *
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.
19  *
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.
25  *
26  * BSD LICENSE
27  *
28  * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
29  * All rights reserved.
30  *
31  * Redistribution and use in source and binary forms, with or without
32  * modification, are permitted provided that the following conditions
33  * are met:
34  *
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
40  *     distribution.
41  *
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.
53  *
54  * $FreeBSD$
55  */
56 #ifndef _SCIF_SAS_DESIGN_H_
57 #define _SCIF_SAS_DESIGN_H_
58 
59 /**
60 @page scif_sas_design_page SCIF SAS High Level Design
61 
62 <b>Authors:</b>
63 - Nathan Marushak
64 
65 <b>Key Contributors:</b>
66 - Richard Boyd
67 
68 @section scif_sas_scope_and_audience Scope and Audience
69 
70 This document provides design information relating to the SAS specific
71 implementation of the SCI Framework.  Driver developers are the primary
72 audience for this document.  The reader is expected to have an understanding
73 of the SCU Software Architecture Specification, the Storage Controller
74 Interface Specification, and the SCI Base Design.
75 
76 @section scif_sas_overview Overview
77 
78 To begin, it's important to discuss the utilization of state machines in
79 the design.  State machines are pervasive in this design, because of the
80 abilities they provide.  A properly implemented state machine allows the
81 developer to code for a specific task.  The developer is not encumbered
82 with needed to handle other situations all in a single function.  For
83 example, if a specific event can only occur when the object is in a specific
84 state, then the event handler is added to handle such an event.  Thus, a
85 single function is not spliced to handle multiple events under various
86 potentially disparate conditions.
87 
88 Additionally, the SCI Base Design document specifies a number of state
89 machines, objects, and methods that are heavily utilized by this design.
90 Please refer to Base Design specification for further information.
91 
92 Many of the framework objects have state machines associated with them.
93 As a result, there are a number of state entrance and exit methods as well
94 as event handlers for each individual state.  This design places all of
95 the state entrance and exit methods for a given state machine into a single
96 file (e.g. scif_sas_controller_states.c).  Furthermore, all of the state
97 event handler methods are also placed into a single file (e.g.
98 scif_sas_controller_state_handlers.c).  This format is reused for each
99 object that contains state machine(s).
100 
101 Some of the SAS framework objects contain sub-state machines.  These
102 sub-state machines are started upon entrance to the super-state and stopped
103 upon exit of the super-state.
104 
105 All other method, data, constant description information will be found in
106 the remaining source file (e.g. scif_sas_controller.c).  As a result, please
107 be sure to follow the link to that specific object/file definition for
108 further information.
109 
110 @note Currently a large number of function pointers are utilized during the
111 course of a normal IO request.  Once stability of the driver is achieved,
112 performance improvements will be made as needed.  This likely will include
113 removal of the function pointers from the IO path.
114 
115 @section scif_sas_use_cases Use Cases
116 
117 The following use case diagram depicts the high-level user interactions with
118 the SAS framework.  This diagram does not encompass all use cases implemented
119 in the system.  The low-level design section will contain detailed use cases
120 for each significant object and their associated detailed sequences and/or
121 activities.  For the purposes of readability, the use cases are not directly
122 connected to the associated actor utilizing the use case.  Instead naming
123 is utilized to different which actor is involved with the use case.
124 
125 Actors:
126 - The Framework user also called the OS Specific Driver initiates activities in
127 the Framework.
128 - The SCI Core calls back into the Framework as a result of an operation either
129 started by the OS Specific Driver or by the Framework itself.
130 
131 @image latex Use_Case_Diagram__SCIF_SAS__Use_Cases.eps "SCIF SAS OS Use Cases" width=11cm
132 @image html Use_Case_Diagram__SCIF_SAS__Use_Cases.jpg "SCIF SAS OS Use Cases"
133 
134 @section scif_sas_class_hierarchy Class Hierarchy
135 
136 This section delineates the high-level class organization for the SCIF_SAS
137 component.  Details concerning each class will be found in the corresponding
138 low-level design sections.  Furthermore, additional classes not germane to
139 the overall architecture of the component will also be defined in these
140 low-level design sections.
141 
142 @image latex Class_Diagram__scif_sas__Class_Diagram.eps "SCIF SAS Class Diagram" width=16cm
143 @image html Class_Diagram__scif_sas__Class_Diagram.jpg "SCIF SAS Class Diagram"
144 
145 For more information on each object appearing in the diagram, please
146 reference the subsequent sections.
147 
148 @section scif_sas_library SCIF SAS Library
149 
150 First, the SCIF_SAS_LIBRARY object provides an implementation
151 for the roles and responsibilities defined in the Storage Controller
152 Interface (SCI) specification.  It is suggested that the user read the
153 storage controller interface specification for background information on
154 the library object.
155 
156 The SCIF_SAS_LIBRARY object is broken down into 2 individual source files
157 and one direct header file.  These files delineate the methods, members, etc.
158 associated with this object.  Please reference these files directly for
159 further design information:
160 - scif_sas_library.h
161 - scif_sas_library.c
162 
163 @section scif_sas_controller SCIF SAS Controller
164 
165 First, the SCIF_SAS_CONTROLLER object provides an implementation
166 for the roles and responsibilities defined in the Storage Controller
167 Interface (SCI) specification.  It is suggested that the user read the
168 storage controller interface specification for background information on
169 the controller object.
170 
171 The SCIF_SAS_CONTROLLER object is broken down into 3 individual source files
172 and one direct header file.  These files delineate the methods, members, etc.
173 associated with this object.  Please reference these files directly for
174 further design information:
175 - scif_sas_controller.h
176 - scif_sas_controller.c
177 - scif_sas_controller_state_handlers.c
178 - scif_sas_controller_states.c
179 
180 @section scif_sas_domain SCIF SAS Domain
181 
182 First, the SCIF_SAS_DOMAIN object provides an implementation
183 for the roles and responsibilities defined in the Storage Controller
184 Interface (SCI) specification.  It is suggested that the user read the
185 storage controller interface specification for background information on
186 the SCIF_SAS_DOMAIN object.
187 
188 The SCIF_SAS_DOMAIN object is broken down into 3 individual
189 source files and one direct header file.  These files delineate the
190 methods, members, etc. associated with this object.  Please reference
191 these files directly for
192 further design information:
193 - scif_sas_domain.h
194 - scif_sas_domain.c
195 - scif_sas_domain_state_handlers.c
196 - scif_sas_domain_states.c
197 
198 @section scif_sas_remote_device SCIF SAS Remote Device
199 
200 First, the SCIF_SAS_REMOTE_DEVICE object provides an implementation
201 for the roles and responsibilities defined in the Storage Controller
202 Interface (SCI) specification.  It is suggested that the user read the
203 storage controller interface specification for background information on
204 the SCIF_SAS_REMOTE_DEVICE object.
205 
206 The SCIF_SAS_REMOTE_DEVICE object is broken down into 7 individual source files
207 and one direct header file.  These files delineate the methods, members, etc.
208 associated with this object.  Methods, data, and functionality specific to a
209 particular protocol type (e.g. SMP, STP, etc.) are broken out into their own
210 object/file.  SSP specific remote device functionality is covered by the base
211 classes (common files).  Please reference these files directly for further
212 design information:
213 - scif_sas_remote_device.h
214 - scif_sas_smp_remote_device.h
215 - scif_sas_stp_remote_device.h
216 - scif_sas_remote_device.c
217 - scif_sas_remote_device_state_handlers.c
218 - scif_sas_remote_device_states.c
219 - scif_sas_remote_device_starting_substate_handlers.c
220 - scif_sas_remote_device_starting_substates.c
221 - scif_sas_remote_device_ready_substate_handlers.c
222 - scif_sas_remote_device_ready_substates.c
223 - scif_sas_smp_remote_device.c
224 - scif_sas_stp_remote_device.c
225 
226 The SCIF_SAS_REMOTE_DEVICE object has sub-state machines defined for
227 the READY and STARTING super-states.  For more information on the
228 super-state machine please refer to SCI_BASE_REMOTE_DEVICE_STATES
229 in the SCI Base design document.
230 
231 In the SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATES sub-state machine,
232 the remote device currently has to wait for the core to
233 return an indication that the remote device has successfully started
234 and become ready.  If all goes well, then the remote device will
235 transition into the READY state.
236 
237 For more information on the starting sub-state machine states please refer
238 to the scif_sas_remote_device.h::_SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATES
239 enumeration.
240 
241 @image latex State_Machine_Diagram__STARTING_SUB-STATE__STARTING_SUB-STATE.eps "SCIF SAS Remote Device Starting Sub-state Machine Diagram" width=16cm
242 @image html State_Machine_Diagram__STARTING_SUB-STATE__STARTING_SUB-STATE.jpg "SCIF SAS Remote Device Starting Sub-state Machine Diagram"
243 
244 In the SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATES sub-state machine,
245 the remote device currently only allows new host IO requests during the
246 OPERATIONAL state.  In the TASK MANAGEMENT state only new task management
247 requests are allowed.
248 
249 For more information on the ready sub-state machine states please refer
250 to the scif_sas_remote_device.h::_SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATES
251 enumeration.
252 
253 @image latex State_Machine_Diagram__READY_SUB-STATE__READY_SUB-STATE.eps "SCIF SAS Remote Device Ready Sub-state Machine Diagram" width=16cm
254 @image html State_Machine_Diagram__READY_SUB-STATE__READY_SUB-STATE.jpg "SCIF SAS Remote Device Ready Sub-state Machine Diagram"
255 
256 @section scif_sas_request SCIF SAS Request
257 
258 The SCIF_SAS_REQUEST object provide common functionality for the
259 SCIF_SAS_IO_REQUEST and the SCIF_SAS_TASK_REQUEST objects.  This object
260 does not directly map to an SCI defined object, but its children do.  For
261 additional information, you may reference the SCIF_SAS_IO_REQUEST or
262 SCIF_SAS_TASK_REQUEST objects.
263 
264 The SCIF_SAS_REQUEST object is broken down into 1 individual source file
265 and one direct header file.  These files delineate the methods, members, etc.
266 associated with this object.  Please reference these files directly for
267 further design information:
268 - scif_sas_request.h
269 - scif_sas_request.c
270 
271 @section scif_sas_io_request SCIF SAS IO Request
272 
273 First, the SCIF_SAS_IO_REQUEST object provides an implementation
274 for the roles and responsibilities defined in the Storage Controller
275 Interface (SCI) specification.  It is suggested that the user read the
276 storage controller interface specification for background information on
277 the SCIF_SAS_IO_REQUEST object.
278 
279 The SCIF_SAS_IO_REQUEST object is broken down into 3 individual
280 source files and one direct header file.  These files delineate the
281 methods, members, etc. associated with this object.  Please reference
282 these files directly for further design information:
283 - scif_sas_io_request.h
284 - scif_sas_smp_io_request.h
285 - scif_sas_stp_io_request.h
286 - scif_sas_sati_binding.h
287 - scif_sas_io_request.c
288 - scif_sas_io_request_state_handlers.c
289 - scif_sas_io_request_states.c
290 - scif_sas_smp_io_request.c
291 - scif_sas_stp_io_request.c
292 
293 @section scif_sas_task_request SCIF SAS Task Request
294 
295 First, the SCIF_SAS_TASK_REQUEST object provides an implementation
296 for the roles and responsibilities defined in the Storage Controller
297 Interface (SCI) specification.  It is suggested that the user read the
298 storage controller interface specification for background information on
299 the SCIF_SAS_TASK_REQUEST object.
300 
301 The SCIF_SAS_TASK_REQUEST object is broken down into 3 individual
302 source files and one direct header file.  These files delineate the
303 methods, members, etc. associated with this object.  Please reference
304 these files directly for further design information:
305 - scif_sas_task_request.h
306 - scif_sas_stp_task_request.h
307 - scif_sas_task_request.c
308 - scif_sas_task_request_state_handlers.c
309 - scif_sas_task_request_states.c
310 - scif_sas_stp_task_request.c
311 
312 @section scif_sas_internal_io_request SCIF SAS INTERNAL IO Request
313 
314 The SCIF_SAS_INTERNAL_IO_REQUEST object fulfills the SCI's need to create
315 and send out the internal io request. These internal io requests could be
316 smp request for expander device discover process, or stp request for NCQ
317 error handling. Internal IOs consume the reserved internal io space in
318 scif_sas_controller. When an internal IO is constructed, it is put into an
319 internal high priority queue. A defferred task (start_internal_io_task) will be
320 scheduled at the end of every completion process. The task looks up the high
321 priority queue and starts each internal io in the queue. There is one exception
322 that start_internal_io_task is scheduled immediately when the first internal io
323 is constructed. A retry mechanism is also provided for internal io. When an
324 internal io response is decoded, if the decoding indicates a retry is needed,
325 the internal io will be retried.
326 
327 Please refer to these files directly for further design information:
328 - scif_sas_internal_io_request.h
329 - scif_sas_internal_io_request.c
330 - scif_sas_controller.h
331 
332 @section scif_sas_smp_remote_device SCIF SAS SMP REMOTE DEVICE
333 
334 The SCIF SAS SMP REMOTE DEVICE object represents the expander device and fulfills
335 its SMP discover activities. The discover procedure includes a initial discover
336 phase and a following SATA spinup_hold release phase, if there are expander attached
337 SATA device is discovered and in spinup_hold conditon. The SCIF SAS SMP REMOTE DEVICE
338 object also fulfills expander attached device Target Reset (Phy Control) activity.
339 
340 @image latex Discover Process.eps "SMP Discover Activity Diagram" width=10cm
341 @image html Discover Process.jpg "SMP Discover Activity Diagram"
342 
343 Please refer to these files directly for further design information:
344 - scif_sas_smp_remote_device.h
345 - scif_sas_smp_remote_device.c
346 - scif_sas_smp_request.h
347 - scif_sas_smp_request.c
348 */
349 
350 #endif // _SCIF_SAS_DESIGN_H_
351