/*- * SPDX-License-Identifier: BSD-2-Clause OR GPL-2.0 * * This file is provided under a dual BSD/GPLv2 license. When using or * redistributing this file, you may do so under either license. * * GPL LICENSE SUMMARY * * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. * * This program is free software; you can redistribute it and/or modify * it under the terms of version 2 of the GNU General Public License as * published by the Free Software Foundation. * * This program is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. * The full GNU General Public License is included in this distribution * in the file called LICENSE.GPL. * * BSD LICENSE * * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * * Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in * the documentation and/or other materials provided with the * distribution. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * * $FreeBSD$ */ #ifndef _SCI_OVERVIEW_H_ #define _SCI_OVERVIEW_H_ /** @mainpage The Intel Storage Controller Interface (SCI) SCI provides a common interface across intel storage controller hardware. This includes abstracting differences between Physical PCI functions and Virtual PCI functions. The SCI is comprised of four primary components: -# SCI Base classes -# SCI Core -# SCI Framework It is important to recognize that no component, object, or functionality in SCI directly allocates memory from the operating system. It is expected that the SCI User (OS specific driver code) allocates and frees all memory from and to the operating system itself. The C language is utilized to implement SCI. Although C is not an object oriented language the SCI driver components, methods, and structures are modeled and organized following object oriented principles. The Unified Modeling Language is utilized to present graphical depictions of the SCI classes and their relationships. The following figure denotes the meanings of the colors utilized in UML diagrams throughout this document. @image latex object_color_key.eps "Object Color Legend" width=8cm The following figure denotes the meanings for input and output arrows that are utilized to define parameters for methods defined in this specification. @image latex arrow_image.eps "Method Parameter Symbol Definition" @page abbreviations_section Abbreviations - ATA: Advanced Technology Attachment - IAF: Identify Address Frame - SAS: Serial Attached SCSI - SAT: SCSI to ATA Translation - SATA: Serial ATA - SCI: Storage Controller Interface - SCIC: SCI Core - SCIF: SCI Framework - SCU: Storage Controller Unit - SDS: SCU Driver Standard (i.e. non-virtualization) - SDV: SCU Driver Virtualized - SDVP: SDV Physical (PCI function) - SDVV: SDV Virtual (PCI function) - SGE: Scatter-Gather Element - SGL: Scatter-Gather List - SGPIO: Serial General Purpose Input/Output - SSC: Spread Spectrum Clocking @page definitions_section Definitions - construct - The term "construct" is utilized throughout the interface to indicate when an object is being created. Typically construct methods perform pure memory initialization. No "construct" method ever performs memory allocation. It is incumbent upon the SCI user to provide the necessary memory. - initialize - The term "initialize" is utilized throughout the interface to indicate when an object is performing actions on other objects or on physical resources in an attempt to allow these resources to become operational. - protected - The term "protected" is utilized to denote a method defined in this standard that MUST NOT be invoked directly by operating system specific driver code. - SCI Component - An SCI component is one of: SCI base classes, Core, or Framework. - SCI User - The user callbacks for each SCI Component represent the dependencies that the SCI component implementation has upon the operating system/environment specific portion of the driver. It is essentially a set of functions or macro definitions that are specific to a particular operating system. - THIN - A term utilized to describe an SCI Component implementation that is built to conserve memory. @page inheritance SCI Inheritance Hierarchy This section describes the inheritance (i.e. "is-a") relationships between the various objects in SCI. Due to various operating environment requirements the programming language employed for the SCI driver is C. As a result, one might be curious how inheritance shall be applied in such an environment. The SCI driver source shall maintain generalization relationships by ensuring that child object structures shall contain an instance of their parent's structure as the very first member of their structure. As a result, parent object methods can be invoked with a child structure parameter. This works since casting of the child structure to the parent structure inside the parent method will yield correct access to the parent structure fields. Consider the following example: 
typedef struct SCI_OBJECT
{
   U32 object_type;
};

typedef struct SCI_CONTROLLER
{
   U32 state;

} SCI_CONTROLLER_T;

typedef struct SCIC_CONTROLLER
{
   SCI_CONTROLLER_T parent;
   U32 type;

} SCIC_CONTROLLER_T;
With the above structure orientation, a user would be allowed to perform method invocations in a manner similar to the following: 
SCIC_CONTROLLER_T scic_controller;
scic_controller_initialize((SCIC_CONTROLLER_T*) &scic_controller);

// OR

sci_object_get_association(&scic_controller);
@note The actual interface will not require type casting. The following diagram graphically depicts the inheritance relationships between the various objects defined in the Storage Controller Interface. @image latex inheritance.eps "SCI Inheritance Hierarchy" width=16cm @page sci_classes SCI Classes This section depicts the common classes and utility functions across the entire set of SCI Components. Descriptions about each of the specific objects will be found in the header file definition in the File Documentation section. The following is a list of features that can be found in the SCI base classes: -# Logging utility methods, constants, and type definitions -# Memory Descriptor object methods common to the core and framework. -# Controller object methods common to SCI derived controller objects. -# Library object methods common to SCI derived library objects. -# Storage standard (e.g. SAS, SATA) defined constants, structures, etc. -# Standard types utilized by SCI sub-components. -# The ability to associate/link SCI objects together or to user objects. SCI class methods can be overridden by sub-classes in the SCI Core, SCI Framework, etc. SCI class methods that MUST NOT be invoked directly by operating system specific driver code shall be adorned with a [protected] keyword. These [protected] API are still defined as part of the specification in order to demonstrate commonality across components as well as provide a common description of related methods. If these methods are invoked directly by operating system specific code, the operation of the driver as a whole is not specified or supported. The following UML diagram graphically depicts the SCI base classes and their relationships to one another. @image latex sci_base_classes.eps "SCI Classes" width=4cm @page associations_section Associations The sci_object class provides functionality common to all SCI objects. An important feature provided by this base class is the means by which to associate one object to another. An SCI object can be made to have an association to another SCI object. Additionally, an SCI object can be made to have an association to a non-SCI based object. For example, an SCI Framework library can have it's association set to an operating system specific adapter/device driver structure. Simply put, the association that an object has is a handle (i.e. a void pointer) to a user structure. This enables the user of the SCI object to easily determine it's own associated structure. This association is useful because the user is now enabled to easily determine their pertinent information inside of their SCI user callback methods. Setting an association within an SCI object is generally optional. The primary case in which an association is not optional is in the case of IO request objects. These associations are necessary in order to fill to fill in appropriate information for an IO request (i.e. CDB address, size, SGL information, etc.) in an efficient manner. In the case of other objects, the user is free to not create associations. When the user chooses not to create an association, the user is responsible for being able to determine their data structures based on the SCI object handles. Additionally, the user may be forced to invoke additional functionality in situations where the SCI Framework is employed. If the user does not establish proper associations between objects (i.e. SCIC Library to SCIF Library), then the framework is unable to automate interactions. Users should strongly consider establishing associations between SCI Framework objects and OS Driver related structures. Example Associations: - The user might set the scif_controller association to their adapter or controller object. - The user might set the scif_domain association to their SCSI bus object. If SCIF is being utilized, then the framework will set the associations in the core. In this situation, the user should only set the associations in the framework objects, unless otherwise directed. */ #endif // _SCI_OVERVIEW_H_