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 ESP_SYS

System based function for OS management, timings, etc.

Main

uint8_t esp_sys_init(void)

Init system dependant parameters.

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

Return

1 on success, 0 otherwise

uint32_t esp_sys_now(void)

Get current time in units of milliseconds.

Return

Current time in units of milliseconds

uint8_t esp_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.

Return

1 on success, 0 otherwise

uint8_t esp_sys_unprotect(void)

Unprotect middleware core.

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

Note

Most operating systems support recursive mutexes.

Return

1 on success, 0 otherwise

Mutex

uint8_t esp_sys_mutex_create(esp_sys_mutex_t *p)

Create new recursive mutex.

Note

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

Return

1 on success, 0 otherwise

Parameters
  • [out] p: Pointer to mutex structure to allocate

uint8_t esp_sys_mutex_delete(esp_sys_mutex_t *p)

Delete recursive mutex from system.

Return

1 on success, 0 otherwise

Parameters
  • [in] p: Pointer to mutex structure

uint8_t esp_sys_mutex_lock(esp_sys_mutex_t *p)

Lock recursive mutex, wait forever to lock.

Return

1 on success, 0 otherwise

Parameters
  • [in] p: Pointer to mutex structure

uint8_t esp_sys_mutex_unlock(esp_sys_mutex_t *p)

Unlock recursive mutex.

Return

1 on success, 0 otherwise

Parameters
  • [in] p: Pointer to mutex structure

uint8_t esp_sys_mutex_isvalid(esp_sys_mutex_t *p)

Check if mutex structure is valid system.

Return

1 on success, 0 otherwise

Parameters
  • [in] p: Pointer to mutex structure

uint8_t esp_sys_mutex_invalid(esp_sys_mutex_t *p)

Set recursive mutex structure as invalid.

Return

1 on success, 0 otherwise

Parameters
  • [in] p: Pointer to mutex structure

Semaphores

uint8_t esp_sys_sem_create(esp_sys_sem_t *p, uint8_t cnt)

Create a new binary semaphore and set initial state.

Note

Semaphore may only have 1 token available

Return

1 on success, 0 otherwise

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

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

uint8_t esp_sys_sem_delete(esp_sys_sem_t *p)

Delete binary semaphore.

Return

1 on success, 0 otherwise

Parameters
  • [in] p: Pointer to semaphore structure

uint32_t esp_sys_sem_wait(esp_sys_sem_t *p, uint32_t timeout)

Wait for semaphore to be available.

Return

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

Parameters
  • [in] p: Pointer to semaphore structure

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

uint8_t esp_sys_sem_release(esp_sys_sem_t *p)

Release semaphore.

Return

1 on success, 0 otherwise

Parameters
  • [in] p: Pointer to semaphore structure

uint8_t esp_sys_sem_isvalid(esp_sys_sem_t *p)

Check if semaphore is valid.

Return

1 on success, 0 otherwise

Parameters
  • [in] p: Pointer to semaphore structure

uint8_t esp_sys_sem_invalid(esp_sys_sem_t *p)

Invalid semaphore.

Return

1 on success, 0 otherwise

Parameters
  • [in] p: Pointer to semaphore structure

Message queues

uint8_t esp_sys_mbox_create(esp_sys_mbox_t *b, size_t size)

Create a new message queue with entry type of void *

Return

1 on success, 0 otherwise

Parameters
  • [out] b: Pointer to message queue structure

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

uint8_t esp_sys_mbox_delete(esp_sys_mbox_t *b)

Delete message queue.

Return

1 on success, 0 otherwise

Parameters
  • [in] b: Pointer to message queue structure

uint32_t esp_sys_mbox_put(esp_sys_mbox_t *b, void *m)

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

Return

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

Parameters
  • [in] b: Pointer to message queue structure

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

uint32_t esp_sys_mbox_get(esp_sys_mbox_t *b, void **m, uint32_t timeout)

Get a new entry from message queue with timeout.

Return

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

Parameters
  • [in] b: Pointer to message queue structure

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

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

uint8_t esp_sys_mbox_putnow(esp_sys_mbox_t *b, void *m)

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

Return

1 on success, 0 otherwise

Parameters
  • [in] b: Pointer to message queue structure

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

uint8_t esp_sys_mbox_getnow(esp_sys_mbox_t *b, void **m)

Get an entry from message queue immediately.

Return

1 on success, 0 otherwise

Parameters
  • [in] b: Pointer to message queue structure

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

uint8_t esp_sys_mbox_isvalid(esp_sys_mbox_t *b)

Check if message queue is valid.

Return

1 on success, 0 otherwise

Parameters
  • [in] b: Pointer to message queue structure

uint8_t esp_sys_mbox_invalid(esp_sys_mbox_t *b)

Invalid message queue.

Return

1 on success, 0 otherwise

Parameters
  • [in] b: Pointer to message queue structure

Threads

uint8_t esp_sys_thread_create(esp_sys_thread_t *t, const char *name, esp_sys_thread_fn thread_func, void *const arg, size_t stack_size, esp_sys_thread_prio_t prio)

Create a new thread.

Return

1 on success, 0 otherwise

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

  • [in] name: Name of a new thread

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

  • [in] arg: Thread function argument

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

  • [in] prio: Thread priority

uint8_t esp_sys_thread_terminate(esp_sys_thread_t *t)

Terminate thread (shut it down and remove)

Return

1 on success, 0 otherwise

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

uint8_t esp_sys_thread_yield(void)

Yield current thread.

Return

1 on success, 0 otherwise

Defines

ESP_SYS_MUTEX_NULL

Mutex invalid value.

Value assigned to esp_sys_mutex_t type when it is not valid.

ESP_SYS_SEM_NULL

Semaphore invalid value.

Value assigned to esp_sys_sem_t type when it is not valid.

ESP_SYS_MBOX_NULL

Message box invalid value.

Value assigned to esp_sys_mbox_t type when it is not valid.

ESP_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

ESP_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 prioer operation.

ESP_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 (*esp_sys_thread_fn)(void*)

Thread function prototype.

typedef osMutexId_t esp_sys_mutex_t

System mutex type.

It is used by middleware as base type of mutex.

typedef osSemaphoreId_t esp_sys_sem_t

System semaphore type.

It is used by middleware as base type of mutex.

typedef osMessageQueueId_t esp_sys_mbox_t

System message queue type.

It is used by middleware as base type of mutex.

typedef osThreadId_t esp_sys_thread_t

System thread ID type.

typedef osPriority esp_sys_thread_prio_t

System thread priority type.

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