The Rockbox kernel

General

The Rockbox kernel is an advanced priority aware cooperative kernel. It consists of thin threads with some means of passing messages and locking data structures.

Threads

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

Thread functions

struct thread_entry* create_thread(void* function, void* stack, int stack_size, const char *name IF_PRIO(, int priority) IF_COP(, unsigned int core, bool fallback))

The priority is the priority at which the thread is scheduled, as defined in thread.h. The core is the core which you want the thread to run on on dual processor targets (iPod, iriver H10, Sansa e200.) This will generally be "CPU" (the main CPU), but in certain cases may be "COP" (the coprocessor). Fallback defines the behaviour if a thread cannot be created on the selected core - true to attempt to create the thread on the other core, false to fail immediately. Normally, if a thread can't be created on the coprocessor (for example, early Rockbox bootloaders do not initialise the coprocessor correctly) it is desirable to try to create it on the main CPU, however a thread that has not been written with dual core use in mind should not be created on the coprocessor.

void remove_thread(struct thread_entry *thread)

void yield(void)

void sleep(int ticks)

Complete thread example

• 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()

%CODE{"cpp"}% #include "thread.h"

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

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", IF_PRIO(, PRIORITY_BACKGROUND) IF_COP(, CPU, false)); } %ENDCODE%

The system tick

Tick helper functions

TIME_AFTER(a, b)

Example:

%CODE{"cpp"}% unsigned long my_delay = current_tick + HZ;

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

TIME_BEFORE(a, b)

Example:

%CODE{"cpp"}% unsigned long my_delay = current_tick + HZ;

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

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

Tick tasks

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

Example:

%CODE{"cpp"}% void my_tick_task(void) { /* Do something fun */ }

void my_init(void) { tick_add_task(my_tick_task); } %ENDCODE%

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

Event queues

An event looks like this:

%CODE{"cpp"}% struct event { long id; void *data; }; %ENDCODE%

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.

%CODE{"cpp"}% struct event_queue my_queue; %ENDCODE%

Before using the queue, you have to initialize it.

%CODE{"cpp"}% queue_init(&my_queue); %ENDCODE%

Queue functions

void queue_init(struct event_queue *queue)

Example:

%CODE{"cpp"}% struct event_queue my_queue;

queue_init(&my_queue) %ENDCODE%

void queue_delete(struct event_queue *q)

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

Example:

%CODE{"cpp"}% struct event ev;

queue_wait(&my_queue, &ev); if(ev.id == 1) { splash(HZ, true, "Got event 1"); } %ENDCODE%

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

Example:

%CODE{"cpp"}% struct event ev;

queue_wait_w_tmo(&my_queue, &ev, HZ); switch(ev.id) { case 1: splash(HZ, true, "Got event 1"); break; case SYS_TIMEOUT: splash(HZ, true, "Timeout"); break; } %ENDCODE%

bool queue_empty(const struct event_queue* q)

Example:

%CODE{"cpp"}% while(queue_empty(&my_queue)) { calculate(); yield(); } queue_wait(&my_queue, &ev); if(ev.id == 1) { splash(HZ, true, "Got event 1"); } %ENDCODE%

void queue_clear(struct event_queue* q)

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

Example:

%CODE{"cpp"}% extern struct event_queue your_queue;

queue_post(&your_queue, 1, NULL); %ENDCODE%

int queue_broadcast(long id, void *data)

Protecting your shared data

Mutex functions

void mutex_init(struct mutex *m)

void mutex_lock(struct mutex *m)

void mutex_unlock(struct mutex *m)

Mutex example

void my_protected_function(void) { mutex_lock(&my_mutex); /* Do the stuff that requires exclusive access */ mutex_unlock(&my_mutex); }

void init_my_protected_function(void) { mutex_init(&my_mutex); } %ENDCODE%

Guidelines for developers

• 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.

Attachment	Action	Size	Date	Who	Comment
graphaae225bff93c22695ff4c90ef7a45c95.png	manage	2.2 K	27 Jul 2006 - 15:03	UnknownUser
scheduler.png	manage	318.7 K	04 Mar 2007 - 15:09	MiikaPekkarinen	Priority scheduler
scheduler.svg	manage	59.2 K	04 Mar 2007 - 15:21	MiikaPekkarinen	Scheduler image source SVG