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.

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 
         (there is no built-in time-slice in the scheduler) 
         See the scheduler behaviour (Handling the scheduler section)
         in the Docbook
      */
   }
}

API Convention

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

kSemaphorePend(&sema, 800); /* pend on a semaphore; 800 ticks time-out */

• 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 failure - an illegal operation.
• A positive value is an unsuccessful operation, but will not lead to a system failure (e.g., any unsuccessful try operation).

---

• Sections explaining the QEMU building system and its integration to VSCode on macOS, Windows, and Linux are available on the Wiki links.

• A comprehensive Docbook explains kernel mechanisms (including the design rationale) and usage examples.

• Besides the QEMU build (on this repository), there are builds for Nucleo boards (on a wiki page). One of these builds doesn’t assume any IDE, and there’s a project for STM32CubeIDE. These can guide you on how to structure your design.

• Currently the kernel only compiles with ARM-GCC and needs the CMSIS-GCC interface (found in core\inc\cmsis_gcc.h).

• www.kernel0.org/blog