begriffs open source - cmsis/blob - CMSIS/DoxyGen/Core/src/core_std_files.md

   1 # CMSIS-Core Files {#cmsis_core_files}
   2
   3 CMSIS-Core files can be differentiated in two main groups:
   4
   5  -# \subpage cmsis_standard_files are provided by Arm for supported CPU cores as part of the CMSIS-Core software component. These files typically do not require any modifications and are expected to be included via CMSIS-Core device files.
   6  -# \subpage cmsis_device_files are specified in CMSIS-Core methodology, and are typically provided by CPU device vendors to correctly cover their specific functionalities. Some of them may expect additional application-specific changes.
   7
   8 The detailed file structure of the CMSIS-Core files is shown in the following picture.
   9
  10 ![CMSIS-Core File Structure](./images/CMSIS_CORE_Files.png)
  11
  12 \subpage cmsis_files_dfps explains how \ref cmsis_core_files can be distributed in CMSIS-Pack format.
  13
  14 ## CMSIS-Core Standard Files {#cmsis_standard_files}
  15
  16 The CMSIS-Core Standard file implement all attributes specific to Arm processor cores and generally do not need any modifications.
  17
  18 The files are provided by Arm as CMSIS-Core software component that is part of the [CMSIS Software pack](../../General/html/cmsis_pack.html). The CMSIS-Core standard files can be split into following categories explained below:
  19
  20  - \ref cmsis_processor_files
  21  - \ref cmsis_compiler_files
  22  - \ref cmsis_feature_files
  23
  24 ### CMSIS-Core Processor Files {#cmsis_processor_files}
  25
  26 The CMSIS-Core processor files define the core peripherals and provide helper functions for their access.
  27
  28 The files have naming convention `core_<cpu>.h`, with one file available for each supported processor `<cpu>` as listed in the table below.
  29
  30 Header File            | Target Processor Core
  31 :----------------------|:-------------------------------
  32 📂 CMSIS/Core/Include  | CMSIS-Core include folder ([See on GitHub](https://github.com/ARM-software/CMSIS_6/blob/main/CMSIS/Core/Include/))
  33  ┣ 📄 core_cm0.h       | Cortex-M0 processor
  34  ┣ 📄 core_cm0plus.h   | Cortex-M0+ processor
  35  ┣ 📄 core_cm1.h       | Cortex-M1 processor
  36  ┣ 📄 core_cm3.h       | Cortex-M3 processor
  37  ┣ 📄 core_cm4.h       | Cortex-M4 processor
  38  ┣ 📄 core_cm7.h       | Cortex-M7 processor
  39  ┣ 📄 core_cm23.h      | Cortex-M23 processor
  40  ┣ 📄 core_cm33.h      | Cortex-M33 processor
  41  ┣ 📄 core_cm35p.h     | Cortex-M35P processor
  42  ┣ 📄 core_cm55.h      | Cortex-M55 processor
  43  ┣ 📄 core_cm85.h      | Cortex-M85 processor
  44  ┣ 📄 core_starmc1.h   | STAR-MC1 processor
  45  ┣ 📄 core_sc000.h     | SC000 processor
  46  ┗ 📄 core_sc300.h     | SC300 processor
  47
  48 The files also include the \ref cmsis_compiler_files and depending on the features supported by the core also correponding \ref cmsis_feature_files.
  49
  50 ### CMSIS-Core Compiler Files {#cmsis_compiler_files}
  51
  52 The CMSIS-Core compiler files provide consistent implementations of `#define` symbols that allow toolchain-agnostic usage of CMSIS-Core. \ref cmsis_processor_files rely on such toolchain-agnostic abstractions by including `cmsis_compiler.h` file that then selects the target compiler-specific implementatation depending on the toolchain used in the project.
  53
  54 CMSIS-Core compiler files are provided in `CMSIS/Core/Include/` directory, and define the supported compilers as listed in \ref tested_tools_sec. \ref compiler_conntrol_gr documents the functionalities provided by the CMSIS compliant toolchains.
  55
  56 Header File                            | Description
  57 :--------------------------------------|:-------------------
  58 📂 CMSIS/Core/Include    | CMSIS-Core include folder ([See on GitHub](https://github.com/ARM-software/CMSIS_6/blob/main/CMSIS/Core/Include/))
  59  ┣ 📄 cmsis_compiler.h                  | Main CMSIS-Core compiler header file
  60  ┗ 📂 m-profile                         | Directory for M-Profile specific files
  61  &emsp;&nbsp; ┣ 📄 cmsis_armclang_m.h   | CMSIS-Core Arm Clang compiler file for Cortex-M
  62  &emsp;&nbsp; ┣ 📄 cmsis_clang_m.h      | CMSIS-Core Clang compiler file for Cortex-M
  63  &emsp;&nbsp; ┣ 📄 cmsis_gcc_m.h        | CMSIS-Core GCC compiler file for Cortex-M
  64  &emsp;&nbsp; ┣ 📄 cmsis_iccarm_m.h     | CMSIS-Core IAR compiler file for Cortex-M
  65  &emsp;&nbsp; ┗ 📄 cmsis_tiarmclang_m.h | CMSIS-Core TI Clang compiler file
  66
  67 ### CMSIS-Core Architecture Feature Files {#cmsis_feature_files}
  68
  69 Several architecture-specific features are implemented in separate header files that then gets included by \ref cmsis_processor_files if corresponding feature is supported.
  70
  71 For Cortex-M cores following architecture feature files are provided in the `CMSIS/Core/Include/m-profile/` folder:
  72
  73 Header File         | Feature
  74 :-------------------|:-------------------
  75 📂 CMSIS/Core/Include    | CMSIS-Core include folder ([See on GitHub](https://github.com/ARM-software/CMSIS_6/blob/main/CMSIS/Core/Include/))
  76  ┣ 📂 m-profile                    | Directory for M-Profile specific files
  77  &emsp;&nbsp; ┣ 📄 armv7m_cache1.h | \ref cache_functions_m7
  78  &emsp;&nbsp; ┣ 📄 armv7m_mpu.h    | \ref mpu_functions
  79  &emsp;&nbsp; ┣ 📄 armv8m_mpu.h    | \ref mpu8_functions
  80  &emsp;&nbsp; ┣ 📄 armv8m_pmu.h    | \ref pmu8_functions
  81  &emsp;&nbsp; ┗ 📄 armv81m_pac.h   | PAC functions
  82  ┗ 📄 tz_context.h                 | API header file for \ref context_trustzone_functions
  83
  84 ### CMSIS Version and Processor Information {#core_version_sect}
  85
  86 Defines in the `core_<cpu>.h` file identify the version of the CMSIS-Core (Cortex-M) and the processor used. They can be used in the \ref device_h_pg to verify a minimum CMSIS-Core version as well as the target processor core.
  87
  88 **core_cm0.h**
  89 ```c
  90 #define __CM0_CMSIS_VERSION_MAIN  (__CM_CMSIS_VERSION_MAIN)                         /* [31:16] CMSIS HAL main version */
  91 #define __CM0_CMSIS_VERSION_SUB   (__CM_CMSIS_VERSION_SUB)                          /* [15:0]  CMSIS HAL sub version */
  92 #define __CM0_CMSIS_VERSION       ((__CM0_CMSIS_VERSION_MAIN << 16U) | \
  93                                     __CM0_CMSIS_VERSION_SUB          )              /* CMSIS HAL version number */
  94
  95 #define __CORTEX_M                (0U)                                              /* Cortex-M Core */
  96 ```
  97
  98 **core_cm0plus.h**
  99 ```c
 100 #define __CM0PLUS_CMSIS_VERSION_MAIN  (__CM_CMSIS_VERSION_MAIN)                     /* [31:16] CMSIS HAL main version */
 101 #define __CM0PLUS_CMSIS_VERSION_SUB   (__CM_CMSIS_VERSION_SUB)                      /* [15:0]  CMSIS HAL sub version */
 102 #define __CM0PLUS_CMSIS_VERSION       ((__CM0P_CMSIS_VERSION_MAIN << 16U) | \
 103                                         __CM0P_CMSIS_VERSION_SUB          )         /* CMSIS HAL version number */
 104
 105 #define __CORTEX_M                    (0U)                                          /* Cortex-M Core */
 106 ```
 107
 108
 109 **core_cm1.h**
 110 ```c
 111 #define __CM1_CMSIS_VERSION_MAIN  (__CM_CMSIS_VERSION_MAIN)                         /*!< \deprecated [31:16] CMSIS HAL main version */
 112 #define __CM1_CMSIS_VERSION_SUB   (__CM_CMSIS_VERSION_SUB)                          /*!< \deprecated [15:0]  CMSIS HAL sub version */
 113 #define __CM1_CMSIS_VERSION       ((__CM1_CMSIS_VERSION_MAIN << 16U) | \
 114                                     __CM1_CMSIS_VERSION_SUB           )             /*!< \deprecated CMSIS HAL version number */
 115
 116 #define __CORTEX_M                (1U)                                              /*!< Cortex-M Core */
 117 ```
 118
 119 **core_cm3.h**
 120 ```c
 121 #define __CM3_CMSIS_VERSION_MAIN  (__CM_CMSIS_VERSION_MAIN)                         /* [31:16] CMSIS HAL main version */
 122 #define __CM3_CMSIS_VERSION_SUB   (__CM_CMSIS_VERSION_SUB)                          /* [15:0]  CMSIS HAL sub version */
 123 #define __CM3_CMSIS_VERSION       ((__CM3_CMSIS_VERSION_MAIN << 16U) | \
 124                                     __CM3_CMSIS_VERSION_SUB          )              /* CMSIS HAL version number */
 125
 126 #define __CORTEX_M                (3U)                                              /* Cortex-M Core */
 127 ```
 128
 129 **core_cm4.h**
 130 ```c
 131 #define __CM4_CMSIS_VERSION_MAIN  (__CM_CMSIS_VERSION_MAIN)                         /* [31:16] CMSIS HAL main version */
 132 #define __CM4_CMSIS_VERSION_SUB   (__CM_CMSIS_VERSION_SUB)                          /* [15:0]  CMSIS HAL sub version */
 133 #define __CM4_CMSIS_VERSION       ((__CM4_CMSIS_VERSION_MAIN << 16U) | \
 134                                     __CM4_CMSIS_VERSION_SUB          )              /* CMSIS HAL version number */
 135
 136 #define __CORTEX_M                (4U)                                              /* Cortex-M Core */
 137 ```
 138
 139 **core_cm7.h**
 140 ```c
 141 #define __CM7_CMSIS_VERSION_MAIN  (__CM_CMSIS_VERSION_MAIN                          /* [31:16] CMSIS HAL main version */
 142 #define __CM7_CMSIS_VERSION_SUB   (__CM_CMSIS_VERSION_SUB)                          /* [15:0]  CMSIS HAL sub version */
 143 #define __CM7_CMSIS_VERSION       ((__CM7_CMSIS_VERSION_MAIN << 16U) | \
 144                                     __CM7_CMSIS_VERSION_SUB          )              /* CMSIS HAL version number */
 145
 146 #define __CORTEX_M                (7U)                                              /* Cortex-M Core */
 147 ```
 148
 149 \if ARMv8M
 150 **core_cm23.h**
 151 ```c
 152 #define __CM23_CMSIS_VERSION_MAIN  (__CM_CMSIS_VERSION_MAIN)                        /* [31:16] CMSIS HAL main version */
 153 #define __CM23_CMSIS_VERSION_SUB   (__CM_CMSIS_VERSION_SUB)                         /* [15:0]  CMSIS HAL sub version */
 154 #define __CM23_CMSIS_VERSION       ((__CM23_CMSIS_VERSION_MAIN << 16U) | \
 155                                      __CM23_CMSIS_VERSION_SUB          )            /* CMSIS HAL version number */
 156
 157 #define __CORTEX_M                (23U)                                             /* Cortex-M Core */
 158 ```
 159
 160 **core_cm33.h**
 161 ```c
 162 #define __CM33_CMSIS_VERSION_MAIN  (__CM_CMSIS_VERSION_MAIN)                        /* [31:16] CMSIS HAL main version */
 163 #define __CM33_CMSIS_VERSION_SUB   (__CM_CMSIS_VERSION_SUB)                         /* [15:0]  CMSIS HAL sub version */
 164 #define __CM33_CMSIS_VERSION       ((__CM33_CMSIS_VERSION_MAIN << 16U) | \
 165                                      __CM33_CMSIS_VERSION_SUB          )            /* CMSIS HAL version number */
 166
 167 #define __CORTEX_M                (33U)                                             /* Cortex-M Core */
 168 ```
 169
 170 **core_cm55.h**
 171 ```c
 172 #define __CM55_CMSIS_VERSION_MAIN  (__CM_CMSIS_VERSION_MAIN)                        /* [31:16] CMSIS HAL main version */
 173 #define __CM55_CMSIS_VERSION_SUB   (__CM_CMSIS_VERSION_SUB)                         /* [15:0]  CMSIS HAL sub version */
 174 #define __CM55_CMSIS_VERSION       ((__CM55_CMSIS_VERSION_MAIN << 16U) | \
 175                                      __CM55_CMSIS_VERSION_SUB          )            /* CMSIS HAL version number */
 176
 177 #define __CORTEX_M                (7U)                                              /* Cortex-M Core */
 178 ```
 179 \endif
 180
 181 \if ARMSC
 182 **core_sc000.h**
 183 ```c
 184 #define __SC000_CMSIS_VERSION_MAIN  (__CM_CMSIS_VERSION_MAIN)                       /* [31:16] CMSIS HAL main version */
 185 #define __SC000_CMSIS_VERSION_SUB   (__CM_CMSIS_VERSION_SUB)                        /* [15:0]  CMSIS HAL sub version */
 186 #define __SC000_CMSIS_VERSION       ((__SC000_CMSIS_VERSION_MAIN << 16U) | \
 187                                       __SC000_CMSIS_VERSION_SUB          )          /* CMSIS HAL version number */
 188
 189 #define __CORTEX_SC                 (0U)                                            /* Cortex secure core */
 190 ```
 191 \endif
 192
 193 \if ARMSC
 194 **core_sc300.h**
 195 ```c
 196 #define __SC300_CMSIS_VERSION_MAIN  (__CM_CMSIS_VERSION_MAIN)                       /* [31:16] CMSIS HAL main version */
 197 #define __SC300_CMSIS_VERSION_SUB   (__CM_CMSIS_VERSION_SUB)                        /* [15:0]  CMSIS HAL sub version */
 198 #define __SC300_CMSIS_VERSION       ((__SC300_CMSIS_VERSION_MAIN << 16U) | \
 199                                       __SC300_CMSIS_VERSION_SUB          )          /* CMSIS HAL version number */
 200
 201 #define __CORTEX_SC                 (300U)                                          /* Cortex secure core */
 202 ```
 203 \endif
 204
 205 \if ARMv8M
 206 \if ARMSC
 207 **core_cm35p.h**
 208 ```c
 209 #define __CM35P_CMSIS_VERSION_MAIN  (__CM_CMSIS_VERSION_MAIN)                       /* [31:16] CMSIS HAL main version */
 210 #define __CM35P_CMSIS_VERSION_SUB   (__CM_CMSIS_VERSION_SUB)                        /* [15:0]  CMSIS HAL sub version */
 211 #define __CM35P_CMSIS_VERSION       ((__CM35P_CMSIS_VERSION_MAIN << 16U) | \
 212                                       __CM35P_CMSIS_VERSION_SUB          )          /* CMSIS HAL version number */
 213
 214 #define __CORTEX_M                (35U)                                             /* Cortex-M Core */
 215 ```
 216 \endif
 217 \endif
 218
 219 \if ARMv8M
 220 **core_ARMv8MBL.h**
 221 ```c
 222 #define __ARMv8MBL_CMSIS_VERSION_MAIN  (__CM_CMSIS_VERSION_MAIN)                    /* [31:16] CMSIS HAL main version */
 223 #define __ARMv8MBL_CMSIS_VERSION_SUB   (__CM_CMSIS_VERSION_SUB)                     /* [15:0]  CMSIS HAL sub version */
 224 #define __ARMv8MBL_CMSIS_VERSION       ((__ARMv8MBL_CMSIS_VERSION_MAIN << 16U) | \
 225                                          __ARMv8MBL_CMSIS_VERSION_SUB           )   /* CMSIS HAL version number */
 226
 227 #define __CORTEX_M                     (2U)                                         /* Cortex secure core */
 228 ```
 229 \endif
 230
 231 \if ARMv8M
 232 **core_ARMv8MML.h**
 233 ```c
 234 #define __ARMv8MML_CMSIS_VERSION_MAIN  (__CM_CMSIS_VERSION_MAIN)                    /* [31:16] CMSIS HAL main version */
 235 #define __ARMv8MML_CMSIS_VERSION_SUB   (__CM_CMSIS_VERSION_SUB)                     /* [15:0]  CMSIS HAL sub version */
 236 #define __ARMv8MML_CMSIS_VERSION       ((__ARMv8MML_CMSIS_VERSION_MAIN << 16U) | \
 237                                          __ARMv8MML_CMSIS_VERSION_SUB           )   /* CMSIS HAL version number */
 238
 239 #define __CORTEX_M                     (80U)                                        /* Cortex secure core */
 240 ```
 241 \endif
 242
 243 \if ARMv81M
 244 **core_ARMv81MML.h**
 245 ```c
 246 #define __ARMv81MML_CMSIS_VERSION_MAIN  (__CM_CMSIS_VERSION_MAIN)                   /* [31:16] CMSIS HAL main version */
 247 #define __ARMv81MML_CMSIS_VERSION_SUB   (__CM_CMSIS_VERSION_SUB)                    /* [15:0]  CMSIS HAL sub version */
 248 #define __ARMv81MML_CMSIS_VERSION       ((__ARMv81MML_CMSIS_VERSION_MAIN << 16U) | \
 249                                           __ARMv81MML_CMSIS_VERSION_SUB           ) /* CMSIS HAL version number */
 250
 251 #define __CORTEX_M                     (81U)                                        /* Cortex secure core */
 252 ```
 253 \endif