System functions

System functions are bridge between operating system system calls and middleware system calls. Middleware is tightly coupled with operating system features hence it is important to include OS features directly.

It includes support for:

  • Thread management, to start/stop threads

  • Mutex management for recursive mutexes

  • Semaphore management for binary-only semaphores

  • Message queues for thread-safe data exchange between threads

  • Core system protection for mutual exclusion to access shared resources

Tip

Check Porting guide for actual implementation guidelines.

group LWESP_SYS

System based function for OS management, timings, etc.

Main

uint8_t lwesp_sys_init(void)

Init system dependant parameters.

After this function is called, all other system functions must be fully ready.

Returns

1 on success, 0 otherwise

uint32_t lwesp_sys_now(void)

Get current time in units of milliseconds.

Returns

Current time in units of milliseconds

uint8_t lwesp_sys_protect(void)

Protect middleware core.

Stack protection must support recursive mode. This function may be called multiple times, even if access has been granted before.

Note

Most operating systems support recursive mutexes.

Returns

1 on success, 0 otherwise

uint8_t lwesp_sys_unprotect(void)

Unprotect middleware core.

This function must follow number of calls of lwesp_sys_protect and unlock access only when counter reached back zero.

Note

Most operating systems support recursive mutexes.

Returns

1 on success, 0 otherwise

Mutex

uint8_t lwesp_sys_mutex_create(lwesp_sys_mutex_t *p)

Create new recursive mutex.

Note

Recursive mutex has to be created as it may be locked multiple times before unlocked

Parameters

p – [out] Pointer to mutex structure to allocate

Returns

1 on success, 0 otherwise

uint8_t lwesp_sys_mutex_delete(lwesp_sys_mutex_t *p)

Delete recursive mutex from system.

Parameters

p – [in] Pointer to mutex structure

Returns

1 on success, 0 otherwise

uint8_t lwesp_sys_mutex_lock(lwesp_sys_mutex_t *p)

Lock recursive mutex, wait forever to lock.

Parameters

p – [in] Pointer to mutex structure

Returns

1 on success, 0 otherwise

uint8_t lwesp_sys_mutex_unlock(lwesp_sys_mutex_t *p)

Unlock recursive mutex.

Parameters

p – [in] Pointer to mutex structure

Returns

1 on success, 0 otherwise

uint8_t lwesp_sys_mutex_isvalid(lwesp_sys_mutex_t *p)

Check if mutex structure is valid system.

Parameters

p – [in] Pointer to mutex structure

Returns

1 on success, 0 otherwise

uint8_t lwesp_sys_mutex_invalid(lwesp_sys_mutex_t *p)

Set recursive mutex structure as invalid.

Parameters

p – [in] Pointer to mutex structure

Returns

1 on success, 0 otherwise

Semaphores

uint8_t lwesp_sys_sem_create(lwesp_sys_sem_t *p, uint8_t cnt)

Create a new binary semaphore and set initial state.

Note

Semaphore may only have 1 token available

Parameters

  • p – [out] Pointer to semaphore structure to fill with result

  • cnt – [in] Count indicating default semaphore state: 0: Take semaphore token immediately 1: Keep token available

Returns

1 on success, 0 otherwise

uint8_t lwesp_sys_sem_delete(lwesp_sys_sem_t *p)

Delete binary semaphore.

Parameters

p – [in] Pointer to semaphore structure

Returns

1 on success, 0 otherwise

uint32_t lwesp_sys_sem_wait(lwesp_sys_sem_t *p, uint32_t timeout)

Wait for semaphore to be available.

Parameters

  • p – [in] Pointer to semaphore structure

  • timeout – [in] Timeout to wait in milliseconds. When 0 is applied, wait forever

Returns

Number of milliseconds waited for semaphore to become available or LWESP_SYS_TIMEOUT if not available within given time

uint8_t lwesp_sys_sem_release(lwesp_sys_sem_t *p)

Release semaphore.

Parameters

p – [in] Pointer to semaphore structure

Returns

1 on success, 0 otherwise

uint8_t lwesp_sys_sem_isvalid(lwesp_sys_sem_t *p)

Check if semaphore is valid.

Parameters

p – [in] Pointer to semaphore structure

Returns

1 on success, 0 otherwise

uint8_t lwesp_sys_sem_invalid(lwesp_sys_sem_t *p)

Invalid semaphore.

Parameters

p – [in] Pointer to semaphore structure

Returns

1 on success, 0 otherwise

Message queues

uint8_t lwesp_sys_mbox_create(lwesp_sys_mbox_t *b, size_t size)

Create a new message queue with entry type of void *

Parameters

  • b – [out] Pointer to message queue structure

  • size – [in] Number of entries for message queue to hold

Returns

1 on success, 0 otherwise

uint8_t lwesp_sys_mbox_delete(lwesp_sys_mbox_t *b)

Delete message queue.

Parameters

b – [in] Pointer to message queue structure

Returns

1 on success, 0 otherwise

uint32_t lwesp_sys_mbox_put(lwesp_sys_mbox_t *b, void *m)

Put a new entry to message queue and wait until memory available.

Parameters

  • b – [in] Pointer to message queue structure

  • m – [in] Pointer to entry to insert to message queue

Returns

Time in units of milliseconds needed to put a message to queue

uint32_t lwesp_sys_mbox_get(lwesp_sys_mbox_t *b, void **m, uint32_t timeout)

Get a new entry from message queue with timeout.

Parameters

  • b – [in] Pointer to message queue structure

  • m – [in] Pointer to pointer to result to save value from message queue to

  • timeout – [in] Maximal timeout to wait for new message. When 0 is applied, wait for unlimited time

Returns

Time in units of milliseconds needed to put a message to queue or LWESP_SYS_TIMEOUT if it was not successful

uint8_t lwesp_sys_mbox_putnow(lwesp_sys_mbox_t *b, void *m)

Put a new entry to message queue without timeout (now or fail)

Parameters

  • b – [in] Pointer to message queue structure

  • m – [in] Pointer to message to save to queue

Returns

1 on success, 0 otherwise

uint8_t lwesp_sys_mbox_getnow(lwesp_sys_mbox_t *b, void **m)

Get an entry from message queue immediately.

Parameters

  • b – [in] Pointer to message queue structure

  • m – [in] Pointer to pointer to result to save value from message queue to

Returns

1 on success, 0 otherwise

uint8_t lwesp_sys_mbox_isvalid(lwesp_sys_mbox_t *b)

Check if message queue is valid.

Parameters

b – [in] Pointer to message queue structure

Returns

1 on success, 0 otherwise

uint8_t lwesp_sys_mbox_invalid(lwesp_sys_mbox_t *b)

Invalid message queue.

Parameters

b – [in] Pointer to message queue structure

Returns

1 on success, 0 otherwise

Threads

uint8_t lwesp_sys_thread_create(lwesp_sys_thread_t *t, const char *name, lwesp_sys_thread_fn thread_func, void *const arg, size_t stack_size, lwesp_sys_thread_prio_t prio)

Create a new thread.

Parameters

  • t – [out] Pointer to thread identifier if create was successful. It may be set to NULL

  • name – [in] Name of a new thread

  • thread_func – [in] Thread function to use as thread body

  • arg – [in] Thread function argument

  • stack_size – [in] Size of thread stack in uints of bytes. If set to 0, reserve default stack size

  • prio – [in] Thread priority

Returns

1 on success, 0 otherwise

uint8_t lwesp_sys_thread_terminate(lwesp_sys_thread_t *t)

Terminate thread (shut it down and remove)

Parameters

t – [in] Pointer to thread handle to terminate. If set to NULL, terminate current thread (thread from where function is called)

Returns

1 on success, 0 otherwise

uint8_t lwesp_sys_thread_yield(void)

Yield current thread.

Returns

1 on success, 0 otherwise

Defines

LWESP_SYS_MUTEX_NULL

Mutex invalid value.

Value assigned to lwesp_sys_mutex_t type when it is not valid.

LWESP_SYS_SEM_NULL

Semaphore invalid value.

Value assigned to lwesp_sys_sem_t type when it is not valid.

LWESP_SYS_MBOX_NULL

Message box invalid value.

Value assigned to lwesp_sys_mbox_t type when it is not valid.

LWESP_SYS_TIMEOUT

OS timeout value.

Value returned by operating system functions (mutex wait, sem wait, mbox wait) when it returns timeout and does not give valid value to application

LWESP_SYS_THREAD_PRIO

Default thread priority value used by middleware to start built-in threads.

Threads can well operate with normal (default) priority and do not require any special feature in terms of priority for proper operation.

LWESP_SYS_THREAD_SS

Stack size in units of bytes for system threads.

It is used as default stack size for all built-in threads.

Typedefs

typedef void (*lwesp_sys_thread_fn)(void*)

Thread function prototype.

typedef void *lwesp_sys_mutex_t

System mutex type.

It is used by middleware as base type of mutex.

typedef void *lwesp_sys_sem_t

System semaphore type.

It is used by middleware as base type of mutex.

typedef void *lwesp_sys_mbox_t

System message queue type.

It is used by middleware as base type of mutex.

typedef void *lwesp_sys_thread_t

System thread ID type.

typedef int lwesp_sys_thread_prio_t

System thread priority type.

It is used as priority type for system function, to start new threads by middleware.