scif_sas_design.h revision 330897
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: stable/11/sys/dev/isci/scil/scif_sas_design.h 330897 2018-03-14 03:19:51Z eadler $ 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 70This document provides design information relating to the SAS specific 71implementation of the SCI Framework. Driver developers are the primary 72audience for this document. The reader is expected to have an understanding 73of the SCU Software Architecture Specification, the Storage Controller 74Interface Specification, and the SCI Base Design. 75 76@section scif_sas_overview Overview 77 78To begin, it's important to discuss the utilization of state machines in 79the design. State machines are pervasive in this design, because of the 80abilities they provide. A properly implemented state machine allows the 81developer to code for a specific task. The developer is not encumbered 82with needed to handle other situations all in a single function. For 83example, if a specific event can only occur when the object is in a specific 84state, then the event handler is added to handle such an event. Thus, a 85single function is not spliced to handle multiple events under various 86potentially disparate conditions. 87 88Additionally, the SCI Base Design document specifies a number of state 89machines, objects, and methods that are heavily utilized by this design. 90Please refer to Base Design specification for further information. 91 92Many of the framework objects have state machines associated with them. 93As a result, there are a number of state entrance and exit methods as well 94as event handlers for each individual state. This design places all of 95the state entrance and exit methods for a given state machine into a single 96file (e.g. scif_sas_controller_states.c). Furthermore, all of the state 97event handler methods are also placed into a single file (e.g. 98scif_sas_controller_state_handlers.c). This format is reused for each 99object that contains state machine(s). 100 101Some of the SAS framework objects contain sub-state machines. These 102sub-state machines are started upon entrance to the super-state and stopped 103upon exit of the super-state. 104 105All other method, data, constant description information will be found in 106the remaining source file (e.g. scif_sas_controller.c). As a result, please 107be sure to follow the link to that specific object/file definition for 108further information. 109 110@note Currently a large number of function pointers are utilized during the 111course of a normal IO request. Once stability of the driver is achieved, 112performance improvements will be made as needed. This likely will include 113removal of the function pointers from the IO path. 114 115@section scif_sas_use_cases Use Cases 116 117The following use case diagram depicts the high-level user interactions with 118the SAS framework. This diagram does not encompass all use cases implemented 119in the system. The low-level design section will contain detailed use cases 120for each significant object and their associated detailed sequences and/or 121activities. For the purposes of readability, the use cases are not directly 122connected to the associated actor utilizing the use case. Instead naming 123is utilized to different which actor is involved with the use case. 124 125Actors: 126- The Framework user also called the OS Specific Driver initiates activities in 127the Framework. 128- The SCI Core calls back into the Framework as a result of an operation either 129started 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 136This section delineates the high-level class organization for the SCIF_SAS 137component. Details concerning each class will be found in the corresponding 138low-level design sections. Furthermore, additional classes not germane to 139the overall architecture of the component will also be defined in these 140low-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 145For more information on each object appearing in the diagram, please 146reference the subsequent sections. 147 148@section scif_sas_library SCIF SAS Library 149 150First, the SCIF_SAS_LIBRARY object provides an implementation 151for the roles and responsibilities defined in the Storage Controller 152Interface (SCI) specification. It is suggested that the user read the 153storage controller interface specification for background information on 154the library object. 155 156The SCIF_SAS_LIBRARY object is broken down into 2 individual source files 157and one direct header file. These files delineate the methods, members, etc. 158associated with this object. Please reference these files directly for 159further design information: 160- scif_sas_library.h 161- scif_sas_library.c 162 163@section scif_sas_controller SCIF SAS Controller 164 165First, the SCIF_SAS_CONTROLLER object provides an implementation 166for the roles and responsibilities defined in the Storage Controller 167Interface (SCI) specification. It is suggested that the user read the 168storage controller interface specification for background information on 169the controller object. 170 171The SCIF_SAS_CONTROLLER object is broken down into 3 individual source files 172and one direct header file. These files delineate the methods, members, etc. 173associated with this object. Please reference these files directly for 174further 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 182First, the SCIF_SAS_DOMAIN object provides an implementation 183for the roles and responsibilities defined in the Storage Controller 184Interface (SCI) specification. It is suggested that the user read the 185storage controller interface specification for background information on 186the SCIF_SAS_DOMAIN object. 187 188The SCIF_SAS_DOMAIN object is broken down into 3 individual 189source files and one direct header file. These files delineate the 190methods, members, etc. associated with this object. Please reference 191these files directly for 192further 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 200First, the SCIF_SAS_REMOTE_DEVICE object provides an implementation 201for the roles and responsibilities defined in the Storage Controller 202Interface (SCI) specification. It is suggested that the user read the 203storage controller interface specification for background information on 204the SCIF_SAS_REMOTE_DEVICE object. 205 206The SCIF_SAS_REMOTE_DEVICE object is broken down into 7 individual source files 207and one direct header file. These files delineate the methods, members, etc. 208associated with this object. Methods, data, and functionality specific to a 209particular protocol type (e.g. SMP, STP, etc.) are broken out into their own 210object/file. SSP specific remote device functionality is covered by the base 211classes (common files). Please reference these files directly for further 212design 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 226The SCIF_SAS_REMOTE_DEVICE object has sub-state machines defined for 227the READY and STARTING super-states. For more information on the 228super-state machine please refer to SCI_BASE_REMOTE_DEVICE_STATES 229in the SCI Base design document. 230 231In the SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATES sub-state machine, 232the remote device currently has to wait for the core to 233return an indication that the remote device has successfully started 234and become ready. If all goes well, then the remote device will 235transition into the READY state. 236 237For more information on the starting sub-state machine states please refer 238to the scif_sas_remote_device.h::_SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATES 239enumeration. 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 244In the SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATES sub-state machine, 245the remote device currently only allows new host IO requests during the 246OPERATIONAL state. In the TASK MANAGEMENT state only new task management 247requests are allowed. 248 249For more information on the ready sub-state machine states please refer 250to the scif_sas_remote_device.h::_SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATES 251enumeration. 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 258The SCIF_SAS_REQUEST object provide common functionality for the 259SCIF_SAS_IO_REQUEST and the SCIF_SAS_TASK_REQUEST objects. This object 260does not directly map to an SCI defined object, but its children do. For 261additional information, you may reference the SCIF_SAS_IO_REQUEST or 262SCIF_SAS_TASK_REQUEST objects. 263 264The SCIF_SAS_REQUEST object is broken down into 1 individual source file 265and one direct header file. These files delineate the methods, members, etc. 266associated with this object. Please reference these files directly for 267further design information: 268- scif_sas_request.h 269- scif_sas_request.c 270 271@section scif_sas_io_request SCIF SAS IO Request 272 273First, the SCIF_SAS_IO_REQUEST object provides an implementation 274for the roles and responsibilities defined in the Storage Controller 275Interface (SCI) specification. It is suggested that the user read the 276storage controller interface specification for background information on 277the SCIF_SAS_IO_REQUEST object. 278 279The SCIF_SAS_IO_REQUEST object is broken down into 3 individual 280source files and one direct header file. These files delineate the 281methods, members, etc. associated with this object. Please reference 282these 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 295First, the SCIF_SAS_TASK_REQUEST object provides an implementation 296for the roles and responsibilities defined in the Storage Controller 297Interface (SCI) specification. It is suggested that the user read the 298storage controller interface specification for background information on 299the SCIF_SAS_TASK_REQUEST object. 300 301The SCIF_SAS_TASK_REQUEST object is broken down into 3 individual 302source files and one direct header file. These files delineate the 303methods, members, etc. associated with this object. Please reference 304these 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 314The SCIF_SAS_INTERNAL_IO_REQUEST object fulfills the SCI's need to create 315and send out the internal io request. These internal io requests could be 316smp request for expander device discover process, or stp request for NCQ 317error handling. Internal IOs consume the reserved internal io space in 318scif_sas_controller. When an internal IO is constructed, it is put into an 319internal high priority queue. A defferred task (start_internal_io_task) will be 320scheduled at the end of every completion process. The task looks up the high 321priority queue and starts each internal io in the queue. There is one exception 322that start_internal_io_task is scheduled immediately when the first internal io 323is constructed. A retry mechanism is also provided for internal io. When an 324internal io response is decoded, if the decoding indicates a retry is needed, 325the internal io will be retried. 326 327Please 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 334The SCIF SAS SMP REMOTE DEVICE object represents the expander device and fulfills 335its SMP discover activities. The discover procedure includes a initial discover 336phase and a following SATA spinup_hold release phase, if there are expander attached 337SATA device is discovered and in spinup_hold conditon. The SCIF SAS SMP REMOTE DEVICE 338object 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 343Please 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