1# CMSIS-Core Device Templates {#templates_pg} 2 3Arm 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. 4 5These CMSIS-Core device template files include the following: 6 - Register names of the Core Peripherals and names of the Core Exception Vectors. 7 - Functions to access core peripherals, cache, MMU and special CPU instructions 8 - Generic startup code and system configuration code. 9 10## CMSIS-Core Processor Files {#CMSIS_Processor_files} 11 12The CMSIS-Core processor files provided by Arm are in the directory .\\CMSIS\\Core\\Include. These header files define all processor specific attributes do not need any modifications. 13 14The `core_<cpu>.h` defines the core peripherals and provides helper functions that access the core registers. 15 16Header File | Target Processor Core 17:----------------------|:------------------------------- 18�� CMSIS/Core/Include | CMSIS-Core include folder ([See on GitHub](https://github.com/ARM-software/CMSIS_6/tree/main/CMSIS/Core/Include/)) 19 ┗ �� core_ca.h | Generics for all supported Cortex-A processors 20 21## Device Examples {#device_examples} 22 23The [Cortex_DFP pack](https://github.com/ARM-software/Cortex_DFP) provides generic device definitions for supported Arm Cortex-A cores and contains corresponding CMSIS-Core device files. 24 25## Template Files {#template_files_sec} 26 27To 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. 28Silicon vendors add to these template files the following information: 29 - **Device Peripheral Access Layer** that provides definitions for device-specific peripherals. 30 - **Access Functions for Peripherals** (optional) that provides additional helper functions to access device-specific peripherals. 31 - **Interrupt vectors** in the startup file that are device specific. 32 33Template File | Description 34:-----------------------------------|:---------------------------------------- 35�� CMSIS/Core/Template/Device_A | Folder with CMSIS-Core device file templates ([See on GitHub](https://github.com/ARM-software/CMSIS_6/tree/main/CMSIS/Core/Template/Device_A/)) 36 ┣ �� Config | Template configuration files 37   ┣ �� Device_ac6.sct | Linker scatter file template for Arm C/C++ Compiler 38   ┗ �� mem_Device.h |\ref mem_h_pg template 39 ┣ �� Include | Template header files 40   ┣ �� Device.h | \ref device_h_pg template 41   ┗ �� system_Device.h | \ref system_Device_h_sec 42 ┗ �� Source | Template C files 43   ┣ �� mmu_Device.c | \ref mmu_c_pg template 44   ┣ �� startup_Device.c | \ref startup_c_pg template 45   ┗ �� system_Device.c | \ref system_Device_sec 46 47**Adapt Template Files to a Device** 48 49The following steps describe how to adopt the template files to a specific device or device family. 50Copy the complete all files in the template directory and replace: 51 - directory name 'Vendor' with the abbreviation for the device vendor e.g.: NXP. 52 - directory name 'Device' with the specific device name e.g.: LPC17xx. 53 - in the file names 'Device' with the specific device name e.g.: LPC17xx. 54 55Each template file contains comments that start with \b ToDo: that describe a required modification. 56The template files contain place holders: 57 58Placeholder | To be replaced with 59:--------------------------|:---------------------------------------- 60`<Device>` | The specific device name or device family name, for example `LPC17xx` 61`<DeviceInterrupt>` | The specific interrupt name of the device, for example `TIM1` for Timer 1 interrupt 62`<DeviceAbbreviation>` | Short name or abbreviation of the device family, for example `LPC` 63`Cortex-A#` | The specific Cortex-A processor name, for example `Cortex-A9` 64 65The device configuration of the template files is described in detail on the following pages: 66 - \subpage startup_c_pg 67 - \subpage system_c_pg 68 - \subpage device_h_pg 69 - \subpage mem_h_pg 70 - \subpage mmu_c_pg 71 72\page startup_c_pg Startup File startup_<Device>.c 73 74The \ref startup_c_pg contains: 75 - Exception vectors of the Cortex-A Processor with weak functions that implement default routines. 76 - The reset handler which is executed after CPU reset and typically calls the \ref SystemInit function. 77 - The setup values for the various stack pointers, i.e. per exceptional mode and main stack. 78 79The file exists for each supported toolchain and is the only tool-chain specific CMSIS file. 80 81\section startup_c_sec startup_Device.c Template File 82 83An Arm Compiler specific startup file for an Armv7-A processor like Cortex-A9 is shown below. 84The files for other compiler vendors differ slightly in the syntax, but not in the overall structure. 85 86\verbinclude "Source/startup_Device.c" 87 88 89\page system_c_pg System Configuration Files system_<Device>.c and system_<Device>.h 90 91The \ref system_c_pg provides as a minimum the functions described under \ref system_init_gr. 92These functions are device specific and need adaptations. In addition, the file might have 93configuration settings for the device such as XTAL frequency or PLL prescaler settings. 94 95For devices with external memory BUS the system_<Device>.c also configures the BUS system. 96 97The silicon vendor might expose other functions (i.e. for power configuration) in the system_<Device>.c file. 98 99In case of additional features the function prototypes need to be added to the system_<Device>.h header file. 100 101\section system_Device_sec system_Device.c Template File 102 103The \ref system_Device_sec is shown below. 104 105\verbinclude "Source/system_Device.c" 106 107\section system_Device_h_sec system_Device.h Template File 108 109The 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. 110 111\verbinclude "Include/system_Device.h" 112 113\page device_h_pg Device Header File \<Device.h> 114 115The \ref device_h_pg contains the following sections that are device specific: 116 - \ref interrupt_number_sec provides interrupt numbers (IRQn) for all exceptions and interrupts of the device. 117 - \ref core_config_sect reflect the features of the device. 118 - \ref device_access definitions for the \ref peripheral_gr to all device peripherals. It contains all data structures and the address mapping for device-specific peripherals. 119 - <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. 120 121<a href="modules.html">\b Reference </a> describes the standard features and functions of the \ref device_h_pg in detail. 122 123\section interrupt_number_sec Interrupt Number Definition 124 125\ref device_h_pg contains the enumeration \ref IRQn_ID_t that defines all exceptions and interrupts of the device. 126For devices implementing an Arm GIC these are defined as: 127 - IRQn 0-15 represents software generated interrupts (SGI), local to each processor core. 128 - IRQn 16-31 represents private peripheral interrupts (PPI), local to each processor core. 129 - IRQn 32-1019 represents shared peripheral interrupts (SPI), routable to all processor cores. 130 - IRQn 1020-1023 represents special interrupts, refer to the GIC Architecture Specification. 131 132**Example:** 133 134The following example shows the extension of the interrupt vector table for Cortex-A9 class device. 135 136```c 137typedef enum IRQn 138{ 139/****** SGI Interrupts Numbers ****************************************/ 140 SGI0_IRQn = 0, 141 SGI1_IRQn = 1, 142 SGI2_IRQn = 2, 143 : : 144 SGI15_IRQn = 15, 145 146/****** Cortex-A9 Processor Exceptions Numbers ****************************************/ 147 GlobalTimer_IRQn = 27, /*!< Global Timer Interrupt */ 148 PrivTimer_IRQn = 29, /*!< Private Timer Interrupt */ 149 PrivWatchdog_IRQn = 30, /*!< Private Watchdog Interrupt */ 150 151/****** Platform Exceptions Numbers ***************************************************/ 152 Watchdog_IRQn = 32, /*!< SP805 Interrupt */ 153 Timer0_IRQn = 34, /*!< SP804 Interrupt */ 154 Timer1_IRQn = 35, /*!< SP804 Interrupt */ 155 RTClock_IRQn = 36, /*!< PL031 Interrupt */ 156 UART0_IRQn = 37, /*!< PL011 Interrupt */ 157 : : 158 : : 159} IRQn_Type; 160``` 161 162\section core_config_sect Configuration of the Processor and Core Peripherals 163 164The \ref device_h_pg configures the Cortex-A processor and the core peripherals with <i>\#defines</i> 165that are set prior to including the file <b>core_<cpu>.h</b>. 166 167The following tables list the <i>\#defines</i> along with the possible values for each processor core. 168If these <i>\#defines</i> are missing default values are used. 169 170<table class="cmtable"> 171 <tr> 172 <th>\#define</th> 173 <th>Value Range</th> 174 <th>Default</th> 175 <th>Description</th> 176 </tr> 177 <tr> 178 <td>__CM0_REV</td> 179 <td>0x0000</td> 180 <td>0x0000</td> 181 <td>Core revision number ([15:8] revision number, [7:0] patch number)</td> 182 </tr> 183 <tr> 184 <td>__CORTEX_A</td> 185 <td>5, 7, 9</td> 186 <td>(n/a)</td> 187 <td>Core type number</td> 188 </tr> 189 <tr> 190 <td>__FPU_PRESENT</td> 191 <td>0 .. 1</td> 192 <td>0</td> 193 <td>Defines if an FPU is present or not</td> 194 </tr> 195 <tr> 196 <td>__GIC_PRESENT</td> 197 <td>0 ..1 </td> 198 <td>Defines if an GIC is present or not</td> 199 <td>Core revision number ([15:8] revision number, [7:0] patch number)</td> 200 </tr> 201 <tr> 202 <td>__TIM_PRESENT</td> 203 <td>0 .. 1</td> 204 <td>0</td> 205 <td>Defines if a private timer is present or not</td> 206 </tr> 207 <tr> 208 <td>__L2C_PRESENT</td> 209 <td>0 .. 1</td> 210 <td>0</td> 211 <td>Defines if a level 2 cache controller is present or not</td> 212 </tr> 213</table> 214 215**Example** 216 217The following code exemplifies the configuration of the Cortex-A9 Processor and Core Peripherals. 218 219```c 220#define __CA_REV 0x0000U /*!< Core revision r0p0 */ 221#define __CORTEX_A 9U /*!< Cortex-A9 Core */ 222#define __FPU_PRESENT 1U /*!< FPU present */ 223#define __GIC_PRESENT 1U /*!< GIC present */ 224#define __TIM_PRESENT 0U /*!< TIM not present */ 225#define __L2C_PRESENT 0U /*!< L2C not present */ 226: 227: 228#include "core_ca.h" /* Cortex-A processor and core peripherals */ 229``` 230 231 232\section core_version_sect CMSIS Version and Processor Information 233 234Defines in the core_<i>cpu</i>.h file identify the version of the CMSIS-Core-A and the processor used. 235The following shows the defines in the various core_<i>cpu</i>.h files that may be used in the \ref device_h_pg 236to verify a minimum version or ensure that the right processor core is used. 237 238```c 239#define __CA_CMSIS_VERSION_MAIN (5U) /* [31:16] CMSIS Core main version */ 240#define __CA_CMSIS_VERSION_SUB (0U) /* [15:0] CMSIS Core sub version */ 241#define __CA_CMSIS_VERSION ((__CA_CMSIS_VERSION_MAIN << 16U) | \ 242 __CA_CMSIS_VERSION_SUB ) /* CMSIS Core version number */ 243``` 244 245\section device_access Device Peripheral Access Layer 246 247The \ref device_h_pg contains for each peripheral: 248 - Register Layout Typedef 249 - Base Address 250 - Access Definitions 251 252The section \ref peripheral_gr shows examples for peripheral definitions. 253 254\section device_h_sec Device.h Template File 255 256The silicon vendor needs to extend the Device.h template file with the CMSIS features described above. 257In addition the \ref device_h_pg may contain functions to access device-specific peripherals. 258The \ref system_Device_h_sec which is provided as part of the CMSIS specification is shown below. 259 260\verbinclude "Include/Device.h" 261 262 263\page mem_h_pg Memory Configuration Files mem_<device>.h 264 265\verbinclude "Config/mem_Device.h" 266 267 268\page mmu_c_pg Memory Management Unit Files mmu_<device>.c 269 270\verbinclude "Source/mmu_Device.c" 271
