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