Multitasking API¶

API Reference¶

Header File¶

#include <os_api.h>

Functions¶

void sys_reset(void)¶: Reset System

int sys_get_coreversion(char *verbuf, int len)¶

Get Core system version

Parameters

verbuf – [in,out] Buffer to store version (minimum 30)
len – [in] Length of verbuf

Returns

Returns length of data stored in verbuf

void sys_setsleep_timeout(uint32_t ms)¶

Set sleep timeout. System will wake up as soon as timeout finishes or an any event occurs.

Note

only available on NBIoT Platforms

Parameters: ms – [in] Sleep timeout in miliseconds

void sys_setsleep(int type)¶

Enter sleep mode

Note

only available on NBIoT Platforms

Parameters: type – [in] Type of sleep sleeptype_e

void os_task_sleep(unsigned int ms)¶

Task sleep API

Parameters: ms – [in] time in milliseconds

int os_message_get(struct osmsg_t *msg)¶

Get message from task message queue

Parameters: msg – [in] Pointer to OS message structure osmsg_t
Returns: 0 on success, negative value on error

int os_message_send(int dest_taskid, uint32_t message, uint32_t param1, uint32_t param2)¶

Send message to a task message queue, Maximum number of messages are 30

Note

on GSM Platform, an assert is raised if more than 30 messages are sent to task queue.

Parameters

dest_taskid – [in] Destination task id
message – [in] Message ID
param1 – [in] Parameter 1
param2 – [in] Parameter 2

Returns

0 on success, negative value on error

uint32_t os_mutex_create(void)¶

Create a mutex Mutex created once cannot be destroyed.

Returns: Mutex ID

int os_mutex_take(uint32_t mutex)¶

Take a mutex. If mutex is not available, Task will be suspended until mutex is available.

Parameters: mutex – [in] Mutex ID created by os_mutex_create()
Returns: 0 on success, negative value on error

int os_mutex_trytake(uint32_t mutex, uint32_t timeout)¶

Try to take a mutex. This API is similar to os_mutex_take() with a optional timeout

Parameters

mutex – [in] Mutex ID created by os_mutex_create()
timeout – [in] duration in ms to wait, OS_WAIT_FOREVER for indefinite wait, 0 to return immediately

Returns

0 on success, negative value on error

int os_mutex_give(uint32_t mutex)¶

Release a mutex. Once a mutex is released, OS does not yield on waiting task. Task switch happens when executing task is suspended by sleep or waiting on external queue message.

Parameters: mutex – [in] Mutex ID created by os_mutex_create()
Returns: 0 on success, negative value on error

uint32_t os_semaphore_create(int val)¶

Create a semaphore

Parameters: val – [in] Initial value of semaphore
Returns: Semaphore ID

int os_semaphore_take(uint32_t sem, int timeout)¶

Take a semaphore. When semaphore is not available and wait is requested, task will be suspended until semaphore is available

Parameters

sem – [in] Semaphore ID created by os_semaphore_create()
timeout – [in] duration in ms to timeout, OS_WAIT_FOREVER
for indefinite timeout, 0 to return immediately

On GSM platforms, when timeout is non zero API blocks until semaphore is acquired

Returns

0 on success, negative value on error

int os_semaphore_give(uint32_t sem)¶

Give a semaphore.

Parameters: sem – [in] Semaphore ID created by os_semaphore_create()
Returns: 0 on success, negative value on error

uint32_t os_eventgroup_create(void)¶

Create event group. Event group has 32 flags represented by each bit of a 32-bit word.

Returns: event group ID

int os_eventgroup_setevent(uint32_t egid, uint32_t event_flags)¶

Set event in event group

Parameters

egid – [in] Event group ID
event_flags – [in] Event flags to set. Each bit represents an event flags

Returns

int os_eventgroup_waitevent(uint32_t egid, uint32_t event_flags)¶

Wait for event flag to set

Parameters

egid – [in] Event group id
event_flags – [in] Requested flags

Returns

0 on success, negative value on error

int os_eventgroup_waiteventex(uint32_t egid, uint32_t req_flags, int op, uint32_t *out_flags, uint32_t timeout)¶

Extended function for event flag wait

Parameters

egid – [in] Event group ID
req_flags – [in] Requested flags
op – [in] Operation type ev_flags
out_flags – [out] Actual event flags available
timeout – [in] Timeout in milliseconds or OS_WAIT_FOREVER to wait until an event is raised

Returns

0 on success, negative value on error

uint32_t os_task_getavailstack(void)¶

Get available stack size of running task

Returns: Returns size in bytes

uint32_t os_task_getid(void)¶

Get task id of running task

Returns: Returns task id

int os_task_create(os_taskfn_f fn, const char *name, void *arg, int suspend)¶

Create a new OS task, Maximum 10 tasks can be created

Parameters

fn – [in] Task function of type os_taskfn_f
name – [in] Task name, cannot be NULL
arg – [in] Argument to task function
suspend – [in] TRUE will suspend the task on creation, FALSE otherwise. Suspended task can be started later by calling os_start_task()

Returns

On success task ID is returned, -1 on error.

int os_task_create_ex(os_taskfn_f fn, const char *name, uint32_t stack, void *arg, int suspend)¶

Create a new OS task, with extended parameters

Note

only available on NBIoT Platforms

Parameters

fn – [in] Task function of type os_taskfn_f
name – [in] Task name, cannot be NULL
stack – [in] Task stack size in bytes
arg – [in] Argument to task function
suspend – [in] TRUE will suspend the task on creation, FALSE otherwise. Suspended task can be started later by calling os_start_task()

Returns

On success task ID is returned, -1 on error.

int os_task_delete(int taskid)¶

Start a task created by os_task_create() /os_task_create_ex()

Note

only available on NBIoT Platforms

Parameters: taskid – [in] Task ID
Returns: 0 on success, negative value on error

uint64_t os_get_tickms(void)¶

Get OS tick/uptime in milliseconds

Returns: tick counter in milliseconds

uint64_t os_get_tickus(void)¶

Get OS tick/uptime in microseconds

Returns: tick counter in microseconds

int os_task_start(int taskid)¶

Start a suspended task created by os_task_create()

Parameters: taskid – [in] Task ID
Returns: 0 on success, negative value on error

uint32_t os_enter_critical(void)¶

Enter critical section

Returns: IRQ flags

void os_exit_critical(uint32_t flags)¶

Exit critical section

Parameters: flags – [in] IRQ flags from os_enter_critical()

Structures¶

struct osmsg_t¶

OS message structure for external Queue

Public Members

uint32_t message¶: Message ID

uint32_t param1¶: First parameter

uint32_t param2¶: Second parameter

int source_taskid¶: Filled automatically by os_message_get()

Macros¶

EVENT_OP_AND¶: All event flags are required

EVENT_OP_OR¶: Not all event flags are required

OS_WAIT_FOREVER¶: Wait indefinitely

Type Definitions¶

typedef void (*os_taskfn_f)(void *arg)¶

OS Task Function typedef

Param arg: User data argument to function

Enumerations¶

enum sleeptype_e¶

Sleep Type

Values:

enumerator SLEEP_TYPE_NONE¶: Sleep disable

enumerator SLEEP_TYPE_LIGHT¶: Light sleep mode

enumerator SLEEP_TYPE_DEEP¶: Deep sleep mode