Porting to a new platform

While the core library is platform agnostic and written in pure C++, there is also platform dependent code which needs to be written for each supported micro-controller. This article is a high level step-by-step instruction on how write this code.

Overview

The main steps to support a new platform are:

1. Create directories
2. Create meson.build file and adapt build system
3. Implement timer tick function
4. Implement enable/disable IRQ functions
5. Create serial driver
6. Create examples

Create the directory structure

Create a directory for your new platform in cicada/platform/ and in examples/. Both should have the same name and be descriptive of the supported MCU, like stm32f1.

Adapt build system

Create a meson.build file in your new platform directory, use an existing one as template. The minimum requirements for the build file are the list of source files assigned to platform_src_files and the binary suffix assigned to bin_suffix. Depending on your platform, there may be many more settings required, like compiler flags and include paths.

Finally, create a cross build file. Use the existing stm32.cross.build as template. The cicada_build_target must correspond to the names of the directories created before.

Implement timer tick function

Implement E_TICK_TYPE eTickFunction(). The E_TICK_TYPE is defined in defines.h and should usually be an uint32_t. The function must return the number of milliseconds since an arbitrary point of time. Most micro-controller APIs already provide this function, so you can simply forward the call if you use such a library.

Implement enable/disable IRQ functions

Implement eDisableInterrupts() and eEnableInterrupts(). This is required by the library to lock access to buffers by disabling interrupts. It usually forwards to a call of your MCU library or to the according assembly instruction.

Create serial driver

This is usually the largest task when supporting a new platform. Use one of the existing serial drivers as template. Subclass BufferedSerial and implement all the pure virtual functions from ISerial. The functions accessed by the enduser of your serial driver are already implemented in the BufferedSerial base class. It's non-blocking functions copy the data into the read/write buffers. Your task when writing a serial driver is to actually transmit the content these buffers to the serial hardware using an interrupt driven design.

Create an example how to use the serial driver on your new platform

Each micro-controller has different ways on how to configure pins and ports for it's serial hardware. Write an example in the examples/<yourplatform> directory to show how to get your new serial driver running on the new platform. Create a meson.build file and make sure the example compiles and runs on the new micro-controller.