You are viewing an older revision! See the latest version

mbed SDK porting

Table of Contents

  1. Build System
  2. CMSIS Module
  3. mbed HAL API
  4. Testing
  5. Contributing

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/mbedmicro/mbed

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

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 class to this python module: workspace_tools/targets.py

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

class LPC1768(Target):
    def __init__(self):
        Target.__init__(self)
        
        self.core = "Cortex-M3"
        self.vendor = "nxp"
        
        self.supported_toolchains = ["ARM", "GCC_ARM", "GCC_CS", "GCC_CR", "IAR"]

An instance of this new Target class has to be added to the TARGETS list:

TARGETS = [
    LPC2368(),
    LPC1768(),
    LPC11U24(),
    KL25Z()
]

When scanning for source code to be compiled, directories named like one of the TARGETS are considered "target specific" and get included only if they match with the desired microcontroller target name.

Target directory names

The target directory names will have to match the name (case sensitive) of the Target.

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 projects to one of the supported offline toolchains:

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 API

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/emimon01/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