Mistake on this page?
Report an issue in GitHub or email us

Porting HAL modules

Based on criticality and dependency of Mbed OS software stack, we recommend the following order:

  1. Create a basic example (based on the Blinky example).
  2. Bootstrap and entry point.
  3. Serial port (synchronous transfer).
  4. Low power ticker.
  5. Microsecond ticker.
  6. GPIO and IRQ.
  7. RTC.
  8. SPI.
  9. TRNG.
  10. Connectivity.
  11. Flash.
  12. Bootloader.
  13. Pelion Client (optional).
  14. Other HAL modules (optional).

Detailed instructions for porting each module are given in the module-specific sections of this documentation.

Create the example mbed-os-example-blinky

The official mbed-os-example-blinky uses the RTOS, a DigitalOut object and timers. The direct register version of the example doesn't rely on RTOS, GPIO and timers; LED toggling is done directly by accessing hardware registers. Modify the Blinky program you checked out earlier to not use the timer and DigitalOut object:

#include "mbed.h"
#include "MK64F12.h"

void bm_gpio_init(void)
{
    SIM->SCGC5 = SIM_SCGC5_PORTB_MASK;
    PORTB->PCR[22] = PORT_PCR_MUX(1U);
    PTB->PDDR = (1U << 22U);
}

void bm_delay(void)
{
    volatile unsigned int i,j;

    for (i = 0U; i < 100000U; i++) {
        for (j = 0U; j < 100U; j++) {
            __asm__("nop");
        }
    }
}

int main(void)
{
    bm_gpio_init();

    PTB->PSOR = (1U << 22U);

    while (1) {
        PTB->PTOR = (1U << 22U);
      	bm_delay();
    }
}


Bootstrap and entry point

Bootstrap porting instructions.

Mbed OS uses CMSIS for bootstrap. If your target doesn't have a CMSIS implementation (which is distributed in CMSIS pack-form) yet, you'll need to create your own CMSIS files:

  1. Locate CMSIS Device Template files and startup code. On Windows and if uVision is installed, you can find them in the following directories:

    C:\Keil_v5\ARM\PACK\ARM\CMSIS\5.3.0\Device\_Template_Vendor\Vendor\Device\Source
    C:\Keil_v5\ARM\PACK\ARM\CMSIS\5.3.0\Device\_Template_Vendor\Vendor\Device\Include
    
  2. Create linker scripts from the templates.

  3. Implement pin mapping and basic peripheral initialization code.

    At this point, none of the peripherals for the new target has been implemented. To build for this new target with just the bootstrap, create a file called .mbedignore in your mbed-os directory (if one doesn't exist), and add the following entry:

    features/
    events/
    rtos/
    

    This removes dependencies on timers and peripherals that are yet to be ported.

When both the bootstrap and entry point are ready, you should be able to build and run the direct register Blinky program:

cd mbed-os-example-blinky
mbed compile --target <target_name> --toolchain GCC_ARM
mbed compile --target <target_name> --toolchain ARM
mbed compile --target <target_name> --toolchain IAR

Serial Port (synchronous transfer)

Serial port porting instructions.

Serial port porting can be done in two stages: synchronous UART and asynchronous UART. We recommend porting synchronous UART as early as possible, because the HAL Greentea tests require it, and because printf() is a powerful debugging tool.

Low power ticker

Note: Low power ticker is mandatory for any platform that supports it.

Low power ticker porting instructions.

When you finish porting low power ticker:

  1. Remove the rtos entry from the .mbedignore file, because the OS kernel initialization is now possible.
  2. In Blinky, set a breakpoint at osKernelInitialize and make sure it is called.

The Mbed OS doxygen describes LowPowerTicker tests.

Microsecond Ticker

Microsecond ticker porting instructions.

When you finish porting the microsecond ticker, the wait API should work, and the intervals should be exact. You can verify this with printf.

GPIO (write and read) and IRQ

GPIO porting instructions.

The vanilla Blinky program uses GPIO, which is a great tool for debugging with an oscilloscope or logic analyzer. It's a good idea to port GPIO before any other peripherals.

You can now try using the normal Blinky application.

RTC

RTC porting instructions.

RTC is a dependency of SPI (master) tests.

On some targets, RTC is shared with low power ticker and you can only use one of them. On these targets, you must use low power ticker instead of RTC.

SPI (master)

SPI (master) is used to communicate with storage devices that have an SPI interface, such as SD cards. The CI test shield supports an SD card as a slave device, so you can use it to test SPI (master) implementations on evaluation boards that don't have an SPI slave.

TRNG

True random number generator entropy source (TRNG) porting instructions.

If the hardware supports TRNG, you must port it before running Device Management Client, because the client uses TLS, which in turn requires an entropy source.

Connectivity

Porting instructions for all connectivity options.

You can now try running the example applications for your connectivity methods. For example:

Flash

Flash porting instructions.

Flash drivers are required by Device Management Client.

There are two ways to implement flash API: using CMSIS flash algorithms or vanilla C source code. We recommend using vanilla C source code, because it's easier to maintain and upgrade. It's also more portable across different platforms.

Bootloader

Bootloader porting instructions.

The bootloader is a separate application, which needs to be created and integrated into Device Management Client to allow firmware updates.

Device Management Client

You do not need to manually port Device Management Client; when the above modules are ported, you should be ready to demo the Connect and Update functionalities of the Device Management Client.

Other HAL modules (Optional)

You are now ready to port any other HAL modules that your use case and MCU require. These modules are covered in the rest of this document, with the exception of Mbed Cordio, which has its own porting documentation.

Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.