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 * $FreeBSD$ 55 */ 56 #ifndef _SCI_OVERVIEW_H_ 57 #define _SCI_OVERVIEW_H_ 58 59 /** 60 @mainpage The Intel Storage Controller Interface (SCI) 61 62 SCI provides a common interface across intel storage controller hardware. 63 This includes abstracting differences between Physical PCI functions and 64 Virtual PCI functions. The SCI is comprised of four primary components: 65 -# SCI Base classes 66 -# SCI Core 67 -# SCI Framework 68 69 It is important to recognize that no component, object, or functionality in 70 SCI directly allocates memory from the operating system. It is expected that 71 the SCI User (OS specific driver code) allocates and frees all memory from 72 and to the operating system itself. 73 74 The C language is utilized to implement SCI. Although C is not an object 75 oriented language the SCI driver components, methods, and structures are 76 modeled and organized following object oriented principles. 77 78 The Unified Modeling Language is utilized to present graphical depictions 79 of the SCI classes and their relationships. 80 81 The following figure denotes the meanings of the colors utilized in UML 82 diagrams throughout this document. 83 @image latex object_color_key.eps "Object Color Legend" width=8cm 84 85 The following figure denotes the meanings for input and output arrows that 86 are utilized to define parameters for methods defined in this specification. 87 @image latex arrow_image.eps "Method Parameter Symbol Definition" 88 89 @page abbreviations_section Abbreviations 90 91 - ATA: Advanced Technology Attachment 92 - IAF: Identify Address Frame 93 - SAS: Serial Attached SCSI 94 - SAT: SCSI to ATA Translation 95 - SATA: Serial ATA 96 - SCI: Storage Controller Interface 97 - SCIC: SCI Core 98 - SCIF: SCI Framework 99 - SCU: Storage Controller Unit 100 - SDS: SCU Driver Standard (i.e. non-virtualization) 101 - SDV: SCU Driver Virtualized 102 - SDVP: SDV Physical (PCI function) 103 - SDVV: SDV Virtual (PCI function) 104 - SGE: Scatter-Gather Element 105 - SGL: Scatter-Gather List 106 - SGPIO: Serial General Purpose Input/Output 107 - SSC: Spread Spectrum Clocking 108 109 @page definitions_section Definitions 110 111 - <b>construct</b> - The term "construct" is utilized throughout the 112 interface to indicate when an object is being created. Typically construct 113 methods perform pure memory initialization. No "construct" method ever 114 performs memory allocation. It is incumbent upon the SCI user to provide 115 the necessary memory. 116 - <b>initialize</b> - The term "initialize" is utilized throughout the 117 interface to indicate when an object is performing actions on other objects 118 or on physical resources in an attempt to allow these resources to become 119 operational. 120 - <b>protected</b> - The term "protected" is utilized to denote a method 121 defined in this standard that MUST NOT be invoked directly by operating 122 system specific driver code. 123 - <b>SCI Component</b> - An SCI component is one of: SCI base classes, Core, 124 or Framework. 125 - <b>SCI User</b> - The user callbacks for each SCI Component represent the 126 dependencies that the SCI component implementation has upon the operating 127 system/environment specific portion of the driver. It is essentially a 128 set of functions or macro definitions that are specific to a particular 129 operating system. 130 - <b>THIN</b> - A term utilized to describe an SCI Component implementation 131 that is built to conserve memory. 132 133 @page inheritance SCI Inheritance Hierarchy 134 135 This section describes the inheritance (i.e. "is-a") relationships between 136 the various objects in SCI. Due to various operating environment requirements 137 the programming language employed for the SCI driver is C. As a result, one 138 might be curious how inheritance shall be applied in such an environment. 139 The SCI driver source shall maintain generalization relationships by ensuring 140 that child object structures shall contain an instance of their parent's 141 structure as the very first member of their structure. As a result, parent 142 object methods can be invoked with a child structure parameter. This works 143 since casting of the child structure to the parent structure inside the parent 144 method will yield correct access to the parent structure fields. 145 146 Consider the following example: 147 <pre> 148 typedef struct SCI_OBJECT 149 { 150 U32 object_type; 151 }; 152 153 typedef struct SCI_CONTROLLER 154 { 155 U32 state; 156 157 } SCI_CONTROLLER_T; 158 159 typedef struct SCIC_CONTROLLER 160 { 161 SCI_CONTROLLER_T parent; 162 U32 type; 163 164 } SCIC_CONTROLLER_T; 165 </pre> 166 167 With the above structure orientation, a user would be allowed to perform 168 method invocations in a manner similar to the following: 169 <pre> 170 SCIC_CONTROLLER_T scic_controller; 171 scic_controller_initialize((SCIC_CONTROLLER_T*) &scic_controller); 172 173 // OR 174 175 sci_object_get_association(&scic_controller); 176 </pre> 177 @note The actual interface will not require type casting. 178 179 The following diagram graphically depicts the inheritance relationships 180 between the various objects defined in the Storage Controller Interface. 181 @image latex inheritance.eps "SCI Inheritance Hierarchy" width=16cm 182 183 @page sci_classes SCI Classes 184 185 This section depicts the common classes and utility functions across the 186 entire set of SCI Components. Descriptions about each of the specific 187 objects will be found in the header file definition in the File Documentation 188 section. 189 190 The following is a list of features that can be found in the SCI base classes: 191 -# Logging utility methods, constants, and type definitions 192 -# Memory Descriptor object methods common to the core and framework. 193 -# Controller object methods common to SCI derived controller objects. 194 -# Library object methods common to SCI derived library objects. 195 -# Storage standard (e.g. SAS, SATA) defined constants, structures, etc. 196 -# Standard types utilized by SCI sub-components. 197 -# The ability to associate/link SCI objects together or to user objects. 198 199 SCI class methods can be overridden by sub-classes in the SCI Core, 200 SCI Framework, etc. SCI class methods that MUST NOT be invoked directly 201 by operating system specific driver code shall be adorned with a 202 <code>[protected]</code> keyword. These <code>[protected]</code> API are still 203 defined as part of the specification in order to demonstrate commonality across 204 components as well as provide a common description of related methods. If 205 these methods are invoked directly by operating system specific code, the 206 operation of the driver as a whole is not specified or supported. 207 208 The following UML diagram graphically depicts the SCI base classes and their 209 relationships to one another. 210 @image latex sci_base_classes.eps "SCI Classes" width=4cm 211 212 @page associations_section Associations 213 The sci_object class provides functionality common to all SCI objects. 214 An important feature provided by this base class is the means by which to 215 associate one object to another. An SCI object can be made to have an 216 association to another SCI object. Additionally, an SCI object can be 217 made to have an association to a non-SCI based object. For example, an SCI 218 Framework library can have it's association set to an operating system 219 specific adapter/device driver structure. 220 221 Simply put, the association that an object has is a handle (i.e. a void pointer) 222 to a user structure. This enables the user of the SCI object to 223 easily determine it's own associated structure. This association is useful 224 because the user is now enabled to easily determine their pertinent information 225 inside of their SCI user callback methods. 226 227 Setting an association within an SCI object is generally optional. The 228 primary case in which an association is not optional is in the case of IO 229 request objects. These associations are necessary in order to fill 230 to fill in appropriate information for an IO request (i.e. CDB address, size, 231 SGL information, etc.) in an efficient manner. 232 233 In the case of other objects, the user is free to not create associations. 234 When the user chooses not to create an association, the user is responsible for 235 being able to determine their data structures based on the SCI object handles. 236 Additionally, the user may be forced to invoke additional functionality in 237 situations where the SCI Framework is employed. If the user does not 238 establish proper associations between objects (i.e. SCIC Library to SCIF Library), then the framework is unable to automate interactions. Users should 239 strongly consider establishing associations between SCI Framework objects and 240 OS Driver related structures. 241 242 Example Associations: 243 - The user might set the scif_controller association to their adapter or 244 controller object. 245 - The user might set the scif_domain association to their SCSI bus object. 246 247 If SCIF is being utilized, then the framework will set the associations 248 in the core. In this situation, the user should only set the associations 249 in the framework objects, unless otherwise directed. 250 */ 251 252 #endif // _SCI_OVERVIEW_H_ 253 254