Adding Device folder containing CMSIS Core Device Vendor files templates

[cmsis] / CMSIS / DoxyGen / General / src / introduction.txt

/**************************************************************************************************/\r
/** \r
\mainpage Introduction\r
\r
The <b>Cortex Microcontroller Software Interface Standard</b> (CMSIS) is a vendor-independent \r
hardware abstraction layer for the Cortex&reg;-M processor series and defines generic tool\r
interfaces.  The CMSIS enables consistent device support and \r
simple software interfaces to the processor and the peripherals, simplifying software re-use, \r
reducing the learning curve for microcontroller developers, and reducing the time to market for new devices. \r
    \r
The CMSIS is defined in close cooperation with various silicon and software vendors and \r
provides a common approach to interface to peripherals, real-time operating systems, \r
and middleware components. The CMSIS is intended to enable the combination of software components \r
from multiple middleware vendors. \r
\r
CMSIS Version 5 supports also the <a href="http://www.arm.com/products/processors/instruction-set-architectures/armv8-m-architecture.php" target="_blank"><b>ARMv8-M architecture</b></a> \r
including ARM TrustZone&reg; hardware security extensions.\r
\r
\anchor CM_Components\r
The CMSIS components are:\r
 - <a href="../../Core/html/index.html"><b>CMSIS-CORE</b></a>: API for the Cortex-M processor core and peripherals. It provides at standardized interface for Cortex-M0, Cortex-M3, Cortex-M4, Cortex-M7, SC000, and SC300. \r
   Included are also SIMD intrinsic functions for Cortex-M4 and Cortex-M7 SIMD instructions.\r
\r
 - <a href="../../Driver/html/index.html"><b>CMSIS-Driver</b></a>: defines generic peripheral driver interfaces for middleware making it reusable across supported devices. The API is RTOS independent\r
    and connects microcontroller peripherals with middleware that implements for example communication stacks, file systems, or graphic user interfaces.\r
\r
 - <a href="../../DSP/html/index.html"><b>CMSIS-DSP</b></a>: DSP Library Collection with over 60 Functions for various data types: fix-point (fractional q7, q15, q31) and single precision floating-point (32-bit).\r
   The library is available for all Cortex-M cores. The Cortex-M4 and Cortex-M7 implementations are optimized for the SIMD instruction set.\r
\r
 - <a href="../../RTOS/html/index.html"><b>CMSIS-RTOS API</b></a>: Common API for Real-Time operating systems. It provides a standardized programming interface that is portable to many RTOS and enables therefore \r
    software templates, middleware, libraries, and other components that can work across supported the RTOS systems.\r
\r
 - <a href="../../Pack/html/index.html"><b>CMSIS-Pack</b></a>: describes with a XML based package description (PDSC) file the user and device relevant parts of a file collection (called software pack) that includes source, header, and library files, documentation, \r
    Flash programming algorithms, source code templates, and example projects. Development tools and web infrastructures use the PDSC file to extract device parameters, \r
    software components, and evaluation board configurations.\r
\r
 - <a href="../../SVD/html/index.html"><b>CMSIS-SVD</b></a>: System View Description for Peripherals. Describes the peripherals of a device in an XML file and can be used to create peripheral awareness in \r
    debuggers or header files with peripheral register and interrupt definitions.\r
\r
 - <a href="../../DAP/html/index.html"><b>CMSIS-DAP</b></a>: Debug Access Port. Standardized firmware for a Debug Unit that connects to the CoreSight Debug Access Port. CMSIS-DAP is distributed as separate package and\r
    well suited for integration on evaluation boards. This component is provided as separate download.\r
\r
\note Refer to \ref CM_Pack_Content for more information on the content of the Software Pack.\r
\r
\image html CMSISv4_small.png "CMSIS Structure"\r
        \r
\section Motivation Motivation\r
\r
CMSIS has been created to help the industry in standardization. It enables consistent software layers and device support across a wide range of development tools and microcontrollers.\r
CMSIS is not a huge software layer that introduces overhead and does not define standard peripherals. The silicon industry can\r
therefore support the wide variations of Cortex-M processor-based devices with this common standard.\r
\r
In detail the benefits of the CMSIS are:\r
\r
 - Overall CMSIS reduces the learning curve, development costs, and time-to-market. Developers can write software quicker through a variety of easy-to-use, standardized software interfaces.\r
 - Consistent software interfaces improve the software portability and re-usability. Generic software libraries and interfaces provide consistent software framework.\r
 - Provides interfaces for debug connectivity, debug peripheral views, software delivery, and device support to reduce time-to-market for new microcontroller deployment.\r
 - Provides a compiler independent layer that allows using different compilers. CMSIS is supported by all mainstream compilers (ARMCC, IAR, and GNU).\r
 - Enhances program debugging with peripheral information for debuggers and ITM channels for printf-style output and RTOS kernel awareness. \r
 - CMSIS is delivered in CMSIS-Pack format which enables fast software delivery, simplifies updates, and enables consistent integration into development tools. \r
\r
\r
\section CodingRules Coding Rules\r
\r
The CMSIS uses the following essential coding rules and conventions:\r
 - Compliant with ANSI C and C++.\r
 - Uses ANSI C standard data types defined in \b <stdint.h>.\r
 - Variables and parameters have a complete data type.\r
 - Expressions for \em \#define constants are enclosed in parenthesis.\r
 - Conforms to MISRA 2004. MISRA rule violations are documented.\r
          \r
In addition, the CMSIS recommends the following conventions for identifiers:\r
 - \b CAPITAL names to identify Core Registers, Peripheral Registers, and CPU Instructions.\r
 - \b CamelCase names to identify function names and interrupt functions.\r
 - \b Namespace_ prefixes avoid clashes with user identifiers and provide functional groups (i.e. for peripherals, RTOS, or DSP Library).\r
\r
The CMSIS is documented within the source files with:\r
 \li Comments that use the C or C++ style. \r
 \li Doxygen compliant <b>function comments</b> that provide:\r
    - brief function overview.\r
    - detailed description of the function.\r
    - detailed parameter explanation.\r
    - detailed information about return values.\r
\r
Doxygen comment example:\r
\verbatim\r
/** \r
 * @brief  Enable Interrupt in NVIC Interrupt Controller\r
 * @param  IRQn  interrupt number that specifies the interrupt\r
 * @return none.\r
 * Enable the specified interrupt in the NVIC Interrupt Controller.\r
 * Other settings of the interrupt such as priority are not affected.\r
 */\r
\endverbatim\r
\r
\r
\section License Licence\r
\r
The CMSIS is provided free of charge by ARM under Apache 2.0 license. \r
View the <a href="LICENSE">Apache 2.0 License</a>.\r
\r
\r
\section CM_Pack_Content ARM::CMSIS Pack\r
\r
The <b>ARM::CMSIS</b> Pack contains the following:\r
|File/Directory    |Content                                                                           |\r
|:-----------------|:---------------------------------------------------------------------------------|\r
|\b ARM.CMSIS.pdsc |Package description file                                                          |\r
|\b CMSIS          |\ref CM_Components "CMSIS components" (see below)                                 |\r
|\b CMSIS_RTX      |<a class=el href="http://www.keil.com/pack/doc/cmsis_rtx/index.html" target="_blank">Keil RTX</a> implementation of <a href="../../RTOS/html/index.html"><b>CMSIS-RTOS</b></a>|\r
|\b Device         |ARM reference implementations of Cortex-M devices                                 |\r
\r
CMSIS Directory\r
---------------\r
\r
The directory <b>CMSIS</b> contains the  "CMSIS End User License Agreement" as PDF and RTF, a README text file, the\r
index.html file for this documentation, and the following sub-directories:\r
\r
|Directory                 |Content                                                                                                                                  |\r
|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------------------|\r
|\b Documentation          |This documentation                                                                                                                       |\r
|\b DAP                    |<a href="../../DAP/html/index.html"><b>CMSIS-DAP</b></a> Debug Access Port source code and reference implementations                     |\r
|\b Driver                 |Header files for the <a href="../../Driver/html/index.html"><b>CMSIS-Driver</b></a> peripheral interface API                             |\r
|\b DSP_Lib                |<a href="../../DSP/html/index.html"><b>CMSIS-DSP</b></a> software library source code                                                    |\r
|\b Include                |Include files for <a href="../../Core/html/index.html"><b>CMSIS-CORE</b></a> and <a href="../../DSP/html/index.html"><b>CMSIS-DSP</b></a>|\r
|\b Lib                    |<a href="../../DSP/html/index.html"><b>CMSIS-DSP</b></a> generated libraries for ARMCC and GCC                                           |\r
|\b Pack                   |<a href="../../Pack/html/_pack__example.html"><b>CMSIS-Pack</b></a> example                                                              |\r
|\b RTOS                   |<a href="../../RTOS/html/index.html"><b>CMSIS-RTOS</b></a> API header file                                                               |\r
|\b SVD                    |<a href="../../SVD/html/index.html"><b>CMSIS-SVD</b></a> example                                                                         |\r
|\b UserCodeTemplates\\ARM |ITM_Retarget.c, CMSIS <a href="../../Core/html/group___i_t_m___debug__gr.html"><b>retarget output</b></a> to ITM Channel 0 template file |\r
|\b Utilities              |PACK.xsd (<a href="../../Pack/html/_pack__example.html"><b>CMSIS-Pack</b></a> schema file), PackChk.exe (checking tool for software packs), \n CMSIS-SVD.xsd (<a href="../../SVD/html/index.html"><b>CMSIS-SVD</b></a> schema file), SVDConv.exe (conversion tool for SVD files)|\r
\r
<hr>\r
*/\r
\r
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/\r
/**\r
\page CM_revisionHistory Revision History \r
\r
\r
The following table shows the overall high-level history of the various CMSIS releases.\r
In addition, each CMSIS component has its own release history:\r
\r
- <a href="../../Core/html/core_revision_history.html"><b>CORE Revision History</b></a>\r
- <a href="../../DAP/html/rev_hist_dap.html"><b>DAP Revision History</b></a>\r
- <a href="../../Driver/html/driver_revision_history.html"><b>Driver Revision History</b></a>\r
- <a href="../../DSP/html/_change_log_pg.html"><b>DSP Revision History (Change Log)</b></a>\r
- <a href="../../Pack/html/pack_revision_history.html"><b>Pack Revision History</b></a>\r
- <a href="../../RTOS/html/rtos_revision_history.html"><b>RTOS API Revision History</b></a>\r
- <a href="../../RTX/html/rtx_revision_history.html"><b>RTX Revision History</b></a>\r
- <a href="../../SVD/html/svd_revision_history.html"><b>SVD Revision History</b></a>\r
\r
\r
\r
<table class="cmtable" summary="Revision History">\r
    <tr>\r
      <th>Version</th>\r
      <th>Description</th>\r
    </tr>\r
    <tr>\r
      <td>5.0.0</td>\r
      <td>\r
        Added <a href="http://www.arm.com/products/processors/instruction-set-architectures/armv8-m-architecture.php" target="_blank"><b>ARMv8-M architecture</b></a> support.\r
        - CMSIS-CORE 5.0.0\r
      </td>\r
    </tr>\r
    <tr>\r
      <td>4.5.0</td>\r
      <td>\r
        Maintenance release that is fixing defects. See component's revision history for more details.\r
        See component's revision history for more details.\r
        - CMSIS-CORE 4.30.0\r
        - CMSIS-DAP 1.1.0 (unchanged)\r
        - CMSIS-Driver 2.04.0\r
        - CMSIS-DSP 1.4.7\r
        - CMSIS-PACK 1.4.1\r
        - CMSIS-RTOS RTX 4.80.0\r
        - CMSIS-SVD 1.3.1 \r
      </td>\r
    </tr>\r
    <tr>\r
      <td>4.4.0</td>\r
      <td>\r
        Feature release adding CMSIS-DAP (see extended End User Licence Agreement) and CMSIS-Driver for CAN.\r
        See component's revision history for more details.\r
        - CMSIS-CORE 4.20.0\r
        - CMSIS-DAP 1.1.0\r
        - CMSIS-Driver 2.03.0\r
        - CMSIS-DSP 1.4.5  (unchanged)\r
        - CMSIS-RTOS RTX 4.79.0\r
        - CMSIS-PACK 1.4.0\r
        - CMSIS-SVD 1.3.0\r
      </td>\r
    </tr>\r
    <tr>\r
      <td>4.3.0</td>\r
      <td>\r
        Maintenance release adding SAI CMSIS-Driver and fixing defects. See component's revision history for more details.\r
        - CMSIS-CORE 4.10.0\r
        - CMSIS-Driver 2.02.0\r
        - CMSIS-DSP 1.4.5\r
        - CMSIS-RTOS RTX 4.78.0\r
        - CMSIS-PACK 1.3.3\r
        - CMSIS-SVD (unchanged)\r
      </td>\r
    </tr>\r
    <tr>\r
      <td>4.2</td>\r
      <td>Introducing processor support for Cortex-M7.\r
      </td>\r
    </tr>\r
    <tr>\r
      <td>4.1</td>\r
      <td>Enhancements in CMSIS-Pack and CMSIS-Driver.\n\r
      Added: PackChk validation utility\n\r
      Removed support for GNU: Sourcery G++ Lite Edition for ARM</td>\r
    </tr>\r
    <tr>\r
      <td>4.0</td>\r
      <td>First release in CMSIS-Pack format.\n Added specifications for CMSIS-Pack, CMSIS-Driver</td>\r
    </tr>\r
    <tr>\r
      <td>3.30</td>\r
      <td>Maintenance release with enhancements in each component</td>\r
    </tr>\r
    <tr>\r
      <td>3.20</td>\r
      <td>Maintenance release with enhancements in each component</td>\r
    </tr>\r
    <tr>\r
      <td>3.01</td>\r
      <td>Added support for Cortex-M0+ processors</td>\r
    </tr>\r
    <tr>\r
      <td>3.00</td>\r
      <td>Added support for SC000 and SC300 processors\n\r
      Added support for GNU GCC Compiler\n\r
      Added CMSIS-RTOS API</td>\r
    </tr>\r
    <tr>\r
      <td>2.10</td>\r
      <td>Added CMSIS-DSP Library</td>\r
    </tr>\r
    <tr>\r
      <td>2.0</td>\r
      <td>Added support for Cortex-M4 processor</td>\r
    </tr>\r
    <tr>\r
      <td>1.30</td>\r
      <td>Reworked CMSIS startup concept</td>\r
    </tr>\r
    <tr>\r
      <td>1.01</td>\r
      <td>Added support for Cortex-M0 processor</td>\r
    </tr>\r
    <tr>\r
      <td>1.00</td>\r
      <td>Initial release of CMSIS-CORE for Cortex-M3 processor</td>\r
    </tr>\r
</table>\r
\r
*/\r