mbed SDK porting

Table of Contents

  1. Coding style
  2. Build System
  3. CMSIS Module
  4. mbed HAL
  5. Testing
  6. Contributing

This content relates to a deprecated version of Mbed

Mbed 2 is now deprecated. For the latest version please see the Mbed OS documentation.

For the latest information about porting, please see our porting guide.

The porting of the mbed SDK to a new target is divided in four steps:

  1. Add the new target to the build system
  2. Add a CMSIS module for the given target
  3. Implement the mbed HAL API for the given target
  4. Validate the new target with the test suite

The source code of the mbed SDK (tools + libraries) is available in this repository: https://github.com/ARMmbed/mbed-os

Before starting the mbed SDK porting, you might want to familiarize with the mbed library internals first.

For discussing the development of the mbed SDK itself (Addition/support of microcontrollers/toolchains, build and test system, Hardware Abstraction Layer API, etc) please join our mbed-devel mailing list.

Coding style

mbed SDK coding style is described in detail in mbed SDK team's wiki page, please visit for further details mbed SDK coding style

Build System

You can get an introduction about the mbed SDK command line tools, from a user perspective, reading the mbed-tools handbook page.

Adding a new target to the build system is as easy as adding a new Target to this json file: hal/targets.json

For example, this is the Target class for the LPC1768:

    "LPC1768": {
        "inherits": ["LPCTarget"],
        "core": "Cortex-M3",
        "extra_labels": ["NXP", "LPC176X", "MBED_LPC1768"],
        "supported_toolchains": ["ARM", "uARM", "GCC_ARM", "GCC_CR", "IAR"],
        "progen": {"target": "mbed-lpc1768"},
        "detect_code": ["1010"],
        "device_has": ["ANALOGIN", "ANALOGOUT", "CAN", "DEBUG_AWARENESS", "ERROR_PATTERN", "ETHERNET", "I2C", "I2CSLAVE", "INTERRUPTIN", "LOCALFILESYSTEM", "PORTIN", "PORTINOUT", "PORTOUT", "PWMOUT", "RTC", "SEMIHOST", "SERIAL", "SERIAL_FC", "SLEEP", "SPI", "SPISLAVE", "STDIO_MESSAGES"],
        "release_versions": ["2", "5"]
},

The target and toolchain specified for a given build define a set of TARGET_ and TOOLCHAIN_ "labels". For example:

Targets:
  * LPC1768 : ['TARGET_LPC1768', 'TARGET_M3', 'TARGET_LPC176X']
  * LPC11U24: ['TARGET_LPC11U24', 'TARGET_M0', 'TARGET_LPC11UXX']
  * KL25Z   : ['TARGET_KL25Z', 'TARGET_M0P']

Toolchains:
  * ARM    : ['TOOLCHAIN_ARM_STD', 'TOOLCHAIN_ARM']
  * uARM   : ['TOOLCHAIN_ARM_MICRO', 'TOOLCHAIN_ARM']
  * GCC_ARM: ['TOOLCHAIN_GCC_ARM', 'TOOLCHAIN_GCC']
  * IAR    : ['TOOLCHAIN_IAR']

When the build system scans for resources to be compiled, it filters out all the TARGET_ and TOOLCHAIN_ directories that are not in the set of "labels" defined by the current build.

IDE

You can develop the code for adding support for a new target in you favourite IDE. As a starting point, you can export one of the following program to one of the supported offline toolchains:

Import programmbed-src-program

Hello World program using the mbed library sources

Last commit 14 Jun 2013 by mbed official

CMSIS Module

Each target has its standalone CMSIS directory under its vendor directory, for example:

CMSIS Sources

There are three sources for a "cmsis" module used by an mbed target.

The ARM CMSIS-CORE module is providing the files that are specific to the Cortex-M cores:

  • core_cmFunc.h
  • core_cmInstr.h
  • cortex_cm0.h / cortex_cm0plus.h / core_cm3.h / cortex_cm4.h

The Silicon Vendor is providing the files for the startup, system initialization, the structures and addressed of the peripherals registers, for a given DEVICE:

  • startup_DEVICE.s
  • system_DEVICE.c
  • system_DEVICE.h
  • DEVICE.h

The mbed SDK has to provide additional files to dynamically set the vector table and to configure the memory model for the given C standard library:

  • cmsis_nvic.c
  • cmsis_nvic.h
  • sys.cpp
  • TARGET.sct
  • cmsis.h

CMSIS sources

Usually, silicon vendors provide source packages containing both the CMSIS-CORE and the CMSIS device specific files.

mbed HAL

Each target does have a standalone directory containing the implementation of the mbed HAL API, for example:

Probably the most important file, at the beginning of a port to a new target, is device.h.

device.h contains all the defines that enable/disable the inclusion of a certain set of peripherals in the mbed library.

When you start a port for a new target, setting all these defines to 0 will quickly allow you to compile the whole mbed library and start running tests.

Currently, the bare minimum you should implement to start running the first tests is:

Having this initial block in place will allow you to run simple programs like the mbed hello world:

#include "mbed.h"

DigitalOut myled(LED1);

int main() {
    while(1) {
        myled = 1;
        wait(0.2);
        myled = 0;
        wait(0.2);
    }
}

This is the full list of the mbed drivers API that could be potentially implemented for a target:

Testing

The mbed SDK provides a test system to validate the addition of your new target.

You may want to familiarize with the command line interface and structure of the test system reading the mbed-tools handbook page.

The description of the tests aimed at validating the mbed SDK are prefixed with the string "MBED:".

pinout

You will need to edit the source code of many of the tests adding, under conditional compilation, the pinout of your new target board.

automation

Not all the tests are yet automated presenting a clear {success}/{failure} result string. Some of the tests still require additional instrumentation like a logic analyser and human intervention to verify the output.

Smoke Test

[ 0] MBED: Basic is the first smoke test that represents the basis to execute all the other tests in the mbed SDK suite. 

#include "test_env.h"

int main() {
    notify_completion(true);
}

This is an example command line test run:

mbed> python workspace_tools\make.py -m LPC1768 -t ARM -s COM41 -d E:\ -p 0

>>> BUILD PROJECT: BASIC (LPC1768, ARM)
Compile: main.cpp
Compile: test_env.cpp
Link: basic
Elf2Bin: basic
Image: C:/Users/xxxx/mbed/build\test\LPC1768\ARM\MBED_A1\basic.bin
{success}
{end}

C/C++ environment initialization

  • MBED: Heap & Stack - setting of the single area memory model with heap and stack collision detection.
  • MBED: C++ - initialization of static C++ objects

Digital I/O and IRQ

For this set of tests you will need to connect together a pair of pins:

  • MBED: DigitalInOut - Setting digital I/O functionality, direction and value.
  • MBED: InterruptIn - Triggering and handling of GPIO IRQs

Timing functionalities

For this set of functionalities it is preferable to use a logic analyser to verify the correctness of the time intervals. Ideally the following tests should be repeated changing the time periods across a wide time interval (from micro-seconds, to seconds):

  • MBED: Time us - simple us_ticker init/read functionality
  • MBED: Ticker 2 - correct triggering of timing events

PWM

For this set of functionalities it is preferable to use a logic analyser to verify the correctness of the time intervals. Ideally the following tests should be repeated changing the time periods across a wide time interval (from micro-seconds, to seconds):

  • MBED: PWM - PWM

I2C

The I2C tests require the wiring of additional peripherals:

SPI

The SPI tests require the wiring of additional peripherals:

UART

The basic UART functionalities are used to communicate the results of all the other test, but the following tests are stressing some of the other UART APIs:

  • MBED: Serial Echo at 115200 - change baud rate to 115200 and test transmission
  • MBED: Serial Interrupt and MBED: Serial Interrupt 2 - serial tx/rx interrupt handlers

ADC/DAC

This test relies on a connection among one ADC pin and one DAQ pin on the same target:

  • MBED: Analog

Port

Testing the Port API requires connecting at least a couple of pins from a port to a couple of pins in another port:

  • MBED: PortInOut

RTC

  • MBED: RTC

Sleep

  • MBED: Sleep
  • MBED: Sleep Timeout

Semihosting

The following tests are used to verify the semihosting functionalities that may be provided by the "mbed interface"

  • MBED: semihost file system - Local file system
  • MBED: Semihost - mbed unique ID
  • MBED: SW Reset - request to the interface chip a complete reset

Contributing

To contribute your new target to the official mbed SDK:

  1. Open a "pull request" to the official mbed SDK repository, containing:
    • all the changes to the C/C++ libraries and the Python tools.
    • information about the reference target board
  2. logged in with your mbed.org account, sign our Apache Contribution Agreement and send us a Private Message with the URL of the "pull request".
All wikipages