Docs › Porting › Port process overview › Porting

Getting a working baseline

Create forks

Please fork or branch the following repositories:

DAPLink.
pyOCD.
FlashAlgo.
Mbed OS. Create a development branch, and name it using the format https://github.com/ARMmbed/mbed-os-new-target.
Mbed OS bootloader.
Blinky.
Device Management Cloud Client example.

Get the Mbed OS source code

The following Mbed CLI commands retrieve and fork the mbed-os-example-blinky code, and redirect mbed-os to point to the newly forked mbed-os repository:

Import the code:

mbed import https://github.com/ARMmbed/mbed-os-example-blinky

Delete the file mbed-os.lib (rm mbed-os.lib on Linux/macOS, del mbed-os.lib on Windows).
Add your fork of mbed-os (change the URL to match your repository).
```
mbed add https://github.com/ARMmbed/mbed-os-new-target mbed-os
```

Set up the upstream remote, and create a branch for the new port.

cd mbed-os
git remote add upstream https://github.com/ARMmbed/mbed-os
git checkout -b <branch_name>

Build the Blinky program for an existing target

To verify that you have a working fork, please build Blinky to a supported target:

cd mbed-os-example-blinky
mbed compile --target K64F --toolchain GCC_ARM
mbed compile --target K64F --toolchain ARM
mbed compile --target K64F --toolchain IAR

Verify the build succeeds. Make sure the program runs correctly, if it fails, please see the debugging page.

You now have a working baseline and are ready to add a new target.

Adding a new target

Add a new target to FlashAlgo

DAPlink requires FlashAlgo to program a target. You need to either write FlashAlgo source code yourself, or use the one provided with your MCU.

This step requires a Windows PC.

Repo: https://github.com/mbedmicro/flashalgo

To add the Flash programming source code to the FlashAlgo repository:
- Add a record to projects.yaml.
- Create a <target>.yaml file in the records/projects directory.
- Create a FlashDev.c file describing the attributes of the new flash device.
- Create a FlashPrg.c file containing all the necessary functions, including Init, UnInit, EraseChip, EraseSector and ProgramPage.
You can use this PR as an example: https://github.com/mbedmicro/FlashAlgo/pull/46/files.
To generate uVision project files, follow the instructions in Develop Setup and Develop in the FlashAlgo documentation.
In Keil MDK, open the project file for your target in \projectfiles\uvision<target>, and build it. The build directory of a successful build will have the files c_blob.c and c_blob_mbed.c; save both files. You will use them in the next step (c_blob.c in flash_blob.c, and c_blob_mbed.c in Flash API).

Add your new target to DAPLink

This step requires a Windows PC.

The new target needs a unique board ID. To get one, please contact your technical account manager or email our support team.

Repo: https://github.com/armmbed/daplink.

Port a target to DAPLink.
Copy the content of c_blob.c into flash_blob.c.
Verify your port by running DAPLink tests.
When all DAPlink tests pass create two PRs:
- One PR against the DAPLink repository.
- One PR against the FlashAlgo repository.

Add your new target to pyOCD

To be able to debug your port:

Wait for your target support to be merged into pyOCD's master branch and released in PyPi. You can then use pip install pyOCD to enable debug.

Setting up to debug Mbed OS programs

Update DAPLink interface firmware

You need to update the new DAPLink interface firmware, which includes the new target support, on your interface MCU.

To include the new target support:

Clone the latest DAPLink firmware with the new target support completed above.
Use the DAPLink instructions to build the DAPLink firmware release package.
Locate the generated .bin or .hex firmware under DAPLink\uvision_release\<your_board_name_if>.
To update the interface firmware:
1. Press the Reset button.
2. Plug the USB cable to the host.
3. Drag-n-drop the interface firmware.

Create GDB pyOCD debug configuration

Install pyOCD. You need the version with the new target support. If you contributed to PyOCD and an updated version hasn't been released yet, you can invoke the local copy:
```
pip install --editable <path_to_pyOCD_with_new_target_support>
```
Make a note of the installation path of pyocd-gdbserver; you'll need it when you set up the debug configuration inside the IDE.
The following example is for Eclipse IDE; find similar settings for Keil and IAR.
1. Under Debugger, point the Executable path and Actual executable path to the pyocd-gdbserver you installed earlier.
  
  For example: /Library/Frameworks/Python.framework/Versions/2.7/bin/pyocd-gdbserver on macOS.
2. In GDB Client Setup, change the executable to arm-none-eabi-gdb, which was part of the GNU Arm Embedded Toolchain you installed earlier.
  
  For example, on Windows, it looks like:
```
C:\Program Files (x86)\GNU Tools ARM Embedded\7 2017-q4-major\bin\arm-none-eabi-gdb.exe
```
  On macOS, it may be:
```
/usr/local/mbed-tools/gcc-arm-none-eabi-7-2017-q4-major/bin/arm-none-eabi-gdb
```
You can use the default values for all other settings.

Porting HAL APIs

Recommended porting order

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

Create a bare metal example (based on the Blinky example).
Bootstrap and entry point.
Serial port (synchronous transfer).
Low power ticker.
Microsecond ticker.
GPIO and IRQ.
RTC.
SPI.
TRNG.
Connectivity.
Flash.
Bootloader.
Pelion Client (optional).
Other HAL modules (optional).

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

Create the bare metal mbed-os-example-blinky

The official mbed-os-example-blinky uses the RTOS, a DigitalOut object and timers. The bare metal 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:

main.cppImport into Mbed IDE

#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:

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

Create linker scripts from the templates.
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 bare metal 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 board that supports it.

Low power ticker porting instructions.

When you finish porting low power ticker:

Remove the rtos entry from the .mbedignore file, because the OS kernel initialization is now possible.
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 boards.

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.