Mbed Memory Bank Information

This page documents a proposal to add a "memory bank information" feature to the build system of Mbed OS Community Edition.

1. Goals

The Memory Bank Information feature will provide information about the available flash and RAM banks on an MCU to the application and build system. This will allow various pieces of the Mbed system to have a better picture of where & how much memory is available and do useful things with it.

1.1 Intended Users

• C/C++ source code: The Mbed library and application code may be interested in knowing how much memory is available and what addresses it is located at. Current examples include:
  • mbed_stats.c, which collects stats about the total memory available on the device
  • FlashIAPBlockDevice, which would highly benefit from a way to know where the flash starts and ends
  • HAL layer code using DMA, such as the Ethernet MAC drivers, which needs to detect if buffers are inside a given RAM bank or not and use that to control cache handling or decide whether to copy them somewhere else
• memap: This script currently just prints the total RAM and flash usage, but this does not include a percentage of how much of the RAM is actually used. Additionally, it sums all the memory banks together, ignoring the fact that Mbed can only use one contiguous memory bank for static data (dang GNU LD limitations). In both cases, this requires the user to remember annoying details about their specific MCU, like which memory bank Mbed primarily targets and how much space it has.
• Linker scripts: Mbed OS is chock full of copy-pasted linker scripts. In many cases, the only real differences between them are the sizes of memory banks (if even that -- some are identical!). If the linker scripts had well-defined access to information about a target's memory banks, they could use this info to adjust themselves, to some extent, to the current target being compiled for. This, in turn, would let us significantly cut down on the number of duplicate/near duplicate linker scripts in Mbed.
• Custom target users: In many cases, Mbed officially supports one specific variant of an MCU with X amount of memory, but someone wants to develop for another variant with Y amount of memory. Currently, this requires editing the linker script, which is a fairly high barrier to entry (I didn't really learn linker scripts until I'd been employed full time as an embedded SW engineer for over a year). Or, you could not do that, and just hope that the memory layout of your new chip is similar enough to work. With a smarter system to declare memory bank information, and a linker script that is set up to take in that information, making these kind of custom targets could be done without modifying any linker scripts!

1.2 Goals of the proposal

1. Provide memory bank information to Mbed and its tools that conveys:
   1. Where each bank starts and ends
   2. The type of each mem bank (flash vs RAM)
   3. The user identifiable name of each bank (e.g. builtin flash, DTCM, ITCM, etc).
2. Be compatible, within reason, with C/C++ code and JSON files designed for the Mbed CLI 1 memory bank system.
   1. Naming of #defines should not change, though new ones can be added
   2. Where it makes sense, mbed_app.json properties should work in the same way as Mbed CLI 1.

2. Prior Work

As people with experience with Mbed CLI 1 may remember, Mbed OS actually used to have a feature somewhat similar to this. Mbed CLI 1 had behavior where it would read the CMSIS MCU description file, list out the memory banks as #defines, and then add those to the build. However, this feature was... flawed, for several reasons:

• It was not very well documented, making it a bit of a mystery where the memory bank defines came from. Like, by default, they came out of the CMSIS MCU descriptions file, but they could also be overridden via undocumented mbed_app.json/targets.json options.
• It didn't preserve the names of memory banks, losing out on potentially useful information (e.g. which of the memory banks is DTCM and which is general RAM)
• It was unclear to users and developers if it was supposed to declare the memory that exists on a target, or the memory that Mbed should be using. In practice, this led to different people using it in different ways.