[English]

OS API

Functions

void rtos_enter_critical(void)

Enter a critical session, all interrupts are disabled.

参数

void –

返回

  • void

void rtos_exit_critical(void)

Exit a critical session, all interrupts are enabled.

参数

void –

返回

  • void

void rtos_lock_scheduling(void)

disable os scheduling

参数

void –

返回

  • void

void rtos_unlock_scheduling(void)

enable os scheduling

参数

void –

返回

  • void

OSStatus 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 with any step

OSStatus 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. (0:Highest priority, 9:Lowest priority)

  • 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 (can be null)

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

OSStatus 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 with any step

OSStatus rtos_thread_set_priority(beken_thread_t *thread, int priority)

Set thread priority.

参数

thread – : the handle of the thread

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

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 with any step

void rtos_resume_thread(beken_thread_t *thread)

Resume a thread.

参数

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

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

OSStatus 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 with any step

OSStatus 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 with any step

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

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

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.

OSStatus rtos_delay_milliseconds(uint32_t num_ms)

Suspend current thread for a specific time.

参数

num_ms – : A time interval (Unit: millisecond)

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

OSStatus 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

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

OSStatus rtos_init_semaphore(beken_semaphore_t *semaphore, int maxCount)

Initialises a counting semaphore and set count to 0.

参数

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

  • maxCount – : the max count number of this semaphore

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

OSStatus rtos_init_semaphore_adv(beken_semaphore_t *semaphore, int maxCount, int init_count)

Initialises a counting semaphore and set count to init count.

参数

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

  • maxCount – : the max count number of this semaphore

  • init_count – : the init count number of this semaphore

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

OSStatus 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 with any step

OSStatus 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 with any step

int rtos_get_sema_count(beken_semaphore_t *semaphore)

Get (wait/decrement) semaphore number.

参数

semaphore – : a pointer to the semaphore handle

返回

the number of semaphore

OSStatus 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 with any step

OSStatus 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 with any step

OSStatus 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 with any step

OSStatus 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 with any step

OSStatus 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 with any step

OSStatus 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 with any step

OSStatus rtos_init_recursive_mutex(beken_mutex_t *mutex)

Initialises a recursive 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 with any step

OSStatus rtos_lock_recursive_mutex(beken_mutex_t *mutex, uint32_t timeout)

Obtains the lock on a recursive 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

  • timeout: timeout for wait mutex

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

OSStatus rtos_unlock_recursive_mutex(beken_mutex_t *mutex)

Releases the lock on a recursive 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 with any step

OSStatus 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 with any step

OSStatus rtos_push_to_queue(beken_queue_t *queue, void *message, uint32_t timeout_ms)

Pushes an object onto a queue (to the back)

参数

  • 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 occurred with any step

OSStatus 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 occurred with any step

OSStatus 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 occurred with any step

OSStatus 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 with any step

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.

uint32_t rtos_get_time(void)

Gets time in miiliseconds since RTOS start.

Attention

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

返回

Time in milliseconds since RTOS started.

uint64_t rtos_get_time_us(void)

Gets time in microsecond since RTOS start.

Attention

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

返回

Time in milliseconds since RTOS started.

OSStatus rtos_init_oneshot_timer(beken2_timer_t *timer, uint32_t time_ms, timer_2handler_t function, void *larg, void *rarg)

Deinitialization a RTOS oneshot timer.

Attention

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

  • larg – : an argument that will be passed to the callback function

  • rarg – : an argument that will be passed to the callback function

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

OSStatus rtos_deinit_oneshot_timer(beken2_timer_t *timer)

De-initialise a RTOS oneshot timer.

参数

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

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

OSStatus rtos_deinit_oneshot_timer_block(beken2_timer_t *timer)

De-initialise a RTOS timer with block way.

参数

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

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

OSStatus rtos_stop_oneshot_timer(beken2_timer_t *timer)

stop a RTOS oneshot timer

参数

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

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

BOOL rtos_is_oneshot_timer_running(beken2_timer_t *timer)

whether oneshot_timer is running

参数

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

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

OSStatus rtos_start_oneshot_timer(beken2_timer_t *timer)

start a RTOS oneshot timer

参数

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

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

BOOL rtos_is_oneshot_timer_init(beken2_timer_t *timer)

whether oneshot_timer is inited

参数

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

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

OSStatus rtos_oneshot_reload_timer(beken2_timer_t *timer)

Reloads oneshot_timer is inited that has expired.

参数

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

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

OSStatus rtos_change_period_1(beken2_timer_t *timer, uint32_t time_ms)

change timeout for a RTOS oneshot timer that has expired

参数

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

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

OSStatus rtos_init_timer(beken_timer_t *timer, uint32_t time_ms, timer_handler_t function, void *arg)

Initialize a RTOS timer.

Attention

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 with any step

OSStatus rtos_start_timer(beken_timer_t *timer)

Starts a RTOS timer running.

Attention

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

OSStatus rtos_change_period(beken_timer_t *timer, uint32_t time_ms)

change timeout for a RTOS oneshot timer that has expired

参数

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

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

OSStatus rtos_stop_timer(beken_timer_t *timer)

Stops a running RTOS timer.

Attention

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 with any step

OSStatus rtos_reload_timer(beken_timer_t *timer)

Reloads a RTOS timer that has expired.

Attention

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 with any step

OSStatus rtos_deinit_timer(beken_timer_t *timer)

De-initialise a RTOS timer.

Attention

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 with any step

OSStatus rtos_deinit_timer_block(beken_timer_t *timer)

De-initialise a RTOS timer with black way.

Attention

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 with any step

BOOL rtos_is_timer_init(beken_timer_t *timer)

Check if an RTOS timer is running.

参数

timer – : a pointer to the RTOS timer handle

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step

BOOL rtos_is_timer_running(beken_timer_t *timer)

whether oneshot_timer is running

参数

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

返回

  • kNoErr : on success.

  • kGeneralErr : if an error occurred with any step