OS API
The OS abstraction layer mainly adapts to different operating systems of platform Armino
For different operating systems, the OS abstraction layer provides a unified set of interfaces
Currently supported operating system include: FreeRTOS,HarmonyOS,RTThread.
Header File
Functions
-
uint32_t rtos_enter_critical(void)
Enter a critical session, all interrupts are disabled.
- Returns
irq flags
-
void rtos_exit_critical(uint32_t flags)
Exit a critical session, all interrupts are enabled.
- Parameters
flags – : irq flags
- Returns
none
-
bk_err_t beken_time_get_time(beken_time_t *time_ptr)
Get system time value in milliseconds.
- Parameters
time_ptr – : the pointer of time value in milliseconds
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_create_thread(beken_thread_t *thread, uint8_t priority, const char *name, beken_thread_function_t function, uint32_t stack_size, beken_thread_arg_t arg)
Creates and starts a new thread.
- Parameters
thread – : Pointer to variable that will receive the thread handle (can be null)
priority – : A priority number.
name – : a text name for the thread (can be null)
function – : the main thread function
stack_size – : stack size for this thread
arg – : argument which will be passed to thread function
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_create_psram_thread(beken_thread_t *thread, uint8_t priority, const char *name, beken_thread_function_t function, uint32_t stack_size, beken_thread_arg_t arg)
Creates and starts a new thread on psram.
- Parameters
thread – : Pointer to variable that will receive the thread handle (can be null)
priority – : A priority number.
name – : a text name for the thread (can be null)
function – : the main thread function
stack_size – : stack size for this thread
arg – : argument which will be passed to thread function
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_delete_thread(beken_thread_t *thread)
Deletes a terminated thread.
- Parameters
thread – : the handle of the thread to delete, , NULL is the current thread
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_create_worker_thread(beken_worker_thread_t *worker_thread, uint8_t priority, uint32_t stack_size, uint32_t event_queue_size)
Creates a worker thread.
Creates a worker thread A worker thread is a thread in whose context timed and asynchronous events execute.
- Parameters
worker_thread – : a pointer to the worker thread to be created
priority – : thread priority
stack_size – : thread’s stack size in number of bytes
event_queue_size – : number of events can be pushed into the queue
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_delete_worker_thread(beken_worker_thread_t *worker_thread)
Deletes a worker thread.
- Parameters
worker_thread – : a pointer to the worker thread to be created
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
void rtos_suspend_thread(beken_thread_t *thread)
Suspend a thread.
- Parameters
thread – : the handle of the thread to suspend, NULL is the current thread
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
void rtos_suspend_all_thread(void)
Suspend all other thread.
- Parameters
none –
- Returns
none
-
void rtos_resume_thread(beken_thread_t *thread)
resume a thread
- Parameters
thread – : the handle of the thread to resume, NULL is the current thread
- Returns
none
-
long rtos_resume_all_thread(void)
Rresume all other thread.
- Parameters
none –
- Returns
none
-
bk_err_t rtos_thread_join(beken_thread_t *thread)
Sleeps until another thread has terminated.
@Details Causes the current thread to sleep until the specified other thread has terminated. If the processor is heavily loaded with higher priority tasks, this thread may not wake until significantly after the thread termination.
- Parameters
thread – : the handle of the other thread which will terminate
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_thread_force_awake(beken_thread_t *thread)
Forcibly wakes another thread.
@Details Causes the specified thread to wake from suspension. This will usually cause an error or timeout in that thread, since the task it was waiting on is not complete.
- Parameters
thread – : the handle of the other thread which will be woken
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bool rtos_is_current_thread(beken_thread_t *thread)
Checks if a thread is the current thread.
@Details Checks if a specified thread is the currently running thread
- Parameters
thread – : the handle of the other thread against which the current thread will be compared
- Returns
true : specified thread is the current thread
- Returns
false : specified thread is not currently running
-
beken_thread_t *rtos_get_current_thread(void)
Get current thread handler.
- Returns
Current RTOS thread handler
-
void rtos_thread_sleep(uint32_t seconds)
Suspend current thread for a specific time.
- Parameters
seconds – : A time interval (Unit: seconds)
- Returns
None.
-
void rtos_thread_msleep(uint32_t milliseconds)
Suspend current thread for a specific time.
- Parameters
milliseconds – : A time interval (Unit: millisecond)
- Returns
None.
-
bk_err_t rtos_delay_milliseconds(uint32_t num_ms)
Suspend current thread for a specific time.
- Parameters
num_ms – : A time interval (Unit: millisecond)
- Returns
kNoErr.
-
bk_err_t rtos_print_thread_status(char *buffer, int length)
Print Thread status into buffer.
- Parameters
buffer, point – to buffer to store thread status
length, length – of the buffer
- Returns
none
-
bk_err_t rtos_init_semaphore(beken_semaphore_t *semaphore, int max_count)
Initialises a counting semaphore and set count to 0.
- Parameters
semaphore – : a pointer to the semaphore handle to be initialised
max_count – : the max count number of this semaphore
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_init_semaphore_ex(beken_semaphore_t *semaphore, int max_count, int init_count)
Initialises a counting semaphore and set count to init count.
- Parameters
semaphore – : a pointer to the semaphore handle to be initialised
max_count – : the max count number of this semaphore
init_count – : the init count number of this semaphore
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_set_semaphore(beken_semaphore_t *semaphore)
Set (post/put/increment) a semaphore.
- Parameters
semaphore – : a pointer to the semaphore handle to be set
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_get_semaphore(beken_semaphore_t *semaphore, uint32_t timeout_ms)
Get (wait/decrement) a semaphore.
@Details Attempts to get (wait/decrement) a semaphore. If semaphore is at zero already, then the calling thread will be suspended until another thread sets the semaphore with rtos_set_semaphore
- Parameters
semaphore – : a pointer to the semaphore handle
timeout_ms – the number of milliseconds to wait before returning
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
int rtos_get_semaphore_count(beken_semaphore_t *semaphore)
-
bk_err_t rtos_deinit_semaphore(beken_semaphore_t *semaphore)
De-initialise a semaphore.
@Details Deletes a semaphore created with rtos_init_semaphore
- Parameters
semaphore – : a pointer to the semaphore handle
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_init_mutex(beken_mutex_t *mutex)
Initialises a mutex.
@Details A mutex is different to a semaphore in that a thread that already holds the lock on the mutex can request the lock again (nested) without causing it to be suspended.
- Parameters
mutex – : a pointer to the mutex handle to be initialised
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_trylock_mutex(beken_mutex_t *mutex)
Obtains the lock on a mutex.
@Details Attempts to obtain the lock on a mutex. If the lock is already held by another thead, the calling thread will not be suspended until the mutex lock is released by the other thread.
- Parameters
mutex – : a pointer to the mutex handle to be locked
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_lock_mutex(beken_mutex_t *mutex)
Obtains the lock on a mutex.
@Details Attempts to obtain the lock on a mutex. If the lock is already held by another thead, the calling thread will be suspended until the mutex lock is released by the other thread.
- Parameters
mutex – : a pointer to the mutex handle to be locked
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_lock_mutex_timeout(beken_mutex_t *mutex, uint32_t timeout_ms)
Obtains the lock on a mutex.
@Details Attempts to obtain the lock on a mutex. If the lock is already held by another thead, the calling thread will be suspended until the mutex lock is released by the other thread or timeout.
- Parameters
mutex – : a pointer to the mutex handle to be locked
timeout_ms – : timeout for get lock
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_unlock_mutex(beken_mutex_t *mutex)
Releases the lock on a mutex.
@Details Releases a currently held lock on a mutex. If another thread is waiting on the mutex lock, then it will be resumed.
- Parameters
mutex – : a pointer to the mutex handle to be unlocked
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_deinit_mutex(beken_mutex_t *mutex)
De-initialise a mutex.
@Details Deletes a mutex created with rtos_init_mutex
- Parameters
mutex – : a pointer to the mutex handle
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_init_queue(beken_queue_t *queue, const char *name, uint32_t message_size, uint32_t number_of_messages)
Initialises a FIFO queue.
- Parameters
queue – : a pointer to the queue handle to be initialised
name – : a text string name for the queue (NULL is allowed)
message_size – : size in bytes of objects that will be held in the queue
number_of_messages – : depth of the queue - i.e. max number of objects in the queue
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_push_to_queue(beken_queue_t *queue, void *message, uint32_t timeout_ms)
Pushes an object onto a queue.
- Parameters
queue – : a pointer to the queue handle
message – : the object to be added to the queue. Size is assumed to be the size specified in rtos_init_queue
timeout_ms – the number of milliseconds to wait before returning
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error or timeout occurred
-
bk_err_t rtos_push_to_queue_front(beken_queue_t *queue, void *message, uint32_t timeout_ms)
Pushes an object to front of the queue.
- Parameters
queue – : a pointer to the queue handle
message – : the object to be added to the queue. Size is assumed to be the size specified in rtos_init_queue
timeout_ms – the number of milliseconds to wait before returning
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error or timeout occurred
-
bk_err_t rtos_pop_from_queue(beken_queue_t *queue, void *message, uint32_t timeout_ms)
Pops an object off a queue.
- Parameters
queue – : a pointer to the queue handle
message – : pointer to a buffer that will receive the object being popped off the queue. Size is assumed to be the size specified in rtos_init_queue , hence you must ensure the buffer is long enough or memory corruption will result
timeout_ms – the number of milliseconds to wait before returning
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error or timeout occurred
-
bk_err_t rtos_deinit_queue(beken_queue_t *queue)
De-initialise a queue created with rtos_init_queue.
- Parameters
queue – : a pointer to the queue handle
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bool rtos_is_queue_empty(beken_queue_t *queue)
Check if a queue is empty.
- Parameters
queue – : a pointer to the queue handle
- Returns
true : queue is empty.
- Returns
false : queue is not empty.
-
bool rtos_is_queue_full(beken_queue_t *queue)
Check if a queue is full.
- Parameters
queue – : a pointer to the queue handle
- Returns
true : queue is empty.
- Returns
false : queue is not empty.
-
bool rtos_reset_queue(beken_queue_t *queue)
Reset queue.
- Parameters
queue – : a pointer to the queue handle
- Returns
true : reset ok.
- Returns
false : reset fail.
-
bk_err_t rtos_send_asynchronous_event(beken_worker_thread_t *worker_thread, event_handler_t function, void *arg)
Sends an asynchronous event to the associated worker thread.
- Parameters
worker_thread – :the worker thread in which context the callback should execute from
function – : the callback function to be called from the worker thread
arg – : the argument to be passed to the callback function
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_register_timed_event(beken_timed_event_t *event_object, beken_worker_thread_t *worker_thread, event_handler_t function, uint32_t time_ms, void *arg)
Requests a function be called at a regular interval
This function registers a function that will be called at a regular interval. Since this is based on the RTOS time-slice scheduling, the accuracy is not high, and is affected by processor load.
- Parameters
event_object – : pointer to a event handle which will be initialised
worker_thread – : pointer to the worker thread in whose context the callback function runs on
function – : the callback function that is to be called regularly
time_ms – : the time period between function calls in milliseconds
arg – : an argument that will be supplied to the function when it is called
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_deregister_timed_event(beken_timed_event_t *event_object)
Removes a request for a regular function execution
This function de-registers a function that has previously been set-up with rtos_register_timed_event.
- Parameters
event_object – : the event handle used with rtos_register_timed_event
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
uint32_t rtos_get_time(void)
Gets time in miiliseconds since RTOS start.
Note
: Since this is only 32 bits, it will roll over every 49 days, 17 hours.
- Returns
Time in milliseconds since RTOS started.
-
uint32_t beken_ms_per_tick(void)
Gets time in miiliseconds since RTOS start.
Note
: Since this is only 32 bits, it will roll over every 49 days, 17 hours.
- Returns
Time in milliseconds since RTOS started.
-
bk_err_t rtos_init_timer(beken_timer_t *timer, uint32_t time_ms, timer_handler_t function, void *arg)
Initialize a RTOS timer.
Note
Timer does not start running until beken_start_timer is called
- Parameters
timer – : a pointer to the timer handle to be initialised
time_ms – : Timer period in milliseconds
function – : the callback handler function that is called each time the timer expires
arg – : an argument that will be passed to the callback function
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_init_oneshot_timer(beken2_timer_t *timer, uint32_t time_ms, timer_2handler_t function, void *larg, void *rarg)
-
bk_err_t rtos_deinit_oneshot_timer(beken2_timer_t *timer)
-
bk_err_t rtos_stop_oneshot_timer(beken2_timer_t *timer)
-
bool rtos_is_oneshot_timer_running(beken2_timer_t *timer)
-
bk_err_t rtos_start_oneshot_timer(beken2_timer_t *timer)
-
bool rtos_is_oneshot_timer_init(beken2_timer_t *timer)
-
bk_err_t rtos_oneshot_reload_timer(beken2_timer_t *timer)
-
bk_err_t rtos_change_period(beken_timer_t *timer, uint32_t time_ms)
-
bk_err_t rtos_oneshot_reload_timer_ex(beken2_timer_t *timer, uint32_t time_ms, timer_2handler_t function, void *larg, void *rarg)
-
bk_err_t rtos_start_timer(beken_timer_t *timer)
Starts a RTOS timer running.
Note
Timer must have been previously initialised with rtos_init_timer
- Parameters
timer – : a pointer to the timer handle to start
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_stop_timer(beken_timer_t *timer)
Stops a running RTOS timer.
Note
Timer must have been previously started with rtos_init_timer
- Parameters
timer – : a pointer to the timer handle to stop
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_reload_timer(beken_timer_t *timer)
Reloads a RTOS timer that has expired.
Note
This is usually called in the timer callback handler, to reschedule the timer for the next period.
- Parameters
timer – : a pointer to the timer handle to reload
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bk_err_t rtos_deinit_timer(beken_timer_t *timer)
De-initialise a RTOS timer.
Note
Deletes a RTOS timer created with rtos_init_timer
- Parameters
timer – : a pointer to the RTOS timer handle
- Returns
kNoErr : on success.
- Returns
kGeneralErr : if an error occurred
-
bool rtos_is_timer_init(beken_timer_t *timer)
Check if an RTOS timer is init.
- Parameters
timer – : a pointer to the RTOS timer handle
- Returns
true : if init.
- Returns
false : if not init
-
bool rtos_is_timer_running(beken_timer_t *timer)
Check if an RTOS timer is running.
- Parameters
timer – : a pointer to the RTOS timer handle
- Returns
true : if running.
- Returns
false : if not running
-
uint32_t rtos_get_timer_expiry_time(beken_timer_t *timer)
-
uint32_t rtos_get_next_expire_time()
-
uint32_t rtos_get_current_timer_count(void)
-
void rtos_start_scheduler(void)
-
bool rtos_is_scheduler_started(void)
-
uint32_t rtos_get_cpsr(void)
-
char *rtos_get_name(void)
-
char *rtos_get_version(void)
-
size_t rtos_get_total_heap_size(void)
-
size_t rtos_get_free_heap_size(void)
-
size_t rtos_get_minimum_free_heap_size(void)
-
size_t rtos_get_psram_total_heap_size(void)
-
size_t rtos_get_psram_free_heap_size(void)
-
size_t rtos_get_psram_minimum_free_heap_size(void)
-
uint32_t rtos_get_tick_count(void)
-
uint32_t rtos_disable_int(void)
-
void rtos_enable_int(uint32_t int_level)
-
uint32_t rtos_before_sleep(void)
-
void rtos_after_sleep(uint32_t int_level)
-
bool rtos_is_in_interrupt_context(void)
-
bool rtos_local_irq_disabled(void)
-
void rtos_wait_for_interrupt(void)
-
void rtos_shutdown(void)
-
bk_err_t rtos_init_recursive_mutex(beken_mutex_t *mutex)
-
bk_err_t rtos_lock_recursive_mutex(beken_mutex_t *mutex)
-
bk_err_t rtos_unlock_recursive_mutex(beken_mutex_t *mutex)
-
bk_err_t rtos_deinit_recursive_mutex(beken_mutex_t *mutex)
Structures
-
struct beken_timer_t
OS timer handle struct type.
Public Members
-
void *handle
OS timer handle pointer
-
timer_handler_t function
OS timer handle callback function
-
void *arg
OS timer handle callback argument
-
void *handle
-
struct beken_worker_thread_t
OS worker thread handle struct type.
-
struct beken_timed_event_t
OS timer event struct type.
Public Members
-
event_handler_t function
OS event callback function
-
void *arg
OS event callback argument
-
beken_timer_t timer
OS timer handle
-
beken_worker_thread_t *thread
OS work thread handle
-
event_handler_t function
-
struct beken2_timer_t
OS timer handle struct type.
Macros
-
RTOS_TAG
OS log tag
-
RTOS_LOGI(...)
Output OS Info log
-
RTOS_LOGW(...)
Output OS Warning log
-
RTOS_LOGE(...)
Output OS Error log
-
RTOS_LOGD(...)
Output OS Debug log
-
GLOBAL_INT_STOP
os stop interrupt
-
GLOBAL_INT_DECLARATION()
os declaration interrupt status
-
GLOBAL_INT_DISABLE()
os read interrupt status and disable interrupt
-
GLOBAL_INT_RESTORE()
os restore interrupt status
-
RTOS_SUCCESS
Return Success
-
RTOS_FAILURE
Return Failure
-
BEKEN_DEFAULT_WORKER_PRIORITY
Default Worker Priority
-
BEKEN_APPLICATION_PRIORITY
Application Task Priority
-
NanosecondsPerSecond
Nanoseconds Per Second
-
MicrosecondsPerSecond
Microseconds Per Second
-
MillisecondsPerSecond
Milliseconds Per Second
-
BEKEN_NEVER_TIMEOUT
Never Timeout
-
BEKEN_WAIT_FOREVER
Wait Forever
-
BEKEN_NO_WAIT
No Wait
-
NANOSECONDS
Nanoseconds Per Milliseconds
-
MICROSECONDS
Microseconds Per Milliseconds
-
MILLISECONDS
One Milliseconds
-
SECONDS
Milliseconds Per Second
-
MINUTES
Milliseconds Per MINUTES
-
HOURS
Milliseconds Per HOURS
-
DAYS
Milliseconds Per DAYS
-
BEKEN_MAGIC_WORD
Beken Magic word
-
os_printf
OS printf, will be replace with RTOS_LOGI later
-
os_null_printf
OS drop print string
-
rtos_init_semaphore_adv
To be replace with rtos_init_semaphore_ex
-
rtos_get_sema_count
To be replace with rtos_get_semaphore_count
Type Definitions
-
typedef int bk_err_t
Return error code
-
typedef void *beken_thread_arg_t
Thread argument pointer type
-
typedef uint8_t beken_bool_t
Bool type
-
typedef uint32_t beken_time_t
Time value in milliseconds
-
typedef uint32_t beken_utc_time_t
UTC Time in seconds
-
typedef uint64_t beken_utc_time_ms_t
UTC Time in milliseconds
-
typedef uint32_t beken_event_flags_t
Event flag type
-
typedef void *beken_semaphore_t
OS Semaphore handle pointer
-
typedef void *beken_mutex_t
OS Mutex handle pointer
-
typedef void *beken_thread_t
OS Thread handle pointer
-
typedef void *beken_queue_t
OS Queue handle pointer
-
typedef void *beken_event_t
OS Event handle pointer
-
typedef void (*timer_handler_t)(void*)
timer callback function type with one parameter
-
typedef void (*timer_2handler_t)(void *Larg, void *Rarg)
timer callback function type with two parameters
-
typedef void (*beken_thread_function_t)(beken_thread_arg_t arg)
OS Thread entry function type.