APIDOC.md

WeeOs API Documentation

Here you can find details about all the functions provided by WeeOs.

Table of Contents

1. Starting WeeOs
2. weeos.h
   • Functions Provided by weeOs.h
     1. wee_os_launch()
     2. wee_os_addthread()
     3. wee_os_yield()
     4. wee_os_kill()
3. mutex.h
   • Functions Provided by mutex.h
     1. spin_lock_aquire()
     2. spin_lock_release()

Starting WeeOs

The Scheduler can be launched by calling wee_os_launch() from the main function. Before starting the scheduler, tasks have to be added into the the task-list.

A task is basically a function of type void task(void). Each task has an associated task_prop structure that holds information like pointer to the task function, name of the task, weight(in case of weighted_round_robin sheduling), etc.

The flow includes:-

• Defining the task function.
• Declaring a task_prop for the task.
• Filling the task_prop with details of the task.
• Calling wee_os_addthread() to add the task to the task-list.
• The above steps are repeated to add more tasks.
• Calling wee_os_launch() to start the scheduler.

Once the scheduler starts, it automatically runs the first task in the list and keeps on scheduling other tasks as per the selected scheduling algorithm.

An Example where two tasks are being added and the scheduler is being started.

#include <weeOs.h>

void task0(void)
{
    while(1);
}

void task1(void)
{
    while(1);
}

int main()
{
    task_prop task0_data = {
        .task = task0, 
        .name="TASK0"
    };

    task_prop task1_data = {
        .task = task1, 
        .name="TASK1"
    };

    wee_os_addthread(&task0_data);
    wee_os_addthread(&task1_data);
    wee_os_launch(10);

    /* This never runs as wee_os_launch never returns */
    while(1);
}

weeOs.h

#include <weeOs.h>

This is the main header file for the WeeOs and it exposes all the basic functionality of the RTOS. This file has to be included in all projects using WeeOs.

Functions Provided by weeOs.h

1. wee_os_launch(uint32_t quanta)

This function starts the scheduler with the given quanta.

Parameters - uint32_t quanta : This is the quanta per task in ms.

Returns - Void : This function should never return.

2. wee_os_addthread(task_prop *task_property)

This function add the task to the task-list. This has to be called before starting the scheduler. It can also be used by other tasks to spawn new tasks.

Parameters - task_prop *task_property : This is the address of the task property structure of the task to be added.

Returns - Void : This function returns void.

task_prop structure

This structure defines the properties of a task. Members of task_prop:-

• .task : pointer of type void (*task)(void) : This has to be assigned with the task's function.
• .name : pointer of type char * : This has to be filled with the name of the structure.
• .weight : integer of type uint32_t : This has to be assigned with the weight of the task. This is only applicable if the selected scheduling algorithm is weighted_round_robin

Example usage

#include <weeOs.h>

void task0(void)
{
    while(1);
}

int main()
{
    task_prop task0_data = {
        .task = task0, 
        .name="TASK0"
    };

    wee_os_addthread(&task0_data);
    wee_os_launch(10);

    /* This never runs as wee_os_launch never returns */
    while(1);
}

3. wee_os_yield()

This function yields the CPU and forces a reschedule. After this call the task which is next in the task-list gets to run.

Parameters - Void : This funtion doesn't take any arguments.

Returns - Void : This function returns void.

4. wee_os_kill()

This function yields the CPU and removes the caller task from the task-list. After this call the caller task is never re-scheduled.

Parameters - Void : This funtion doesn't take any arguments.

Returns - Void : This function returns void.

mutex.h

#include <mutex.h>

This header provides the support for busy wait spin-locks. The spinlocks have been implemented using hardware support.

Functions Provided by mutex.h

1. int spin_lock_aquire(mutex *lock);

This function tries to get a lock and loops until it gets the lock

Parameters - mutex lock : This is the lock which has to be aquired

Returns - Int : This function always returns 0.

mutex

The mutex type is used to declare locks, it has to be initialized to LOCKED or UNLOCKED.

Example usage

#include <weeOs.h>
#include <mutex.h>

mutex lock = UNLOCKED;

volatile extern int a;

void task0(void)
{
    spin_lock_aquire(&lock);
    a++;
    spin_lock_release(&lock);

    while(1);
}

int main()
{
    task_prop task0_data = {
        .task = task0, 
        .name="TASK0"
    };

    wee_os_addthread(&task0_data);
    wee_os_launch(10);

    /* This never runs as wee_os_launch never returns */
    while(1);
}

2. void spin_lock_release(mutex *lock);

This function releases a lock.

Parameters - mutex lock : This is the lock which has to be released.

Returns - Void : This function returns void.