Skip to content

Commit 5eb7285

Browse files
hugueskambahugueskamba
committed
adr: Recommend CMSIS component source structure
Added an ADR to recommend component source structure.
1 parent b3c1922 commit 5eb7285

File tree

1 file changed

+129
-0
lines changed

1 file changed

+129
-0
lines changed

‎docs/adr/0001_cmsis_component_source_structure_recommendations.md

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# CMSIS component source structure recommendations
2+
Date: 2020-08-19
3+
4+
## Status
5+
Proposed
6+
7+
## Context
8+
9+
[`ARM-software/CMSIS_5`](https://github.com/ARM-software/CMSIS_5) has been ported to Mbed OS. However, it is split across multiple directories and it is not immediately obvious that it comes from that directory. It also makes it difficult to create an independent CMake target can be built as a library that can be optionally be added by end users.
10+
11+
The current proposal is to create a new directory `CMSIS_5/` at the root of the repository that will mirror closely the structure used by `ARM-software/CMSIS_5/` keeping only the directories and files needed by Mbed OS. It will also include Mbed OS specific files and rename some directories in order to work with Mbed OS build tools (see [Decision](#decision) section below). This will result in the removal of the `rtos/source/TARGET_CORTEX/` and `cmsis/` directories.
12+
13+
Additionally it will provide the following advantages:
14+
* Better maintenance of component
15+
* Easy creation of an independent CMake target
16+
* Easy source navigation that mirrors closely the upstream repository
17+
18+
19+
## <a name="decision"></a>Decision
20+
The following directory restructure is recommended:
21+
22+
```
23+
+--cmsis
24+
| +-- README.md
25+
| +-- TARGET_CORTEX_A/
26+
| +-- TOOLCHAIN_IAR/
27+
| +-- cmain.S # Currently cmsis/TARGET_CORTEX_A/TOOLCHAIN_IAR
28+
| +-- device/
29+
| +-- rtos2/
30+
| +-- mbed_lib.json # New Mbed library named `cmsis-device-rtos2`, so it can be excluded from bare metal profile
31+
| +-- include/
32+
| +-- A # Header files currently in rtos/source/TARGET_CORTEX/
33+
| +-- mbed_cmsis_conf.h # Currently in cmsis/
34+
| +-- source/
35+
| +-- B # Source files currently in rtos/source/TARGET_CORTEX/
36+
| +-- RTE/
37+
| +-- include/
38+
| +-- RTE_Components.h # Currently in cmsis/
39+
| +-- TOOLCHAIN_ARM_MICRO/ # Currently in rtos/source/TARGET_CORTEX/
40+
| +-- TOOLCHAIN_ARM_STD/ # Currently in rtos/source/TARGET_CORTEX/
41+
| +-- TOOLCHAIN_GCC_ARM/ # Currently in rtos/source/TARGET_CORTEX/
42+
| +-- TOOLCHAIN_IAR/ # Currently in rtos/source/TARGET_CORTEX/
43+
| +-- CMSIS_5/
44+
| +-- CMSIS/
45+
| +-- RTOS2/
46+
| +-- mbed_lib.json # Currently in rtos/source/TARGET_CORTEX/, creates `cmsis-cmsis5-rtos2` Mbed library
47+
| +-- Include/
48+
| +-- C # Content of rtos/source/TARGET_CORTEX/rtx5/Include/
49+
| +-- RTX/
50+
| +-- Config/
51+
| +-- D # Content of rtos/source/TARGET_CORTEX/rtx5/RTX/Config/
52+
| +-- Include/
53+
| +-- E # Content of rtos/source/TARGET_CORTEX/rtx5/RTX/Include/
54+
| +-- Include1/
55+
| +-- cmsis_os.h # Currently in rtos/source/TARGET_CORTEX/rtx4/
56+
| +-- Library/
57+
| +-- cmsis_os1.c # Currently in rtos/source/TARGET_CORTEX/rtx4/
58+
| +-- Source/
59+
| +-- F # Content of rtos/source/TARGET_CORTEX/rtx5/RTX/Source/
60+
| +-- Source/
61+
| +-- G # Content of rtos/source/TARGET_CORTEX/rtx5/Source
62+
| +-- Core_A/
63+
| +-- Include/
64+
| +-- H # Header files currently in cmsis/TARGET_CORTEX_A/
65+
| +-- Source/
66+
| +-- I # Source files currently in cmsis/TARGET_CORTEX_A/
67+
| +-- Core/
68+
| +-- Include/
69+
| +-- J # Header files currently in cmsis/TARGET_CORTEX_M/
70+
| +-- Source/
71+
| +-- K # Source files currently in cmsis/TARGET_CORTEX_M/
72+
```
73+
74+
However, to cope with Mbed-CLI requirement to find directories to process with the target labels mechanism, some directories will be prefixed with `TARGET_` and capitalized. It will therefore look as follows:
75+
76+
```
77+
+--cmsis
78+
| +-- README.md
79+
| +-- TARGET_CORTEX_A/
80+
| +-- TOOLCHAIN_IAR/
81+
| +-- cmain.S # Currently cmsis/TARGET_CORTEX_A/TOOLCHAIN_IAR
82+
| +-- device/
83+
| +-- rtos2/
84+
| +-- mbed_lib.json # New Mbed library named `cmsis-rtos2`, so it can be excluded from bare metal profile
85+
| +-- include/
86+
| +-- A # Header files currently in rtos/source/TARGET_CORTEX/
87+
| +-- mbed_cmsis_conf.h # Currently in cmsis/
88+
| +-- source/
89+
| +-- B # Source files currently in rtos/source/TARGET_CORTEX/
90+
| +-- RTE/
91+
| +-- include/
92+
| +-- RTE_Components.h # Currently in cmsis/
93+
| +-- TOOLCHAIN_ARM_MICRO/ # Currently in rtos/source/TARGET_CORTEX/
94+
| +-- TOOLCHAIN_ARM_STD/ # Currently in rtos/source/TARGET_CORTEX/
95+
| +-- TOOLCHAIN_GCC_ARM/ # Currently in rtos/source/TARGET_CORTEX/
96+
| +-- TOOLCHAIN_IAR/ # Currently in rtos/source/TARGET_CORTEX/
97+
| +-- CMSIS_5/
98+
| +-- CMSIS/
99+
| +-- RTOS2/
100+
| +-- mbed_lib.json # Currently in rtos/source/TARGET_CORTEX/, creates `rtos` Mbed library
101+
| +-- Include/
102+
| +-- C # Content of rtos/source/TARGET_CORTEX/rtx5/Include/
103+
| +-- RTX/
104+
| +-- Config/
105+
| +-- D # Content of rtos/source/TARGET_CORTEX/rtx5/RTX/Config/
106+
| +-- Include/
107+
| +-- E # Content of rtos/source/TARGET_CORTEX/rtx5/RTX/Include/
108+
| +-- Include1/
109+
| +-- cmsis_os.h # Currently in rtos/source/TARGET_CORTEX/rtx4/
110+
| +-- Library/
111+
| +-- cmsis_os1.c # Currently in rtos/source/TARGET_CORTEX/rtx4/
112+
| +-- Source/
113+
| +-- F # Content of rtos/source/TARGET_CORTEX/rtx5/RTX/Source/
114+
| +-- Source/
115+
| +-- G # Content of rtos/source/TARGET_CORTEX/rtx5/Source
116+
| +-- TARGET_CORTEX_A/
117+
| +-- Include/
118+
| +-- H # Header files currently in cmsis/TARGET_CORTEX_A/
119+
| +-- Source/
120+
| +-- I # Source files currently in cmsis/TARGET_CORTEX_A/
121+
| +-- TARGET_CORTEX_M/
122+
| +-- Include/
123+
| +-- J # Header files currently in cmsis/TARGET_CORTEX_M/
124+
| +-- Source/
125+
| +-- K # Source files currently in cmsis/TARGET_CORTEX_M/
126+
```
127+
128+
## Documentation
129+
The README.md may contain a brief introduction to the component. Detailed documentation may be added under `docs` directory.

0 commit comments

Comments
 (0)