sci_overview.h revision 230843
1214456Srpaulo/*- 2214456Srpaulo * This file is provided under a dual BSD/GPLv2 license. When using or 3214456Srpaulo * redistributing this file, you may do so under either license. 4214456Srpaulo * 5214456Srpaulo * GPL LICENSE SUMMARY 6214456Srpaulo * 7214456Srpaulo * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 8214456Srpaulo * 9214456Srpaulo * This program is free software; you can redistribute it and/or modify 10214456Srpaulo * it under the terms of version 2 of the GNU General Public License as 11214456Srpaulo * published by the Free Software Foundation. 12214456Srpaulo * 13214456Srpaulo * This program is distributed in the hope that it will be useful, but 14214456Srpaulo * WITHOUT ANY WARRANTY; without even the implied warranty of 15214456Srpaulo * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16214456Srpaulo * General Public License for more details. 17214456Srpaulo * 18214456Srpaulo * You should have received a copy of the GNU General Public License 19214456Srpaulo * along with this program; if not, write to the Free Software 20214456Srpaulo * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. 21214456Srpaulo * The full GNU General Public License is included in this distribution 22214456Srpaulo * in the file called LICENSE.GPL. 23214456Srpaulo * 24214456Srpaulo * BSD LICENSE 25214456Srpaulo * 26214456Srpaulo * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 27214456Srpaulo * All rights reserved. 28214456Srpaulo * 29214456Srpaulo * Redistribution and use in source and binary forms, with or without 30214456Srpaulo * modification, are permitted provided that the following conditions 31214456Srpaulo * are met: 32214456Srpaulo * 33214456Srpaulo * * Redistributions of source code must retain the above copyright 34214456Srpaulo * notice, this list of conditions and the following disclaimer. 35214456Srpaulo * * Redistributions in binary form must reproduce the above copyright 36214456Srpaulo * notice, this list of conditions and the following disclaimer in 37214456Srpaulo * the documentation and/or other materials provided with the 38214456Srpaulo * distribution. 39214456Srpaulo * 40214456Srpaulo * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 41214456Srpaulo * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 42214456Srpaulo * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 43214456Srpaulo * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 44214456Srpaulo * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45214456Srpaulo * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 46214456Srpaulo * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 47214456Srpaulo * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 48214456Srpaulo * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 49214456Srpaulo * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 50214456Srpaulo * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 51214456Srpaulo * 52214456Srpaulo * $FreeBSD$ 53214456Srpaulo */ 54214456Srpaulo#ifndef _SCI_OVERVIEW_H_ 55214456Srpaulo#define _SCI_OVERVIEW_H_ 56214456Srpaulo 57214456Srpaulo/** 58214456Srpaulo@mainpage The Intel Storage Controller Interface (SCI) 59214456Srpaulo 60214456SrpauloSCI provides a common interface across intel storage controller hardware. 61214456SrpauloThis includes abstracting differences between Physical PCI functions and 62214456SrpauloVirtual PCI functions. The SCI is comprised of four primary components: 63214456Srpaulo-# SCI Base classes 64214456Srpaulo-# SCI Core 65214456Srpaulo-# SCI Framework 66214456Srpaulo 67214456SrpauloIt is important to recognize that no component, object, or functionality in 68214456SrpauloSCI directly allocates memory from the operating system. It is expected that 69214456Srpaulothe SCI User (OS specific driver code) allocates and frees all memory from 70214456Srpauloand to the operating system itself. 71214456Srpaulo 72214456SrpauloThe C language is utilized to implement SCI. Although C is not an object 73214456Srpaulooriented language the SCI driver components, methods, and structures are 74214456Srpaulomodeled and organized following object oriented principles. 75214456Srpaulo 76214456SrpauloThe Unified Modeling Language is utilized to present graphical depictions 77214456Srpauloof the SCI classes and their relationships. 78214456Srpaulo 79214456SrpauloThe following figure denotes the meanings of the colors utilized in UML 80214456Srpaulodiagrams throughout this document. 81214456Srpaulo@image latex object_color_key.eps "Object Color Legend" width=8cm 82214456Srpaulo 83214456SrpauloThe following figure denotes the meanings for input and output arrows that 84214456Srpauloare utilized to define parameters for methods defined in this specification. 85214456Srpaulo@image latex arrow_image.eps "Method Parameter Symbol Definition" 86214456Srpaulo 87214456Srpaulo@page abbreviations_section Abbreviations 88214456Srpaulo 89214456Srpaulo- ATA: Advanced Technology Attachment 90214456Srpaulo- IAF: Identify Address Frame 91214456Srpaulo- SAS: Serial Attached SCSI 92214456Srpaulo- SAT: SCSI to ATA Translation 93214456Srpaulo- SATA: Serial ATA 94214456Srpaulo- SCI: Storage Controller Interface 95214456Srpaulo- SCIC: SCI Core 96214456Srpaulo- SCIF: SCI Framework 97214456Srpaulo- SCU: Storage Controller Unit 98214456Srpaulo- SDS: SCU Driver Standard (i.e. non-virtualization) 99214456Srpaulo- SDV: SCU Driver Virtualized 100214456Srpaulo- SDVP: SDV Physical (PCI function) 101214456Srpaulo- SDVV: SDV Virtual (PCI function) 102214456Srpaulo- SGE: Scatter-Gather Element 103214456Srpaulo- SGL: Scatter-Gather List 104214456Srpaulo- SGPIO: Serial General Purpose Input/Output 105214456Srpaulo- SSC: Spread Spectrum Clocking 106214456Srpaulo 107214456Srpaulo@page definitions_section Definitions 108214456Srpaulo 109214456Srpaulo- <b>construct</b> - The term "construct" is utilized throughout the 110214456Srpaulo interface to indicate when an object is being created. Typically construct 111214456Srpaulo methods perform pure memory initialization. No "construct" method ever 112214456Srpaulo performs memory allocation. It is incumbent upon the SCI user to provide 113214456Srpaulo the necessary memory. 114214456Srpaulo- <b>initialize</b> - The term "initialize" is utilized throughout the 115214456Srpaulo interface to indicate when an object is performing actions on other objects 116214456Srpaulo or on physical resources in an attempt to allow these resources to become 117214456Srpaulo operational. 118214456Srpaulo- <b>protected</b> - The term "protected" is utilized to denote a method 119214456Srpaulo defined in this standard that MUST NOT be invoked directly by operating 120214456Srpaulo system specific driver code. 121214456Srpaulo- <b>SCI Component</b> - An SCI component is one of: SCI base classes, Core, 122214456Srpaulo or Framework. 123214456Srpaulo- <b>SCI User</b> - The user callbacks for each SCI Component represent the 124214456Srpaulo dependencies that the SCI component implementation has upon the operating 125214456Srpaulo system/environment specific portion of the driver. It is essentially a 126214456Srpaulo set of functions or macro definitions that are specific to a particular 127214456Srpaulo operating system. 128214456Srpaulo- <b>THIN</b> - A term utilized to describe an SCI Component implementation 129214456Srpaulo that is built to conserve memory. 130214456Srpaulo 131214456Srpaulo@page inheritance SCI Inheritance Hierarchy 132214456Srpaulo 133214456SrpauloThis section describes the inheritance (i.e. "is-a") relationships between 134214456Srpaulothe various objects in SCI. Due to various operating environment requirements 135214456Srpaulothe programming language employed for the SCI driver is C. As a result, one 136214456Srpaulomight be curious how inheritance shall be applied in such an environment. 137214456SrpauloThe SCI driver source shall maintain generalization relationships by ensuring 138214456Srpaulothat child object structures shall contain an instance of their parent's 139214456Srpaulostructure as the very first member of their structure. As a result, parent 140214456Srpauloobject methods can be invoked with a child structure parameter. This works 141214456Srpaulosince casting of the child structure to the parent structure inside the parent 142214456Srpaulomethod will yield correct access to the parent structure fields. 143214456Srpaulo 144214456SrpauloConsider the following example: 145214456Srpaulo<pre> 146214456Srpaulotypedef struct SCI_OBJECT 147214456Srpaulo{ 148214456Srpaulo U32 object_type; 149214456Srpaulo}; 150214456Srpaulo 151214456Srpaulotypedef struct SCI_CONTROLLER 152214456Srpaulo{ 153214456Srpaulo U32 state; 154214456Srpaulo 155214456Srpaulo} SCI_CONTROLLER_T; 156214456Srpaulo 157214456Srpaulotypedef struct SCIC_CONTROLLER 158214456Srpaulo{ 159214456Srpaulo SCI_CONTROLLER_T parent; 160214456Srpaulo U32 type; 161214456Srpaulo 162214456Srpaulo} SCIC_CONTROLLER_T; 163214456Srpaulo</pre> 164214456Srpaulo 165214456SrpauloWith the above structure orientation, a user would be allowed to perform 166214456Srpaulomethod invocations in a manner similar to the following: 167214456Srpaulo<pre> 168214456SrpauloSCIC_CONTROLLER_T scic_controller; 169214456Srpauloscic_controller_initialize((SCIC_CONTROLLER_T*) &scic_controller); 170214456Srpaulo 171214456Srpaulo// OR 172214456Srpaulo 173214456Srpaulosci_object_get_association(&scic_controller); 174214456Srpaulo</pre> 175214456Srpaulo@note The actual interface will not require type casting. 176214456Srpaulo 177214456SrpauloThe following diagram graphically depicts the inheritance relationships 178214456Srpaulobetween the various objects defined in the Storage Controller Interface. 179214456Srpaulo@image latex inheritance.eps "SCI Inheritance Hierarchy" width=16cm 180214456Srpaulo 181214456Srpaulo@page sci_classes SCI Classes 182214456Srpaulo 183214456SrpauloThis section depicts the common classes and utility functions across the 184214456Srpauloentire set of SCI Components. Descriptions about each of the specific 185214456Srpauloobjects will be found in the header file definition in the File Documentation 186214456Srpaulosection. 187214456Srpaulo 188214456SrpauloThe following is a list of features that can be found in the SCI base classes: 189214456Srpaulo-# Logging utility methods, constants, and type definitions 190214456Srpaulo-# Memory Descriptor object methods common to the core and framework. 191214456Srpaulo-# Controller object methods common to SCI derived controller objects. 192214456Srpaulo-# Library object methods common to SCI derived library objects. 193214456Srpaulo-# Storage standard (e.g. SAS, SATA) defined constants, structures, etc. 194214456Srpaulo-# Standard types utilized by SCI sub-components. 195214456Srpaulo-# The ability to associate/link SCI objects together or to user objects. 196214456Srpaulo 197214456SrpauloSCI class methods can be overridden by sub-classes in the SCI Core, 198214456SrpauloSCI Framework, etc. SCI class methods that MUST NOT be invoked directly 199214456Srpauloby operating system specific driver code shall be adorned with a 200214456Srpaulo<code>[protected]</code> keyword. These <code>[protected]</code> API are still 201214456Srpaulodefined as part of the specification in order to demonstrate commonality across 202214456Srpaulocomponents as well as provide a common description of related methods. If 203214456Srpaulothese methods are invoked directly by operating system specific code, the 204214456Srpaulooperation of the driver as a whole is not specified or supported. 205214456Srpaulo 206214456SrpauloThe following UML diagram graphically depicts the SCI base classes and their 207214456Srpaulorelationships to one another. 208214456Srpaulo@image latex sci_base_classes.eps "SCI Classes" width=4cm 209214456Srpaulo 210214456Srpaulo@page associations_section Associations 211214456SrpauloThe sci_object class provides functionality common to all SCI objects. 212214456SrpauloAn important feature provided by this base class is the means by which to 213214456Srpauloassociate one object to another. An SCI object can be made to have an 214214456Srpauloassociation to another SCI object. Additionally, an SCI object can be 215214456Srpaulomade to have an association to a non-SCI based object. For example, an SCI 216214456SrpauloFramework library can have it's association set to an operating system 217214456Srpaulospecific adapter/device driver structre. 218214456Srpaulo 219214456SrpauloSimply put, the association that an object has is a handle (i.e. a void pointer) 220214456Srpauloto a user structure. This enables the user of the SCI object to 221214456Srpauloeasily determine it's own associated structure. This association is useful 222214456Srpaulobecause the user is now enabled to easily determine their pertinent information 223214456Srpauloinside of their SCI user callback methods. 224214456Srpaulo 225214456SrpauloSetting an association within an SCI object is generally optional. The 226214456Srpauloprimary case in which an association is not optional is in the case of IO 227214456Srpaulorequest objects. These associations are necessary in order to fill 228214456Srpauloto fill in appropriate information for an IO request (i.e. CDB address, size, 229214456SrpauloSGL information, etc.) in an efficient manner. 230214456Srpaulo 231214456SrpauloIn the case of other objects, the user is free to not create associations. 232214456SrpauloWhen the user chooses not to create an association, the user is responsible for 233214456Srpaulobeing able to determine their data structures based on the SCI object handles. 234214456SrpauloAdditionally, the user may be forced to invoke additional functionality in 235214456Srpaulosituations where the SCI Framework is employed. If the user does not 236214456Srpauloestablish proper associations between objects (i.e. SCIC Library to SCIF Library), then the framework is unable to automate interactions. Users should 237214456Srpaulostrongly consider establishing associations between SCI Framework objects and 238214456SrpauloOS Driver related structures. 239214456Srpaulo 240214456SrpauloExample Associations: 241214456Srpaulo- The user might set the scif_controller association to their adapter or 242214456Srpaulocontroller object. 243214456Srpaulo- The user might set the scif_domain association to their SCSI bus object. 244214456Srpaulo 245214456SrpauloIf SCIF is being utilized, then the framework will set the associations 246214456Srpauloin the core. In this situation, the user should only set the associations 247214456Srpauloin the framework objects, unless otherwise directed. 248214456Srpaulo*/ 249214456Srpaulo 250214456Srpaulo#endif // _SCI_OVERVIEW_H_ 251214456Srpaulo 252214456Srpaulo