1 /*- 2 * SPDX-License-Identifier: BSD-2-Clause OR GPL-2.0 3 * 4 * This file is provided under a dual BSD/GPLv2 license. When using or 5 * redistributing this file, you may do so under either license. 6 * 7 * GPL LICENSE SUMMARY 8 * 9 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 10 * 11 * This program is free software; you can redistribute it and/or modify 12 * it under the terms of version 2 of the GNU General Public License as 13 * published by the Free Software Foundation. 14 * 15 * This program is distributed in the hope that it will be useful, but 16 * WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 18 * General Public License for more details. 19 * 20 * You should have received a copy of the GNU General Public License 21 * along with this program; if not, write to the Free Software 22 * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. 23 * The full GNU General Public License is included in this distribution 24 * in the file called LICENSE.GPL. 25 * 26 * BSD LICENSE 27 * 28 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 29 * All rights reserved. 30 * 31 * Redistribution and use in source and binary forms, with or without 32 * modification, are permitted provided that the following conditions 33 * are met: 34 * 35 * * Redistributions of source code must retain the above copyright 36 * notice, this list of conditions and the following disclaimer. 37 * * Redistributions in binary form must reproduce the above copyright 38 * notice, this list of conditions and the following disclaimer in 39 * the documentation and/or other materials provided with the 40 * distribution. 41 * 42 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 43 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 44 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 45 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 46 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 47 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 48 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 49 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 50 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 51 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 52 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 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 structure. 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 252