dev builds
themes manual
device status forums
mailing lists
IRC bugs
dev guide

Search | Go
Wiki > Main > RockboxKernel (r14)

The Rockbox kernel


The Rockbox kernel is a simple round-robin cooperative kernel. It consists of thin threads with some means of passing messages and locking data structures.

digraph G { edge [len=1.3]; thread1 -> thread2; thread2 -> thread3; thread3 -> thread1; }

Round-robin scheduling


A thread is simply a normal C function that never returns. It has its own stack, and is executed until it allows the kernel to run another thread. Threads are executed in the order they were created.

The kernel related functions are declared in thread.h and kernel.h.

When the kernel switches the execution to another thread, it is called a context switch. You can force a context switch by calling the yield() function, therefore a forced context switch is often called yielding. A function that may cause a context switch is often called a blocking function, or a function that blocks.

The thread context

The thread context consists of the CPU registers that are normally preserved in normal C calls, plus the stack pointer. The "scratch registers" are not included. Also, no extra registers, such as MAC accumulators or status registers are preserved.

Thread functions

int create_thread(void* function, void* stack, int stack_size, const char *name)

Creates a thread. It is immediately inserted in the list of threads, ready to execute. A thread function must not return. You need to use the remove_thread() function to remove a thread. The thread number is returned by create_thread. It is generally of no interest, but is is needed if you want to remove a thread.

void remove_thread(int threadnum)

Removes a thread from the kernel. The threadnum parameter is the thread number returned by create_thread().

void yield(void)

Forces a context switch. The next thread in the list will be executed.

void sleep(int ticks)

Sleeps for ticks number of system ticks, allowing other threads to execute.

Complete thread example

You create a thread in three steps:
  • Write a C function. The thread function should not take any arguments, and obviously not return anything.
  • Reserve some stack. A normal thread should not use that much stack. If in doubt, use the DEFAULT_STACK_SIZE macro, which should be large enough for simple threads. Most CPU's want the stack long-aligned, so it might be a good idea to use the 'long' type.
  • Call create_thread()

#include "thread.h"

/* My thread function */
void my_thread(void)
   while(1) {

static long my_stack[DEFAULT_STACK_SIZE/sizeof(long)];

void init_my_thread(void)
   create_thread(my_thread, my_stack, sizeof(my_stack), "my thread");

The system tick

There is a general timing mechanism called the system tick. It is a 32-bit counter that is increased HZ times per second. You can read the current tick count in the current_tick global variable.

Tick helper functions


Returns true if the a count is later than b.


unsigned long my_delay = current_tick + HZ;

   if(TIME_AFTER(current_tick, my_delay)) {
      splash(HZ, true, "1 second has passed");


Returns true if the a count is earlier than b.


unsigned long my_delay = current_tick + HZ;

   while(TIME_BEFORE(current_tick, my_delay)) {
   splash(HZ, true, "1 second has passed");

Note: This is (almost) how the sleep() function is implemented.

Tick tasks

You can declare a function to be called on every kernel tick. It will be executed in interrupt context and has to be very short and simple.

int tick_add_task(void (*f)(void))

Adds a tick task to the kernel. Returns 0 on success or -1 on failure.


void my_tick_task(void)
   /* Do something fun */

void my_init(void)

int tick_remove_task(void (*f)(void))

Removes a tick task from the kernel. Returns 0 if it was found and removed or -1 if the task wasn't found in the kernel list.

Event queues

Threads can communicate using event queues. An event queue is a circular buffer of events. A thread can wait for messages to arrive in the queue while other threads are executing. When an event arrives, the thread will receive the event the next time it is scheduled.

An event looks like this:

struct event
    long id;
    void *data;

The id is what identifies this particular event. It can be any 32-bit positive number. Negative numbers are reserved for system events. The data can be anything you want to pass along with the event.

If you want to receive events in your thread, declare a global event queue and you're set.

struct event_queue my_queue;

Before using the queue, you have to initialize it.


Queue functions

Here are the functions for using event queues.

void queue_init(struct event_queue *queue)

Initializes a queue. This must be done before using it.


struct event_queue my_queue;


void queue_delete(struct event_queue *q)

Removes q from the queue list. You should use this function if the queue could be destroyed (like in plugins), otherwise calling of queue_broadcast() or sending an event to this queue could/will do a very bad thing (tm).

void queue_wait(struct event_queue *q, struct event *ev)

Waits for an event to arrive, removes the event from the queue and copies it to the event structure pointed to by ev.


struct event ev;

   queue_wait(&my_queue, &ev);
   if( == 1) {
       splash(HZ, true, "Got event 1");

void queue_wait_w_tmo(struct event_queue *q, struct event *ev, int ticks)

Waits for an event to arrive, removes the event from the queue and copies it to the event structure pointed to by ev. If ticks system ticks have passed, it returns anyway with set to SYS_TIMEOUT.


struct event ev;

   queue_wait_w_tmo(&my_queue, &ev, HZ);
   switch( {
      case 1:
          splash(HZ, true, "Got event 1");
      case SYS_TIMEOUT:
          splash(HZ, true, "Timeout");

bool queue_empty(const struct event_queue* q)

Returns true if a queue is empty


while(queue_empty(&my_queue)) {
   queue_wait(&my_queue, &ev);
   if( == 1) {
       splash(HZ, true, "Got event 1");

void queue_clear(struct event_queue* q)

Empties a queue.

void queue_post(struct event_queue *q, long id, void *data)

Sends an event to a queue. This can be called from another thread or from an interrupt handler.


extern struct event_queue your_queue;

   queue_post(&your_queue, 1, NULL);

int queue_broadcast(long id, void *data)

Sends the event to all threads in the system, including the sending thread.

Protecting your shared data

To protect your shared data, there is a mechanism called a mutex. It is a simple locking mechanism to allow exclusive access to a resource. Mutexes can only be used in a thread context and not in an interrupt handler.

Mutex functions

void mutex_init(struct mutex *m)

Initializes a mutex before it can be used.

void mutex_lock(struct mutex *m)

Attempts to lock a mutex. If it is already locked, it blocks until the mutex is unlocked.

void mutex_unlock(struct mutex *m)

Unlocks a mutex.

Mutex example

struct mutex my_mutex;

void my_protected_function(void)
   /* Do the stuff that requires exclusive access */

void init_my_protected_function(void)

Guidelines for developers

When you develop Rockbox code, you have to be nice to the other threads in the system.

  • Don't spend time in an interrupt handler (or tick task)
  • Yield or sleep every so often. Many threads in the system rely on being executed regularly. If your code performs lengthy operations, like Mandelbrot calculations, you must call yield() once in a while, so the other threads can run.
  • Sleeping is often better than yielding, because the kernel can execute a SLEEP instruction (architecture specific) if all threads are asleep, which will reduce the power consumption.
Edit | Attach | Print version | History: r29 | r15 < r14 < r13 < r12 | Backlinks | View wiki text | More topic actions...
r14 - 20 Jul 2006 - 13:29:10 - LinusNielsenFeltzing
Copyright by the contributing authors.