adr: Recommend CMSIS component source structure

.travis.yml

@@ -280,7 +280,7 @@ matrix:
         # Check that example compiles without rtos
         - sed -n '/``` cpp/,/```/{/```$/Q;/```/d;p;}' ${EVENTS}/README.md > main.cpp
         - |
-          rm -r rtos/source/TARGET_CORTEX drivers/source/usb connectivity/cellular connectivity/drivers/cellular \
+          rm -r cmsis/CMSIS_5/CMSIS/RTOS2 cmsis/device/rtos drivers/source/usb connectivity/cellular connectivity/drivers/cellular \
             connectivity/libraries/ppp connectivity/netsocket connectivity/nanostack connectivity/lwipstack features/frameworks/greentea-client \
             features/frameworks/utest features/frameworks/unity components BUILD
         - python tools/make.py -t GCC_ARM -m NUCLEO_F103RB --source=. --build=BUILD/NUCLEO_F103RB/GCC_ARM -j0

cmsis/CMSIS_5/CMSIS/RTOS2/mbed_lib.json

@@ -0,0 +1,3 @@
+{
+    "name": "cmsis-cmsis5-rtos2"
+}

cmsis/README.md

@@ -0,0 +1,43 @@
+
+# CMSIS Version 5
+
+This directory contains a ported version of the upstream repository for [CMSIS_5](http://arm-software.github.io/CMSIS_5/General/html/index.html) as well as Mbed specific RTX configuration and RTOS boot source files.
+
+The upstream source code is imported using the Python script located at [`tools/importer/importer.py`](../tools/importer/importer.py) when passed the [`tools/importer/cmsis_importer.json`](../tools/importer/cmsis_importer.json) configuration file.
+For more information on the importer script please read [`tools/importer/README.md`](../tools/importer/README.md).
+
+The directory is organised as follows:
+
+```
++--cmsis
+|   +-- README.md                           # The present mardown file
+|   +-- device/
+|       +-- mbed_cmsis_conf.h               # Process stack configuration
+|       +-- RTE/
+|           +-- include/
+|               +-- RTE_Components.h        # Run-Time-Environment Component Configuration File
+|       +-- rtos/
+|           +-- mbed_lib.json               # Mbed library configuration file
+|           +-- include/
+|               +-- mbed_boot.h             # Declares the functions that run before main()
+|               +-- mbed_rtx_conf.h         # Changes to RTX configuration
+|               +-- mbed_rtx_storage.h      # Declares the primitives storage types for RTX
+|           +-- source/
+|               +-- mbed_boot.c             # Implements some of the functions that run before main()
+|               +-- mbed_rtos_rtx.c         # Implements some of the functions that run before main()
+|               +-- mbed_rtx_handlers.c     # Implements RTX handlers
+|               +-- mbed_rtx_idle.cpp       # Implements RTX idle loop
+|           +-- TOOLCHAIN_ARM_MICRO/
+|               +-- mbed_boot_arm_micro.c   # Mbed entry point for the uARM toolchain
+|           +-- TOOLCHAIN_ARM_STD/
+|               +-- mbed_boot_arm_std.c     # Mbed entry point for the ARM toolchain
+|           +-- TOOLCHAIN_GCC_ARM/
+|               +-- mbed_boot_gcc_arm.c     # Mbed entry point for the GCC_ARM toolchain
+|           +-- TOOLCHAIN_IAR/
+|               +-- mbed_boot_iar.c         # Mbed entry point for the IAR toolchain
+|   +-- CMSIS_5/                            # Imported from the upstream repository as described in the importer script configuration file (cmsis_importer.json)
+```
+
+Two Mbed libraries live within this directory:
+* `rtos` from `device/rtos`
+* `cmsis-cmsis5-rtos2` from `CMSIS_5/CMSIS/RTOS2`

docs/adr/0001_cmsis_component_source_structure_recommendations.md

@@ -0,0 +1,24 @@
+# CMSIS component source structure recommendations
+Date: 2020-08-19
+
+## Status
+Proposed
+
+## Context
+[`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 repository when imported with the [importer script](../../tools/importer/importer.py ).
+
+## Decision
+The current proposal is to create new directories within the existing `cmsis/` directory:
+* `CMSIS_5/`: mirrors closely the structure used by `ARM-software/CMSIS_5/` keeping only the directories and files needed by Mbed OS and renames some directories in order to work with Mbed OS build tools. See [importer configuration file](./../tools/importer/cmsis_importer.json).
+* `device`: includes Mbed OS specific files to configure RTX.
+
+This will result in the removal of the `rtos/source/TARGET_CORTEX/` directory.
+Additionally, `cmsis/TARGET_CORTEX_A/TOOLCHAIN_IAR/cmain.S` to `platform/source/TARGET_CORTEX_A/TOOLCHAIN_IAR/cmain.S` so it can be accessible when building with the bare metal profile. Note that we already have the equivalent file for TARGET_CORTEX_M at `platform/source/TARGET_CORTEX_M/TOOLCHAIN_IAR/cmain.S`.
+
+It will provide the following advantages:
+* Better maintenance of the CMSIS component
+* Easy creation of an independent CMake target that can be built as a library that can be optionally be linked against by end users
+* Easy source navigation that mirrors closely the upstream CMSIS_5 repository
+
+## Documentation
+A `README.md` within the `cmsis` will contain a brief introduction of the component and will detail the Mbed specific files added.

platform/source/mbed_sdk_boot.c

@@ -23,7 +23,7 @@
 
 /* This startup is for baremetal. There is no RTOS in baremetal,
  * therefore we protect this file with MBED_CONF_RTOS_PRESENT.
- * Note: The start-up code for mbed OS is in rtos/source/TARGET_CORTEX/mbed_boot code file.
+ * Note: The start-up code for mbed OS is in cmsis/device/rtos/TOOLCHAIN_<TOOLCHAIN>/mbed_boot_<TOOLCHAIN>.c code file.
  */
 #if !defined(MBED_CONF_RTOS_PRESENT)
 

tools/importer/README.md

@@ -22,7 +22,7 @@ Note: You must resolve any conflicts that arise during this cherry-pick process.
   "files" : [
     {
       "src_file" : "CMSIS/Core/Template/ARMv8-M/tz_context.c",
-      "dest_file" : "cmsis/TARGET_CORTEX_M/mbed_tz_context.c"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/TARGET_CORTEX_M/Source/mbed_tz_context.c"
     },
     ...
     {
@@ -33,7 +33,7 @@ Note: You must resolve any conflicts that arise during this cherry-pick process.
   "folders" : [
     {
       "src_folder" : "CMSIS/Core/Include/",
-      "dest_folder" : "cmsis/TARGET_CORTEX_M/"
+      "dest_folder" : "cmsis/CMSIS_5/CMSIS/TARGET_CORTEX_M/Include"
     },
     ...
     {

tools/importer/cmsis_importer.json

@@ -2,145 +2,145 @@
   "files" : [
     {
       "src_file" : "CMSIS/Core/Template/ARMv8-M/tz_context.c",
-      "dest_file" : "cmsis/TARGET_CORTEX_M/mbed_tz_context.c"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/TARGET_CORTEX_M/Source/mbed_tz_context.c"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Config/handlers.c",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Config/TARGET_CORTEX_A/handlers.c"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Config/TARGET_CORTEX_A/handlers.c"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Config/RTX_Config.h",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Config/RTX_Config.h"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Config/RTX_Config.h"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Config/RTX_Config.c",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Config/RTX_Config.c"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Config/RTX_Config.c"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/ARM/irq_cm0.s",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_ARM/TARGET_M0/irq_cm0.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_ARM/TARGET_M0/irq_cm0.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/ARM/irq_cm0.s",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_ARM/TARGET_M0P/irq_cm0.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_ARM/TARGET_M0P/irq_cm0.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/ARM/irq_armv8mbl.s",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_ARM/TARGET_M23/irq_armv8mbl.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_ARM/TARGET_M23/irq_armv8mbl.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/ARM/irq_cm3.s",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_ARM/TARGET_M3/irq_cm3.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_ARM/TARGET_M3/irq_cm3.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/ARM/irq_armv8mml.s",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_ARM/TARGET_M33/irq_armv8mml.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_ARM/TARGET_M33/irq_armv8mml.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/ARM/irq_cm4f.s",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_ARM/TARGET_RTOS_M4_M7/irq_cm4f.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_ARM/TARGET_RTOS_M4_M7/irq_cm4f.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/ARM/irq_ca.s",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_ARM/TARGET_CORTEX_A/irq_ca.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_ARM/TARGET_CORTEX_A/irq_ca.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/GCC/irq_cm0.S",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_GCC/TARGET_M0/irq_cm0.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_GCC/TARGET_M0/irq_cm0.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/GCC/irq_cm0.S",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_GCC/TARGET_M0P/irq_cm0.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_GCC/TARGET_M0P/irq_cm0.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/GCC/irq_armv8mbl.S",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_GCC/TARGET_M23/irq_armv8mbl.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_GCC/TARGET_M23/irq_armv8mbl.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/GCC/irq_cm3.S",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_GCC/TARGET_M3/irq_cm3.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_GCC/TARGET_M3/irq_cm3.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/GCC/irq_armv8mml.S",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_GCC/TARGET_M33/irq_armv8mml.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_GCC/TARGET_M33/irq_armv8mml.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/GCC/irq_cm4f.S",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_GCC/TARGET_RTOS_M4_M7/irq_cm4f.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_GCC/TARGET_RTOS_M4_M7/irq_cm4f.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/GCC/irq_ca.S",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_GCC/TARGET_CORTEX_A/irq_ca.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_GCC/TARGET_CORTEX_A/irq_ca.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/IAR/irq_cm0.s",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_IAR/TARGET_M0/irq_cm0.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_IAR/TARGET_M0/irq_cm0.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/IAR/irq_cm0.s",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_IAR/TARGET_M0P/irq_cm0.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_IAR/TARGET_M0P/irq_cm0.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/IAR/irq_armv8mbl_common.s",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_IAR/TARGET_M23/irq_armv8mbl_common.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_IAR/TARGET_M23/irq_armv8mbl_common.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/IAR/irq_cm3.s",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_IAR/TARGET_M3/irq_cm3.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_IAR/TARGET_M3/irq_cm3.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/IAR/irq_armv8mml_common.s",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_IAR/TARGET_M33/irq_armv8mml_common.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_IAR/TARGET_M33/irq_armv8mml_common.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/IAR/irq_cm4f.s",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_IAR/TARGET_RTOS_M4_M7/irq_cm4f.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_IAR/TARGET_RTOS_M4_M7/irq_cm4f.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/Source/os_systick.c",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/Source/os_systick.c"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/Source/os_systick.c"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Source/IAR/irq_ca.s",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/TOOLCHAIN_IAR/TARGET_CORTEX_A/irq_ca.S"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/TOOLCHAIN_IAR/TARGET_CORTEX_A/irq_ca.S"
     },
     {
       "src_file" : "CMSIS/RTOS2/RTX/Library/cmsis_os1.c",
-      "dest_file" : "rtos/source/TARGET_CORTEX/rtx4/cmsis_os1.c"
+      "dest_file" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Library/cmsis_os1.c"
     }
   ],
   "folders" : [
     {
       "src_folder" : "CMSIS/Core/Include/",
-      "dest_folder" : "cmsis/TARGET_CORTEX_M/"
+      "dest_folder" : "cmsis/CMSIS_5/CMSIS/TARGET_CORTEX_M/Include"
     },
     {
       "src_folder" : "CMSIS/RTOS2/Include/",
-      "dest_folder" : "rtos/source/TARGET_CORTEX/rtx5/Include/"
+      "dest_folder" : "cmsis/CMSIS_5/CMSIS/RTOS2/Include/"
     },
     {
       "src_folder" : "CMSIS/RTOS2/RTX/Include1/",
-      "dest_folder" : "rtos/source/TARGET_CORTEX/rtx4/"
+      "dest_folder" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Include1/"
     },
     {
       "src_folder" : "CMSIS/RTOS2/RTX/Include/",
-      "dest_folder" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Include/"
+      "dest_folder" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Include/"
     },
     {
       "src_folder" : "CMSIS/RTOS2/RTX/Source/",
-      "dest_folder" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/"
+      "dest_folder" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/"
     },
     {
       "src_folder" : "CMSIS/RTOS2/RTX/Source/",
-      "dest_folder" : "rtos/source/TARGET_CORTEX/rtx5/RTX/Source/"
+      "dest_folder" : "cmsis/CMSIS_5/CMSIS/RTOS2/RTX/Source/"
     },
     {
       "src_folder" : "CMSIS/Core_A/Include/",
-      "dest_folder" : "cmsis/TARGET_CORTEX_A/"
+      "dest_folder" : "cmsis/CMSIS_5/CMSIS/TARGET_CORTEX_A/Include/"
     },
     {
       "src_folder" : "CMSIS/Core_A/Source/",
-      "dest_folder" : "cmsis/TARGET_CORTEX_A/"
+      "dest_folder" : "cmsis/CMSIS_5/CMSIS/TARGET_CORTEX_A/Source/"
     }
   ],
    "commit_sha" : [