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/tree/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/tree/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/tree/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 \ref __CM_CMSIS_VERSION is defined in the `cmsis_version.h` file and provides the version of the CMSIS-Core (Cortex-M). It is constructed as follows:
  87
  88 ```c
  89 #define __CM_CMSIS_VERSION_MAIN  ( 5U)                                    /* [31:16] CMSIS Core(M) main version */
  90 #define __CM_CMSIS_VERSION_SUB   ( 7U)                                    /* [15:0]  CMSIS Core(M) sub version */
  91 #define __CM_CMSIS_VERSION       ((__CM_CMSIS_VERSION_MAIN << 16U) | \
  92                                    __CM_CMSIS_VERSION_SUB           )     /* CMSIS Core(M) version number */
  93
  94 ```
  95
  96 The `cmsis_version.h` is included by each `cpu_<core>.h` so the CMSIS version defines are available via them already.
  97
  98 The `cpu_<core>.h` files use specific defines (such as \ref __CORTEX_M) that provide identification of the target processor core.
  99
 100 These defines can be used in the \ref device_h_pg to verify a minimum CMSIS-Core version as well as the target processor. Read more at \ref version_control_gr.