© simplycreate

The Zephyr Guide

Hello.

This book will cover all basic aspects of the Zephyr RTOS, to help you get started quickly. Primarily though it will be concerned with the peripheral API, since this is the most I struggled with starting, and is the least well documented in the official docs. A rough overview is as follows:

  • Environment Setup

  • Kernel API - Primitives

  • Basic Peripherals API

  • Kernel API - Advanced

  • Device Drivers

So buckle up and enjoy the ride...

Introduction

Zephyr is currently the prefered RTOS for new embedded product projects. Especially for IoT related projects. Considering that 99% of embedded projects these days is IoT, it is no surprise that Zephyr is the current mainline RTOS taking on the previous mainstay the freeRTOS.

In this text we will go through the basics of Zephyr, enough to get started quickly. Some advanced topics are later covered including a guide porting to a new board.

Prerequisites

The hardware required to follow along is the BBC micro:bit v2*. And obviously a host computer, preferably running a recent edition of Linux. You should have a good grasp of the C language. Previous knowledege in embedded development (MCUs, reading datasheets, protocols, etc) is certainly helpful.

* Currently the book targets the stm32f103c8t6 bluepill. I'll re-adjust to the micro:bit v2.

Source Code

The source code for this book is available on the Github repository.

Installation

The official docs have a great section on getting the environment setup. (That's about all that's good of the offical docs IMO) See the Getting Started Guide.

A follow up to this, the Application Development page explaining about how to go about creating a new application folder structure from scratch, is also good.

Once you get this under the belt, you're ready to start building Zephyr applications. This book provides easy hand-holding in the initial phases. So flip over, and let's get started.

The Kernel API - Threads

We will now look at the minimum Kernel API required to get going with the Peripherals. We will now look at the Threads API in this section. First the concepts.

Real-Time System

Real-time systems are characterized by the severe consequences that result if logical as well as timing correctness properties of the system are not met. Two types of real-time systems exist: soft and hard. In a soft real-time system, tasks are performed by the system as fast as possible, but the tasks don’t have to finish by specific times. In hard real-time systems, tasks have to be performed not only correctly but on time. Most real-time systems have a combination of soft and hard requirements. Real-time applications cover a wide range, but most real-time systems are embedded.

Real-time software applications are typically more difficult to design than non-real-time applications. This chapter describes real-time concepts.

RTOS

What is an RTOS?

RTOSes include a component called the kernel. The kernel is responsible for task management in a multitasking system.

Multitasking can be achieved without an RTOS. This can be done in a super-loop. Small systems of low complexity are designed this way. It is upto the application to manage the scheduling between tasks. But this is error-prone and most notably, if a code change is made, the timing of the loop is affected.

The RTOS abstracts this away for us. And brings in the concept called threads. A firmware designer splits the related work responsible for a portion of the solution to be done into individual threads. The kernel performs the context switching, ie: save the current thread context (CPU registers) in the current task storage area then resume execution of new code1. Each thread is assigned a priority. Each thread is an infinite loop that can be in any one of the 6 states; see the diagram below.

A task is ready when it can execute but its priority is less than the currently running task. A task is running when it has control of the CPU. A task is waiting when it requires the occurrence of an event (for example, waiting for an I/O operation to complete, a shared resource to be available, a timing pulse to occur, or time to expire). Finally a task is in suspended state when it is explicitly requested by the code (either within itself or another thread).

the 6 thread states

You may want to ask, when should I use an RTOS?

- The answer is ALWAYS. These days the embedded system landscape has changed that such is the case. For example the bluepill2 with 128k flash and 20K RAM can be had for a fraction of a dollar.

In addition to the kernel, an RTOS can include device drivers and peripheral management as in the case of Zephyr. Now that we have an understanding of the kernel and threads, let's see the implementation in Zephyr.

1

This adds overhead, the biggest downsides of using RTOS.

2

https://docs.zephyrproject.org/2.6.0/boards/arm/stm32_min_dev/doc/index.html

Thread Creation

define MY_STACK_SIZE 500
define MY_PRIORITY 5

extern void my_entry_point(void *, void *, void *);

K_THREAD_STACK_DEFINE(my_stack_area, MY_STACK_SIZE);
struct k_thread my_thread_data;

k_tid_t my_tid = k_thread_create(&my_thread_data, my_stack_area,
                                 K_THREAD_STACK_SIZEOF(my_stack_area),
                                 my_entry_point,
                                 NULL, NULL, NULL,
                                 MY_PRIORITY, 0, K_NO_WAIT);

The preceding code spawns a thread immediately. We will study the arguments of the above function one at a time.

&my_thread_data: this is of type struct k_thread defined in thread.h. see definition in docs.

my_stack_area: Pointer to the stack space.

The above C structs must be initialised using the above shown functions before using in the creation function! See here for more info.

my_entry_point: the entry point function (user defined), that takes upto 3 arguments. It's passed 'NULL' in this example.

MY_PRIORITY: the priority assigned for this thread. We will discuss priorities in detail below.

timeout: the amount of time in milliseconds to wait before the kernel actually starts the thread. Here it's K_NO_WAIT; ie 0.

Thread Priorities

There are two classes of threads:

  • cooperative thread (cannot be pre-empted): negative priority. Ideally used for device drivers and critical work.
  • preemptible thread: positive priotity

Note that thread priorities can be changed later in the program. The kernel natively supports unlimited priority levels. But in a real application, it's as follows:

priorities

As can be seen, CONFIG_NUM_COOP_PRIORITIES and CONFIG_NUM_PREEMPT_PRIORITIES specify the limits of usable priority values for the specific application.

Notable thread option

  • K_ESSENTIAL: if the thread terminates, treat as system failure! default: not enabled.

Thread termination

Once a thread is started it runs forever. A thread may terminate by returning to the caller. ie 'return x'. The thread must be responsible for releasing any held resourses. To wait until another thread terminates use k_thread_join(). k_thread_abort() (ungracefully) terminates the thread. Can be also used from within an external thread. It's not recommended to use this function as it leads to unfreed resources.

Notable system threads

These are essential threads that are always present in an application.

main thread

By default has a priority of 0 (highest pre-emptive). Performs kernel initialisation and runs the main() function.

idle thread

Executes when no work. Puts the processor to auto- powersave. Always has the lowest priority.

Delays

Use k_sleep() to do a delay within a thread. k_msleep() is a more useful version where you supply the delay in milliseconds. An inactive thread that's in this state can be woken up from another thread prematurely by k_wakeup(). If the delay is too short to warrant pre-emption use the blocking function k_busy_wait().

Simple thread example

We will see an example built on the above concepts and study it...

#include <zephyr.h>
#include <sys/printk.h>

#define MY_STACK_SIZE 1024
#define MY_PRIORITY 7

void* thread1(void) {
	while(1) {
		printk("thread1\n");
		k_msleep(2000);		// sleep 2s
	}
	return NULL;
}

void* thread2(void) {
	while(1) {
		printk("thread2\n");
		k_msleep(2000);		// sleep 2s
	}
	return NULL;
}

K_THREAD_DEFINE(thread1_id, MY_STACK_SIZE, thread1, NULL, NULL, NULL,
		MY_PRIORITY, 0, 0);
K_THREAD_DEFINE(thread2_id, MY_STACK_SIZE, thread2, NULL, NULL, NULL,
		MY_PRIORITY, 0, 0);

The first line includes the 'zephyr.h' file which in turn includes the kernel. Which enables the kernel subsystem which is the subject of our topic here. The second line imports the print subsytem which we use here to print though the UART.

We are writing two individual thread functions (to keep things simple) that'll be invoked next. Here we are using the short-hand method of creating threads whick is functionally similar to the function explained earlier. This is specified in the docs.

Open up a terminal and fire-up a screen session on the serial device to which the micro:bit is connected to; typically /dev/ttyUSB0. Like so:

> screen /dev/ttyUSB0 115200

You should see a similar alternating prompt output:

thread1
thread2
thread1
thread2
thread1
thread2
thread1
thread2

You may note that the board you're using has several uart peripherals (eg. uart1, uart2). The default one that's used is defined in your board's dts file. It's defined as zephyr,console. In our case it's the uart2.

Basic Peripherals API

In this section we will see how to operate the GPIO, timers and the PWM.

Device Tree 101

Zephyr uses the device tree, a concept borrowed from Linux. It is a prerequisite to understand this before making any additions to the target board (Zephyr has a predefined set of popular boards, see here). However we will cover it now before our discussion on peripheral APIs since they build on this and understanding the device tree could ease the process.

But there is already a good video preliminary on Youtube that'll help you get started. It's quite long (~ 2 hours) and informative. This will help you navigate the device tree specification viewable on devicetree.org to fill in the gaps.

GPIO

We will first discuss the GPIO - the most basic peripheral on an MCU.

As basic functionality of GPIOs, we set the output levels using the following commands:

    gpio_pin_toggle_dt(const struct gpio_dt_spec *spec);

    gpio_pin_set_dt(const struct gpio_dt_spec *spec, int value);

Value 0 sets the pin in logical 0 / inactive state. Any value other than 0 sets the pin in logical 1 / active state.

int i = gpio_pin_get_dt(const struct gpio_dt_spec *spec);

1 – If pin logical value is 1 / active. 0 – If pin logical value is 0 / inactive.

the *_dt functions are a variant for ones without the suffix. For example, gpio_pin_toggle_dt(spec) is:

gpio_pin_toggle(spec->port, spec->pin);

GPIO Config

We must initialse and configure a GPIO pin before we can use it. Use the following command:

gpio_pin_configure_dt(const struct gpio_dt_spec *spec, gpio_flags_t extra_flags);

Remember to set the correct Pin direction [GPIO_INPUT | GPIO_OUTPUT_INACTIVE | GPIO_OUTPUT_ACTIVE] using the flags.

Init Structure

Before we could use the above GPIO API, the gpio struct must be defined and assigned:

static const struct gpio_dt_spec myled = GPIO_DT_SPEC_GET(<node_id>, gpios);

The reference page for GPIO details the above functions and also lists other flags that can be used.

Example - add an external button

This will require writing an overlay file. And use the GPIO API.

First create the boards/ folder in a new app directory. See Installation for creating an empty app template. And in the directory create the file "stm32_min_dev_blue.overlay", with the following contents. This will be the device tree for the external button addition.

/ {
	gpio_keys {
		compatible = "gpio-keys";
		butn: butn {
			label = "Key";
			gpios = <&gpioa 0 GPIO_ACTIVE_LOW>;
		};
	};

	aliases {
		butn0 = &butn;
	};
};

Wire up a button to the stm32 board with a pull up resistor like this:

< image for connecting button to PA0 >

Using the concepts discussed above; here is the final code for button prompted blink:

#include <zephyr.h>
#include <drivers/gpio.h>

/* The devicetree node identifier for the "led0" alias. */
#define LED0_NODE DT_ALIAS(led0)

/*
 * A build error on this line means your board is unsupported.
 * See the sample documentation for information on how to fix this.
 */
static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(LED0_NODE, gpios);
static const struct gpio_dt_spec specb = GPIO_DT_SPEC_GET(DT_ALIAS(butn0), gpios);

void main(void)
{
	int ret;

	if (!device_is_ready(led.port)) {
		return;
	}
	if (!device_is_ready(specb.port)) {
		return;
	}

	ret = gpio_pin_configure_dt(&led, GPIO_OUTPUT_ACTIVE);
	if (ret < 0) {
		return;
	}
	ret = gpio_pin_configure_dt(&specb, GPIO_INPUT);
	if (ret < 0) {
		return;
	}

	while (1) {
		if (gpio_pin_get(specb.port, specb.pin)) {
			gpio_pin_set(led.port, led.pin, 1);
		}
			
		else {
			gpio_pin_set(led.port, led.pin, 0);
		}
	}
}

We will now discuss the code above in detail.

The first line includes the 'zephyr.h' file which in turn includes the kernel. Which enables the kernel subsystem as we saw in the previous chapter.

The second line speaks for itself. It includes the 'gpio' related API functions that we will use here.

Further down we use the function GPIO_DT_SPEC_GET to initialise a LED device C structure, as we have seen in the previous section. We do the same for 'specb' the struct for the button pin.

Then inside main the first thing we do is do the mandatory check to see if the device is ready for use. This indicates whether the provided device pointer is for a device known to be in a state where it can be used with its standard API. Using a device that does not return true for this check, results in undefined behaviour.

This is followed by the pin configuration as we have seen earlieer. Inside the while loop is the program logic. It simply relays the pin state of the button to the LED pin.

This is a very basic demonstration of push button with no debounce mechanism. The led may inadvertently toggle multiple times for a single push.

Interrupts

We will continue on our discussions with the GPIO with looking at interrupts. First for some prerequisites...

An Interrupt Service Routine (ISR) has the following properties:

  • IRQ signal (that triggers the ISR)
  • priority level
  • interrupt handler function
  • argument value passed to the function

Other notable facts:

  • Only a single ISR can be defined for an IRQ
  • But multiple ISRs can utilise the same function
  • Zephyr supports interrupt nesting. ie, higher priority interrupt can interrupt a running ISR

Use the following functions to setup an ISR:

IRQ_CONNECT(MY_DEV_IRQ, MY_DEV_PRIO, my_isr, MY_ISR_ARG, MY_IRQ_FLAGS);
irq_enable(MY_DEV_IRQ);

See Implementation for an example.

Disabling interrupts

To prevent IRQs when a particular thread is running use the functions inside that thread to block (and unblock) any interrupts.

irq_lock()
irq_unlock()

Note that if this thread is pre-empted by another one and is not the active thread, interrupts can occur.

GPIO Interrupts

#include <zephyr.h>
#include <drivers/gpio.h>
#include <sys/util.h>
#include <inttypes.h>

/* 1000 msec = 1 sec */
#define SLEEP_TIME_MS   1000

/* The devicetree node identifier for the "led0" alias. */
#define LED0_NODE DT_ALIAS(led0)

static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(LED0_NODE, gpios);
static const struct gpio_dt_spec specb = GPIO_DT_SPEC_GET(DT_ALIAS(butn0), gpios);

static struct gpio_callback button_cb_data;

void button_pressed(const struct device *dev, struct gpio_callback *cb,
		    uint32_t pins)
{
	gpio_pin_toggle_dt(&led);
}

void main(void)
{
	int ret;

	if (!device_is_ready(led.port)) {
		return;
	}
	if (!device_is_ready(specb.port)) {
		return;
	}

	ret = gpio_pin_configure_dt(&led, GPIO_OUTPUT_ACTIVE);
	if (ret < 0) {
		return;
	}
	ret = gpio_pin_configure_dt(&specb, GPIO_INPUT);
	if (ret < 0) {
		return;
	}
	ret = gpio_pin_interrupt_configure_dt(&specb,
					      GPIO_INT_EDGE_TO_ACTIVE);
	if (ret != 0) {
		printk("Error %d: failed to configure interrupt on %s pin %d\n",
			ret, specb.port->name, specb.pin);
		return;
	}

	gpio_init_callback(&button_cb_data, button_pressed, BIT(specb.pin));
	gpio_add_callback(specb.port, &button_cb_data);

	while (1) {
	}
}

The above is a modified example from the samples folder 'basic->button'. It simply toggles the LED when the button is pushed.

In principle, what we do is write a 'callback function' that'll be called when the interrupt is triggered, by indicating this function in the interrupt setup. The interrupt is setup in the following lines:

gpio_init_callback(&button_cb_data, button_pressed, BIT(specb.pin));
gpio_add_callback(specb.port, &button_cb_data);

The first argument to the 'init' function is the struct defined for this purpose earlier as type: gpio_callback. The second argument is our desired function to run when interrupt triggers.

Much of the code is hopefully self-explanatory. Study the example and follow this layout when you define interrupts in your application.

Timers

Basic timing, there is nothing much to it. We just need a couple of functions for basic timing. If you are familiar with tick based timing in another RTOS, it's exactly the same.

// k_uptime_get_32();        // the original 64bit function is blocking and inefficient, use 32bit if possible

int time_stamp;
int milliseconds_spent;

time_stamp = k_uptime_get_32();

<do stuff>

milliseconds_spent = k_uptime_delta(&time_stamp);

Hardware Timers with Interrupts

Some discussion on nRF52 HW timers:

Block schematic for timer/counter

The timer/counter runs on the high-frequency clock source (HFCLK) and includes a four-bit (1/2X) prescaler that can divide the timer input clock from the HFCLK controller. Clock source selection between PCLK16M and PCLK1M is automatic according to TIMER base frequency set by the prescaler. The TIMER base frequency is always given as 16 MHz divided by the prescaler value.

The good thing about Zephyr's timer API (as with other peripheral APIs) is that it abstracts away all the device specific details...

First we acquire the device timer: In main:

	const struct device *counter_dev;

	counter_dev = device_get_binding(TIMER);
	if (counter_dev == NULL) {
		printk("Device not found\n");
		return;
	}

where TIMER is bound to an appropriately initiated device in the tree. As long as your board/chip is in the Zephyr supported list this has been done for you! All you have to do is to define TIMER to the selected device in your application.

Then the basic principle is that we set a callback function using the alarm_cfg.callback property and setup the 'alarm' using counter_set_channel_alarm(). For this we initiate a counter_alarm_cfg struct to hold the desired counter settings. Also set the desired delay with alarm_cfg.ticks. See the official explanation. Finally call the set alarm function. It has a very similar structure to setting interrupts as seen in the previous topic, considering the alarm is basically an interrupt.

See the sample application in 'samples/drivers/counters/alarm'.

PWM

Breather Led

Step 1: Breather LED

< sample: samples/basic/fade_led >

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut elit ipsum, bibendum eget semper ac, eleifend sit amet ex. In hac habitasse platea dictumst. Morbi tempus metus a nibh blandit condimentum. Quisque quis neque urna. Etiam eget sapien ac lacus accumsan tincidunt nec nec felis. Quisque placerat, justo vitae congue efficitur, est est volutpat magna, sit amet consectetur purus lorem sed neque. Ut aliquet elit a ultrices hendrerit. In hac habitasse platea dictumst. Pellentesque quis eros lacinia, porttitor justo a, suscipit erat. Etiam vestibulum nibh quis mattis laoreet. Aenean sed lacus in massa elementum dapibus. Maecenas at arcu condimentum, consectetur ipsum a, dignissim nibh. Nulla facilisi. Suspendisse potenti. Aliquam eleifend ultrices gravida. Proin lacinia pellentesque faucibus.

Step 2: Breather LED with DMA & Interrupts (Idle CPU)

Kernel Facilities - Messaging

In chapter 2 we saw that the kernel provides context switching. The kernel also performs another duty, it's also responsible for the communication between tasks. In this chapter we will study this.

Semaphores

The easiest way for threads to communicate with each other is through shared data structures. This process is especially easy when all threads exist in a single address space and can reference elements, such as global variables, pointers, buffers, linked lists, and ring buffers, ie use global variables. Although sharing data simplifies the exchange of information, you must ensure that each task has exclusive access to the data to avoid contention and data corruption.

To illustrate the problem, the figure below shows a hypothetical example of two threads reading and writing the same variable. In this example, thread A reads the variable and then writes a new value to it, but the write operation takes two memory cycles. If thread B reads the same variable between the two write cycles, it will see an inconsistent value.

Interleaved memory cycles with two threads

To solve this problem, the threads have to use a lock that will allow only one thread to access the variable at a time.

Test-and-Set Operations

The simplest way to mitigate this situation. Two functions could agree that to access a resource, they must check a global variable and if the variable is 0, the function has access to the resource. To prevent the other function from accessing the resource, however, the first function that gets the resource sets the variable to 1, which is called a test-and-set (or TAS) operation. We would also have to disable the interrupts however. Pseudocode:

Disable interrupts;
if (‘Access Variable’ is 0) {
    Set variable to 1;
    Reenable interrupts;
    Access the resource;
    Disable interrupts;
    Set the ‘Access Variable’ back to 0;
    Reenable interrupts;
} else {
    Reenable interrupts;
    /* You don’t have access to the resource, try back later; */
}

Using Semaphores

A semaphore is a key that your code acquires in order to continue execution. If the semaphore is already in use, the requesting task is suspended until the semaphore is released by its current owner. In other words, the requesting task says: “Give me the key. If someone else is using it, I am willing to wait for it!” Two types of semaphores exist: binary semaphores and counting semaphores. As its name implies, a binary semaphore can only take two values: 0 or 1. A counting semaphore allows values between 0 and < what's the MAX?> In the context of Zephyr, counting semaphores are simply referred as semaphores, while binary semaphores are mutexes(the implementation of which we will see in the next section). Along with the semaphore’s value, the kernel also needs to keep track of tasks waiting for the semaphore’s availability.

A value must be provided when a semaphore is created. This is the desired maximum concurrent threads that can hold the semaphore. Waiting list always starts empty. When a semaphore is accessed by a task this value will get decremented; gradually to zero when no more threads can acquire it... When this happens, we will start seeing threads in the waiting list.

A desired task does a WAIT operation. Semaphore is checked (if > 0), then decremented and handed over. Else the task waits until a predefined timeout. If the semaphore was busy, when it becomes available the task releases by performing a SIGNAL operation, the control is yeilded to the waiting task (semaphore is not incremented!). Any number of threads may wait on a locked mutex simultaneously. When the mutex becomes unlocked it is then locked by the highest-priority thread that has waited the longest. If however, the thread wasn't allowed to acquire the semaphore within the specified timeout, the requesting task is allowed to resume, which may then signal an error to the caller.

See the official docs implementation for function definitions. We will now see an example to illustrate the concept...

#include <zephyr.h>
#include <sys/printk.h>

#define MY_STACK_SIZE 1024
#define MY_PRIORITY 7

K_THREAD_STACK_DEFINE(my_stack_area, MY_STACK_SIZE);
struct k_thread my_thread_data;

K_THREAD_STACK_DEFINE(my_stack_area1, MY_STACK_SIZE);
struct k_thread my_thread_data1;


struct k_sem my_binary_sem;

void print_thread(void *a, void *b, void *c)
{
    if (k_sem_take(&my_binary_sem, K_MSEC(50)) != 0) {
        printk("Input data not available!");
    } else {
        printk("\nEntered..\n");

        //critical section
        k_msleep(4000);      // sleep 4s

        printk("\nJust Exiting...\n");
    }
}

void main(void)
{
    k_sem_init(&my_binary_sem, 1, 1); // configures a binary semaphore by setting its count to 1 and its limit to 1.

    k_thread_create(&my_thread_data, my_stack_area,
                                 K_THREAD_STACK_SIZEOF(my_stack_area),
                                 print_thread,
                                 NULL, NULL, NULL,
                                 MY_PRIORITY, 0, K_NO_WAIT);

    k_msleep(2000);      // delay 2s
    k_thread_create(&my_thread_data1, my_stack_area1,
                                 K_THREAD_STACK_SIZEOF(my_stack_area1),
                                 print_thread,
                                 NULL, NULL, NULL,
                                 MY_PRIORITY, 0, K_NO_WAIT);
    
    while (1)
    {
        /* code */
    }
    
}

Here we are just using a count/limit of 1 (binary semaphore) to keep things simple.

2 threads are being created, one 2 seconds after the first one. But the first thread will sleep for 4 seconds after acquiring the lock. Thus the second thread will not enter immediately after it is called, it will enter 4 – 2 = 2 secs after it is called. And still the output is:

Entered..

Just Exiting...

Entered..

Just Exiting...

instead of:

Entered..

Entered..

Just Exiting...

Just Exiting...

Mutex

In contrast a mutex allows exclusive access to the resource from the thread. This is why it's called binary semaphore. You either have the lock or you don't. It is practically similar to initiating a semaphore with a value of one. Since we've seen the concepts already in the previous topic, you'll be equipped to read the page on Mutexes in the official documentation.

As an aid lookup the test sample on mutex available in the Zephyr source zephyr/tests/kernel/mutex/sys_mutex/.

Message Queues

Device Driver Intro