Port a ChibiOS based application to another platform

Port a ChibiOS based application to another platform

Published on Updated on Posted by CategoryChibiOS - Further readings

Intro

We already talked about ChibiOS/HAL design and its multiple architectures support. This is very important for regular developers: imagine a scenario in which you design an application using a certain MCU and after a first stage you decide to upgrade your application. Imagine also that hardware resources on the MCU you decided to use are not enough to make that upgrade. At that point you have to port application on another MCU and this could cost a big effort in terms of time/money.
If your application is ChibiOS based and you followed some guidelines already introduced in C Library design for embedded applications or HAL portability, the effort needed to port you application could be reduced.

Some clarifications

To make things simplest let’s do some clarifications:

  • When we say MCU or platform we are talking about the specific microcontroller, when we say board we are talking about the pcb containing, among other devices, the MCU; so STM32F303 is a MCU and STM32F3 Discovery is a board;
  • There is a big difference between architecture and family. ARM-Cortex M is an architecture, STM32 is a family; TIVA, SAM and STM32 have the same architecture but they belong to different families;
  • If ChibiOS/HAL supports a certain peripheral of a certain MCU it is not true that it supports the same peripheral for the whole family. This because substantially some peripherals could be different from MCU to MCU even if they are from the same family;

So, before to port our application ChibiOS based on a new platform we have to answer some questions. This will define what we need to do:

  • Is ChibiOS/RT or ChibiOS/NIL supporting our new MCU?
  • What peripherals is our application using? Is ChibiOS/HAL supporting these peripherals for the new considered platform?
  • There is an official demo for our board?

Case analysis

We would not explain how to solve every case we are going to enumerate and it would require much more than a simple article. Anyway, we will provide an overview of cases ordered by worst to best.

ChibiOS is not supporting our MCU

Brave users can undertake this port scenario. To do this, user must understand details about MCUs architecture and produce a new ChibiOS port layer. Note that often community provides and maintains port for several MCUs: consulting forum is always a good idea. We have planned to provide more explanation on this procedure so stay tuned!.

ChibiOS is supporting our MCUs but not every used peripheral

Here things are less complicated than previous case. As we are coming from a fully supported platform, ChibiOS/HAL already provides an almost complete API. Brave users can try to develop the low level driver. In this case here some suggestions:

  • Check the forum: most likely someone had the same your problem;
  • Take a look to ChibiOS/HAL design article;
  • Take a look to C Library design for embedded applications article;
  • If HAL supports that driver for another platform from the same family exploring the code could be good as guideline;
  • Embrace the MCU’s Reference Manual;
  • Embrace the MCU’s Reference Manual (This repetition is not an error);
  • Here we provided some complex drivers as tutorial (see nRF24L01 or HD44780): they could be a good example about driver design;
  • Interact with ChibiOS community and don’t forget to share your code.

ChibiOS is supporting our MCU and every peripheral we need for, but there is no demo about my board

This case is the most frequently one as it responds to typical scenario in which user is using an unofficial board or has reached an advanced development step and he creates its own PCBs containing a specific MCU. In this case we have to create a working project for our board before doing the application port. This is the much interesting case and it will be the main topic of this article starting from paragraph number 4.

ChibiOS is supporting our MCU and every driver we need for, even more there is a demo on my board

This case is the simplest one. We can start to port our application creating a new project from the official demo editing hardware related code.

Our case study

To explain how to port our application (if ChibiOS is supporting our MCUs and every peripheral we need for), let’s make an example. I just create an application based on STM32F3 Discovery. Now I would like to port this application on a custom board based on STM32F401xC.

Creating a working demo

Let’s pretending that there is no official demo on STM32F401C. So, we are going to create a working demo starting from the STM32F4 Discovery official demo. First step is create a new project making a copy of the STM32F4 demo editing debug configuration properly. Now we have to create our own board files. This procedure could be simplified using a configuration file to automatically generate board.h, board.c and board.mk.
We already talk about board files during early tutorial. During HAL start-up, precisely when main() calls halInit(), these file are used to configure MCU pins. Configuration depends on what is connected to our pin. Remember that we can overwrite these configuration at runtime using PAL driver APIs like palSetPadMode(). By the next short video we will demonstrate how to create new board file starting from a configuration file.

Of course file created on video are for demo purpose only: to use STM32F401 Discovery board we have at least to configure SWD pins used by the ST-link V2. Even more we should configure LED and button pins properly (info about board electrical connections are provided by user manual or they are known by the custom board developer). Note that actually STM32F401C Discovery already has board files into the folder chibios3\os\hal\boards\ST_STM32F401C_DISCOVERY.
Now, we can proceed editing makefile. We have just to edit few line under the section Project, sources and paths. Let’s make an example: the next codebox is a piece of makefile from the STM32F3 Discovery official demo:

# Project, sources and paths
#
# Define project name here
PROJECT = ch
# Imported source files and paths
CHIBIOS = ../../..
# Startup files.
include $(CHIBIOS)/os/common/ports/ARMCMx/compilers/GCC/mk/startup_stm32f3xx.mk
# HAL-OSAL files (optional).
include $(CHIBIOS)/os/hal/hal.mk
include $(CHIBIOS)/os/hal/ports/STM32/STM32F3xx/platform.mk
include $(CHIBIOS)/os/hal/boards/ST_STM32F3_DISCOVERY/board.mk
include $(CHIBIOS)/os/hal/osal/rt/osal.mk
# RTOS files (optional).
include $(CHIBIOS)/os/rt/rt.mk
include $(CHIBIOS)/os/rt/ports/ARMCMx/compilers/GCC/mk/port_v7m.mk
# Other files (optional).
include $(CHIBIOS)/test/rt/test.mk
# Define linker script file here
LDSCRIPT= $(STARTUPLD)/STM32F303xC.ld

And this is the same piece from STM32F401C Discovery official demo:

# Define project name here
PROJECT = ch
# Imported source files and paths
CHIBIOS = ../../..
# Startup files.
include $(CHIBIOS)/os/common/ports/ARMCMx/compilers/GCC/mk/startup_stm32f4xx.mk
# HAL-OSAL files (optional).
include $(CHIBIOS)/os/hal/hal.mk
include $(CHIBIOS)/os/hal/ports/STM32/STM32F4xx/platform.mk
include $(CHIBIOS)/os/hal/boards/ST_STM32F401C_DISCOVERY/board.mk
include $(CHIBIOS)/os/hal/osal/rt/osal.mk
# RTOS files (optional).
include $(CHIBIOS)/os/rt/rt.mk
include $(CHIBIOS)/os/rt/ports/ARMCMx/compilers/GCC/mk/port_v7m.mk
# Other files (optional).
include $(CHIBIOS)/test/rt/test.mk
# Define linker script file here
LDSCRIPT= $(STARTUPLD)/STM32F401xC.ld

Mainly, differences are on lines where we are including files which have mk extension (we talked about these files in the already mentioned articles). Just note that if we want to use our custom board file we had to properly edit the string:

include $(CHIBIOS)/os/hal/boards/ST_STM32F401C_DISCOVERY/board.mk

Proceeding in our porting, we had to replace mcuconf.h with once copied from a demo that uses our same MCU. As our MCU is supported, we will have for sure this demo under the folder chibios3\os\demos or chibios3\os\testhal. We should edit main creating two threads: once making a led blinking and another launching the test suite on button press. If project doesn’t compile returning errors that sounds like “no rule to make target” most likely something is gone messed up in the makefile paths.

Porting our application

At this point we are in the simplest case in which ChibiOS is supporting our MCU and every needed peripheral, furthermore we have just created a working demo for our board. We can proceed making another project duplicating the last one (it is a good idea to have a backup of a working demo for our board). Now we have to:

  • Adding any user library still acting on makefile; If code has been written with some criteria there will be few or little edit to do on it. Indeed if code is well designed, hardware depending parts should be clustered in main.c or even so in a restricted piece of code.
  • Update PAL related code since most likely pin map is changed.
  • Update drivers configuration (as example spiConfig, i2cConfig, pwmConfig, etc.) since most likely they are changed. Making an example if we port from STM32F3 to STM32F4 an application that uses SPI driver the spiConfig structure changes.

Concluding we often talked about ChibiOS design and its portability, but even if the HAL or the RTOS are well design if we do not design our applications we will lose certain properties like portability or Real Time capability. Quoting Giovanni Di Sirio, the creator of ChibiOS:

There are no magic bullets.

Be the first to reply at Port a ChibiOS based application to another platform

Leave a Reply