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