Porting Guide

[WORK IN PROGRESS]

Howto port RIOT to a new target

This page will give you an overview on how to proceed if you want port RIOT to a new platform. You will get an overview on the controller and board specific interfaces that need to be implemented and also some of the common pitfalls and misconceptions will be pointed out.

Assumptions

This guide assumes that the port is done in a 'gcc' environment making use of the 'newlib'. In case some other (or none at all) C standard library is used, the part describing the system calls is to be adapted accordingly.

Things to do first:

• know your silicon (get all documentation available)
• get header files for CPU register definitions (you don't want do define them by hand)
• addresses of the memory you want to use
• how to get your binary on the device

The RIOT architecture

Platform independent

• RIOT/core
• RIOT/sys
• RIOT/drivers

Platform dependent

• RIOT/cpu
  Containing controller specific code
• RIOT/boards
  Containing board specific code, as pin definitions etc

The core interfaces

CPU interfaces that have to be implemented

The interfaces that have to be implemented in the CPU specific code are defined in RIOT/core/include/arch/. These cover functions that are essential for the kernel to work like interrupt handling and thread management but also provides interfaces for timers and a generic IO function and power mode management.

List of files:

atomic_arch.h
hwtimer_arch.h
io_arch.h
irq_arch.h
lpm_arch.h
reboot_arch.h
thread_arch.h

Implementing these interfaces is mandatory but not limited to these.

Documentation can be found here

Interfaces to the board

Board specific implementations and definition should lie in its own directory in RIOT/boards/$BOARDNAME. These should cover e.g. GPIO definitions, UART configurations and configurations providing CPU frequency and timer resolutions needed.
Mandatory however are:

• Definitions of macros to control LEDs on the board:

#define LED_GREEN_ON        ....
#define LED_GREEN_OFF       ....
#define LED_GREEN_TOGGLE    ....
#define LED_RED_ON          ....
#define LED_RED_OFF         ....
#define LED_RED_TOGGLE      ....

• Definition of the CPU frequency:

#define F_CPU   (24000000UL)

• Implementation of board_init function which gets call immediately after startup code and before kernel initialization.

void board_init(void)
{
    ....
}

Also, for each board there has to be a Makefile.include providing information on the development environment. This covers the toolchain and its flags, the tool used to flash the binary and defines the CPU used for this board. Examples can be found in RIOT/boards/

Standard Peripheral Driver Interface

Work is in progress to unify interfaces for drivers of peripheral hardware modules. This will increase portability and provides consistent usage of drivers. To follow the progress watch RIOT/drivers/include/periph/