1CMSIS Support and Integration
2=============================
3
4Overview                                                       {#cmsis_overview}
5========
6
7Firmware using components with a dependency on the CMSIS library will need to
8configure CMSIS for the target device. This is done by way of a `<fmw_cmsis.h>`
9header, which should provide the definitions necessary to ensure CMSIS is
10properly configured for the device. It is recommended that this header resides
11in the directory of the firmware.
12
13While the build system does not enforce this strategy, for consistency it is
14recommended that new architectures, products and firmwares follow it.
15
16Example                                                         {#cmsis_example}
17=======
18
19The example below configures CMSIS to run on an Arm Cortex-M3 r2p1 with an MPU
20and basic interrupts. The definitions used in this example are expected by
21CMSIS, and are described in the CMSIS 5 documentation.
22
23    #ifndef FMW_CMSIS_H
24    #define FMW_CMSIS_H
25
26    #define __CHECK_DEVICE_DEFINES
27    #define __CM3_REV 0x0201
28    #define __MPU_PRESENT 1
29    #define __NVIC_PRIO_BITS 3
30    #define __Vendor_SysTickConfig 0
31
32    typedef enum IRQn {
33        NonMaskableInt_IRQn   = -14,
34        MemoryManagement_IRQn = -12,
35        BusFault_IRQn         = -11,
36        UsageFault_IRQn       = -10,
37        SVCall_IRQn           = -5,
38        DebugMonitor_IRQn     = -4,
39        PendSV_IRQn           = -2,
40        SysTick_IRQn          = -1,
41    } IRQn_Type;
42
43    #include <core_cm3.h>
44
45    #endif /* FMW_CMSIS_H */
46
47Sharing Configurations                                   {#cmsis_shared_configs}
48======================
49
50In some cases, it may be desirable to use the same CMSIS configuration for more
51than one firmware in a product. The build system provides no provisions for
52sharing a configuration, but the suggested strategy is laid out below:
53
54    <root>
55     └─ product
56        └── <product>
57            ├── include
58            │   ├── fmw_cmsis_a.h
59            │   ├── fmw_cmsis_b.h
60            │   └── ...
61            ├── a1
62            │   ├── fmw_cmsis.h (includes <fmw_cmsis_a.h>)
63            │   └── ...
64            ├── a2
65            │   ├── fmw_cmsis.h (includes <fmw_cmsis_a.h>)
66            │   └── ...
67            └── b
68                ├── fmw_cmsis.h (includes <fmw_cmsis_b.h>)
69                └── ...
70
71Alternatively, for products with only one CMSIS configuration, it is reasonable
72to move `<fmw_cmsis.h>` to the product include directory:
73
74    <root>
75     └─ product
76        └── <product>
77            ├── include
78            │   ├── fmw_cmsis.h
79            │   └── ...
80            ├── a
81            │   └── ...
82            ├── b
83            │   └── ...
84            └── c
85                └── ...
86