Microkernel APIs

Events

const kevent_t TICK_EVENT

Well-known events.

void isr_event_send(kevent_t event)

Signal an event from an ISR.

This routine does not validate the specified event number.

Return
N/A
Parameters
  • event: Event to signal.

void fiber_event_send(kevent_t event)

Signal an event from a fiber.

This routine does not validate the specified event number.

Return
N/A
Parameters
  • event: Event to signal.

int task_event_handler_set(kevent_t event, kevent_handler_t handler)

Set event handler request.

This routine specifies the event handler that runs in the context of the microkernel server fiber when the associated event is signaled. Specifying a non-NULL handler installs a new handler, while specifying a NULL event handler removes the existing event handler.

A new event handler cannot be installed if one already exists for that event. The old handler must be removed first. However, the NULL event handler can be replaced with itself.

Parameters
  • event: Event upon which to register.
  • handler: Function pointer to handler.
Return Value
  • RC_FAIL: If an event handler exists or the event number is invalid.
  • RC_OK: Otherwise.

int task_event_send(kevent_t event)

Signal an event request.

This routine signals the specified event from a task. If an event handler is installed for that event, it will run. If no event handler is installed, any task waiting on the event is released.

Parameters
  • event: Event to signal.
Return Value
  • RC_FAIL: If the event number is invalid.
  • RC_OK: Otherwise.

int task_event_recv(kevent_t event, int32_t timeout)

Test for an event request with timeout.

This routine tests an event to see if it has been signaled.

Parameters
  • event: Event to test.
  • timeout: Determines the action to take when the event has not yet been signaled. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successfully received signaled event
  • RC_TIME: Timed out while waiting for signaled event
  • RC_FAIL: Failed to immediately receive signaled event when timeout = TICKS_NONE

FIFOs

int task_fifo_put(kfifo_t queue, void *data, int32_t timeout)

FIFO enqueue request.

This routine adds an item to the FIFO queue. When the FIFO is full, the routine will wait either for space to become available, or until the specified time limit is reached.

See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • queue: FIFO queue.
  • data: Pointer to data to add to queue.
  • timeout: Determines the action to take when the FIFO is full. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successfully added item to FIFO.
  • RC_TIME: Timed out while waiting to add item to FIFO.
  • RC_FAIL: Failed to immediately add item to FIFO when timeout = TICKS_NONE.

int task_fifo_get(kfifo_t queue, void *data, int32_t timeout)

FIFO dequeue request.

This routine fetches the oldest item from the FIFO queue. When the FIFO is found empty, the routine will wait either until an item is added to the FIFO queue or until the specified time limit is reached.

See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • queue: FIFO queue.
  • data: Pointer to storage location of the FIFO entry.
  • timeout: Affects the action to take when the FIFO is empty. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successfully fetched item from FIFO.
  • RC_TIME: Timed out while waiting to fetch item from FIFO.
  • RC_FAIL: Failed to immediately fetch item from FIFO when timeout = TICKS_NONE.

task_fifo_size_get(q) _task_fifo_ioctl(q, 0)

Query the number of FIFO entries.

Return
# of FIFO entries on query.
Parameters
  • q: FIFO queue.

task_fifo_purge(q) _task_fifo_ioctl(q, 1)

Purge the FIFO of all its entries.

Return
RC_OK on purge.

DEFINE_FIFO(name, depth, width) static char __noinit __##name##_buffer[(depth * width)]; \ struct _k_fifo_struct _k_fifo_obj_##name = \ __K_FIFO_DEFAULT(depth, width, __##name##_buffer); \ const kfifo_t name = (kfifo_t)&_k_fifo_obj_##name;

Define a private microkernel FIFO.

This declares and initializes a private FIFO. The new FIFO can be passed to the microkernel FIFO functions.

Parameters
  • name: Name of the FIFO.
  • depth: Depth of the FIFO.
  • width: Width of the FIFO.

Pipes

int task_pipe_put(kpipe_t id, void *buffer, int bytes_to_write, int *bytes_written, K_PIPE_OPTION options, int32_t timeout)

Pipe write request.

Attempt to write data from a memory-buffer area to the specified pipe with a timeout option.

See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • id: Pipe ID.
  • buffer: Buffer.
  • bytes_to_write: Number of bytes to write.
  • bytes_written: Pointer to number of bytes written.
  • options: Pipe options.
  • timeout: Determines the action to take when the pipe is already full. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successfully wrote data to pipe.
  • RC_ALIGNMENT: Data is improperly aligned.
  • RC_INCOMPLETE: Only some of the data was written to the pipe when options = _ALL_N.
  • RC_TIME: Timed out while waiting to write to pipe.
  • RC_FAIL: Failed to immediately write to pipe when timeout = TICKS_NONE

int task_pipe_get(kpipe_t id, void *buffer, int bytes_to_read, int *bytes_read, K_PIPE_OPTION options, int32_t timeout)

Pipe read request.

Attempt to read data into a memory buffer area from the specified pipe with a timeout option.

See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • id: Pipe ID.
  • buffer: Buffer.
  • bytes_to_read: Number of bytes to read.
  • bytes_read: Pointer to number of bytes read.
  • options: Pipe options.
  • timeout: Determines the action to take when the pipe is already full. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successfully read data from pipe.
  • RC_ALIGNMENT: Data is improperly aligned.
  • RC_INCOMPLETE: Only some of the data was read from the pipe when options = _ALL_N.
  • RC_TIME: Timed out waiting to read from pipe.
  • RC_FAIL: Failed to immediately read from pipe when timeout = TICKS_NONE.

int _task_pipe_block_put(kpipe_t id, struct k_block block, int size, ksem_t sema)
task_pipe_block_put(id, block, size, sema) _task_pipe_block_put(id, block, size, sema)

Asynchronous pipe write request.

This routine attempts to write data from a memory pool block to the specified pipe. (Note that partial transfers and timeouts are not supported, unlike the case for synchronous write requests.)

Return
RC_OK, RC_FAIL, or RC_ALIGNMENT
Parameters
  • id: Pipe ID.
  • block: Block.
  • size: Size of data to be transferred.
  • sema: Semphore ID.

DEFINE_PIPE(name, size) char __noinit __pipe_buffer_##name[size]; \ struct _k_pipe_struct _k_pipe_obj_##name = \ __K_PIPE_INITIALIZER(size, __pipe_buffer_##name); \ const kpipe_t name \ __in_section(_k_pipe_ptr, private, pipe) = \ (kpipe_t)&_k_pipe_obj_##name;

Define a private microkernel pipe.

Parameters
  • name: Name of the pipe.
  • size: Size of the pipe buffer, in bytes.

Interrupt Services

uint32_t task_irq_alloc(kirq_t irq_obj, uint32_t irq, uint32_t priority, uint32_t flags)

Register a task IRQ object.

This routine connects a task IRQ object to a system interrupt based upon the specified IRQ and priority values.

IRQ allocation is done via the microkernel server fiber, making simultaneous allocation requests single-threaded.

Return
assigned interrupt vector if successful, INVALID_VECTOR if not
Parameters
  • irq_obj: IRQ object identifier.
  • irq: Request IRQ.
  • priority: Requested interrupt priority.
  • flags: IRQ flags.

void task_irq_ack(kirq_t irq_obj)

Re-enable a task IRQ object’s interrupt.

This re-enables the interrupt for a task IRQ object.

Return
N/A
Parameters
  • irq_obj: IRQ object identifier.

int task_irq_wait(kirq_t irq_obj, int32_t timeout)

Wait for task IRQ to signal an interrupt.

This routine waits up to timeout ticks for the IRQ object irq_obj to signal an interrupt.

See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • irq_obj: IRQ object identifier.
  • timeout: Determines the action when task IRQ is not yet signaled. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successfully detected signaled interrupt.
  • RC_TIME: Timed out while waiting for interrupt.
  • RC_FAIL: Failed to immediately detect signaled interrupt when timeout = TICKS_NONE.

INVALID_VECTOR 0xFFFFFFFF

Mailboxes

int task_mbox_put(kmbox_t mbox, kpriority_t prio, struct k_msg *M, int32_t timeout)

Send a message to a mailbox.

This routine sends a message to a mailbox and looks for a matching receiver.

Return
RC_OK Successfully delivered message.
Return
RC_TIME Timed out while waiting to deliver message.
Return
RC_FAIL Failed to immediately deliver message when timeout = TICKS_NONE.
See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • mbox: Mailbox.
  • prio: Priority of data transfer.
  • M: Pointer to message to send.
  • timeout: Determines the action to take when there is no waiting receiver. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.

int task_mbox_get(kmbox_t mbox, struct k_msg *M, int32_t timeout)

Get struct k_msg message header structure information from a mailbox and wait with timeout.

Return
RC_OK Successfully received message.
Return
RC_TIME Timed out while waiting to receive message.
Return
RC_FAIL Failed to immediately receive message when timeout = TICKS_NONE.
See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • mbox: Mailbox.
  • M: Pointer to message.
  • timeout: Determines the action to take when there is no waiting receiver. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.

int task_mbox_data_block_get(struct k_msg *M, struct k_block *block, kmemory_pool_t pool_id, int32_t timeout)

Retrieve message data into a block, with time-limited waiting.

See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • M: Message from which to get data.
  • block: Block.
  • pool_id: Memory pool name.
  • timeout: Determines the action to take when no waiting sender exists. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successful retrieval of message data.
  • RC_TIME: Timed out while waiting to receive message data.
  • RC_FAIL: Failed to immediately receive message data when timeout = TICKS_NONE.

task_mbox_block_put(b, p, m, s) _task_mbox_block_put(b, p, m, s)

Send a message asynchronously to a mailbox.

This routine sends a message to a mailbox and does not wait for a matching receiver. No exchange header is returned to the sender. When the data has been transferred to the receiver, the semaphore signaling is performed.

Return
N/A
Parameters
  • b: Mailbox to which to send message.
  • p: Priority of data transfer.
  • m: Pointer to message to send.
  • s: Semaphore to signal when transfer is complete.

task_mbox_data_get(m) _task_mbox_data_get(m)

Get message data.

Call this routine for one of two reasons:

  1. To transfer data when the call to task_mbox_get() yields an existing field in the struct k_msg header structure.
  2. To wake up and release a transmitting task currently blocked from calling task_mbox_put[wait|wait_timeout]().

Return
N/A
Parameters
  • m: Message from which to get data.

DEFINE_MAILBOX(name) struct _k_mbox_struct _k_mbox_obj_##name = __K_MAILBOX_DEFAULT; \ const kmbox_t name = (kmbox_t)&_k_mbox_obj_##name;

Define a private microkernel mailbox.

This routine declares and initializes a private mailbox. The new mailbox can be passed to the microkernel mailbox functions.

Parameters
  • name: Name of the mailbox

Memory Maps

int task_mem_map_used_get(kmemory_map_t map)

Read the number of used blocks in a memory map.

This routine returns the number of blocks in use for the memory map.

Return
Number of used blocks.
Parameters
  • map: Memory map name.

int task_mem_map_alloc(kmemory_map_t mmap, void **mptr, int32_t timeout)

Allocate memory map block.

This routine allocates a block from memory map mmap, and saves the block’s address in the area indicated by mptr. When no block is available, the routine waits until either one can be allocated, or until the specified time limit is reached.

See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • mmap: Memory map name.
  • mptr: Pointer to memory block address area.
  • timeout: Determines the action to take when the memory map is exhausted. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successfully allocated memory block.
  • RC_TIME: Timed out while waiting for memory block.
  • RC_FAIL: Failed to immediately allocate memory block when timeout = TICKS_NONE.

task_mem_map_free(m, p) _task_mem_map_free(m, p)

Return memory map block.

This routine returns a block to the specified memory map.

Return
N/A
Parameters
  • m: Memory map name.
  • p: Memory block address.

DEFINE_MEM_MAP(name, blocks, block_size) char __noinit __mem_map_buffer_##name[(blocks * block_size)]; \ struct _k_mem_map_struct _k_mem_map_obj_##name = \ __K_MEM_MAP_INITIALIZER(blocks, block_size, \ __mem_map_buffer_##name); \ const kmemory_map_t name \ __in_section(_k_mem_map_ptr, private, mem_map) = \ (kmemory_map_t)&_k_mem_map_obj_##name;

Define a private microkernel memory map.

Parameters
  • name: Memory map name.
  • blocks: Number of blocks.
  • block_size: Size of each block, in bytes.

Memory Pools

void task_mem_pool_free(struct k_block *b)

Return memory pool block.

This routine returns a block to the memory pool from which it was allocated.

Return
N/A
Parameters
  • b: Pointer to block descriptor.

void task_mem_pool_defragment(kmemory_pool_t p)

Defragment memory pool.

This routine concatenates unused blocks that can be merged in memory pool p.

Doing a full defragmentation of a memory pool before allocating a set of blocks may be more efficient than having the pool do an implicit partial defragmentation each time a block is allocated.

Return
N/A
Parameters
  • p: Memory pool name.

int task_mem_pool_alloc(struct k_block *blockptr, kmemory_pool_t pool_id, int reqsize, int32_t timeout)

Allocate memory pool block.

This routine allocates a block of at least reqsize bytes from memory pool pool_id, and saves its information in block descriptor blockptr. When no such block is available, the routine waits either until one can be allocated, or until the specified time limit is reached.

See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • blockptr: Pointer to block descriptor.
  • pool_id: Memory pool name.
  • reqsize: Requested block size, in bytes.
  • timeout: Determines the action to take when the memory pool is exhausted. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successfully allocated memory block
  • RC_TIME: Timed out while waiting for memory block
  • RC_FAIL: Failed to immediately allocate memory block when timeout = TICKS_NONE

void *task_malloc(uint32_t size)

Allocate memory.

This routine provides traditional malloc semantics and is a wrapper on top of microkernel pool alloc API. It returns an aligned memory address which points to the start of a memory block of at least size bytes. This memory comes from heap memory pool, consequently the app should specify its intention to use a heap pool via the HEAP_SIZE keyword in MDEF file, if it uses this API. When not enough free memory is available in the heap pool, it returns NULL

Parameters
  • size: Size of memory requested by the caller.
Return Value
  • address: of the block if successful otherwise returns NULL

void task_free(void *ptr)

Free memory allocated through task_malloc.

This routine provides traditional free semantics and is intended to free memory allocated using task_malloc API.

Return
NA
Parameters
  • ptr: pointer to be freed

Mutexes

void _task_mutex_unlock(kmutex_t mutex)
int task_mutex_lock(kmutex_t mutex, int32_t timeout)

Lock mutex.

This routine locks mutex mutex. When the mutex is locked by another task, the routine will either wait until it becomes available, or until a specified time limit is reached.

A task is permitted to lock a mutex it has already locked; in such a case, this routine immediately succeeds.

See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • mutex: Mutex name.
  • timeout: Determine the action to take when the mutex is already locked. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successfully locked mutex.
  • RC_TIME: Timed out while waiting for mutex.
  • RC_FAIL: Failed to immediately lock mutex when timeout = TICKS_NONE.

__MUTEX_DEFAULT { \ .owner = ANYTASK, \ .current_owner_priority = 64, \ .original_owner_priority = 64, \ .level = 0, \ .waiters = NULL, \ .count = 0, \ .num_conflicts = 0, \ }
task_mutex_unlock(m) _task_mutex_unlock(m)

Unlock mutex.

This routine unlocks mutex m. The mutex must already be locked by the requesting task.

The mutex cannot be claimed by another task until it has been unlocked by the requesting task as many times as it was locked by that task.

Return
N/A
Parameters
  • m: Mutex name.

DEFINE_MUTEX(name) struct _k_mutex_struct _k_mutex_obj_##name = __MUTEX_DEFAULT; \ const kmutex_t name = (kmutex_t)&_k_mutex_obj_##name;

Define a private mutex.

Parameters
  • name: Mutex name.

Semaphores

void _k_sem_struct_value_update(int n, struct _k_sem_struct *S)
void isr_sem_give(ksem_t sema)

Give semaphore from an ISR.

This routine gives semaphore sema from an ISR, rather than a task.

Return
N/A
Parameters
  • sema: Semaphore name.

void fiber_sem_give(ksem_t sema)

Give semaphore from a fiber.

This routine gives semaphore sema from a fiber, rather than a task.

Return
N/A
Parameters
  • sema: Semaphore name.

void task_sem_give(ksem_t sema)

Give semaphore.

This routine gives semaphore sema.

Return
N/A
Parameters
  • sema: Semaphore name.

void task_sem_group_give(ksemg_t semagroup)

Give a group of semaphores.

This routine gives each semaphore in a semaphore group semagroup. This method is faster than giving the semaphores individually, and ensures that all the semaphores are given before any waiting tasks run.

Return
N/A
Parameters
  • semagroup: Array of semaphore names - terminated by ENDLIST.

int task_sem_count_get(ksem_t sema)

Read a semaphore’s count.

This routine reads the current count of the semaphore sema.

Return
Semaphore count.
Parameters
  • sema: Semaphore name.

void task_sem_reset(ksem_t sema)

Reset the semaphore’s count.

This routine resets the count of the semaphore sema to zero.

Return
N/A
Parameters
  • sema: Semaphore name.

void task_sem_group_reset(ksemg_t semagroup)

Reset a group of semaphores.

This routine resets the count for each semaphore in the sempahore group semagroup to zero. This method is faster than resetting the semaphores individually.

Return
N/A
Parameters
  • semagroup: Array of semaphore names - terminated by ENDLIST.

int task_sem_take(ksem_t sema, int32_t timeout)

Take a semaphore or fail.

This routine takes the semaphore sema. If the semaphore’s count is zero the routine immediately returns a failure indication.

See
TICKS_NONE, TICKS_UNLIMITED must be added.
Parameters
  • sema: Semaphore name.
  • timeout: Determines the action to take when the semaphore is unavailable. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successfully took semaphore
  • RC_TIME: Timed out while waiting for semaphore
  • RC_FAIL: Failed to immediately take semaphore when timeout = TICKS_NONE

ksem_t task_sem_group_take(ksemg_t group, int32_t timeout)

Wait for a semaphore from the semaphore group.

This routine waits for the timeout ticks to take a semaphore from the semaphore group group.

See
TICKS_NONE, TICKS_UNLIMITED must be added.
Parameters
  • group: Array of semaphore names - terminated by ENDLIST.
  • timeout: Determines the action to take when the semaphore is unavailable. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • sema: Name of the semaphore that was taken if successful.
  • ENDLIST: Otherwise.

__K_SEMAPHORE_DEFAULT { \ .waiters = NULL, \ .level = 0, \ .count = 0, \ }

Initializer for a semaphore.

DEFINE_SEMAPHORE(name) struct _k_sem_struct _k_sem_obj_##name = __K_SEMAPHORE_DEFAULT; \ const ksem_t name = (ksem_t)&_k_sem_obj_##name;

Define a private microkernel semaphore.

Parameters
  • name: Semaphore name.

Timers

void sys_scheduler_time_slice_set(int32_t t, kpriority_t p)

Set time-slicing period and scope.

This routine controls how task time slicing is performed by the task scheduler; it specifes the maximum time slice length (in ticks) and the highest priority task level for which time slicing is performed.

To enable time slicing, a non-zero time slice length must be specified. The task scheduler then ensures that no executing task runs for more than the specified number of ticks before giving other tasks of that priority a chance to execute. (However, any task whose priority is higher than the specified task priority level is exempted, and may execute as long as desired without being pre-empted due to time slicing.)

Time slicing limits only the maximum amount of time a task may continuously execute. Once the scheduler selects a task for execution, there is no minimum guaranteed time the task will execute before tasks of greater or equal priority are scheduled.

When the currently-executing task is the only one of that priority eligible for execution, this routine has no effect; the task is immediately rescheduled after the slice period expires.

To disable timeslicing, call the API with both parameters set to zero.

Return
N/A

ktimer_t task_timer_alloc(void)

Allocate a timer and return its object identifier.

Return
timer identifier

void task_timer_free(ktimer_t timer)

Deallocate a timer.

This routine frees the resources associated with the timer. If a timer was started, it has to be stopped using task_timer_stop() before it can be freed.

Return
N/A
Parameters
  • timer: Timer to deallocate.

void task_timer_start(ktimer_t timer, int32_t duration, int32_t period, ksem_t sema)

Start or restart the specified low-resolution timer.

This routine starts or restarts the specified low-resolution timer.

Signals the semaphore after a specified number of ticks set by duration expires. The timer repeats the expiration/signal cycle each time period ticks elapses.

Setting period to 0 stops the timer at the end of the initial delay.

If either duration or period is passed an invalid value (duration <= 0, period < 0), this kernel API acts like a task_timer_stop(): if the allocated timer was still running (from a previous call), it will be cancelled; if not, nothing will happen.

Return
N/A
Parameters
  • timer: Timer to start.
  • duration: Initial delay in ticks.
  • period: Repetition interval in ticks.
  • sema: Semaphore to signal.

static void task_timer_restart(ktimer_t timer, int32_t duration, int32_t period)

Restart a timer.

This routine restarts the timer specified by timer. The timer must have previously been started by a call to task_timer_start().

Return
N/A
Parameters
  • timer: Timer to restart.
  • duration: Initial delay.
  • period: Repetition interval.

void task_timer_stop(ktimer_t timer)

Stop a timer.

This routine stops the specified timer. If the timer period has already elapsed, the call has no effect.

Return
N/A
Parameters
  • timer: Timer to stop.

static void task_sleep(int32_t ticks)

Sleep for a number of ticks.

This routine suspends the calling task for the specified number of timer ticks. When the suspension expires, the task is rescheduled by priority.

Return
N/A
Parameters
  • ticks: Number of ticks for which to sleep.

int task_workload_get(void)

Read the processor workload.

This routine returns the workload as a number ranging from 0 to 1000.

Each unit equals 0.1% of the time the idle task was not scheduled by the microkernel during the period set by sys_workload_time_slice_set().

IMPORTANT: This workload monitor ignores any time spent servicing ISRs and fibers! Thus, a system with no meaningful task work to do may spend up to 100% of its time servicing ISRs and fibers, yet it will report 0% workload because the microkernel always selects the idle task.

Return
workload

void sys_workload_time_slice_set(int32_t t)

Set workload period.

This routine specifies the workload measuring period for task_workload_get().

Return
N/A
Parameters
  • t: Time slice

Tasks

void task_yield(void)

Yield the CPU to another task.

This routine yields the processor to the next-equal priority runnable task. With task_yield(), the effect of round-robin scheduling is possible. When no task of equal priority is runnable, no task switch occurs, and the calling task resumes execution.

Return
N/A

void task_priority_set(ktask_t task, kpriority_t prio)

Set the priority of a task.

This routine changes the priority of the specified task.

The call has immediate effect. When the calling task no longer is the highest-priority runnable task, a task switch occurs.

Priority can be assigned in the range 0 to 62, where 0 is the highest priority.

Return
N/A
Parameters
  • task: Task whose priority is to be set.
  • prio: New priority.

void task_entry_set(ktask_t task, void (*func)(void))

Set the entry point of a task.

This routine sets the entry point of a task to a given routine. It is needed only when an entry point differs from what is set in the project file. In order to have any effect, it must be called before task_start(), and it cannot work with members of the EXE group or with any group that starts automatically on application loading.

The routine is executed when the task is started.

Return
N/A
Parameters
  • task: Task to operate on.
  • func: Entry point.

void task_abort_handler_set(void (*func)(void))

Install an abort handler.

This routine installs an abort handler for the calling task.

The abort handler runs when the calling task is aborted by a _TaskAbort() or task_group_abort() call.

Each call to task_abort_handler_set() replaces the previously-installed handler.

To remove an abort handler, set the parameter to NULL as below: task_abort_handler_set (NULL)

Return
N/A
Parameters
  • func: Abort handler.

int task_offload_to_fiber(int (*func)()void *argp, )

Issue a custom call from within the microkernel server fiber.

This routine issues a request to execute a function from within the context of the microkernel server fiber.

Return
return value from custom func call
Parameters
  • func: Function to call from within the microkernel server fiber.
  • argp: Argument to pass to custom function.

ktask_t task_id_get(void)

Gets task identifier.

Return
identifier for current task

kpriority_t task_priority_get(void)

Gets task priority.

Return
priority of current task

uint32_t task_group_mask_get(void)

Get task groups for task.

Return
task groups associated with current task

void task_group_join(uint32_t groups)

Add task to task group(s)

Return
N/A
Parameters
  • groups: Task Groups

void task_group_leave(uint32_t groups)

Remove task from task group(s)

Return
N/A
Parameters
  • groups: Task Groups

EXE_GROUP 1 /* TASKGROUP EXE */
USR_GROUP 2 /* TASKGROUP SYS */
FPU_GROUP 4 /* TASKGROUP FPU */
TASK_START 0
TASK_ABORT 1
TASK_SUSPEND 2
TASK_RESUME 3
TASK_BLOCK 4
TASK_UNBLOCK 5
TASK_GROUP_START 0
TASK_GROUP_ABORT 1
TASK_GROUP_SUSPEND 2
TASK_GROUP_RESUME 3
TASK_GROUP_BLOCK 4
TASK_GROUP_UNBLOCK 5
task_start(t) _task_ioctl(t, TASK_START)

Start a task.

Return
N/A
Parameters
  • t: Task to start

task_abort(t) _task_ioctl(t, TASK_ABORT)

Abort a task.

Return
N/A
Parameters
  • t: Task to abort

task_suspend(t) _task_ioctl(t, TASK_SUSPEND)

Suspend a task.

Return
N/A
Parameters
  • t: Task to suspend

task_resume(t) _task_ioctl(t, TASK_RESUME)

Resume a task.

Return
N/A
Parameters
  • t: Task to resume

task_group_start(g) _task_group_ioctl(g, TASK_GROUP_START)

Start a task group.

Return
N/A
Parameters
  • g: Task group to start

task_group_abort(g) _task_group_ioctl(g, TASK_GROUP_ABORT)

Abort a task group.

Return
N/A
Parameters
  • g: Task group to abort

task_group_suspend(g) _task_group_ioctl(g, TASK_GROUP_SUSPEND)

Suspend a task group.

Return
N/A
Parameters
  • g: Task group to suspend

task_group_resume(g) _task_group_ioctl(g, TASK_GROUP_RESUME)

Resume a task group.

Return
N/A
Parameters
  • g: Task group to resume

isr_task_id_get task_id_get()

Get task identifier.

Return
identifier for current task

isr_task_priority_get task_priority_get()

Get task priority.

Return
priority of current task

isr_task_group_mask_get task_group_mask_get()

Get task groups for task.

Return
task groups associated with current task

DEFINE_TASK(name, priority, entry, stack_size, groups) extern void entry(void); \ char __noinit __stack __stack_##name[stack_size]; \ struct k_task _k_task_obj_##name \ __in_section(_k_task_list, private, task) = \ __K_TASK_INITIALIZER( \ (ktask_t)&_k_task_obj_##name, \ priority, 0x00000001, groups, \ entry, &__stack_##name[0], stack_size, NULL); \ const ktask_t name \ __in_section(_k_task_ptr, private, task) = \ (ktask_t)&_k_task_obj_##name;

Define a private microkernel task.

This declares and initializes a private task. The new task can be passed to the microkernel task functions.

Parameters
  • name: Name of the task.
  • priority: Priority of task.
  • entry: Entry function.
  • stack_size: Size of stack (in bytes)
  • groups: Groups this task belong to.