OS API

[English]

  • OS抽象层主要为了适配Armino平台不同的操作系统

  • 对于不同的操作系统,OS抽象层对外提供一套统一的接口

  • 目前Armino平台OS抽象层支持的操作系统有FreeRTOS,鸿蒙OS,RTThread.

Header File

Functions

void rtos_enter_critical(void)

Enter a critical session, all interrupts are disabled.

返回

none

void rtos_exit_critical(void)

Exit a critical session, all interrupts are enabled.

返回

none

bk_err_t beken_time_get_time(beken_time_t *time_ptr)

Get system time value in milliseconds.

参数

time_ptr – : the pointer of time value in milliseconds

返回

kNoErr : on success.

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.

参数
  • 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

返回

kNoErr : on success.

kGeneralErr : if an error occurred

bk_err_t rtos_delete_thread(beken_thread_t *thread)

Deletes a terminated thread.

参数

thread – : the handle of the thread to delete, , NULL is the current thread

返回

kNoErr : on success.

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.

参数
  • 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

返回

kNoErr : on success.

kGeneralErr : if an error occurred

bk_err_t rtos_delete_worker_thread(beken_worker_thread_t *worker_thread)

Deletes a worker thread.

参数

worker_thread – : a pointer to the worker thread to be created

返回

kNoErr : on success.

kGeneralErr : if an error occurred

void rtos_suspend_thread(beken_thread_t *thread)

Suspend a thread.

参数

thread – : the handle of the thread to suspend, NULL is the current thread

返回

kNoErr : on success.

kGeneralErr : if an error occurred

void rtos_suspend_all_thread(void)

Suspend all other thread.

参数

none

返回

none

void rtos_resume_thread(beken_thread_t *thread)

resume a thread

参数

thread – : the handle of the thread to resume, NULL is the current thread

返回

none

long rtos_resume_all_thread(void)

Rresume all other thread.

参数

none

返回

none

bk_err_t rtos_thread_join(beken_thread_t *thread)

Sleeps until another thread has terminated.

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.

参数

thread – : the handle of the other thread which will terminate

返回

kNoErr : on success.

kGeneralErr : if an error occurred

bk_err_t rtos_thread_force_awake(beken_thread_t *thread)

Forcibly wakes another thread.

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.

参数

thread – : the handle of the other thread which will be woken

返回

kNoErr : on success.

kGeneralErr : if an error occurred

bool rtos_is_current_thread(beken_thread_t *thread)

Checks if a thread is the current thread.

Checks if a specified thread is the currently running thread

参数

thread – : the handle of the other thread against which the current thread will be compared

返回

true : specified thread is the current thread

false : specified thread is not currently running

beken_thread_t *rtos_get_current_thread(void)

Get current thread handler.

返回

Current RTOS thread handler

void rtos_thread_sleep(uint32_t seconds)

Suspend current thread for a specific time.

参数

seconds – : A time interval (Unit: seconds)

返回

None.

void rtos_thread_msleep(uint32_t milliseconds)

Suspend current thread for a specific time.

参数

milliseconds – : A time interval (Unit: millisecond)

返回

None.

bk_err_t rtos_delay_milliseconds(uint32_t num_ms)

Suspend current thread for a specific time.

参数

num_ms – : A time interval (Unit: millisecond)

返回

kNoErr.

bk_err_t rtos_print_thread_status(char *buffer, int length)

Print Thread status into buffer.

参数
  • buffer, point – to buffer to store thread status

  • length, length – of the buffer

返回

none

bk_err_t rtos_init_semaphore(beken_semaphore_t *semaphore, int max_count)

Initialises a counting semaphore and set count to 0.

参数
  • semaphore – : a pointer to the semaphore handle to be initialised

  • max_count – : the max count number of this semaphore

返回

kNoErr : on success.

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.

参数
  • 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

返回

kNoErr : on success.

kGeneralErr : if an error occurred

bk_err_t rtos_set_semaphore(beken_semaphore_t *semaphore)

Set (post/put/increment) a semaphore.

参数

semaphore – : a pointer to the semaphore handle to be set

返回

kNoErr : on success.

kGeneralErr : if an error occurred

bk_err_t rtos_get_semaphore(beken_semaphore_t *semaphore, uint32_t timeout_ms)

Get (wait/decrement) a semaphore.

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

参数
  • semaphore – : a pointer to the semaphore handle

  • timeout_ms, : – the number of milliseconds to wait before returning

返回

kNoErr : on success.

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.

Deletes a semaphore created with rtos_init_semaphore

参数

semaphore – : a pointer to the semaphore handle

返回

kNoErr : on success.

kGeneralErr : if an error occurred

bk_err_t rtos_init_mutex(beken_mutex_t *mutex)

Initialises a mutex.

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.

参数

mutex – : a pointer to the mutex handle to be initialised

返回

kNoErr : on success.

kGeneralErr : if an error occurred

bk_err_t rtos_trylock_mutex(beken_mutex_t *mutex)

Obtains the lock on a mutex.

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.

参数

mutex – : a pointer to the mutex handle to be locked

返回

kNoErr : on success.

kGeneralErr : if an error occurred

bk_err_t rtos_lock_mutex(beken_mutex_t *mutex)

Obtains the lock on a mutex.

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.

参数

mutex – : a pointer to the mutex handle to be locked

返回

kNoErr : on success.

kGeneralErr : if an error occurred

bk_err_t rtos_unlock_mutex(beken_mutex_t *mutex)

Releases the lock on a mutex.

Releases a currently held lock on a mutex. If another thread is waiting on the mutex lock, then it will be resumed.

参数

mutex – : a pointer to the mutex handle to be unlocked

返回

kNoErr : on success.

kGeneralErr : if an error occurred

bk_err_t rtos_deinit_mutex(beken_mutex_t *mutex)

De-initialise a mutex.

Deletes a mutex created with rtos_init_mutex

参数

mutex – : a pointer to the mutex handle

返回

kNoErr : on success.

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.

参数
  • 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

返回

kNoErr : on success.

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.

参数
  • 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

返回

kNoErr : on success.

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.

参数
  • 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

返回

kNoErr : on success.

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.

参数
  • 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

返回

kNoErr : on success.

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.

参数

queue – : a pointer to the queue handle

返回

kNoErr : on success.

kGeneralErr : if an error occurred

bool rtos_is_queue_empty(beken_queue_t *queue)

Check if a queue is empty.

参数

queue – : a pointer to the queue handle

返回

true : queue is empty.

false : queue is not empty.

bool rtos_is_queue_full(beken_queue_t *queue)

Check if a queue is full.

参数

queue – : a pointer to the queue handle

返回

true : queue is empty.

false : queue is not empty.

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.

参数
  • 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

返回

kNoErr : on success.

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.

参数
  • 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

返回

kNoErr : on success.

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.

参数

event_object – : the event handle used with rtos_register_timed_event

返回

kNoErr : on success.

kGeneralErr : if an error occurred

uint32_t rtos_get_time(void)

Gets time in miiliseconds since RTOS start.

备注

: Since this is only 32 bits, it will roll over every 49 days, 17 hours.

返回

Time in milliseconds since RTOS started.

uint32_t beken_ms_per_tick(void)

Gets time in miiliseconds since RTOS start.

备注

: Since this is only 32 bits, it will roll over every 49 days, 17 hours.

返回

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.

备注

Timer does not start running until beken_start_timer is called

参数
  • 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

返回

kNoErr : on success.

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.

备注

Timer must have been previously initialised with rtos_init_timer

参数

timer – : a pointer to the timer handle to start

返回

kNoErr : on success.

kGeneralErr : if an error occurred

bk_err_t rtos_stop_timer(beken_timer_t *timer)

Stops a running RTOS timer.

备注

Timer must have been previously started with rtos_init_timer

参数

timer – : a pointer to the timer handle to stop

返回

kNoErr : on success.

kGeneralErr : if an error occurred

bk_err_t rtos_reload_timer(beken_timer_t *timer)

Reloads a RTOS timer that has expired.

备注

This is usually called in the timer callback handler, to reschedule the timer for the next period.

参数

timer – : a pointer to the timer handle to reload

返回

kNoErr : on success.

kGeneralErr : if an error occurred

bk_err_t rtos_deinit_timer(beken_timer_t *timer)

De-initialise a RTOS timer.

备注

Deletes a RTOS timer created with rtos_init_timer

参数

timer – : a pointer to the RTOS timer handle

返回

kNoErr : on success.

kGeneralErr : if an error occurred

bool rtos_is_timer_init(beken_timer_t *timer)

Check if an RTOS timer is init.

参数

timer – : a pointer to the RTOS timer handle

返回

true : if init.

false : if not init

bool rtos_is_timer_running(beken_timer_t *timer)

Check if an RTOS timer is running.

参数

timer – : a pointer to the RTOS timer handle

返回

true : if running.

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)

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

struct beken_worker_thread_t

OS worker thread handle struct type.

Public Members

beken_thread_t thread

OS thread handle

beken_queue_t event_queue

OS event queue

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

struct beken2_timer_t

OS timer handle struct type.

Public Members

void *handle

OS timer handle pointer

timer_2handler_t function

OS timer handle callback function

void *left_arg

OS timer handle callback first argument

void *right_arg

OS timer handle callback second argument

uint32_t beken_magic

OS timer magic word

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 bk_err_t (*event_handler_t)(void *arg)

event callback function type with one parameter

typedef void (*beken_thread_function_t)(beken_thread_arg_t arg)

OS Thread entry function type.

Enumerations

enum beken_event_flags_wait_option_t

OS Event wait options.

Values:

enumerator WAIT_FOR_ANY_EVENT

Wait for any event

enumerator WAIT_FOR_ALL_EVENTS

Wait for all event