Wiring OS API

Description
A wrapper to CMSIS (Cortex Microcontroller Software Interface Standard) OS API which serves as an RTOS to create the multi-threaded application with real-time behavior.

Syntax
NA

Members

os_thread_create

Description
Create a thread and add it to Active Threads and set it to state READY.

Syntax
uint32_t os_thread_create(void (*task)(const void *argument), void *argument, int priority, uint32_t stack_size);

Parameters
task: task Function pointer which is the thread body. It should not run into the end of function unless os_thread_terminate is invoked
argument: the data pointer which brings to task
priority: The underlying os is FreeRTOS. It executes tasks with highest priority which are not in idle state.
stack_size: The stack_size is used as memory heap only for this task.

Returns
The thread id which is used in thread operation and signalling.

Example Code
NA

Notes and Warnings
NA
 

os_thread_get_id

Description
Return the thread ID of the current running thread

Syntax
uint32_t os_thread_get_id(void);

Parameters
The function requires no input parameter.

Returns
Current thread id which calls os_thread_get_id.

Example Code
NA

Notes and Warnings
NA
 

os_thread_terminate

Description
Terminate execution of a thread and remove it from Active Threads

Syntax
uint32_t os_thread_terminate(uint32_t thread_id);

Parameters
thread_id: Terminate the thread with specific thread_id

Returns
os_status code

Example Code
NA

Notes and Warnings
Thread should not ended without terminate first.
 

os_thread_yield

Description
Pass control to next thread that is in state READY

Syntax
uint32_t os_thread_yield(void);

Parameters
The function requires no input parameter.

Returns
os_status code

Example Code
NA

Notes and Warnings
By default, the minimal execution unit is 1 millisecond. In a scenario that if a thread with smaller want to handout execution right to a thread with higher priority immediately without waiting for the ending of current 1 millisecond, then invoke os_thread_yield can transfer exection right to OS’s idle task and check which is the next execution thread.
 

os_thread_set_priority

Description
Change priority of an active thread

Syntax
uint32_t os_thread_set_priority(uint32_t thread_id, int priority);

Parameters
thread_id: The target thread with the thread id to be changed
priority: The updated priority

Returns
The function returns nothing.

Example Code
NA

Notes and Warnings
NA
 

os_thread_get_priority

Description
Get current priority of an active thread

Syntax
uint32_t os_thread_get_priority(uint32_t thread_id);

Parameters
thread_id: The target thread with the thread id to be searched

Returns
os_priority

Example Code
NA

Notes and Warnings
NA
 

os_signal_set

Description
Set the specified Signal Flags of an active thread

Syntax
int32_t os_signal_set(uint32_t thread_id, int32_t signals);

Parameters
thread_id: Send signal to a thread with the thread id
signals: the signals to be send

Returns
os_status code

Example Code
NA

Notes and Warnings
NA
 

os_signal_clear

Description
Clear the specified Signal Flags of an active thread

Syntax
int32_t os_signal_clear(uint32_t thread_id, int32_t signals);

Parameters
thread_id: Clear signal to a thread with the thread id
signals: The signals to be clear

Returns
os_status code

Example Code
NA

Notes and Warnings
NA
 

os_signal_wait

Description
Wait for one or more Signal Flags to become signaled for the current RUNNING thread

Syntax
os_event_t os_signal_wait(int32_t signals, uint32_t millisec);

Parameters
signals: the signals to be wait
millisec: the timeout value if no signal comes in. Fill in 0xFFFFFFFF for infinite wait

Returns
os_status code

Example Code
NA

Notes and Warnings
NA
 

os_timer_create

Description
Create a timer

Syntax
uint32_t os_timer_create(void (*callback)(void const *argument), uint8_t isPeriodic, void *argument);

Parameters
callback: The function to be invoke when timer timeout
isPeriodic: OS_TIMER_ONCE or OS_TIMER_PERIODIC
argument: The argument that is bring into callback function

Returns
timer id

Example Code
NA

Notes and Warnings
NA
 

os_timer_start

Description
Start or restart a timer

Syntax
uint32_t os_timer_start(uint32_t timer_id, uint32_t millisec);

Parameters
timer_id: The timer id obtained from by os_timer_create
millisec: The delays after timer starts

Returns
os_status code

Example Code
NA

Notes and Warnings
NA
 

os_timer_stop

Description
Stop the timer

Syntax
uint32_t os_timer_stop(uint32_t timer_id);

Parameters
timer_id: The timer id obtained from by os_timer_create

Returns
os_status code

Example Code
NA

Notes and Warnings
NA
 

os_timer_delete

Description
Delete a timer that was created by os_timer_create

Syntax
uint32_t os_timer_delete(uint32_t timer_id);

Parameters
timer_id: The timer id obtained from by os_timer_create

Returns
os_status code

Example Code
NA

Notes and Warnings
NA
 

os_semaphore_create

Description
Create and Initialize a Semaphore object used for managing resources

Syntax
uint32_t os_semaphore_create(int32_t count);

Parameters
count: The number of available resources

Returns
semaphore ID

Example Code
NA

Notes and Warnings
NA
 

os_semaphore_wait

Description
Wait until a Semaphore token becomes available

Syntax
int32_t os_semaphore_wait(uint32_t semaphore_id, uint32_t millisec);

Parameters
semaphore_id: semaphore id obtained from os_semaphore_create
millisec: timeout value

Returns
os_status code

Example Code
NA

Notes and Warnings
NA
 

os_semaphore_release

Description
Release a Semaphore token

Syntax
uint32_t os_semaphore_release(uint32_t semaphore_id);

Parameters
semaphore_id: semaphore id obtained from os_semaphore_create

Returns
os_status code

Example Code
NA

Notes and Warnings
NA
 

os_semaphore_delete

Description
Delete a Semaphore that was created by os_semaphore_create

Syntax
uint32_t os_semaphore_delete(uint32_t semaphore_id);

Parameters
semaphore_id: semaphore id obtained from os_semaphore_create

Returns
os_status code

Example Code
NA

Notes and Warnings
NA
 

os_get_free_heap_size

Description
Return the available heap memory space when called

Syntax
size_t os_get_free_heap_size(void);

Parameters
The function requires no input parameter.

Returns
The function returns the current free heap size

Example Code
Example: MemInfo
This example shows how to get the free heap size of the current OS. The heap is meant for memory to allocate and creating the thread. If the heap size is too low, then some function may behave abnormally from the failure of the memory allocation.

void setup() {  
  char *buf;   
  Serial.print("Dynamic memory size: ");  
  Serial.println(os_get_free_heap_size());  
  Serial.println();  
  
  buf = (char *) malloc ( 1000 );  
  Serial.println("Allocate 1000 bytes");  
  Serial.print("Dynamic memory size: ");  
  Serial.println(os_get_free_heap_size());  
  Serial.println();  
  
  free(buf);  
  Serial.println("Free 1000 bytes");  
  Serial.print("Dynamic memory size: ");  
  Serial.println(os_get_free_heap_size());  
}  
  
void loop() {  
    delay(1000);  
}  

Notes and Warnings
NA