begriffs open source - cmsis/blob - CMSIS/Core/Test/README.md

   1 # CMSIS-Core Unit Tests
   2
   3 This folder contains a unit test suite that validates CMSIS-Core implementation.
   4 It uses test tools from LLVM, namely LIT and FileCheck, to validate consistency across compilers and devices.
   5
   6 Consult the manual of [FileCheck - Flexible pattern matching file verifier](https://llvm.org/docs/CommandGuide/FileCheck.html)
   7 for details.
   8
   9 ## Folder structure
  10
  11 ```txt
  12     📂 Test
  13     ┣ 📂 src                       Test source files
  14     ┣ 📂 build.py                  Build wrapper
  15     ┣ 📂 lit.cfg.py                LIT test suite configuration
  16     ┣ 📂 requirements.txt          Python dependencies required for build.py script
  17     ┗ 📂 vcpkg-configuration.json  vcpkg configuration to create virtual environment required for running these tests
  18 ```
  19
  20 ## Test matrix
  21
  22 Currently, the following build configurations are provided:
  23
  24 1. Compiler
  25    - Arm Compiler 6 (AC6)
  26    - GNU Compiler (GCC)
  27    - LLVM/Clang (Clang)
  28 2. Devices
  29    - Cortex-M0
  30    - Cortex-M0+
  31    - Cortex-M3
  32    - Cortex-M4
  33      - w/o FPU
  34      - with FPU
  35    - Cortex-M7
  36      - w/o FPU
  37      - with SP FPU
  38      - with DP FPU
  39    - Cortex-M23
  40      - w/o security extensions (TrustZone)
  41      - in secure mode
  42      - in non-secure mode
  43    - Cortex-M33 (with FPU and DSP extensions)
  44      - w/o security extensions (TrustZone)
  45      - in secure mode
  46      - in non-secure mode
  47    - Cortex-M35P (with FPU and DSP extensions)
  48      - w/o security extensions (TrustZone)
  49      - in secure mode
  50      - in non-secure mode
  51    - Cortex-M55 (with FPU and DSP extensions)
  52      - in secure mode
  53      - in non-secure mode
  54    - Cortex-M85 (with FPU and DSP extensions)
  55      - in secure mode
  56      - in non-secure mode
  57    - Cortex-A5
  58      - w/o NEON extensions
  59      - w NEON extensions
  60    - Cortex-A7
  61      - w/o NEON extensions
  62      - w NEON extensions
  63    - Cortex-A9
  64      - w/o NEON extensions
  65      - w NEON extensions
  66 3. Optimization Levels
  67    - none
  68    - balanced
  69    - size
  70    - speed
  71
  72 ## Prerequisites
  73
  74 The following tools are required to build and run the Core tests:
  75
  76 - [Arm Compiler 6.23](https://artifacts.tools.arm.com/arm-compiler/6.23/32/)*
  77 - [GCC Compiler 14.2.1](https://artifacts.keil.arm.com/arm-none-eabi-gcc/14.2.1/)*
  78 - [Clang Compiler 19.1.5](https://github.com/ARM-software/LLVM-embedded-toolchain-for-Arm/releases/tag/release-19.1.5)*
  79 - [Python 3.9](https://www.python.org/downloads/)
  80 - [LLVM FileCheck](https://github.com/llvm/llvm-project/releases/)
  81   - Ubuntu package `llvm-<version>-tools`
  82   - MacOS Homebrew formula `llvm`
  83     Symlink FileCheck binary `ln -s /opt/homebrew/opt/llvm/bin/FileCheck /opt/homebrew/bin`
  84
  85 The executables need to be present on the `PATH`.
  86 For tools distributed via vcpkg (*) this can be achieved automatically:
  87
  88 ```bash
  89  ./CMSIS/Core/Test $ vcpkg activate
  90 ```
  91
  92 Install the Python packages required by `build.py`:
  93
  94 ```bash
  95  ./CMSIS/Core/Test $ pip install -r requirements.txt
  96 ```
  97
  98 ## Execute LIT tests
  99
 100 To build and run the CoreValidation tests for one or more configurations use the following command line.
 101 Select the `<compiler>`, `<device>`, and `<optimize>` level to execute `lit` for.
 102
 103 ```bash
 104  ./CMSIS/Core/Test $ ./build.py -c <compiler> -d <device> -o <optimize> [lit]
 105 ```
 106
 107 For example, to execute the LIT tests using GCC for Cortex-M3 with no optimization, run:
 108
 109 ```bash
 110  ./CMSIS/Core/Test $ ./build.py -c GCC -d CM3 -o none lit
 111 [GCC][Cortex-M3][none](lit:run_lit) /opt/homebrew/bin/lit --xunit-xml-output lit.xml -D toolchain=GCC -D device=CM3 -D optimize=none src
 112 [GCC][Cortex-M3][none](lit:run_lit) -- Testing: 49 tests, 10 workers --
 113  :
 114 [GCC][Cortex-M3][none](lit:run_lit) /opt/homebrew/bin/lit succeeded with exit code 0
 115
 116 Matrix Summary
 117 ==============
 118
 119 compiler    device     optimize    lit
 120 ----------  ---------  ----------  -----
 121 GCC         Cortex-M3  none        33/33
 122 ```
 123
 124 The summary lists the amount of test cases executed and passed.
 125
 126 ## Analyze failing test cases
 127
 128 In case of failing test cases, one can run a single test case with verbose output like this:
 129
 130 ```bash
 131  ./CMSIS/Core/Test $ lit -D toolchain=GCC -D device=CM3 -D optimize=none -a src/apsr.c
 132 -- Testing: 1 tests, 1 workers --
 133 PASS: CMSIS-Core :: src/apsr.c (1 of 1)
 134 Script:
 135 --
 136 : 'RUN: at line 2';   arm-none-eabi-gcc -mcpu=cortex-m3 -mfloat-abi=soft -O1 -I ../Include -D CORE_HEADER="core_cm3.h" -c -D __CM3_REV=0x0000U -D __MPU_PRESENT=1U -D __VTOR_PRESENT=1U -D __NVIC_PRIO_BITS=3U -D __Vendor_SysTickConfig=0U -o ./src/Output/apsr.c.o ./src/apsr.c; llvm-objdump --mcpu=cortex-m3 -d ./src/Output/apsr.c.o | FileCheck --allow-unused-prefixes --check-prefixes CHECK,CHECK-THUMB ./src/apsr.c
 137 --
 138 Exit Code: 0
 139  :
 140 ********************
 141
 142 Testing Time: 0.10s
 143   Passed: 1
 144 ```
 145
 146 The output reveals which commands are chained and their error output if any.
 147
 148 Failing FileCheck requires in detail analysis of the `// CHECK` annotations in the test source file
 149 against the `llvm-objdump` output of the test compilation.
 150
 151 Investigating the disassembly can be done like
 152
 153 ```bash
 154  ./CMSIS/Core/Test $ llvm-objdump --mcpu=cortex-m3 -d ./src/Output/apsr.c.o
 155
 156 ./src/Output/apsr.c.o:  file format elf32-littlearm
 157
 158 Disassembly of section .text:
 159
 160 00000000 <get_apsr>:
 161        0: b082          sub     sp, #0x8
 162        2: f3ef 8300     mrs     r3, apsr
 163        6: 9301          str     r3, [sp, #0x4]
 164        8: b002          add     sp, #0x8
 165        a: 4770          bx      lr
 166 ```
 167
 168 This output is expected to match the test case
 169
 170 ```c
 171     // CHECK: mrs {{r[0-9]+}}, apsr
 172     volatile uint32_t result = __get_APSR();
 173 ```
 174
 175 I.e., the test case expects the `mrs {{r[0-9]+}}, apsr` instruction, additional whitespace is ignored.