sys/dev/isci/scil/sci_overview.h

   1 /*-
   2  * This file is provided under a dual BSD/GPLv2 license.  When using or
   3  * redistributing this file, you may do so under either license.
   4  *
   5  * GPL LICENSE SUMMARY
   6  *
   7  * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of version 2 of the GNU General Public License as
  11  * published by the Free Software Foundation.
  12  *
  13  * This program is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA.
  21  * The full GNU General Public License is included in this distribution
  22  * in the file called LICENSE.GPL.
  23  *
  24  * BSD LICENSE
  25  *
  26  * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
  27  * All rights reserved.
  28  *
  29  * Redistribution and use in source and binary forms, with or without
  30  * modification, are permitted provided that the following conditions
  31  * are met:
  32  *
  33  *   * Redistributions of source code must retain the above copyright
  34  *     notice, this list of conditions and the following disclaimer.
  35  *   * Redistributions in binary form must reproduce the above copyright
  36  *     notice, this list of conditions and the following disclaimer in
  37  *     the documentation and/or other materials provided with the
  38  *     distribution.
  39  *
  40  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  41  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  42  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  43  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  44  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  45  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  46  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  47  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  48  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  49  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  50  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  51  *
  52  * $FreeBSD$
  53  */
  54 #ifndef _SCI_OVERVIEW_H_
  55 #define _SCI_OVERVIEW_H_
  56
  57 /**
  58 @mainpage The Intel Storage Controller Interface (SCI)
  59
  60 SCI provides a common interface across intel storage controller hardware.
  61 This includes abstracting differences between Physical PCI functions and
  62 Virtual PCI functions.  The SCI is comprised of four primary components:
  63 -# SCI Base classes
  64 -# SCI Core
  65 -# SCI Framework
  66
  67 It is important to recognize that no component, object, or functionality in
  68 SCI directly allocates memory from the operating system.  It is expected that
  69 the SCI User (OS specific driver code) allocates and frees all memory from
  70 and to the operating system itself.
  71
  72 The C language is utilized to implement SCI.  Although C is not an object
  73 oriented language the SCI driver components, methods, and structures are
  74 modeled and organized following object oriented principles.
  75
  76 The Unified Modeling Language is utilized to present graphical depictions
  77 of the SCI classes and their relationships.
  78
  79 The following figure denotes the meanings of the colors utilized in UML
  80 diagrams throughout this document.
  81 @image latex object_color_key.eps "Object Color Legend" width=8cm
  82
  83 The following figure denotes the meanings for input and output arrows that
  84 are utilized to define parameters for methods defined in this specification.
  85 @image latex arrow_image.eps "Method Parameter Symbol Definition"
  86
  87 @page abbreviations_section Abbreviations
  88
  89 - ATA: Advanced Technology Attachment
  90 - IAF: Identify Address Frame
  91 - SAS: Serial Attached SCSI
  92 - SAT: SCSI to ATA Translation
  93 - SATA: Serial ATA
  94 - SCI: Storage Controller Interface
  95 - SCIC: SCI Core
  96 - SCIF: SCI Framework
  97 - SCU: Storage Controller Unit
  98 - SDS: SCU Driver Standard (i.e. non-virtualization)
  99 - SDV: SCU Driver Virtualized
 100 - SDVP: SDV Physical (PCI function)
 101 - SDVV: SDV Virtual (PCI function)
 102 - SGE: Scatter-Gather Element
 103 - SGL: Scatter-Gather List
 104 - SGPIO: Serial General Purpose Input/Output
 105 - SSC: Spread Spectrum Clocking
 106
 107 @page definitions_section Definitions
 108
 109 - <b>construct</b> - The term "construct" is utilized throughout the
 110   interface to indicate when an object is being created.  Typically construct
 111   methods perform pure memory initialization.  No "construct" method ever
 112   performs memory allocation.  It is incumbent upon the SCI user to provide
 113   the necessary memory.
 114 - <b>initialize</b> - The term "initialize" is utilized throughout the
 115   interface to indicate when an object is performing actions on other objects
 116   or on physical resources in an attempt to allow these resources to become
 117   operational.
 118 - <b>protected</b> - The term "protected" is utilized to denote a method
 119   defined in this standard that MUST NOT be invoked directly by operating
 120   system specific driver code.
 121 - <b>SCI Component</b> - An SCI component is one of: SCI base classes, Core,
 122   or Framework.
 123 - <b>SCI User</b> - The user callbacks for each SCI Component represent the
 124   dependencies that the SCI component implementation has upon the operating
 125   system/environment specific portion of the driver.  It is essentially a
 126   set of functions or macro definitions that are specific to a particular
 127   operating system.
 128 - <b>THIN</b> - A term utilized to describe an SCI Component implementation
 129   that is built to conserve memory.
 130
 131 @page inheritance SCI Inheritance Hierarchy
 132
 133 This section describes the inheritance (i.e. "is-a") relationships between
 134 the various objects in SCI.  Due to various operating environment requirements
 135 the programming language employed for the SCI driver is C.  As a result, one
 136 might be curious how inheritance shall be applied in such an environment.
 137 The SCI driver source shall maintain generalization relationships by ensuring
 138 that child object structures shall contain an instance of their parent's
 139 structure as the very first member of their structure.  As a result, parent
 140 object methods can be invoked with a child structure parameter.  This works
 141 since casting of the child structure to the parent structure inside the parent
 142 method will yield correct access to the parent structure fields.
 143
 144 Consider the following example:
 145 <pre>
 146 typedef struct SCI_OBJECT
 147 {
 148    U32 object_type;
 149 };
 150
 151 typedef struct SCI_CONTROLLER
 152 {
 153    U32 state;
 154
 155 } SCI_CONTROLLER_T;
 156
 157 typedef struct SCIC_CONTROLLER
 158 {
 159    SCI_CONTROLLER_T parent;
 160    U32 type;
 161
 162 } SCIC_CONTROLLER_T;
 163 </pre>
 164
 165 With the above structure orientation, a user would be allowed to perform
 166 method invocations in a manner similar to the following:
 167 <pre>
 168 SCIC_CONTROLLER_T scic_controller;
 169 scic_controller_initialize((SCIC_CONTROLLER_T*) &scic_controller);
 170
 171 // OR
 172
 173 sci_object_get_association(&scic_controller);
 174 </pre>
 175 @note The actual interface will not require type casting.
 176
 177 The following diagram graphically depicts the inheritance relationships
 178 between the various objects defined in the Storage Controller Interface.
 179 @image latex inheritance.eps "SCI Inheritance Hierarchy" width=16cm
 180
 181 @page sci_classes SCI Classes
 182
 183 This section depicts the common classes and utility functions across the
 184 entire set of SCI Components.  Descriptions about each of the specific
 185 objects will be found in the header file definition in the File Documentation
 186 section.
 187
 188 The following is a list of features that can be found in the SCI base classes:
 189 -# Logging utility methods, constants, and type definitions
 190 -# Memory Descriptor object methods common to the core and framework.
 191 -# Controller object methods common to SCI derived controller objects.
 192 -# Library object methods common to SCI derived library objects.
 193 -# Storage standard (e.g. SAS, SATA) defined constants, structures, etc.
 194 -# Standard types utilized by SCI sub-components.
 195 -# The ability to associate/link SCI objects together or to user objects.
 196
 197 SCI class methods can be overridden by sub-classes in the SCI Core,
 198 SCI Framework, etc.  SCI class methods that MUST NOT be invoked directly
 199 by operating system specific driver code shall be adorned with a
 200 <code>[protected]</code> keyword.  These <code>[protected]</code> API are still
 201 defined as part of the specification in order to demonstrate commonality across
 202 components as well as provide a common description of related methods.  If
 203 these methods are invoked directly by operating system specific code, the
 204 operation of the driver as a whole is not specified or supported.
 205
 206 The following UML diagram graphically depicts the SCI base classes and their
 207 relationships to one another.
 208 @image latex sci_base_classes.eps "SCI Classes" width=4cm
 209
 210 @page associations_section Associations
 211 The sci_object class provides functionality common to all SCI objects.
 212 An important feature provided by this base class is the means by which to
 213 associate one object to another.  An SCI object can be made to have an
 214 association to another SCI object.  Additionally, an SCI object can be
 215 made to have an association to a non-SCI based object.  For example, an SCI
 216 Framework library can have it's association set to an operating system
 217 specific adapter/device driver structre.
 218
 219 Simply put, the association that an object has is a handle (i.e. a void pointer)
 220 to a user structure.  This enables the user of the SCI object to
 221 easily determine it's own associated structure. This association is useful
 222 because the user is now enabled to easily determine their pertinent information
 223 inside of their SCI user callback methods.
 224
 225 Setting an association within an SCI object is generally optional.  The
 226 primary case in which an association is not optional is in the case of IO
 227 request objects.  These associations are necessary in order  to fill
 228 to fill in appropriate information for an IO request (i.e. CDB address, size,
 229 SGL information, etc.) in an efficient manner.
 230
 231 In the case of other objects, the user is free to not create associations.
 232 When the user chooses not to create an association, the user is responsible for
 233 being able to determine their data structures based on the SCI object handles.
 234 Additionally, the user may be forced to invoke additional functionality in
 235 situations where the SCI Framework is employed.  If the user does not
 236 establish proper associations between objects (i.e. SCIC Library to SCIF Library), then the framework is unable to automate interactions.  Users should
 237 strongly consider establishing associations between SCI Framework objects and
 238 OS Driver related structures.
 239
 240 Example Associations:
 241 - The user might set the scif_controller association to their adapter or
 242 controller object.
 243 - The user might set the scif_domain association to their SCSI bus object.
 244
 245 If SCIF is being utilized, then the framework will set the associations
 246 in the core.  In this situation, the user should only set the associations
 247 in the framework objects, unless otherwise directed.
 248 */
 249
 250 #endif // _SCI_OVERVIEW_H_
 251