nOS_ThreadCreate

Home

nOS_ThreadCreate

Definition

nOS_Error nOS_ThreadCreate (nOS_Thread *thread,
                            nOS_ThreadEntry entry,
                            void *arg,
                            nOS_Stack *stack,
                            size_t ssize
#ifdef NOS_USE_SEPARATE_CALL_STACK
                           ,size_t cssize
#endif
#if (NOS_CONFIG_HIGHEST_THREAD_PRIO > 0)
                           ,uint8_t prio
#endif
#if (NOS_CONFIG_THREAD_SUSPEND_ENABLE > 0)
                           ,nOS_ThreadState state
#endif
#if (NOS_CONFIG_THREAD_NAME_ENABLE > 0)
                           ,const char *name
#endif
                           );

Description

Create a new thread and add it to the list of threads managed by the scheduler.

Parameters

Parameter		Description
thread		Pointer to a nOS_Thread object needed to store informations used for scheduling, context switching and event waiting. Application is responsible to create a nOS_Thread object per thread to create and pass a pointer of the object to this function.
entry		Pointer to the function that implement the tread. Threads are normally implemented as infinite loop and never return, but if thread joining is enable by configuration, threads can return an error code if needed.
arg		A value that will be passed as thread's parameter. Thread execution can be delayed in time and variable's address should be valid at any time in the application's life cycle.
stack		Pointer to a nOS_Stack array that will be used as thread's stack. Application is responsible to create this array, one stack per thread to create, and pass a pointer to the array to this function.
ssize		Size of the stack passed by parameter in number of nOS_Stack entries, not bytes.
cssize	optional	Size of the call stack to reserve on the stack in number of functions call. It is only needed for AVR ATmega architecture with IAR compiler.
prio	optional	Priority of the tread to create. Priority should be higher or equal to 0 (lowest priority) and lower or equal to NOS_CONFIG_HIGHEST_THREAD_PRIO (highest priority).
state	optional	State of the thread to create. Can be NOS_THREAD_READY (thread is immediately added to list of threads ready to run) or NOS_THREAD_SUSPENDED (thread is created but will not be allowed to run until it is resumed).
name	optional	Pointer to a const string representing the name of the thread. Scheduler don't use this information, it is only useful for application debugging.

Return

Return	Description
NOS_OK	Thread created sucessfully.
NOS_E_INV_OBJ	Pointer to the nOS_Thread object is invalid.
NOS_E_INV_VAL	Some parameters are invalid.
NOS_E_INV_PRIO	Requested priority is higher than allowed by configuration.
NOS_E_INV_STATE	State of the thread given in parameter is invalid.

Notes

1. Application is required to allocate memory used by the kernel; no dynamic memory allocation is done by the kernel. It gives more flexibility and control over memory used by the application to the designer.
2. This function should be called for every thread that need to be created.
3. Each thread should have their own nOS_Thread object and nOS_Stack array: these variables can't be shared between threads.
4. The same function can be used by multiple threads (aka worker thread) provided that each thread have it's own nOS_Thread object and nOS_Stack array.

Example

#include "nOS.h"

#define FOO_STACK_SIZE             64
#define FOO_THREAD_PRIO            1

nOS_Thread FooHandle;
nOS_Stack  FooStack[FOO_STACK_SIZE];

void Foo(void *arg)
{
    NOS_UNUSED(arg);

    while (1) {
        //...

        nOS_Sleep(1);
    }
}

void Systick_Init(void)
{
    // Initialise timer
    // Start timer used as system tick
}

void main(void)
{
    disable_interrupts();

    nOS_Init();
    // Application specific initialisation

    nOS_ThreadCreate(&FooHandle, Foo, NULL, FooStack, FOO_STACK_SIZE, FOO_THREAD_PRIO);

    nOS_Start(Systick_Init);

    enable_interrupts();

    // ...

    while(1) {
        // Idle loop

        // ...
    }
}