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 condition. 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