begriffs open source - cmsis/blob - CMSIS/DoxyGen/General/src/introduction.txt

   1 /**************************************************************************************************/
   2 /**
   3 \mainpage Introduction
   4
   5 The <b>Cortex Microcontroller Software Interface Standard</b> (CMSIS) is a vendor-independent
   6 hardware abstraction layer for the Cortex&reg;-M processor series and defines generic tool
   7 interfaces.  The CMSIS enables consistent device support and
   8 simple software interfaces to the processor and the peripherals, simplifying software re-use,
   9 reducing the learning curve for microcontroller developers, and reducing the time to market for new devices.
  10
  11 The CMSIS is defined in close cooperation with various silicon and software vendors and
  12 provides a common approach to interface to peripherals, real-time operating systems,
  13 and middleware components. The CMSIS is intended to enable the combination of software components
  14 from multiple middleware vendors.
  15
  16 CMSIS Version 5 supports also the <a class="el" href="http://www.arm.com/products/processors/instruction-set-architectures/armv8-m-architecture.php" target="_blank">ARMv8-M architecture</a>
  17 including <a class="el" href="http://www.arm.com/products/processors/technologies/trustzone/index.php" target="_blank">TrustZone&reg; for ARMv8-M</a> hardware security extensions and the
  18 <a class="el" href="http://www.arm.com/products/processors/cortex-m/cortex-m23-processor.php" target="_blank">Cortex-M23</a> and <a class="el" href="http://www.arm.com/products/processors/cortex-m/cortex-m33-processor.php" target="_blank">Cortex-M33</a> processors.
  19
  20 \anchor CM_Components
  21 The CMSIS components are:
  22  - <a href="../../Core/html/index.html"><b>CMSIS-Core (Cortex-M)</b></a>: API for the Cortex-M processor core and peripherals.
  23    It provides a standardized interface for Cortex-M0, Cortex-M0+, Cortex-M3, Cortex-M4, Cortex-M7, Cortex-M23, Cortex-M33, SC000, and SC300.
  24    Also included are SIMD intrinsic functions for Cortex-M4, Cortex-M7, and Cortex-M33 SIMD instructions.
  25
  26  - <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
  27     and connects microcontroller peripherals with middleware that implements for example communication stacks, file systems, or graphic user interfaces.
  28
  29  - <a href="../../DSP/html/index.html"><b>CMSIS-DSP</b></a>: DSP Library Collection with over 60 Functions for various data types: fixed-point (fractional q7, q15, q31) and single precision floating-point (32-bit).
  30    The library is available for all Cortex-M cores. Implementations that are optimized for the SIMD instruction set are available for Cortex-M4, Cortex-M7, and Cortex-M33.
  31
  32
  33  - <a href="../../RTOS/html/index.html"><b>CMSIS-RTOS v1</b></a>: Common API for Real-Time Operating Systems along with reference implementation based on RTX.
  34     It provides a standardized programming interface that is portable to many RTOS and enables software components that can work across multiple RTOS systems.
  35
  36  - <a href="../../RTOS2/html/index.html"><b>CMSIS-RTOS v2</b></a>: extends CMSIS-RTOS v1 with support for ARMv8-M architecture, dynamic object creation,
  37     provisions for multi-core systems, and binary compatible interface across ABI compliant compilers.
  38
  39  - <a href="../../Pack/html/index.html"><b>CMSIS-Pack</b></a>: describes with an XML-based package description (PDSC) file the user and device relevant parts of a file collection (called a software pack) that includes source, header and library files, documentation,
  40     Flash programming algorithms, source code templates, and example projects. Development tools and web infrastructures use the PDSC file to extract device parameters,
  41     software components, and evaluation board configurations.
  42
  43  - <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
  44     debuggers or header files with peripheral register and interrupt definitions.
  45
  46  - <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 a separate package and is
  47     well suited for integration on evaluation boards. This component is provided as separate download.
  48
  49 \note Refer to \ref CM_Pack_Content for more information on the content of the Software Pack.
  50
  51 \image html CMSISv4_small.png "CMSIS Structure"
  52
  53 \section Motivation Motivation
  54
  55 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.
  56 CMSIS is not a huge software layer that introduces overhead and does not define standard peripherals. The silicon industry can
  57 therefore support the wide variations of Cortex-M processor-based devices with this common standard.
  58
  59 In detail the benefits of the CMSIS are:
  60
  61  - 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.
  62  - Consistent software interfaces improve the software portability and re-usability. Generic software libraries and interfaces provide consistent software framework.
  63  - Provides interfaces for debug connectivity, debug peripheral views, software delivery, and device support to reduce time-to-market for new microcontroller deployment.
  64  - Provides a compiler independent layer that allows using different compilers. CMSIS is supported by mainstream compilers.
  65  - Enhances program debugging with peripheral information for debuggers and ITM channels for printf-style output and RTOS kernel awareness.
  66  - CMSIS is delivered in CMSIS-Pack format which enables fast software delivery, simplifies updates, and enables consistent integration into development tools.
  67
  68
  69 \section CodingRules Coding Rules
  70
  71 The CMSIS uses the following essential coding rules and conventions:
  72  - Compliant with ANSI C and C++.
  73  - Uses ANSI C standard data types defined in \b <stdint.h>.
  74  - Variables and parameters have a complete data type.
  75  - Expressions for \em \#define constants are enclosed in parenthesis.
  76  - Conforms to MISRA 2012 (but does not claim MISRA compliance). MISRA rule violations are documented.
  77
  78 In addition, the CMSIS recommends the following conventions for identifiers:
  79  - \b CAPITAL names to identify Core Registers, Peripheral Registers, and CPU Instructions.
  80  - \b CamelCase names to identify function names and interrupt functions.
  81  - \b Namespace_ prefixes avoid clashes with user identifiers and provide functional groups (i.e. for peripherals, RTOS, or DSP Library).
  82
  83 The CMSIS is documented within the source files with:
  84  \li Comments that use the C or C++ style.
  85  \li Doxygen compliant <b>function comments</b> that provide:
  86     - brief function overview.
  87     - detailed description of the function.
  88     - detailed parameter explanation.
  89     - detailed information about return values.
  90
  91 Doxygen comment example:
  92 \verbatim
  93 /**
  94  * @brief  Enable Interrupt in NVIC Interrupt Controller
  95  * @param  IRQn  interrupt number that specifies the interrupt
  96  * @return none.
  97  * Enable the specified interrupt in the NVIC Interrupt Controller.
  98  * Other settings of the interrupt such as priority are not affected.
  99  */
 100 \endverbatim
 101
 102
 103 \section Validation Validation
 104
 105 The various components of CMSIS Version 5 are validated using mainstream compilers.  To get a diverse coverage,
 106 ARM uses the ARM Compiler v5 (based on EDG front-end), the ARM Compiler v6 (based on LLVM front-end), and the
 107 GCC Compiler in the various tests. For each component, the section \b "Validation" describes the scope of the
 108 various verifications.
 109
 110 CMSIS components are compatible with a range of C and C++ language standards. The CMSIS components comply with
 111 the <a href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ihi0036b/index.html">Application Binary
 112 Interface (ABI) for the ARM Architecture</a> (exception CMSIS-RTOS v1). This ensures C API interfaces that support
 113 inter-operation between various toolchains.
 114
 115 As CMSIS defines API interfaces and functions that scale to a wide range of processors and devices, the scope of
 116 the run-time test coverage is limited. However, several components are validated using dedicated test suites.
 117
 118 The CMSIS source code is checked for MISRA C:2012 conformance using PC-Lint. MISRA deviations are documented with
 119 reasonable effort, however ARM does not claim MISRA compliance as there is today for example no guideline enforcement
 120 plan. The CMSIS source code is not checked for MISRA C++:2008 conformance as there is a risk that it is incompatible
 121 with C language standards, specifically warnings that may be generated by the various C compilers.
 122
 123
 124 \section License License
 125
 126 The CMSIS is provided free of charge by ARM under Apache 2.0 license.
 127 View the <a href="LICENSE.txt">Apache 2.0 License</a>.
 128
 129
 130 \section CM_Pack_Content ARM::CMSIS Pack
 131
 132 The <b>ARM::CMSIS</b> Pack contains the following:
 133
 134 File/Directory    |Content
 135 :-----------------|:---------------------------------------------------------------------------------
 136 \b ARM.CMSIS.pdsc |Package description file in CMSIS-Pack format.
 137 \b LICENSE.txt    |CMSIS License Agreement (Apache 2.0)
 138 \b CMSIS          |\ref CM_Components "CMSIS components" (see below)
 139 \b Device         |CMSIS reference implementations of ARM Cortex-M processor based devices
 140
 141 CMSIS Directory
 142 ---------------
 143
 144 Directory                 |Content
 145 :-------------------------|:----------------------------------------------------------------------------------------------------------------------------------------
 146 \b Documentation          |This documentation
 147 \b Core                   |User code templates for Core related files, referenced in ARM.CMSIS.PDSC
 148 \b DAP                    |<a href="../../DAP/html/index.html"><b>CMSIS-DAP</b></a> Debug Access Port source code and reference implementations
 149 \b Driver                 |Header files for the <a href="../../Driver/html/index.html"><b>CMSIS-Driver</b></a> peripheral interface API
 150 \b DSP_Lib                |<a href="../../DSP/html/index.html"><b>CMSIS-DSP</b></a> software library source code
 151 \b Include                |Include files for <a href="../../Core/html/index.html"><b>CMSIS-Core (Cortex-M)</b></a> and <a href="../../DSP/html/index.html"><b>CMSIS-DSP</b></a>
 152 \b Lib                    |<a href="../../DSP/html/index.html"><b>CMSIS-DSP</b></a> generated libraries for ARMCC and GCC
 153 \b Pack                   |<a href="../../Pack/html/pack_Example.html"><b>CMSIS-Pack</b></a> example
 154 \b RTOS                   |<a href="../../RTOS/html/index.html"><b>CMSIS-RTOS Version 1</b></a> along with RTX reference implementation
 155 \b RTOS2                  |<a href="../../RTOS/html/index.html"><b>CMSIS-RTOS Version 2</b></a> along with RTX reference implementation
 156 \b SVD                    |<a href="../../SVD/html/index.html"><b>CMSIS-SVD</b></a> example
 157 \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)
 158
 159 <hr>
 160 */
 161
 162 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 163 /**
 164 \page cm_revisionHistory Revision History
 165
 166
 167 The following table shows the overall high-level history of the various CMSIS releases.
 168 In addition, each CMSIS component has its own release history:
 169
 170 - <a href="../../Core/html/core_revisionHistory.html"><b>CMSIS-Core (Cortex-M) Revision History</b></a>
 171 - <a href="../../DAP/html/dap_revisionHistory.html"><b>DAP Revision History</b></a>
 172 - <a href="../../Driver/html/driver_revisionHistory.html"><b>Driver Revision History</b></a>
 173 - <a href="../../DSP/html/ChangeLog_pg.html"><b>DSP Revision History (Change Log)</b></a>
 174 - <a href="../../Pack/html/pack_revisionHistory.html"><b>Pack Revision History</b></a>
 175 - <a href="../../RTOS/html/rtos_revisionHistory.html"><b>RTOS v1 Revision History</b></a>
 176 - <a href="../../RTOS2/html/rtos_revisionHistory.html"><b>RTOS v2 Revision History</b></a>
 177 - <a href="../../SVD/html/svd_revisionHistory.html"><b>SVD Revision History</b></a>
 178
 179
 180
 181 <table class="cmtable" summary="Revision History">
 182     <tr>
 183       <th>Version</th>
 184       <th>Description</th>
 185     </tr>
 186     <tr>
 187       <td>5.0.1</td>
 188       <td>
 189         - CMSIS-Core 5.0.1 added __PACKED_STRUCT macro and uVisor support
 190         - CMSIS-Driver 2.05 updated all typedefs related to status now being volatile.
 191         - CMSIS-DSP 1.5.1 added ARMv8M DSP libraries
 192         - CMSIS-RTOS 2.1.0 added support for critical and uncritical sections
 193         - CMSIS-PACK 1.4.8 add Pack Index File specification
 194         - CMSIS-SVD 1.3.3 (unchanged)
 195         - CMSIS-DAP 1.1.0 (unchanged)
 196       </td>
 197     <tr>
 198       <td>5.0.0</td>
 199       <td>
 200         Added support for: <a href="http://www.arm.com/products/processors/instruction-set-architectures/armv8-m-architecture.php" target="_blank"><b>ARMv8-M architecture</b></a> including TrustZone for ARMv8-M and Cortex-M23, Cortex-M33 processors
 201         - CMSIS-Core (Cortex-M) 5.0.0 added support for ARMv8-M and Cortex-M23, Cortex-M33 processors
 202         - CMSIS-Driver 2.04.0 (unchanged)
 203         - CMSIS-DSP 1.4.9 minor corrections and performance improvements
 204         - CMSIS-RTOS 2.0.0 new API with RTX 5.0.0 reference implementation and corrections in RTX 4.8.2
 205         - CMSIS-PACK 1.4.4 introducing CPDSC project description
 206         - CMSIS-SVD 1.3.3 several enhancements and rework of documentation
 207         - CMSIS-DAP 1.1.0 (unchanged)
 208       </td>
 209     </tr>
 210     <tr>
 211       <td>4.5.0</td>
 212       <td>
 213         Maintenance release that is fixing defects. See component's revision history for more details.
 214         See component's revision history for more details.
 215         - CMSIS-Core (Cortex-M) 4.30.0
 216         - CMSIS-DAP 1.1.0 (unchanged)
 217         - CMSIS-Driver 2.04.0
 218         - CMSIS-DSP 1.4.7
 219         - CMSIS-PACK 1.4.1
 220         - CMSIS-RTOS RTX 4.80.0
 221         - CMSIS-SVD 1.3.1
 222       </td>
 223     </tr>
 224     <tr>
 225       <td>4.4.0</td>
 226       <td>
 227         Feature release adding CMSIS-DAP (see extended End User Licence Agreement) and CMSIS-Driver for CAN.
 228         See component's revision history for more details.
 229         - CMSIS-Core (Cortex-M) 4.20.0
 230         - CMSIS-DAP 1.1.0
 231         - CMSIS-Driver 2.03.0
 232         - CMSIS-DSP 1.4.5  (unchanged)
 233         - CMSIS-RTOS RTX 4.79.0
 234         - CMSIS-PACK 1.4.0
 235         - CMSIS-SVD 1.3.0
 236       </td>
 237     </tr>
 238     <tr>
 239       <td>4.3.0</td>
 240       <td>
 241         Maintenance release adding SAI CMSIS-Driver and fixing defects. See component's revision history for more details.
 242         - CMSIS-Core (Cortex-M) 4.10.0
 243         - CMSIS-Driver 2.02.0
 244         - CMSIS-DSP 1.4.5
 245         - CMSIS-RTOS RTX 4.78.0
 246         - CMSIS-PACK 1.3.3
 247         - CMSIS-SVD (unchanged)
 248       </td>
 249     </tr>
 250     <tr>
 251       <td>4.2</td>
 252       <td>Introducing processor support for Cortex-M7.
 253       </td>
 254     </tr>
 255     <tr>
 256       <td>4.1</td>
 257       <td>Enhancements in CMSIS-Pack and CMSIS-Driver.\n
 258       Added: PackChk validation utility\n
 259       Removed support for GNU: Sourcery G++ Lite Edition for ARM</td>
 260     </tr>
 261     <tr>
 262       <td>4.0</td>
 263       <td>First release in CMSIS-Pack format.\n Added specifications for CMSIS-Pack, CMSIS-Driver</td>
 264     </tr>
 265     <tr>
 266       <td>3.30</td>
 267       <td>Maintenance release with enhancements in each component</td>
 268     </tr>
 269     <tr>
 270       <td>3.20</td>
 271       <td>Maintenance release with enhancements in each component</td>
 272     </tr>
 273     <tr>
 274       <td>3.01</td>
 275       <td>Added support for Cortex-M0+ processors</td>
 276     </tr>
 277     <tr>
 278       <td>3.00</td>
 279       <td>Added support for SC000 and SC300 processors\n
 280       Added support for GNU GCC Compiler\n
 281       Added CMSIS-RTOS API</td>
 282     </tr>
 283     <tr>
 284       <td>2.10</td>
 285       <td>Added CMSIS-DSP Library</td>
 286     </tr>
 287     <tr>
 288       <td>2.0</td>
 289       <td>Added support for Cortex-M4 processor</td>
 290     </tr>
 291     <tr>
 292       <td>1.30</td>
 293       <td>Reworked CMSIS startup concept</td>
 294     </tr>
 295     <tr>
 296       <td>1.01</td>
 297       <td>Added support for Cortex-M0 processor</td>
 298     </tr>
 299     <tr>
 300       <td>1.00</td>
 301       <td>Initial release of CMSIS-Core (Cortex-M) for Cortex-M3 processor</td>
 302     </tr>
 303 </table>
 304
 305 */