1230557Sjimharris/*- 2230557Sjimharris * This file is provided under a dual BSD/GPLv2 license. When using or 3230557Sjimharris * redistributing this file, you may do so under either license. 4230557Sjimharris * 5230557Sjimharris * GPL LICENSE SUMMARY 6230557Sjimharris * 7230557Sjimharris * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 8230557Sjimharris * 9230557Sjimharris * This program is free software; you can redistribute it and/or modify 10230557Sjimharris * it under the terms of version 2 of the GNU General Public License as 11230557Sjimharris * published by the Free Software Foundation. 12230557Sjimharris * 13230557Sjimharris * This program is distributed in the hope that it will be useful, but 14230557Sjimharris * WITHOUT ANY WARRANTY; without even the implied warranty of 15230557Sjimharris * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16230557Sjimharris * General Public License for more details. 17230557Sjimharris * 18230557Sjimharris * You should have received a copy of the GNU General Public License 19230557Sjimharris * along with this program; if not, write to the Free Software 20230557Sjimharris * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. 21230557Sjimharris * The full GNU General Public License is included in this distribution 22230557Sjimharris * in the file called LICENSE.GPL. 23230557Sjimharris * 24230557Sjimharris * BSD LICENSE 25230557Sjimharris * 26230557Sjimharris * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 27230557Sjimharris * All rights reserved. 28230557Sjimharris * 29230557Sjimharris * Redistribution and use in source and binary forms, with or without 30230557Sjimharris * modification, are permitted provided that the following conditions 31230557Sjimharris * are met: 32230557Sjimharris * 33230557Sjimharris * * Redistributions of source code must retain the above copyright 34230557Sjimharris * notice, this list of conditions and the following disclaimer. 35230557Sjimharris * * Redistributions in binary form must reproduce the above copyright 36230557Sjimharris * notice, this list of conditions and the following disclaimer in 37230557Sjimharris * the documentation and/or other materials provided with the 38230557Sjimharris * distribution. 39230557Sjimharris * 40230557Sjimharris * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 41230557Sjimharris * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 42230557Sjimharris * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 43230557Sjimharris * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 44230557Sjimharris * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45230557Sjimharris * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 46230557Sjimharris * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 47230557Sjimharris * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 48230557Sjimharris * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 49230557Sjimharris * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 50230557Sjimharris * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 51230557Sjimharris * 52230557Sjimharris * $FreeBSD$ 53230557Sjimharris */ 54230557Sjimharris#ifndef _SCIF_SAS_DESIGN_H_ 55230557Sjimharris#define _SCIF_SAS_DESIGN_H_ 56230557Sjimharris 57230557Sjimharris/** 58230557Sjimharris@page scif_sas_design_page SCIF SAS High Level Design 59230557Sjimharris 60230557Sjimharris<b>Authors:</b> 61230557Sjimharris- Nathan Marushak 62230557Sjimharris 63230557Sjimharris<b>Key Contributors:</b> 64230557Sjimharris- Richard Boyd 65230557Sjimharris 66230557Sjimharris@section scif_sas_scope_and_audience Scope and Audience 67230557Sjimharris 68230557SjimharrisThis document provides design information relating to the SAS specific 69230557Sjimharrisimplementation of the SCI Framework. Driver developers are the primary 70230557Sjimharrisaudience for this document. The reader is expected to have an understanding 71230557Sjimharrisof the SCU Software Architecture Specification, the Storage Controller 72230557SjimharrisInterface Specification, and the SCI Base Design. 73230557Sjimharris 74230557Sjimharris@section scif_sas_overview Overview 75230557Sjimharris 76230557SjimharrisTo begin, it's important to discuss the utilization of state machines in 77230557Sjimharristhe design. State machines are pervasive in this design, because of the 78230557Sjimharrisabilities they provide. A properly implemented state machine allows the 79230557Sjimharrisdeveloper to code for a specific task. The developer is not encumbered 80230557Sjimharriswith needed to handle other situations all in a single function. For 81230557Sjimharrisexample, if a specific event can only occur when the object is in a specific 82230557Sjimharrisstate, then the event handler is added to handle such an event. Thus, a 83230557Sjimharrissingle function is not spliced to handle multiple events under various 84230557Sjimharrispotentially disparate conditions. 85230557Sjimharris 86230557SjimharrisAdditionally, the SCI Base Design document specifies a number of state 87230557Sjimharrismachines, objects, and methods that are heavily utilized by this design. 88230557SjimharrisPlease refer to Base Design specification for further information. 89230557Sjimharris 90230557SjimharrisMany of the framework objects have state machines associated with them. 91230557SjimharrisAs a result, there are a number of state entrance and exit methods as well 92230557Sjimharrisas event handlers for each individual state. This design places all of 93230557Sjimharristhe state entrance and exit methods for a given state machine into a single 94230557Sjimharrisfile (e.g. scif_sas_controller_states.c). Furthermore, all of the state 95230557Sjimharrisevent handler methods are also placed into a single file (e.g. 96230557Sjimharrisscif_sas_controller_state_handlers.c). This format is reused for each 97230557Sjimharrisobject that contains state machine(s). 98230557Sjimharris 99230557SjimharrisSome of the SAS framework objects contain sub-state machines. These 100230557Sjimharrissub-state machines are started upon entrance to the super-state and stopped 101230557Sjimharrisupon exit of the super-state. 102230557Sjimharris 103230557SjimharrisAll other method, data, constant description information will be found in 104230557Sjimharristhe remaining source file (e.g. scif_sas_controller.c). As a result, please 105230557Sjimharrisbe sure to follow the link to that specific object/file definition for 106230557Sjimharrisfurther information. 107230557Sjimharris 108230557Sjimharris@note Currently a large number of function pointers are utilized during the 109230557Sjimharriscourse of a normal IO request. Once stability of the driver is achieved, 110230557Sjimharrisperformance improvements will be made as needed. This likely will include 111230557Sjimharrisremoval of the function pointers from the IO path. 112230557Sjimharris 113230557Sjimharris@section scif_sas_use_cases Use Cases 114230557Sjimharris 115230557SjimharrisThe following use case diagram depicts the high-level user interactions with 116230557Sjimharristhe SAS framework. This diagram does not encompass all use cases implemented 117230557Sjimharrisin the system. The low-level design section will contain detailed use cases 118230557Sjimharrisfor each significant object and their associated detailed sequences and/or 119230557Sjimharrisactivities. For the purposes of readability, the use cases are not directly 120230557Sjimharrisconnected to the associated actor utilizing the use case. Instead naming 121230557Sjimharrisis utilized to different which actor is involved with the use case. 122230557Sjimharris 123230557SjimharrisActors: 124230557Sjimharris- The Framework user also called the OS Specific Driver initiates activities in 125230557Sjimharristhe Framework. 126230557Sjimharris- The SCI Core calls back into the Framework as a result of an operation either 127230557Sjimharrisstarted by the OS Specific Driver or by the Framework itself. 128230557Sjimharris 129230557Sjimharris@image latex Use_Case_Diagram__SCIF_SAS__Use_Cases.eps "SCIF SAS OS Use Cases" width=11cm 130230557Sjimharris@image html Use_Case_Diagram__SCIF_SAS__Use_Cases.jpg "SCIF SAS OS Use Cases" 131230557Sjimharris 132230557Sjimharris@section scif_sas_class_hierarchy Class Hierarchy 133230557Sjimharris 134230557SjimharrisThis section delineates the high-level class organization for the SCIF_SAS 135230557Sjimharriscomponent. Details concerning each class will be found in the corresponding 136230557Sjimharrislow-level design sections. Furthermore, additional classes not germane to 137230557Sjimharristhe overall architecture of the component will also be defined in these 138230557Sjimharrislow-level design sections. 139230557Sjimharris 140230557Sjimharris@image latex Class_Diagram__scif_sas__Class_Diagram.eps "SCIF SAS Class Diagram" width=16cm 141230557Sjimharris@image html Class_Diagram__scif_sas__Class_Diagram.jpg "SCIF SAS Class Diagram" 142230557Sjimharris 143230557SjimharrisFor more information on each object appearing in the diagram, please 144230557Sjimharrisreference the subsequent sections. 145230557Sjimharris 146230557Sjimharris@section scif_sas_library SCIF SAS Library 147230557Sjimharris 148230557SjimharrisFirst, the SCIF_SAS_LIBRARY object provides an implementation 149230557Sjimharrisfor the roles and responsibilities defined in the Storage Controller 150230557SjimharrisInterface (SCI) specification. It is suggested that the user read the 151230557Sjimharrisstorage controller interface specification for background information on 152230557Sjimharristhe library object. 153230557Sjimharris 154230557SjimharrisThe SCIF_SAS_LIBRARY object is broken down into 2 individual source files 155230557Sjimharrisand one direct header file. These files delineate the methods, members, etc. 156230557Sjimharrisassociated with this object. Please reference these files directly for 157230557Sjimharrisfurther design information: 158230557Sjimharris- scif_sas_library.h 159230557Sjimharris- scif_sas_library.c 160230557Sjimharris 161230557Sjimharris@section scif_sas_controller SCIF SAS Controller 162230557Sjimharris 163230557SjimharrisFirst, the SCIF_SAS_CONTROLLER object provides an implementation 164230557Sjimharrisfor the roles and responsibilities defined in the Storage Controller 165230557SjimharrisInterface (SCI) specification. It is suggested that the user read the 166230557Sjimharrisstorage controller interface specification for background information on 167230557Sjimharristhe controller object. 168230557Sjimharris 169230557SjimharrisThe SCIF_SAS_CONTROLLER object is broken down into 3 individual source files 170230557Sjimharrisand one direct header file. These files delineate the methods, members, etc. 171230557Sjimharrisassociated with this object. Please reference these files directly for 172230557Sjimharrisfurther design information: 173230557Sjimharris- scif_sas_controller.h 174230557Sjimharris- scif_sas_controller.c 175230557Sjimharris- scif_sas_controller_state_handlers.c 176230557Sjimharris- scif_sas_controller_states.c 177230557Sjimharris 178230557Sjimharris@section scif_sas_domain SCIF SAS Domain 179230557Sjimharris 180230557SjimharrisFirst, the SCIF_SAS_DOMAIN object provides an implementation 181230557Sjimharrisfor the roles and responsibilities defined in the Storage Controller 182230557SjimharrisInterface (SCI) specification. It is suggested that the user read the 183230557Sjimharrisstorage controller interface specification for background information on 184230557Sjimharristhe SCIF_SAS_DOMAIN object. 185230557Sjimharris 186230557SjimharrisThe SCIF_SAS_DOMAIN object is broken down into 3 individual 187230557Sjimharrissource files and one direct header file. These files delineate the 188230557Sjimharrismethods, members, etc. associated with this object. Please reference 189230557Sjimharristhese files directly for 190230557Sjimharrisfurther design information: 191230557Sjimharris- scif_sas_domain.h 192230557Sjimharris- scif_sas_domain.c 193230557Sjimharris- scif_sas_domain_state_handlers.c 194230557Sjimharris- scif_sas_domain_states.c 195230557Sjimharris 196230557Sjimharris@section scif_sas_remote_device SCIF SAS Remote Device 197230557Sjimharris 198230557SjimharrisFirst, the SCIF_SAS_REMOTE_DEVICE object provides an implementation 199230557Sjimharrisfor the roles and responsibilities defined in the Storage Controller 200230557SjimharrisInterface (SCI) specification. It is suggested that the user read the 201230557Sjimharrisstorage controller interface specification for background information on 202230557Sjimharristhe SCIF_SAS_REMOTE_DEVICE object. 203230557Sjimharris 204230557SjimharrisThe SCIF_SAS_REMOTE_DEVICE object is broken down into 7 individual source files 205230557Sjimharrisand one direct header file. These files delineate the methods, members, etc. 206230557Sjimharrisassociated with this object. Methods, data, and functionality specific to a 207230557Sjimharrisparticular protocol type (e.g. SMP, STP, etc.) are broken out into their own 208230557Sjimharrisobject/file. SSP specific remote device functionality is covered by the base 209230557Sjimharrisclasses (common files). Please reference these files directly for further 210230557Sjimharrisdesign information: 211230557Sjimharris- scif_sas_remote_device.h 212230557Sjimharris- scif_sas_smp_remote_device.h 213230557Sjimharris- scif_sas_stp_remote_device.h 214230557Sjimharris- scif_sas_remote_device.c 215230557Sjimharris- scif_sas_remote_device_state_handlers.c 216230557Sjimharris- scif_sas_remote_device_states.c 217230557Sjimharris- scif_sas_remote_device_starting_substate_handlers.c 218230557Sjimharris- scif_sas_remote_device_starting_substates.c 219230557Sjimharris- scif_sas_remote_device_ready_substate_handlers.c 220230557Sjimharris- scif_sas_remote_device_ready_substates.c 221230557Sjimharris- scif_sas_smp_remote_device.c 222230557Sjimharris- scif_sas_stp_remote_device.c 223230557Sjimharris 224230557SjimharrisThe SCIF_SAS_REMOTE_DEVICE object has sub-state machines defined for 225230557Sjimharristhe READY and STARTING super-states. For more information on the 226230557Sjimharrissuper-state machine please refer to SCI_BASE_REMOTE_DEVICE_STATES 227230557Sjimharrisin the SCI Base design document. 228230557Sjimharris 229230557SjimharrisIn the SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATES sub-state machine, 230230557Sjimharristhe remote device currently has to wait for the core to 231230557Sjimharrisreturn an indication that the remote device has successfully started 232230557Sjimharrisand become ready. If all goes well, then the remote device will 233230557Sjimharristransition into the READY state. 234230557Sjimharris 235230557SjimharrisFor more information on the starting sub-state machine states please refer 236230557Sjimharristo the scif_sas_remote_device.h::_SCIF_SAS_REMOTE_DEVICE_STARTING_SUBSTATES 237230557Sjimharrisenumeration. 238230557Sjimharris 239230557Sjimharris@image latex State_Machine_Diagram__STARTING_SUB-STATE__STARTING_SUB-STATE.eps "SCIF SAS Remote Device Starting Sub-state Machine Diagram" width=16cm 240230557Sjimharris@image html State_Machine_Diagram__STARTING_SUB-STATE__STARTING_SUB-STATE.jpg "SCIF SAS Remote Device Starting Sub-state Machine Diagram" 241230557Sjimharris 242230557SjimharrisIn the SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATES sub-state machine, 243230557Sjimharristhe remote device currently only allows new host IO requests during the 244230557SjimharrisOPERATIONAL state. In the TASK MANAGEMENT state only new task management 245230557Sjimharrisrequests are allowed. 246230557Sjimharris 247230557SjimharrisFor more information on the ready sub-state machine states please refer 248230557Sjimharristo the scif_sas_remote_device.h::_SCIF_SAS_REMOTE_DEVICE_READY_SUBSTATES 249230557Sjimharrisenumeration. 250230557Sjimharris 251230557Sjimharris@image latex State_Machine_Diagram__READY_SUB-STATE__READY_SUB-STATE.eps "SCIF SAS Remote Device Ready Sub-state Machine Diagram" width=16cm 252230557Sjimharris@image html State_Machine_Diagram__READY_SUB-STATE__READY_SUB-STATE.jpg "SCIF SAS Remote Device Ready Sub-state Machine Diagram" 253230557Sjimharris 254230557Sjimharris@section scif_sas_request SCIF SAS Request 255230557Sjimharris 256230557SjimharrisThe SCIF_SAS_REQUEST object provide common functionality for the 257230557SjimharrisSCIF_SAS_IO_REQUEST and the SCIF_SAS_TASK_REQUEST objects. This object 258230557Sjimharrisdoes not directly map to an SCI defined object, but its children do. For 259230557Sjimharrisadditional information, you may reference the SCIF_SAS_IO_REQUEST or 260230557SjimharrisSCIF_SAS_TASK_REQUEST objects. 261230557Sjimharris 262230557SjimharrisThe SCIF_SAS_REQUEST object is broken down into 1 individual source file 263230557Sjimharrisand one direct header file. These files delineate the methods, members, etc. 264230557Sjimharrisassociated with this object. Please reference these files directly for 265230557Sjimharrisfurther design information: 266230557Sjimharris- scif_sas_request.h 267230557Sjimharris- scif_sas_request.c 268230557Sjimharris 269230557Sjimharris@section scif_sas_io_request SCIF SAS IO Request 270230557Sjimharris 271230557SjimharrisFirst, the SCIF_SAS_IO_REQUEST object provides an implementation 272230557Sjimharrisfor the roles and responsibilities defined in the Storage Controller 273230557SjimharrisInterface (SCI) specification. It is suggested that the user read the 274230557Sjimharrisstorage controller interface specification for background information on 275230557Sjimharristhe SCIF_SAS_IO_REQUEST object. 276230557Sjimharris 277230557SjimharrisThe SCIF_SAS_IO_REQUEST object is broken down into 3 individual 278230557Sjimharrissource files and one direct header file. These files delineate the 279230557Sjimharrismethods, members, etc. associated with this object. Please reference 280230557Sjimharristhese files directly for further design information: 281230557Sjimharris- scif_sas_io_request.h 282230557Sjimharris- scif_sas_smp_io_request.h 283230557Sjimharris- scif_sas_stp_io_request.h 284230557Sjimharris- scif_sas_sati_binding.h 285230557Sjimharris- scif_sas_io_request.c 286230557Sjimharris- scif_sas_io_request_state_handlers.c 287230557Sjimharris- scif_sas_io_request_states.c 288230557Sjimharris- scif_sas_smp_io_request.c 289230557Sjimharris- scif_sas_stp_io_request.c 290230557Sjimharris 291230557Sjimharris@section scif_sas_task_request SCIF SAS Task Request 292230557Sjimharris 293230557SjimharrisFirst, the SCIF_SAS_TASK_REQUEST object provides an implementation 294230557Sjimharrisfor the roles and responsibilities defined in the Storage Controller 295230557SjimharrisInterface (SCI) specification. It is suggested that the user read the 296230557Sjimharrisstorage controller interface specification for background information on 297230557Sjimharristhe SCIF_SAS_TASK_REQUEST object. 298230557Sjimharris 299230557SjimharrisThe SCIF_SAS_TASK_REQUEST object is broken down into 3 individual 300230557Sjimharrissource files and one direct header file. These files delineate the 301230557Sjimharrismethods, members, etc. associated with this object. Please reference 302230557Sjimharristhese files directly for further design information: 303230557Sjimharris- scif_sas_task_request.h 304230557Sjimharris- scif_sas_stp_task_request.h 305230557Sjimharris- scif_sas_task_request.c 306230557Sjimharris- scif_sas_task_request_state_handlers.c 307230557Sjimharris- scif_sas_task_request_states.c 308230557Sjimharris- scif_sas_stp_task_request.c 309230557Sjimharris 310230557Sjimharris@section scif_sas_internal_io_request SCIF SAS INTERNAL IO Request 311230557Sjimharris 312230557SjimharrisThe SCIF_SAS_INTERNAL_IO_REQUEST object fulfills the SCI's need to create 313230557Sjimharrisand send out the internal io request. These internal io requests could be 314230557Sjimharrissmp request for expander device discover process, or stp request for NCQ 315230557Sjimharriserror handling. Internal IOs consume the reserved internal io space in 316230557Sjimharrisscif_sas_controller. When an internal IO is constructed, it is put into an 317230557Sjimharrisinternal high priority queue. A defferred task (start_internal_io_task) will be 318230557Sjimharrisscheduled at the end of every completion process. The task looks up the high 319230557Sjimharrispriority queue and starts each internal io in the queue. There is one exception 320230557Sjimharristhat start_internal_io_task is scheduled immediately when the first internal io 321230557Sjimharrisis constructed. A retry mechanism is also provided for internal io. When an 322230557Sjimharrisinternal io response is decoded, if the decoding indicates a retry is needed, 323230557Sjimharristhe internal io will be retried. 324230557Sjimharris 325230557SjimharrisPlease refer to these files directly for further design information: 326230557Sjimharris- scif_sas_internal_io_request.h 327230557Sjimharris- scif_sas_internal_io_request.c 328230557Sjimharris- scif_sas_controller.h 329230557Sjimharris 330230557Sjimharris@section scif_sas_smp_remote_device SCIF SAS SMP REMOTE DEVICE 331230557Sjimharris 332230557SjimharrisThe SCIF SAS SMP REMOTE DEVICE object represents the expander device and fulfills 333230557Sjimharrisits SMP discover activities. The discover procedure includes a initial discover 334230557Sjimharrisphase and a follwoing SATA spinup_hold release phase, if there are expander attached 335230557SjimharrisSATA device is discovered and in spinup_hold conditon. The SCIF SAS SMP REMOTE DEVICE 336230557Sjimharrisobject also fulfills expander attached device Target Reset (Phy Control) activity. 337230557Sjimharris 338230557Sjimharris@image latex Discover Process.eps "SMP Discover Activity Diagram" width=10cm 339230557Sjimharris@image html Discover Process.jpg "SMP Discover Activity Diagram" 340230557Sjimharris 341230557SjimharrisPlease refer to these files directly for further design information: 342230557Sjimharris- scif_sas_smp_remote_device.h 343230557Sjimharris- scif_sas_smp_remote_device.c 344230557Sjimharris- scif_sas_smp_request.h 345230557Sjimharris- scif_sas_smp_request.c 346230557Sjimharris*/ 347230557Sjimharris 348230557Sjimharris#endif // _SCIF_SAS_DESIGN_H_ 349