Merge pull request #4 from mbed-ce/dev/add-memory-bank-example

Add memory bank example, improve docs a bit

.github/workflows/compile.yml

@@ -16,19 +16,21 @@ jobs:
           - L452RE_SIMPLE
           - L452RE_CUSTOM_PINMAP
           - L452RE_CUSTOM_CLOCK
+          - L452RC_CUSTOM_MEMORY_MAP
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: recursive
 
-      - name: Install Python dependencies
+      - name: Install python3-venv
         run: |
-            python3 -m pip install -r mbed-os/tools/requirements.txt
+          apt-get update
+          apt-get install -y python3-venv
 
       - name: Build project for ${{ matrix.mbed_target }}
         run: |
             mkdir build && cd build
             cmake .. -GNinja -DUPLOAD_METHOD=NONE -DMBED_TARGET=${{ matrix.mbed_target }} 
-            ninja mbed-os # need to build mbed-os explicitly, or it will not be compiled because there are no executables that use it.
+            ninja

CMakeLists.txt

@@ -3,27 +3,22 @@ cmake_policy(VERSION 3.19)
 
 #### Initialize Mbed OS build system. ####
 ######################################################################################################
-### Block of including .json5 files. Files of this block must be included before the app.cmake
 
-#[[ Set path of mbed_app.json (necessary everytime if mbed_app.json5 is in project) ]]
+#[[ Set path of mbed_app.json (necessary at all times) ]]
 set(MBED_APP_JSON_PATH mbed_app.json5)
 
 ###--------------------------------------------------------------------------------------------------- 
 #[[ This part is dedicated for custom targets only! Settings below activate targets from
-    custom_targets.json5 and upload method config, otherwise functions below should be commented. ]]
+    custom_targets.json5 and upload method config, otherwise lines below should be commented. ]]
 
 #[[ Here set path for custom_targets.json5 (this is our default) ]]
- set(CUSTOM_TARGETS_JSON_PATH custom_targets/custom_targets.json5) 
+ set(CUSTOM_TARGETS_JSON_PATH custom_targets/custom_targets.json5)
 
-#[[ Here you can set path for custom upload config .cmake (optional example) ]]
-# set(CUSTOM_UPLOAD_CFG_PATH ${CMAKE_SOURCE_DIR}/${MBED_TARGET}/${MBED_TARGET}.cmake)
+#[[ Here you can set path for custom upload config.
+    You may delete this line if you don't wish to use Mbed CE upload methods
+    in your project.]]
+set(CUSTOM_UPLOAD_CFG_PATH custom_targets/CustomUploadMethods.cmake)
 
-#[[ Note: For custom target you need also an upload method and we have few options how you can do that
-    - use the variable CUSTOM_UPLOAD_CFG_PATH above
-    - use default expected path for custom targets upload methods where you create your own config
-      MY_PROJECT/custom_targets/upload_method_cfg
-    - of course you can do it by yourself directly via cmake in this file
-   For more visit https://github.com/mbed-ce/mbed-os/wiki/Upload-Methods ]]
 
 ### End of block
 ######################################################################################################
@@ -34,12 +29,11 @@ include(mbed-os/tools/cmake/app.cmake)
 ######################################################################################################
 ### Block of including project folders
 
-#[[ If using a custom target, the subdirectory containing the custom target must be included before 
-    the mbed-os subdir, otherwise the next line should be commented]]
+#[[ Add custom targets subdir first, before mbed-os!]]
 add_subdirectory(custom_targets)
 
 ###--------------------------------------------------------------------------------------------------
-## Add mbed-os subdirectory (necessary everytime)
+## Add mbed-os subdirectory next (necessary everytime)
 add_subdirectory(mbed-os)
 
 ###--------------------------------------------------------------------------------------------------
@@ -57,7 +51,7 @@ add_executable(${CMAKE_PROJECT_NAME} main.cpp)
 
 ######################################################################################################
 ### Link libraries block
-#[[For more about this configuraion visit wiki page MbedOS-configuration
+#[[For more about this configuration visit wiki page MbedOS-configuration
 https://github.com/mbed-ce/mbed-os/wiki/MbedOS-configuration#configuration-via-cmake-files]]
 
 #[[link MbedOS and its libraries (necessary everytime)]]
@@ -71,9 +65,10 @@ target_link_libraries(${CMAKE_PROJECT_NAME}  mbed-os)
 
 ### Set post build (necessary everytime)
 mbed_set_post_build(${CMAKE_PROJECT_NAME})
-#[[Or in case of custom linker script which should be placed like this
-   directory PROJECT_NAME/custom_targets/MBED_TARGET/MBED_TARGET.ld]]
-#mbed_set_post_build(${CMAKE_PROJECT_NAME}  ${CMAKE_SOURCE_DIR}/custom_targets/${MBED_TARGET}/${MBED_TARGET}.ld)
 
-### Build finalize does necessary configuration for debug in most cases (necessary everytime)
+#[[ Note: if you wish to use a custom linker script instead of the default Mbed one for
+   your target, you can do that with mbed_set_post_build(${CMAKE_PROJECT_NAME} path/to/linker_script.ld) ]]
+
+### Call this last, after creating all targets.  It writes out IDE configuration files
+### so that you can run your targets in VS Code.
 mbed_finalize_build()

README.md

@@ -2,11 +2,15 @@
 
 This project shows how to use Mbed OS Community Edition to create custom targets and also defines the standard structure of custom target project from Mbed CE perspective.
 
-This repo includes three different custom targets you can use based on the `NUCLEO_L452RE_P` target.  (No real reason it's this target in particular, it's just a board I happen to use).
+This repo includes four different custom targets you can use based on the `NUCLEO_L452RE_P` target.  (No real reason it's this target in particular, it's just a board I happen to use).
 
 1. `L452RE_SIMPLE`, which is simply a clone of `NUCLEO_L452RE_P` with a different name and some extra compile definitions applied.  This would be an example of creating a custom target for your board by simply aliasing one of the built-in Mbed targets.  This target is created only by `custom_targets.json` and `custom_targets/CMakeLists.txt`.  It contains no source files.
 2. `L452RE_CUSTOM_PINMAP`, which replaces the pinmap files included with Mbed with custom ones.  This is a common task if you are e.g. using a different chip package and want to have correct pin names (for STM32 there is a [generator](https://github.com/mbed-ce/mbed-os/tree/master/targets/TARGET_STM#board-specific-files-pinmap)).
 3. `L452RE_CUSTOM_CLOCK`, which takes it one step further and replaces the system clock configuration code in Mbed with a new source file.  This is a fairly common task if you create a custom board and want to regenerate the clocking code from another source, such as STM32Cube IDE or MCUXpresso.
+4. `L452RC_CUSTOM_MEMORY_MAP`, which shows how to adjust the memory layout of Mbed via [memory bank configuration](https://github.com/mbed-ce/mbed-os/wiki/Mbed-Memory-Bank-Information).  In this specific case, we provide memory bank configs in the linker script for the STM32L452RCT variant of the processor, which has half the flash space.  This will be picked up (via the [MBED_ROM_SIZE define](https://github.com/mbed-ce/mbed-os/blob/0a36502cf55bf36112503e72b59e016c5f7993c7/targets/TARGET_STM/TARGET_STM32L4/TARGET_STM32L452xE/TOOLCHAIN_GCC_ARM/stm32l452xe.ld#L26)) in the linker script and used to adjust the memory available to Mbed.
+    - Note that not every Mbed target currently has a linker script that is set up for this; you should read through your target's linker script before using this method to adjust the RAM or flash size.
+
+To understand how these targets work, review custom_targets/custom_targets.json5, CMakeLists.txt, and custom_targets/CMakeLists.txt.  These files have been extensively commented with details on how the project is set up.
 
 ## How to set up this project:
 

custom_targets/CMakeLists.txt

@@ -66,3 +66,10 @@ endif()
 add_library(mbed-l452re-custom-clock INTERFACE)
 target_sources(mbed-l452re-custom-clock INTERFACE L452RE_CUSTOM_CLOCK/system_clock.c)
 target_link_libraries(mbed-l452re-custom-clock INTERFACE mbed-nucleo-l452re-p)
+
+# Part 4: L452RC_CUSTOM_MEMORY_MAP --------------------------------------------------------------
+
+# As in part 1, we just create this target as an empty target that inherits from the NUCLEO_L452RE_P target.
+add_library(mbed-l452rc-custom-memory-map INTERFACE)
+target_link_libraries(mbed-l452rc-custom-memory-map INTERFACE mbed-nucleo-l452re-p)
+

custom_targets/CustomUploadMethods.cmake

@@ -0,0 +1,21 @@
+# In this file you can specify the upload method configuration for your custom target(s).
+# See here for the list of parameters that can be set:
+# https://github.com/mbed-ce/mbed-os/wiki/Upload-Methods
+
+if(MBED_TARGET STREQUAL "L452RE_SIMPLE" OR
+	MBED_TARGET STREQUAL "L452RE_CUSTOM_PINMAP" OR
+	MBED_TARGET STREQUAL "L452RE_CUSTOM_CLOCK" OR
+	MBED_TARGET STREQUAL "L452RC_CUSTOM_MEMORY_MAP")
+
+	# Enable STM32Cube upload method
+	set(STM32CUBE_UPLOAD_ENABLED TRUE)
+	set(STM32CUBE_CONNECT_COMMAND -c port=SWD reset=HWrst)
+	set(STM32CUBE_GDBSERVER_ARGS --swd)
+
+	# Enable Mbed upload method
+	set(MBED_UPLOAD_ENABLED TRUE)
+
+	# Default is STM32CUBE
+	set(UPLOAD_METHOD_DEFAULT STM32CUBE)
+
+endif()

custom_targets/custom_targets.json5

@@ -1,15 +1,87 @@
 {
+  // This target clones the existing NUCLEO_L452RE_P target without making
+  // any changes other than an extra define.
   "L452RE_SIMPLE": {
     "inherits": ["NUCLEO_L452RE_P"],
     "macros_add": ["MY_CUSTOM_DEFINE=5"],
     "device_name": "STM32L452RETx"
   },
+
+  // This target extends MCU_STM32L452xE and defines a custom pinmap.
   "L452RE_CUSTOM_PINMAP": {
     "inherits": ["MCU_STM32L452xE"],
     "device_name": "STM32L452RETx"
   },
+
+  // This target extends NUCLEO_L452RE_P and defines a custom clock configuration.
   "L452RE_CUSTOM_CLOCK": {
     "inherits": ["NUCLEO_L452RE_P"],
     "device_name": "STM32L452RETx"
+  },
+
+  // This target extends NUCLEO_L452RE_P but remaps the memory for a different chip part number.
+  // This assumes we are using the -C variant of the chip with half the flash space.
+  "L452RC_CUSTOM_MEMORY_MAP": {
+    "inherits": ["NUCLEO_L452RE_P"],
+
+    // When using a MCU name whose data is not included with Mbed, it is mandatory to provide a
+    // memory_banks section.  This provides information about the RAM and flash banks to Mbed.
+    // Also note that you should NOT specify a device_name, as that is only used for Mbed-internal targets
+    // to fetch the memory bank information.
+    "memory_banks": {
+
+          // Internal flash bank.  Size 256k, start address 0x08000000
+          "IROM1": {
+              "access": {
+                  "execute": true,
+                  "non_secure": false,
+                  "non_secure_callable": false,
+                  "peripheral": false,
+                  "read": true,
+                  "secure": false,
+                  "write": false
+              },
+              "default": true,
+              "size": 0x40000,
+              "start": 0x08000000,
+              "startup": true
+          },
+
+          // Internal RAM bank 1.  Size 128k, start address 0x20000000.
+          // Note: Important to list this one first, because the bank listed first will become bank 0, and this
+          // target has a legacy linker script that expects that this bank is bank 0 instead of requesting it by name.
+          "IRAM1": {
+              "access": {
+                  "execute": false,
+                  "non_secure": false,
+                  "non_secure_callable": false,
+                  "peripheral": false,
+                  "read": true,
+                  "secure": false,
+                  "write": true
+              },
+              "default": true,
+              "size": 0x20000,
+              "start": 0x20000000,
+              "startup": false
+          },
+
+          // Internal RAM bank 2.  Size 32k, start address 0x10000000 (though it is also aliased at 0x20020000).
+          "IRAM2": {
+              "access": {
+                  "execute": false,
+                  "non_secure": false,
+                  "non_secure_callable": false,
+                  "peripheral": false,
+                  "read": true,
+                  "secure": false,
+                  "write": true
+              },
+              "default": false,
+              "size": 0x8000,
+              "start": 0x10000000,
+              "startup": false
+          }
+    }
   }
-}
+}