Home

RK0 Wiki

Configuring the kernel

• core/kconfig.h contains defines to enable or disable features and other critical configurations.

• It is essential that the number of tasks in your application matches the number defined in RK_CONF_N_USRTASKS, and the lowest effective priority value (the highest number) is defined in RK_CONF_MIN_PRIO (maximum is 31).

• Stack Sizes:

  • Stack addresses are to be aligned to an 8-byte boundary.

  • The stack size must be a multiple of 8. Failing to follow these rules will end up on a crash, sooner or later.

  • As a rule of thumb, the minimal stack size for a task should be 64 WORDs if little work is performed (and FPU is not enabled).

  • If FPU is enabled and the task uses float-point unit math, 96 WORDs is the theoretical minimum. You probably need more.

  • System Stack: normally initial size is defined on linker.ld (for QEMU ARMv7M build is the symbol Min_Stack_Size (in BYTES)). In this case, you need to account for the depth of main(), kApplicationInit(), and all interrupt handlers. Assume interrupts will always add to the worst static depth, and make sure to account for nested interrupts.

The scheduler

In RK0, tasks with the same priority will work cooperatively. This is different from schedulers that employ a time-slice or a quantum for round-robin: after this time expires, task is put at the tail of the Ready Queue.

• A task can assume three states: READY, RUNNING or WAITING. The WAITING state is logically split into different states associated to the waiting condition.
• The scheduler's behaviour is to choose the highest priority READY task to run. Always.
• The scheduler works on a First-In-First-Out discipline for tasks with the same priority.
• A task must switch to the READY state before being eligible for scheduling.
• A task will switch from RUNNING to READY if yielding or if being preempted by a higher priority task. Otherwise it can only go to a WAITING state, and eventually switch back to READY.
• When a task is preempted by a higher priority task, it switches from RUNNING to READY and is placed back on the head position of its Ready Queue. This means that it will be resumed as soon as it is the highest priority ready task again.
• On the contrary, if a task yields, it tells the scheduler it has completed its cycle. Then, it will be enqueued on the ready queue tail - the last queue position.
• When a task waits it is suspended until a condition is satisfied.
• When the condition is satisfied, it switches from WAITING to READY, and is enqueued on the tail.
• So, tasks with the same priority cooperate by either yielding or waiting.
• If a task never yields or waits, other tasks with the same or lower priority will starve.
• Finally, Tasks with the same priority are initially placed on the Ready Queue associated with that priority in the order they are created.

General application structure

app\application.c

#include <board.h> /* platform specific */
#include <kapi.h> /* kernel api */
#include <application.h>  /* application specific */


int main(void)
{
    HAL_Init(); /* board init plls, io, etc. */

    otherInits(); /* 3rd party init filesystems, comm stacks etc */    

    /* RK0 API */
    kCoreInit(); /* init minimal core interrupts for the kernel */
    
    kInit(); /* init scheduler */

    while(1)
    {  
        /* suggested */
        kErrHandler(RK_FAULT_APP_CRASH);   
    }
 
}

/*** Declare kernel objects ***/

/* -- Tasks: */

/* this convenience macro */
RK_DECLARE_TASK(t1Handle, Task1, task1StackBuf, 128) 

/* expands to:
    VOID Task1(VOID *args);                              
    RK_STACK task1StackBuf[128] K_ALIGN(8);                  
    RK_TASK_HANDLE t1Handle;
/*

/* RK_ prefixed macros don’t require a trailing ‘;’ */

/* -- Other objects: e.g., mem allocator, mesg queues, semaphores, etc.,
and any backing storage they need
*/

RK_OBJ_TYPE objInstance;

myAppType_t typeMemPool[N_BLOCKS] K_ALIGN(4);


/* Mandatory function: initialise tasks and other objects  */
VOID ApplicationInit(VOID)
{
   /* initialise tasks and other kernel objects */
   /* low-level scheduler will start when this function returns */
   /* use assertions for init calls */
   /* see kapi.h */
   
}

/* Define Tasks */

/* all task objects must be visible for the unit which 
 task functions are defined */

VOID Task1(VOID* args)
{
   K_UNUSE(args);

   while(1)

   {
      /* task will run until preempted by a higher priority task, 
         blocking or yielding 
      */
   }
}

API Convention

• A kernel call starts with a lowercase k. Typically it is followed by a kernel object identifier and an action.

/* pend on a semaphore; block indefinitely */
kSemaphorePend(&sema, RK_WAIT_FOREVER); 

 /* try to acquire a semaphore token; if unsuccessful return immediately */
kSemaphorePend(&sema, RK_NO_WAIT);

/* pend on a semaphore; return after 800 ticks if no token becomes available */
kSemaphorePend(&sema, 800); 

• When k is followed by an action, it is acting on the caller task.

kSleepDelay(150); /* sleep-delay the caller task for 150 ticks */

• Some calls can act either on the caller or on another task:

/* stores the signal flags of the task identified by task1Handle on ULONG queryVal */

ULONG queryVal;

kTaskFlagsQuery(task1Handle, &queryVal);

/* `NULL` is telling to query the caller's flags */
kTaskFlagsQuery(NULL, &queryVal);

Return Values

• With a few exceptions, kernel calls return a signed (RK_ERR type) error code.
• 0 (RK_ERR_SUCCESS) is a successful operation.
• Any negative value indicates an illegal call (invalid parameters were passed, a blocking call within an ISR, etc.).
• A positive value indicates an unsuccessful operation, but it will not lead to a system failure (e.g., any unsuccessful try operation).