Porting HAL modules
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.
- 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
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. You can see an example using the CC3220SF-LAUNCHXL board.
Bootstrap and entry point
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:
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 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.
When you finish porting low power ticker:
- Remove the
rtosentry from the
.mbedignorefile, because the OS kernel initialization is now possible.
- In Blinky, set a breakpoint at
osKernelInitializeand make sure it is called.
When you finish porting the microsecond ticker, the
wait API should work, and the intervals should be exact. You can verify this with
GPIO (write and read) and IRQ
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 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) 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.
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.
You can now try running the example applications for your connectivity methods. For example:
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.
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.