Porting ChibiOS/RT for Dummies

Porting the operating system on a new platform is one of the most common tasks. The difficulty can range from easy to very difficult depending on several factors.
We can divide in problem in several classes of progressively increasing difficulty:

  • Porting the OS to a different board using the same MCU.
  • Porting the OS to a different MCU belonging to the same family.
  • Porting the OS to another MCU using the same core.
  • Porting the OS to a whole new architecture.

Another kind of port type is porting to another compiler and this is an added complexity level on the above classes. The kernel itself is portable but the port-specific code usually contains compiler specific extensions to the C language and the asm files syntax is almost never compatible.

Porting to a new board

This is the easiest port type, the scenario is that the specific MCU is already supported and a demo exists. This scenario also applies when porting the OS on a custom hardware using a supported MCU. This is the procedure to follow:

  • Create a new directory under ./boards and copy inside the board files from another board using the same MCU.
  • Customize the board files:
    • board.h, this file contains the I/O pins setup for the MCU, it may also contain other board-dependent settings, for example, the clock frequency. Customize this file depending on your target hardware.
    • board.c, this file contains the initialization code, often you just need to customize @p board.h and not this file. If you have some board-specific initialization code then put it here.
  • Create a new directory under the ChibiOS/RT installation directory: ./myprojects/<my_app_name>.
  • Copy an existing demo code under the newly created directory.
  • Customize the following demo files:
    • Makefile, you may edit this file in order to remove the test-related sources and/or add you application source files.
    • main.c, this file contains the demo code, clean it and write your own main() function here, use this file just as a template.
  • Compile your application and debug.

Porting to a closely related MCU

In this scenario all the above steps are required but an analysis must be performed to evaluate the differences between from the supported micro and the target micro. Often the micros just differ for the memory area sizes and a change to the linker script is enough (this file is usually named ch.ld). Chips just having more or less peripherals, everything else being the same or compatible, should not a problem too.
If there are differences in the internal peripherals, for example non compatible interrupt controllers (this happens in the LPC2000 family) or differences in UARTS, timers etc then the port belongs to the following category.

Porting the OS to another MCU using the same core

This kind of port is required when the target MCU has the same core (a common example: ARM7) of a supported MCU but has differences in the internal peripherals.
If this is your case proceed as follow:

  • Create a new directory under ./os/hal/platforms and then name it with the MCU name (or family name). In case of an ARM-based MCUs you also need to create an equally named directory under ./os/ports/<compiler>/<arch> and put there the MCU related files such as the vectors table, see the existing ports for example.
  • Copy into the newly created directory the most closely related existing platform files or the naked template files from ./os/hal/templates.
  • Work out the differences in the drivers or implement them from scratch if you started from the templates.
  • Edit/create the documentation file platform.dox, this is only required if you want to regenerate the documentation including your work.

Usually this kind of ports just require a serial driver (and those are very similar each other) and some code for the interrupt controller (is some cases this one can be part of the core port instead, for example the Cortex-M3 core has an integrated interrupt controller).
When the platform port is completed you can create your application as seen in the previous sections.

Porting the OS to a whole new architecture

This is the hardest scenario, the time required by core ports depends strongly by the target architecture complexity and the level of support you need for the architecture specific features.
As a reference, the MSP430 port took me 2 hours and it worked at the first run, it can be a reference for simple architectures, the ARM Cortex-M3 was painful instead, the architecture enforces you to implement things in a very specific way and I spent 2 week to go through all the documentation and figure out the correct way to implement the port.
Porting an OS to a new architecture is not an easy task and if you have the required experience for such an effort then probably you don't need any advice from me. Just follow the directory patterns and fill the OS template files, the hardest part is decide the correct and efficient way to implement the context switching.

chibios/guides/port_guide.txt · Last modified: 2011/10/03 20:51 by giovanni
Except where otherwise noted, content on this wiki is licensed under the following license:GNU Free Documentation License 1.3