Release preparation: Aligned version information and updated change histories.

[cmsis] / CMSIS / DoxyGen / Core_A / src / Template.txt

/**
\page templates_pg CMSIS-Core Device Templates

\details

ARM supplies CMSIS-Core device template files for the all supported Cortex-A processors and various compiler vendors.
Refer to the list of \ref tested_tools_sec for compliance.

These CMSIS-Core device template files include the following:
 - Register names of the Core Peripherals and names of the Core Exception Vectors.
 - Functions to access core peripherals, cache, MMU and special CPU instructions 
 - Generic startup code and system configuration code.

The detailed file structure of the CMSIS-Core device templates is shown in the following picture.

<!-- \image html "CMSIS_CORE_Files.png" "CMSIS-Core File Structure" -->

\section CMSIS_Processor_files CMSIS-Core Processor Files 

The CMSIS-Core processor files provided by ARM are in the directory .\\CMSIS\\Core_A\\Include. These header files define all processor specific attributes do not need any modifications.
The <b>core_&lt;cpu&gt;.h</b> defines the core peripherals and provides helper functions that access the core registers. One file is available for each supported Cortex-A processor:

Header File      | Processor
:----------------|:------------------------------
core_ca.h        | generics for all supportet Cortex-A processors

\section device_examples Device Examples

The CMSIS Software Pack defines several devices that are based on the various processors. The device related CMSIS-Core files are in the directory .\\Device\\ARM
and include CMSIS-Core processor file explained before. The following sample devices are defined in the CMSIS-Pack description file <b>ARM.CMSIS.pdsc</b>:

Family             | Device            | Description
:------------------|:------------------|:---------------------------------
ARM Cortex-A5      | ARMCA5            | Cortex-A5 based device
ARM Cortex-A7      | ARMCA7            | Cortex-A7 based device
ARM Cortex-A9      | ARMCA9            | Cortex-A9 based device



\section template_files_sec Template Files

To simplify the creation of CMSIS-Core device files, the following template files are provided that should be extended by the silicon vendor to reflect the actual device and device peripherals.
Silicon vendors add to these template files the following information:
 - <b>Device Peripheral Access Layer</b> that provides definitions for device-specific peripherals.
 - <b>Access Functions for Peripherals</b> (optional) that provides additional helper functions to access device-specific peripherals.
 - <b>Interrupt vectors</b> in the startup file that are device specific.

<table class="cmtable">
    <tr>
      <th>Template File</th>
      <th>Description</th>
    </tr>
    <tr>
      <td>.\\Device\\\_Template_Vendor\\Vendor\\Device_A\\Source\\ARM\\startup_Device.c</td>
      <td>Startup file template for ARM C/C++ Compiler.</td>
    </tr>   
    <tr>
      <td>.\\Device\\\_Template_Vendor\\Vendor\\Device_A\\Source\\ARM\\Device.sct</td>
      <td>Linker scatter file template for ARM C/C++ Compiler.</td>
    </tr>
    <tr>
      <td>.\\Device\\\_Template_Vendor\\Vendor\\Device_A\\Source\\system_Device.c</td>
      <td>Generic system_Device.c file for system configuration (i.e. processor clock and memory bus system).</td>
    </tr>
    <tr>
      <td>.\\Device\\\_Template_Vendor\\Vendor\\Device_A\\Source\\mmu_Device.c</td>
      <td>Sample mmu_Device.c file with memory map description for Memory Management Unit (MMU) configuration.</td>
    </tr>
    <tr>
      <td>.\\Device\\\_Template_Vendor\\Vendor\\Device_A\\Include\\Device.h</td>
      <td>Generic device header file. Needs to be extended with the device-specific peripheral registers. Optionally functions that access the peripherals
      can be part of that file.</td>
    </tr>
    <tr>
      <td>.\\Device\\\_Template_Vendor\\Vendor\\Device_A\\Include\\system_Device.h</td>
      <td>Generic system device configuration include file.</td>
    </tr>
    <tr>
      <td>.\\Device\\\_Template_Vendor\\Vendor\\Device_A\\Include\\mem_Device.h</td>
      <td>Generic memory base address and size definitions used in scatter file. Settable via Configuration Wizard.</td>
    </tr>
</table>


<b>Adapt Template Files to a Device</b>

The following steps describe how to adopt the template files to a specific device or device family.
Copy the complete all files in the template directory and replace:
  - directory name 'Vendor' with the abbreviation for the device vendor  e.g.: NXP.
  - directory name 'Device' with the specific device name e.g.: LPC17xx.
  - in the file names 'Device' with the specific device name e.g.: LPC17xx.

Each template file contains comments that start with \b ToDo: that describe a required modification.
The template files contain place holders:

<table class="cmtable">
    <tr>
      <th>Placeholder</th>
      <th>Replaced with</th>
    </tr>
    <tr>
      <td>&lt;Device&gt;</td>
      <td>the specific device name or device family name; i.e. LPC17xx.</td>
    </tr>
    <tr>
      <td>&lt;DeviceInterrupt&gt;</td>
      <td>a specific interrupt name of the device; i.e. TIM1 for Timer 1.</td>
    <tr>
      <td>&lt;DeviceAbbreviation&gt;</td>
      <td>short name or abbreviation of the device family; i.e. LPC.</td>
    </tr>
    <tr>
      <td>Cortex-M#</td>
      <td>the specific Cortex-M processor name; i.e. Cortex-M3.</td>
    </tr>
</table>


The device configuration of the template files is described in detail on the following pages:
  - \subpage startup_c_pg
  - \subpage system_c_pg
  - \subpage device_h_pg
  - \subpage mem_h_pg
  - \subpage mmu_c_pg
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page startup_c_pg Startup File startup_<device>.c

The \ref startup_c_pg contains:
 - Exception vectors of the Cortex-A Processor with weak functions that implement default routines.
 - The reset handler which is executed after CPU reset and typically calls the \ref SystemInit function.
 - The setup values for the various stack pointers, i.e. per exceptional mode and main stack.

The file exists for each supported toolchain and is the only tool-chain specific CMSIS file.

\section startup_c_sec startup_Device.c Template File

An ARM Compiler specific startup file for an ARMv7-A processor like Cortex-A9 is shown below.
The files for other compiler vendors differ slightly in the syntax, but not in the overall structure.

\verbinclude "Source\ARM\startup_Device.c"
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page system_c_pg System Configuration Files system_<device>.c and system_<device>.h

The \ref system_c_pg provides as a minimum the functions described under \ref system_init_gr.
These functions are device specific and need adaptations. In addition, the file might have
configuration settings for the device such as XTAL frequency or PLL prescaler settings.

For devices with external memory BUS the system_<device>.c also configures the BUS system.

The silicon vendor might expose other functions (i.e. for power configuration) in the system_<device>.c file.
In case of additional features the function prototypes need to be added to the system_<device>.h header file.

\section system_Device_sec system_Device.c Template File

The \ref system_Device_sec for the Cortex-M3 is shown below.

\verbinclude "Source\system_Device.c"

\section system_Device_h_sec system_Device.h Template File

The system_<device>.h header file contains prototypes to access the public functions in the system_<device>.c file.
The \ref system_Device_h_sec is shown below.

\verbinclude "Include\system_Device.h"

*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page device_h_pg Device Header File \<device.h>

The \ref device_h_pg contains the following sections that are device specific:
 - \ref irqn_defs provides interrupt numbers (IRQn) for all exceptions and interrupts of the device.
 - \ref config_perifs reflect the features of the device.
 - \ref access_perifs definitions for the \ref peripheral_gr to all device peripherals. It contains all data structures and the address mapping for device-specific peripherals.
 - <b>Access Functions for Peripherals (optional)</b> provide additional helper functions for peripherals that are useful for programming of these peripherals. Access Functions may be provided as inline functions or can be extern references to a device-specific library provided by the silicon vendor.

<a href="Modules.html">\b Reference </a> describes the standard features and functions of the \ref device_h_pg in detail.

\section interrupt_number_sec Interrupt Number Definition

\ref device_h_pg contains the enumeration \ref IRQn_Type that defines all exceptions and interrupts of the device.
For devices implementing an ARM GIC these are defined as:
  - IRQn 0-15 represents software generated interrupts (SGI), local to each processor core.
  - IRQn 16-31 represents private peripheral interrupts (PPI), local to each processor core.
  - IRQn 32-1019 represents shared peripheral interrups (SPI), routeable to all processor cores.
  - IRQn 1020-1023 represents special interrupts, refer to the GIC Architecture Specification.
  
\b Example:

The following example shows the extension of the interrupt vector table for Cortex-A9 class device.

\code
typedef enum IRQn
{
/******  SGI Interrupts Numbers                 ****************************************/
  SGI0_IRQn            =  0,      
  SGI1_IRQn            =  1,
  SGI2_IRQn            =  2,
       :                  :
  SGI15_IRQn           = 15,

/******  Cortex-A9 Processor Exceptions Numbers ****************************************/
  GlobalTimer_IRQn     = 27,        /*!< Global Timer Interrupt                        */
  PrivTimer_IRQn       = 29,        /*!< Private Timer Interrupt                       */
  PrivWatchdog_IRQn    = 30,        /*!< Private Watchdog Interrupt                    */

/******  Platform Exceptions Numbers ***************************************************/
  Watchdog_IRQn        = 32,        /*!< SP805 Interrupt        */
  Timer0_IRQn          = 34,        /*!< SP804 Interrupt        */
  Timer1_IRQn          = 35,        /*!< SP804 Interrupt        */
  RTClock_IRQn         = 36,        /*!< PL031 Interrupt        */
  UART0_IRQn           = 37,        /*!< PL011 Interrupt        */
       :                  :
       :                  :
} IRQn_Type;
\endcode

\section core_config_sect Configuration of the Processor and Core Peripherals

The \ref device_h_pg configures the Cortex-A processor and the core peripherals with <i>\#defines</i>
that are set prior to including the file <b>core_<cpu>.h</b>.

The following tables list the <i>\#defines</i> along with the possible values for each processor core.
If these <i>\#defines</i> are missing default values are used.

<table class="cmtable">
    <tr>
      <th>\#define</th>
      <th>Value Range</th>
      <th>Default</th>
      <th>Description</th>
    </tr>
    <tr>
      <td>__CM0_REV</td>
      <td>0x0000</td>
      <td>0x0000</td>
      <td>Core revision number ([15:8] revision number, [7:0] patch number)</td>
    </tr>
    <tr>
      <td>__CORTEX_A</td>
      <td>5, 7, 9</td>
      <td>(n/a)</td>
      <td>Core type number</td>
    </tr>
    <tr>
      <td>__FPU_PRESENT</td>
      <td>0 .. 1</td>
      <td>0</td>
      <td>Defines if an FPU is present or not</td>
    </tr>
    <tr>
      <td>__GIC_PRESENT</td>
      <td>0 ..1 </td>
      <td>Defines if an GIC is present or not</td>
      <td>Core revision number ([15:8] revision number, [7:0] patch number)</td>
    </tr>
    <tr>
      <td>__TIM_PRESENT</td>
      <td>0 .. 1</td>
      <td>0</td>
      <td>Defines if a private timer is present or not</td>
    </tr>
    <tr>
      <td>__L2C_PRESENT</td>
      <td>0 .. 1</td>
      <td>0</td>
      <td>Defines if a level 2 cache controller is present or not</td>
    </tr>
</table>

\b Example

The following code exemplifies the configuration of the Cortex-A9 Processor and Core Peripherals.

\code
#define __CA_REV        0x0000U    /*!< Core revision r0p0                          */
#define __CORTEX_A           9U    /*!< Cortex-A9 Core                              */
#define __FPU_PRESENT        1U    /*!< FPU present                                 */
#define __GIC_PRESENT        1U    /*!< GIC present                                 */
#define __TIM_PRESENT        0U    /*!< TIM not present                             */
#define __L2C_PRESENT        0U    /*!< L2C not present                             */
:
:
#include "core_ca.h"               /* Cortex-A processor and core peripherals       */
\endcode


\section core_version_sect   CMSIS Version and Processor Information

Defines in the core_<i>cpu</i>.h file identify the version of the CMSIS-Core-A and the processor used.
The following shows the defines in the various core_<i>cpu</i>.h files that may be used in the \ref device_h_pg
to verify a minimum version or ensure that the right processor core is used.

\code
#define __CA_CMSIS_VERSION_MAIN  (5U)                                 /* [31:16] CMSIS Core main version */
#define __CA_CMSIS_VERSION_SUB   (0U)                                 /* [15:0]  CMSIS Core sub version */
#define __CA_CMSIS_VERSION       ((__CA_CMSIS_VERSION_MAIN << 16U) | \
                                   __CA_CMSIS_VERSION_SUB          )  /* CMSIS Core version number */
\endcode

\section device_access Device Peripheral Access Layer

The \ref device_h_pg contains for each peripheral:
 - Register Layout Typedef
 - Base Address
 - Access Definitions

The section \ref peripheral_gr shows examples for peripheral definitions.

\section device_h_sec Device.h Template File

The silicon vendor needs to extend the Device.h template file with the CMSIS features described above.
In addition the \ref device_h_pg may contain functions to access device-specific peripherals.
The \ref system_Device_h_sec which is provided as part of the CMSIS specification is shown below.

\verbinclude "Include\Device.h"

*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page mem_h_pg Memory Configuration Files mem_<device>.h

\verbinclude "Include\mem_Device.h"

*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page mmu_c_pg Memory Management Unit Files mmu_<device>.c

\verbinclude "Source\mmu_Device.c"

*/