Multitasking API

Application Example

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_lock(uint32_t mutex)

Lock 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_take(uint32_t mutex)

Lock a mutex. If mutex is not available, Task will be suspended until mutex is available. This API is deprecated. use os_mutex_lock()

Deprecated:: since v1.0.0

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

int os_mutex_trylock(uint32_t mutex, uint32_t timeout)

Try to lock a mutex. This API is similar to os_mutex_lock() 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_trytake(uint32_t mutex, uint32_t timeout)

Try to lock a mutex. This API is similar to os_mutex_lock() with a optional timeout This API is deprecated. use os_mutex_trylock()

Deprecated:: since v1.0.0

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_unlock(uint32_t mutex)

Unlock a mutex. Once a mutex is Unlocked, 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

int os_mutex_give(uint32_t mutex)

Unlock a mutex. Once a mutex is Unlocked, OS does not yield on waiting task. Task switch happens when executing task is suspended by sleep or waiting on external queue message. This API is deprecated. use os_mutex_unlock()

Deprecated:: since v1.0.0

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

int os_mutex_delete(uint32_t mutex)

Delete mutex.

Note

this function is not available on MT2503/MT6261 chipset.

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()

Deprecated:: use os_task_resume()

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

int os_task_resume(int taskid)

Resume a task which is in suspended state

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

int os_task_suspend(int taskid)

Suspend a task

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