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 _SCI_OVERVIEW_H_ 55230557Sjimharris#define _SCI_OVERVIEW_H_ 56230557Sjimharris 57230557Sjimharris/** 58230557Sjimharris@mainpage The Intel Storage Controller Interface (SCI) 59230557Sjimharris 60230557SjimharrisSCI provides a common interface across intel storage controller hardware. 61230557SjimharrisThis includes abstracting differences between Physical PCI functions and 62230557SjimharrisVirtual PCI functions. The SCI is comprised of four primary components: 63230557Sjimharris-# SCI Base classes 64230557Sjimharris-# SCI Core 65230557Sjimharris-# SCI Framework 66230557Sjimharris 67230557SjimharrisIt is important to recognize that no component, object, or functionality in 68230557SjimharrisSCI directly allocates memory from the operating system. It is expected that 69230557Sjimharristhe SCI User (OS specific driver code) allocates and frees all memory from 70230557Sjimharrisand to the operating system itself. 71230557Sjimharris 72230557SjimharrisThe C language is utilized to implement SCI. Although C is not an object 73230557Sjimharrisoriented language the SCI driver components, methods, and structures are 74230557Sjimharrismodeled and organized following object oriented principles. 75230557Sjimharris 76230557SjimharrisThe Unified Modeling Language is utilized to present graphical depictions 77230557Sjimharrisof the SCI classes and their relationships. 78230557Sjimharris 79230557SjimharrisThe following figure denotes the meanings of the colors utilized in UML 80230557Sjimharrisdiagrams throughout this document. 81230557Sjimharris@image latex object_color_key.eps "Object Color Legend" width=8cm 82230557Sjimharris 83230557SjimharrisThe following figure denotes the meanings for input and output arrows that 84230557Sjimharrisare utilized to define parameters for methods defined in this specification. 85230557Sjimharris@image latex arrow_image.eps "Method Parameter Symbol Definition" 86230557Sjimharris 87230557Sjimharris@page abbreviations_section Abbreviations 88230557Sjimharris 89230557Sjimharris- ATA: Advanced Technology Attachment 90230557Sjimharris- IAF: Identify Address Frame 91230557Sjimharris- SAS: Serial Attached SCSI 92230557Sjimharris- SAT: SCSI to ATA Translation 93230557Sjimharris- SATA: Serial ATA 94230557Sjimharris- SCI: Storage Controller Interface 95230557Sjimharris- SCIC: SCI Core 96230557Sjimharris- SCIF: SCI Framework 97230557Sjimharris- SCU: Storage Controller Unit 98230557Sjimharris- SDS: SCU Driver Standard (i.e. non-virtualization) 99230557Sjimharris- SDV: SCU Driver Virtualized 100230557Sjimharris- SDVP: SDV Physical (PCI function) 101230557Sjimharris- SDVV: SDV Virtual (PCI function) 102230557Sjimharris- SGE: Scatter-Gather Element 103230557Sjimharris- SGL: Scatter-Gather List 104230557Sjimharris- SGPIO: Serial General Purpose Input/Output 105230557Sjimharris- SSC: Spread Spectrum Clocking 106230557Sjimharris 107230557Sjimharris@page definitions_section Definitions 108230557Sjimharris 109230557Sjimharris- <b>construct</b> - The term "construct" is utilized throughout the 110230557Sjimharris interface to indicate when an object is being created. Typically construct 111230557Sjimharris methods perform pure memory initialization. No "construct" method ever 112230557Sjimharris performs memory allocation. It is incumbent upon the SCI user to provide 113230557Sjimharris the necessary memory. 114230557Sjimharris- <b>initialize</b> - The term "initialize" is utilized throughout the 115230557Sjimharris interface to indicate when an object is performing actions on other objects 116230557Sjimharris or on physical resources in an attempt to allow these resources to become 117230557Sjimharris operational. 118230557Sjimharris- <b>protected</b> - The term "protected" is utilized to denote a method 119230557Sjimharris defined in this standard that MUST NOT be invoked directly by operating 120230557Sjimharris system specific driver code. 121230557Sjimharris- <b>SCI Component</b> - An SCI component is one of: SCI base classes, Core, 122230557Sjimharris or Framework. 123230557Sjimharris- <b>SCI User</b> - The user callbacks for each SCI Component represent the 124230557Sjimharris dependencies that the SCI component implementation has upon the operating 125230557Sjimharris system/environment specific portion of the driver. It is essentially a 126230557Sjimharris set of functions or macro definitions that are specific to a particular 127230557Sjimharris operating system. 128230557Sjimharris- <b>THIN</b> - A term utilized to describe an SCI Component implementation 129230557Sjimharris that is built to conserve memory. 130230557Sjimharris 131230557Sjimharris@page inheritance SCI Inheritance Hierarchy 132230557Sjimharris 133230557SjimharrisThis section describes the inheritance (i.e. "is-a") relationships between 134230557Sjimharristhe various objects in SCI. Due to various operating environment requirements 135230557Sjimharristhe programming language employed for the SCI driver is C. As a result, one 136230557Sjimharrismight be curious how inheritance shall be applied in such an environment. 137230557SjimharrisThe SCI driver source shall maintain generalization relationships by ensuring 138230557Sjimharristhat child object structures shall contain an instance of their parent's 139230557Sjimharrisstructure as the very first member of their structure. As a result, parent 140230557Sjimharrisobject methods can be invoked with a child structure parameter. This works 141230557Sjimharrissince casting of the child structure to the parent structure inside the parent 142230557Sjimharrismethod will yield correct access to the parent structure fields. 143230557Sjimharris 144230557SjimharrisConsider the following example: 145230557Sjimharris<pre> 146230557Sjimharristypedef struct SCI_OBJECT 147230557Sjimharris{ 148230557Sjimharris U32 object_type; 149230557Sjimharris}; 150230557Sjimharris 151230557Sjimharristypedef struct SCI_CONTROLLER 152230557Sjimharris{ 153230557Sjimharris U32 state; 154230557Sjimharris 155230557Sjimharris} SCI_CONTROLLER_T; 156230557Sjimharris 157230557Sjimharristypedef struct SCIC_CONTROLLER 158230557Sjimharris{ 159230557Sjimharris SCI_CONTROLLER_T parent; 160230557Sjimharris U32 type; 161230557Sjimharris 162230557Sjimharris} SCIC_CONTROLLER_T; 163230557Sjimharris</pre> 164230557Sjimharris 165230557SjimharrisWith the above structure orientation, a user would be allowed to perform 166230557Sjimharrismethod invocations in a manner similar to the following: 167230557Sjimharris<pre> 168230557SjimharrisSCIC_CONTROLLER_T scic_controller; 169230557Sjimharrisscic_controller_initialize((SCIC_CONTROLLER_T*) &scic_controller); 170230557Sjimharris 171230557Sjimharris// OR 172230557Sjimharris 173230557Sjimharrissci_object_get_association(&scic_controller); 174230557Sjimharris</pre> 175230557Sjimharris@note The actual interface will not require type casting. 176230557Sjimharris 177230557SjimharrisThe following diagram graphically depicts the inheritance relationships 178230557Sjimharrisbetween the various objects defined in the Storage Controller Interface. 179230557Sjimharris@image latex inheritance.eps "SCI Inheritance Hierarchy" width=16cm 180230557Sjimharris 181230557Sjimharris@page sci_classes SCI Classes 182230557Sjimharris 183230557SjimharrisThis section depicts the common classes and utility functions across the 184230557Sjimharrisentire set of SCI Components. Descriptions about each of the specific 185230557Sjimharrisobjects will be found in the header file definition in the File Documentation 186230557Sjimharrissection. 187230557Sjimharris 188230557SjimharrisThe following is a list of features that can be found in the SCI base classes: 189230557Sjimharris-# Logging utility methods, constants, and type definitions 190230557Sjimharris-# Memory Descriptor object methods common to the core and framework. 191230557Sjimharris-# Controller object methods common to SCI derived controller objects. 192230557Sjimharris-# Library object methods common to SCI derived library objects. 193230557Sjimharris-# Storage standard (e.g. SAS, SATA) defined constants, structures, etc. 194230557Sjimharris-# Standard types utilized by SCI sub-components. 195230557Sjimharris-# The ability to associate/link SCI objects together or to user objects. 196230557Sjimharris 197230557SjimharrisSCI class methods can be overridden by sub-classes in the SCI Core, 198230557SjimharrisSCI Framework, etc. SCI class methods that MUST NOT be invoked directly 199230557Sjimharrisby operating system specific driver code shall be adorned with a 200230557Sjimharris<code>[protected]</code> keyword. These <code>[protected]</code> API are still 201230557Sjimharrisdefined as part of the specification in order to demonstrate commonality across 202230557Sjimharriscomponents as well as provide a common description of related methods. If 203230557Sjimharristhese methods are invoked directly by operating system specific code, the 204230557Sjimharrisoperation of the driver as a whole is not specified or supported. 205230557Sjimharris 206230557SjimharrisThe following UML diagram graphically depicts the SCI base classes and their 207230557Sjimharrisrelationships to one another. 208230557Sjimharris@image latex sci_base_classes.eps "SCI Classes" width=4cm 209230557Sjimharris 210230557Sjimharris@page associations_section Associations 211230557SjimharrisThe sci_object class provides functionality common to all SCI objects. 212230557SjimharrisAn important feature provided by this base class is the means by which to 213230557Sjimharrisassociate one object to another. An SCI object can be made to have an 214230557Sjimharrisassociation to another SCI object. Additionally, an SCI object can be 215230557Sjimharrismade to have an association to a non-SCI based object. For example, an SCI 216230557SjimharrisFramework library can have it's association set to an operating system 217230557Sjimharrisspecific adapter/device driver structre. 218230557Sjimharris 219230557SjimharrisSimply put, the association that an object has is a handle (i.e. a void pointer) 220230557Sjimharristo a user structure. This enables the user of the SCI object to 221230557Sjimharriseasily determine it's own associated structure. This association is useful 222230557Sjimharrisbecause the user is now enabled to easily determine their pertinent information 223230557Sjimharrisinside of their SCI user callback methods. 224230557Sjimharris 225230557SjimharrisSetting an association within an SCI object is generally optional. The 226230557Sjimharrisprimary case in which an association is not optional is in the case of IO 227230557Sjimharrisrequest objects. These associations are necessary in order to fill 228230557Sjimharristo fill in appropriate information for an IO request (i.e. CDB address, size, 229230557SjimharrisSGL information, etc.) in an efficient manner. 230230557Sjimharris 231230557SjimharrisIn the case of other objects, the user is free to not create associations. 232230557SjimharrisWhen the user chooses not to create an association, the user is responsible for 233230557Sjimharrisbeing able to determine their data structures based on the SCI object handles. 234230557SjimharrisAdditionally, the user may be forced to invoke additional functionality in 235230557Sjimharrissituations where the SCI Framework is employed. If the user does not 236230557Sjimharrisestablish proper associations between objects (i.e. SCIC Library to SCIF Library), then the framework is unable to automate interactions. Users should 237230557Sjimharrisstrongly consider establishing associations between SCI Framework objects and 238230557SjimharrisOS Driver related structures. 239230557Sjimharris 240230557SjimharrisExample Associations: 241230557Sjimharris- The user might set the scif_controller association to their adapter or 242230557Sjimharriscontroller object. 243230557Sjimharris- The user might set the scif_domain association to their SCSI bus object. 244230557Sjimharris 245230557SjimharrisIf SCIF is being utilized, then the framework will set the associations 246230557Sjimharrisin the core. In this situation, the user should only set the associations 247230557Sjimharrisin the framework objects, unless otherwise directed. 248230557Sjimharris*/ 249230557Sjimharris 250230557Sjimharris#endif // _SCI_OVERVIEW_H_ 251230557Sjimharris 252