scif_sas_design.h revision 231136
151974Smsmith/*- 265245Smsmith * This file is provided under a dual BSD/GPLv2 license. When using or 365245Smsmith * redistributing this file, you may do so under either license. 451974Smsmith * 551974Smsmith * GPL LICENSE SUMMARY 651974Smsmith * 751974Smsmith * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 851974Smsmith * 951974Smsmith * This program is free software; you can redistribute it and/or modify 1051974Smsmith * it under the terms of version 2 of the GNU General Public License as 1151974Smsmith * published by the Free Software Foundation. 1251974Smsmith * 1351974Smsmith * This program is distributed in the hope that it will be useful, but 1451974Smsmith * WITHOUT ANY WARRANTY; without even the implied warranty of 1551974Smsmith * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 1651974Smsmith * General Public License for more details. 1751974Smsmith * 1851974Smsmith * You should have received a copy of the GNU General Public License 1951974Smsmith * along with this program; if not, write to the Free Software 2051974Smsmith * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. 2151974Smsmith * The full GNU General Public License is included in this distribution 2251974Smsmith * in the file called LICENSE.GPL. 2351974Smsmith * 2451974Smsmith * BSD LICENSE 2551974Smsmith * 26119418Sobrien * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 27139749Simp * All rights reserved. 28106225Semoore * 29140688Sscottl * Redistribution and use in source and binary forms, with or without 30106225Semoore * modification, are permitted provided that the following conditions 31106225Semoore * are met: 32106225Semoore * 33106225Semoore * * Redistributions of source code must retain the above copyright 34106225Semoore * notice, this list of conditions and the following disclaimer. 35106225Semoore * * Redistributions in binary form must reproduce the above copyright 36106225Semoore * notice, this list of conditions and the following disclaimer in 37106225Semoore * the documentation and/or other materials provided with the 38106225Semoore * distribution. 39106225Semoore * 40105419Semoore * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 41106225Semoore * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 42105419Semoore * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 43105419Semoore * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 44106225Semoore * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45106225Semoore * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 46106225Semoore * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 47106225Semoore * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 48106225Semoore * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 49106225Semoore * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 50106225Semoore * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 51106225Semoore * 52106225Semoore * $FreeBSD: head/sys/dev/isci/scil/scif_sas_design.h 231136 2012-02-07 17:43:58Z jimharris $ 53106225Semoore */ 54106225Semoore#ifndef _SCIF_SAS_DESIGN_H_ 5551974Smsmith#define _SCIF_SAS_DESIGN_H_ 5651974Smsmith 57119418Sobrien/** 58119418Sobrien@page scif_sas_design_page SCIF SAS High Level Design 59119418Sobrien 6051974Smsmith<b>Authors:</b> 6151974Smsmith- Nathan Marushak 6251974Smsmith 63129879Sphk<b>Key Contributors:</b> 64153409Sscottl- Richard Boyd 6551974Smsmith 66148850Sscottl@section scif_sas_scope_and_audience Scope and Audience 6751974Smsmith 6851974SmsmithThis document provides design information relating to the SAS specific 6951974Smsmithimplementation of the SCI Framework. Driver developers are the primary 7051974Smsmithaudience for this document. The reader is expected to have an understanding 7151974Smsmithof the SCU Software Architecture Specification, the Storage Controller 7251974SmsmithInterface Specification, and the SCI Base Design. 7351974Smsmith 74119277Simp@section scif_sas_overview Overview 75119277Simp 7651974SmsmithTo begin, it's important to discuss the utilization of state machines in 7751974Smsmiththe design. State machines are pervasive in this design, because of the 7851974Smsmithabilities they provide. A properly implemented state machine allows the 7951974Smsmithdeveloper to code for a specific task. The developer is not encumbered 8051974Smsmithwith needed to handle other situations all in a single function. For 8165245Smsmithexample, if a specific event can only occur when the object is in a specific 8265245Smsmithstate, then the event handler is added to handle such an event. Thus, a 8365245Smsmithsingle function is not spliced to handle multiple events under various 8465245Smsmithpotentially disparate conditions. 8565245Smsmith 8665245SmsmithAdditionally, the SCI Base Design document specifies a number of state 8765245Smsmithmachines, objects, and methods that are heavily utilized by this design. 8865245SmsmithPlease refer to Base Design specification for further information. 89174544Sscottl 9065245SmsmithMany of the framework objects have state machines associated with them. 9165245SmsmithAs a result, there are a number of state entrance and exit methods as well 92174544Sscottlas event handlers for each individual state. This design places all of 9351974Smsmiththe state entrance and exit methods for a given state machine into a single 94153409Sscottlfile (e.g. scif_sas_controller_states.c). Furthermore, all of the state 95153409Sscottlevent handler methods are also placed into a single file (e.g. 96153409Sscottlscif_sas_controller_state_handlers.c). This format is reused for each 97153409Sscottlobject that contains state machine(s). 98153409Sscottl 99153409SscottlSome of the SAS framework objects contain sub-state machines. These 10051974Smsmithsub-state machines are started upon entrance to the super-state and stopped 10151974Smsmithupon exit of the super-state. 10251974Smsmith 10351974SmsmithAll other method, data, constant description information will be found in 10465245Smsmiththe remaining source file (e.g. scif_sas_controller.c). As a result, please 10565245Smsmithbe sure to follow the link to that specific object/file definition for 10665245Smsmithfurther information. 10765245Smsmith 10851974Smsmith@note Currently a large number of function pointers are utilized during the 109227843Smariuscourse of a normal IO request. Once stability of the driver is achieved, 11051974Smsmithperformance improvements will be made as needed. This likely will include 11151974Smsmithremoval of the function pointers from the IO path. 11251974Smsmith 11351974Smsmith@section scif_sas_use_cases Use Cases 11451974Smsmith 11551974SmsmithThe following use case diagram depicts the high-level user interactions with 11651974Smsmiththe SAS framework. This diagram does not encompass all use cases implemented 11751974Smsmithin the system. The low-level design section will contain detailed use cases 11889055Smsmithfor each significant object and their associated detailed sequences and/or 11951974Smsmithactivities. For the purposes of readability, the use cases are not directly 120165102Smjacobconnected to the associated actor utilizing the use case. Instead naming 121165102Smjacobis utilized to different which actor is involved with the use case. 12251974Smsmith 123153409SscottlActors: 12451974Smsmith- The Framework user also called the OS Specific Driver initiates activities in 12551974Smsmiththe Framework. 12651974Smsmith- The SCI Core calls back into the Framework as a result of an operation either 127153409Sscottlstarted by the OS Specific Driver or by the Framework itself. 128153409Sscottl 129153409Sscottl@image latex Use_Case_Diagram__SCIF_SAS__Use_Cases.eps "SCIF SAS OS Use Cases" width=11cm 130153409Sscottl@image html Use_Case_Diagram__SCIF_SAS__Use_Cases.jpg "SCIF SAS OS Use Cases" 13151974Smsmith 13251974Smsmith@section scif_sas_class_hierarchy Class Hierarchy 13351974Smsmith 134153409SscottlThis section delineates the high-level class organization for the SCIF_SAS 135153409Sscottlcomponent. Details concerning each class will be found in the corresponding 136155223Spslow-level design sections. Furthermore, additional classes not germane to 137153409Sscottlthe overall architecture of the component will also be defined in these 138153409Sscottllow-level design sections. 139153409Sscottl 140153409Sscottl@image latex Class_Diagram__scif_sas__Class_Diagram.eps "SCIF SAS Class Diagram" width=16cm 141153409Sscottl@image html Class_Diagram__scif_sas__Class_Diagram.jpg "SCIF SAS Class Diagram" 142153409Sscottl 14351974SmsmithFor more information on each object appearing in the diagram, please 14451974Smsmithreference the subsequent sections. 145105419Semoore 146153409Sscottl@section scif_sas_library SCIF SAS Library 147153409Sscottl 14851974SmsmithFirst, the SCIF_SAS_LIBRARY object provides an implementation 149153409Sscottlfor the roles and responsibilities defined in the Storage Controller 150153409SscottlInterface (SCI) specification. It is suggested that the user read the 15151974Smsmithstorage controller interface specification for background information on 152153409Sscottlthe library object. 153153409Sscottl 154153409SscottlThe SCIF_SAS_LIBRARY object is broken down into 2 individual source files 15551974Smsmithand one direct header file. These files delineate the methods, members, etc. 15651974Smsmithassociated with this object. Please reference these files directly for 157153409Sscottlfurther design information: 15870285Smsmith- scif_sas_library.h 15970285Smsmith- scif_sas_library.c 16070285Smsmith 16170285Smsmith@section scif_sas_controller SCIF SAS Controller 162153409Sscottl 16351974SmsmithFirst, the SCIF_SAS_CONTROLLER object provides an implementation 16451974Smsmithfor the roles and responsibilities defined in the Storage Controller 165153409SscottlInterface (SCI) specification. It is suggested that the user read the 166153409Sscottlstorage controller interface specification for background information on 167153409Sscottlthe controller object. 168153409Sscottl 169153409SscottlThe SCIF_SAS_CONTROLLER object is broken down into 3 individual source files 170153409Sscottland one direct header file. These files delineate the methods, members, etc. 171153409Sscottlassociated with this object. Please reference these files directly for 172153409Sscottlfurther design information: 173153409Sscottl- scif_sas_controller.h 174153409Sscottl- scif_sas_controller.c 175153409Sscottl- scif_sas_controller_state_handlers.c 176153409Sscottl- scif_sas_controller_states.c 177153409Sscottl 17851974Smsmith@section scif_sas_domain SCIF SAS Domain 17951974Smsmith 18051974SmsmithFirst, the SCIF_SAS_DOMAIN object provides an implementation 18151974Smsmithfor the roles and responsibilities defined in the Storage Controller 18251974SmsmithInterface (SCI) specification. It is suggested that the user read the 18351974Smsmithstorage controller interface specification for background information on 18451974Smsmiththe SCIF_SAS_DOMAIN object. 185153409Sscottl 18651974SmsmithThe SCIF_SAS_DOMAIN object is broken down into 3 individual 18751974Smsmithsource files and one direct header file. These files delineate the 18865245Smsmithmethods, members, etc. associated with this object. Please reference 18951974Smsmiththese files directly for 19051974Smsmithfurther design information: 19151974Smsmith- scif_sas_domain.h 19251974Smsmith- scif_sas_domain.c 19351974Smsmith- scif_sas_domain_state_handlers.c 19451974Smsmith- scif_sas_domain_states.c 19551974Smsmith 19651974Smsmith@section scif_sas_remote_device SCIF SAS Remote Device 19765245Smsmith 19865245SmsmithFirst, the SCIF_SAS_REMOTE_DEVICE object provides an implementation 19965245Smsmithfor the roles and responsibilities defined in the Storage Controller 20051974SmsmithInterface (SCI) specification. It is suggested that the user read the 20165245Smsmithstorage controller interface specification for background information on 20251974Smsmiththe SCIF_SAS_REMOTE_DEVICE object. 203153409Sscottl 204153409SscottlThe SCIF_SAS_REMOTE_DEVICE object is broken down into 7 individual source files 205153409Sscottland one direct header file. These files delineate the methods, members, etc. 206153409Sscottlassociated with this object. Methods, data, and functionality specific to a 20765245Smsmithparticular protocol type (e.g. SMP, STP, etc.) are broken out into their own 20851974Smsmithobject/file. SSP specific remote device functionality is covered by the base 20951974Smsmithclasses (common files). Please reference these files directly for further 210153409Sscottldesign information: 211153409Sscottl- scif_sas_remote_device.h 212153409Sscottl- scif_sas_smp_remote_device.h 213153409Sscottl- scif_sas_stp_remote_device.h 214153409Sscottl- scif_sas_remote_device.c 215153409Sscottl- scif_sas_remote_device_state_handlers.c 21658883Smsmith- scif_sas_remote_device_states.c 217254263Sscottl- scif_sas_remote_device_starting_substate_handlers.c 21858883Smsmith- scif_sas_remote_device_starting_substates.c 21951974Smsmith- scif_sas_remote_device_ready_substate_handlers.c 22051974Smsmith- scif_sas_remote_device_ready_substates.c 22151974Smsmith- scif_sas_smp_remote_device.c 222119690Sjhb- scif_sas_stp_remote_device.c 22365245Smsmith 224127135SnjlThe SCIF_SAS_REMOTE_DEVICE object has sub-state machines defined for 22551974Smsmiththe READY and STARTING super-states. For more information on the 22665245Smsmithsuper-state machine please refer to SCI_BASE_REMOTE_DEVICE_STATES 22765245Smsmithin the SCI Base design document. 22851974Smsmith 22951974SmsmithIn the SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATES sub-state machine, 23051974Smsmiththe remote device currently has to wait for the core to 23151974Smsmithreturn an indication that the remote device has successfully started 23251974Smsmithand become ready. If all goes well, then the remote device will 23365245Smsmithtransition into the READY state. 23465245Smsmith 23565245SmsmithFor more information on the starting sub-state machine states please refer 236127135Snjlto the scif_sas_remote_device.h::_SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATES 237127135Snjlenumeration. 23865245Smsmith 23965245Smsmith@image latex State_Machine_Diagram__STARTING_SUB-STATE__STARTING_SUB-STATE.eps "SCIF SAS Remote Device Starting Sub-state Machine Diagram" width=16cm 24065245Smsmith@image html State_Machine_Diagram__STARTING_SUB-STATE__STARTING_SUB-STATE.jpg "SCIF SAS Remote Device Starting Sub-state Machine Diagram" 24165245Smsmith 242153409SscottlIn the SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATES sub-state machine, 243166901Spisothe remote device currently only allows new host IO requests during the 244153409SscottlOPERATIONAL state. In the TASK MANAGEMENT state only new task management 24565245Smsmithrequests are allowed. 24665245Smsmith 24765245SmsmithFor more information on the ready sub-state machine states please refer 24865245Smsmithto the scif_sas_remote_device.h::_SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATES 24965245Smsmithenumeration. 25065245Smsmith 25165245Smsmith@image latex State_Machine_Diagram__READY_SUB-STATE__READY_SUB-STATE.eps "SCIF SAS Remote Device Ready Sub-state Machine Diagram" width=16cm 25265245Smsmith@image html State_Machine_Diagram__READY_SUB-STATE__READY_SUB-STATE.jpg "SCIF SAS Remote Device Ready Sub-state Machine Diagram" 25365245Smsmith 25465245Smsmith@section scif_sas_request SCIF SAS Request 25551974Smsmith 25651974SmsmithThe SCIF_SAS_REQUEST object provide common functionality for the 257232854SscottlSCIF_SAS_IO_REQUEST and the SCIF_SAS_TASK_REQUEST objects. This object 258153409Sscottldoes not directly map to an SCI defined object, but its children do. For 259153409Sscottladditional information, you may reference the SCIF_SAS_IO_REQUEST or 260153409SscottlSCIF_SAS_TASK_REQUEST objects. 26165245Smsmith 26265245SmsmithThe SCIF_SAS_REQUEST object is broken down into 1 individual source file 26365245Smsmithand one direct header file. These files delineate the methods, members, etc. 26465245Smsmithassociated with this object. Please reference these files directly for 26565245Smsmithfurther design information: 266138422Sscottl- scif_sas_request.h 267117126Sscottl- scif_sas_request.c 26865245Smsmith 26965245Smsmith@section scif_sas_io_request SCIF SAS IO Request 27065245Smsmith 27165245SmsmithFirst, the SCIF_SAS_IO_REQUEST object provides an implementation 27265245Smsmithfor the roles and responsibilities defined in the Storage Controller 27365245SmsmithInterface (SCI) specification. It is suggested that the user read the 27465245Smsmithstorage controller interface specification for background information on 27565245Smsmiththe SCIF_SAS_IO_REQUEST object. 27665245Smsmith 277153409SscottlThe SCIF_SAS_IO_REQUEST object is broken down into 3 individual 278138422Sscottlsource files and one direct header file. These files delineate the 27965245Smsmithmethods, members, etc. associated with this object. Please reference 28065245Smsmiththese files directly for further design information: 28165245Smsmith- scif_sas_io_request.h 282138422Sscottl- scif_sas_smp_io_request.h 283174544Sscottl- scif_sas_stp_io_request.h 284153409Sscottl- scif_sas_sati_binding.h 285153409Sscottl- scif_sas_io_request.c 28665245Smsmith- scif_sas_io_request_state_handlers.c 28765245Smsmith- scif_sas_io_request_states.c 28865245Smsmith- scif_sas_smp_io_request.c 28965245Smsmith- scif_sas_stp_io_request.c 29065245Smsmith 291153409Sscottl@section scif_sas_task_request SCIF SAS Task Request 292153409Sscottl 293153409SscottlFirst, the SCIF_SAS_TASK_REQUEST object provides an implementation 294153409Sscottlfor the roles and responsibilities defined in the Storage Controller 295153409SscottlInterface (SCI) specification. It is suggested that the user read the 296153409Sscottlstorage controller interface specification for background information on 297153409Sscottlthe SCIF_SAS_TASK_REQUEST object. 298174544Sscottl 299153409SscottlThe SCIF_SAS_TASK_REQUEST object is broken down into 3 individual 300153409Sscottlsource files and one direct header file. These files delineate the 301153409Sscottlmethods, members, etc. associated with this object. Please reference 302153409Sscottlthese files directly for further design information: 303153409Sscottl- scif_sas_task_request.h 304153409Sscottl- scif_sas_stp_task_request.h 305153409Sscottl- scif_sas_task_request.c 30665245Smsmith- scif_sas_task_request_state_handlers.c 30765245Smsmith- scif_sas_task_request_states.c 30865245Smsmith- scif_sas_stp_task_request.c 30965245Smsmith 31065245Smsmith@section scif_sas_internal_io_request SCIF SAS INTERNAL IO Request 311153409Sscottl 312153409SscottlThe SCIF_SAS_INTERNAL_IO_REQUEST object fulfills the SCI's need to create 31365245Smsmithand send out the internal io request. These internal io requests could be 31465245Smsmithsmp request for expander device discover process, or stp request for NCQ 31565245Smsmitherror handling. Internal IOs consume the reserved internal io space in 31665245Smsmithscif_sas_controller. When an internal IO is constructed, it is put into an 31765245Smsmithinternal high priority queue. A defferred task (start_internal_io_task) will be 31865245Smsmithscheduled at the end of every completion process. The task looks up the high 31965245Smsmithpriority queue and starts each internal io in the queue. There is one exception 32065245Smsmiththat start_internal_io_task is scheduled immediately when the first internal io 321232255Skevlois constructed. A retry mechanism is also provided for internal io. When an 32265245Smsmithinternal io response is decoded, if the decoding indicates a retry is needed, 32365245Smsmiththe internal io will be retried. 32465245Smsmith 325232255SkevloPlease refer to these files directly for further design information: 326174544Sscottl- scif_sas_internal_io_request.h 327174544Sscottl- scif_sas_internal_io_request.c 328174544Sscottl- scif_sas_controller.h 329174544Sscottl 33065245Smsmith@section scif_sas_smp_remote_device SCIF SAS SMP REMOTE DEVICE 33165245Smsmith 33265245SmsmithThe SCIF SAS SMP REMOTE DEVICE object represents the expander device and fulfills 33365245Smsmithits SMP discover activities. The discover procedure includes a initial discover 33465245Smsmithphase and a follwoing SATA spinup_hold release phase, if there are expander attached 33565245SmsmithSATA device is discovered and in spinup_hold conditon. The SCIF SAS SMP REMOTE DEVICE 33665245Smsmithobject also fulfills expander attached device Target Reset (Phy Control) activity. 33765245Smsmith 33865245Smsmith@image latex Discover Process.eps "SMP Discover Activity Diagram" width=10cm 33965245Smsmith@image html Discover Process.jpg "SMP Discover Activity Diagram" 34065245Smsmith 34165245SmsmithPlease refer to these files directly for further design information: 34265245Smsmith- scif_sas_smp_remote_device.h 34365245Smsmith- scif_sas_smp_remote_device.c 34465245Smsmith- scif_sas_smp_request.h 34565245Smsmith- scif_sas_smp_request.c 34665245Smsmith*/ 34765245Smsmith 34865245Smsmith#endif // _SCIF_SAS_DESIGN_H_ 34965245Smsmith