Nanokernel APIs

Fibers

void fiber_start(char *stack, unsigned stack_size, nano_fiber_entry_t entry, int arg1, int arg2, unsigned prio, unsigned options)

Initialize and start a fiber.

This routine initializes and starts a fiber. It can be called from either a fiber or a task. When this routine is called from a task, the newly created fiber will start executing immediately.

Return

N/A

Parameters

• stack -

  Pointer to the stack space.

• stack_size -

  Stack size in bytes.

• entry -

  Fiber entry.

• arg1 -

  1st entry point parameter.

• arg2 -

  2nd entry point parameter.

• prio -

  The fiber’s priority.

• options -

  Not used currently.

void fiber_fiber_start(char *pStack, unsigned int stackSize, nano_fiber_entry_t entry, int arg1, int arg2, unsigned prio, unsigned options)

Initialize and start a fiber from a fiber.

This routine initializes and starts a fiber. It can only be called from a fiber.

Return

N/A

Parameters

• pStack -

  Pointer to the stack space.

• stackSize -

  Stack size in bytes.

• entry -

  Fiber entry.

• arg1 -

  1st entry point parameter.

• arg2 -

  2nd entry point parameter.

• prio -

  The fiber’s priority.

• options -

  Not used currently.

void fiber_yield(void)

Yield the current fiber.

Calling this routine results in the current fiber yielding to another fiber of the same or higher priority. If there are no other runnable fibers of the same or higher priority, the routine will return immediately.

This routine can only be called from a fiber.

Return

N/A

void fiber_abort(void)

Abort the currently executing fiber.

This routine aborts the currently executing fiber. An abort can occur because of one of three reasons:

• The fiber has explicitly aborted itself by calling this routine.
• The fiber has implicitly aborted itself by returning from its entry point.
• The fiber has encountered a fatal exception.

This routine can only be called from a fiber.

Return

N/A

void fiber_sleep(int32_t timeout_in_ticks)

Put the current fiber to sleep.

This routine puts the currently running fiber to sleep for the number of system ticks passed in the timeout_in_ticks parameter.

Return

N/A

Parameters

• timeout_in_ticks -

  Number of system ticks the fiber sleeps.

void task_sleep(int32_t timeout_in_ticks)

Put the task to sleep.

This routine puts the currently running task to sleep for the number of system ticks passed in the timeout_in_ticks parameter.

Warning

A value of TICKS_UNLIMITED is considered invalid and may result in unexpected behavior.

Return

N/A

See

TICKS_UNLIMITED

Parameters

• timeout_in_ticks -

  Number of system ticks the task sleeps.

void *fiber_fiber_delayed_start(char *stack, unsigned int stack_size_in_bytes, nano_fiber_entry_t entry_point, int param1, int param2, unsigned int priority, unsigned int options, int32_t timeout_in_ticks)

Start a fiber while delaying its execution.

This routine can only be called from a fiber.

Return

A handle potentially used to cancel the delayed start.

Parameters

• stack -

  Pointer to the stack space.

• stack_size_in_bytes -

  Stack size in bytes.

• entry_point -

  The fiber’s entry point.

• param1 -

  1st entry point parameter.

• param2 -

  2nd entry point parameter.

• priority -

  The fiber’s priority.

• options -

  Not used currently.

• timeout_in_ticks -

  Timeout duration in ticks.

void *fiber_delayed_start(char *stack, unsigned int stack_size_in_bytes, nano_fiber_entry_t entry_point, int param1, int param2, unsigned int priority, unsigned int options, int32_t timeout_in_ticks)

void fiber_delayed_start_cancel(void *handle)

void fiber_fiber_delayed_start_cancel(void *handle)

Cancel a delayed fiber start.

Return

N/A

See

fiber_fiber_delayed_start

Parameters

• handle -

  The handle returned when starting the delayed fiber.

Tasks

void task_fiber_start(char *pStack, unsigned int stackSize, nano_fiber_entry_t entry, int arg1, int arg2, unsigned prio, unsigned options)

Initialize and start a fiber from a task.

See

fiber_fiber_start

void *task_fiber_delayed_start(char *stack, unsigned int stack_size_in_bytes, nano_fiber_entry_t entry_point, int param1, int param2, unsigned int priority, unsigned int options, int32_t timeout_in_ticks)

Start a fiber from a task while delaying its execution.

See

fiber_fiber_delayed_start

void task_fiber_delayed_start_cancel(void *handle)

Cancel a delayed fiber start from a task.

See

fiber_fiber_delayed_start_cancel

Semaphores

void nano_sem_init(struct nano_sem *sem)

Initialize a nanokernel semaphore object.

This function initializes a nanokernel semaphore object structure. After initialization, the semaphore count is 0.

It can be called from either a fiber or task.

Return

N/A

Parameters

• sem -

  Pointer to a nano_sem structure.

void nano_sem_give(struct nano_sem *sem)

Give a nanokernel semaphore.

This routine is a convenience wrapper for the execution of context-specific APIs. It is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Return

N/A

Parameters

• sem -

  Pointer to a nano_sem structure.

int nano_sem_take(struct nano_sem *sem, int32_t timeout_in_ticks)

Take a nanokernel semaphore, poll/pend if not available.

This routine is a convenience wrapper for the execution of context-specific APIs. It is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Warning

If it is to be called from the context of an ISR, then timeout_in_ticks must be set to TICKS_NONE.

See

TICKS_NONE, TICKS_UNLIMITED

Parameters

• sem -

  Pointer to a nano_sem structure.

• timeout_in_ticks -

  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

• 1 -

  When semaphore is available

• 0 -

  Otherwise

void nano_isr_sem_give(struct nano_sem *sem)

Give a nanokernel semaphore (no context switch).

This routine performs a “give” operation on a nanokernel semaphore object; it can only be called from an ISR context. A fiber pending on the semaphore object will be made ready, but will NOT be scheduled to execute.

Return

N/A

Parameters

• sem -

  Pointer to a nano_sem structure.

int nano_isr_sem_take(struct nano_sem *sem, int32_t timeout_in_ticks)

Take a nanokernel semaphore, fail if unavailable.

Attempts to take a nanokernel semaphore. It can only be called from a ISR context.

If the semaphore is not available, this function returns immediately, i.e. a wait (pend) operation will NOT be performed.

Parameters

• sem -

  Pointer to a nano_sem structure.

• timeout_in_ticks -

  Always use TICKS_NONE.

Return Value

• 1 -

  When semaphore is available

• 0 -

  Otherwise

void nano_fiber_sem_give(struct nano_sem *sem)

Give a nanokernel semaphore (no context switch).

This routine performs a “give” operation on a nanokernel semaphore object; it can only be called from a fiber. A fiber pending on the semaphore object will be made ready, but will NOT be scheduled to execute.

Return

N/A

Parameters

• sem -

  Pointer to a nano_sem structure.

int nano_fiber_sem_take(struct nano_sem *sem, int32_t timeout_in_ticks)

Take a nanokernel semaphore, wait or fail if unavailable.

Attempts to take a nanokernel semaphore. It can only be called from a fiber.

Parameters

• sem -

  Pointer to a nano_sem structure.

• timeout_in_ticks -

  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

• 1 -

  When semaphore is available.

• 0 -

  Otherwise.

void nano_task_sem_give(struct nano_sem *sem)

Give a nanokernel semaphore.

This routine performs a “give” operation on a nanokernel semaphore object; it can only be called from a task. A fiber pending on the semaphore object will be made ready, and will preempt the running task immediately.

Return

N/A

Parameters

• sem -

  Pointer to a nano_sem structure.

int nano_task_sem_take(struct nano_sem *sem, int32_t timeout_in_ticks)

Take a nanokernel semaphore, fail if unavailable.

Attempts to take a nanokernel semaphore; it can only be called from a task.

See

TICKS_NONE, TICKS_UNLIMITED

Parameters

• sem -

  Pointer to a nano_sem structure.

• timeout_in_ticks -

  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

• 1 -

  when the semaphore is available.

• 0 -

  Otherwise.

LIFOs

void nano_lifo_init(struct nano_lifo *lifo)

Initialize a nanokernel linked list LIFO (lifo) object.

This function initializes a nanokernel system-level linked list LIFO (lifo) object structure.

It is called from either a fiber or task.

Return

N/A

Parameters

• lifo -

  LIFO to initialize.

void nano_lifo_put(struct nano_lifo *lifo, void *data)

Prepend an element to a LIFO.

This routine is a convenience wrapper for the execution of context-specific APIs. It is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Return

N/A

Parameters

• lifo -

  LIFO on which to put.

• data -

  Data to insert.

void *nano_lifo_get(struct nano_lifo *lifo, int32_t timeout_in_ticks)

Get the first element from a LIFO.

This routine is a convenience wrapper for the execution of context-specific APIs. It is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Warning

If it is to be called from the context of an ISR, then timeout_in_ticks must be set to TICKS_NONE.

Return

Pointer to head element in the list when available. NULL Otherwise.

See

TICKS_NONE, TICKS_UNLIMITED

Parameters

• lifo -

  LIFO on which to receive.

• timeout_in_ticks -

  Affects the action taken should the LIFO be empty. If TICKS_NONE, then return immediately. If TICKS_UNLIMITED, then wait as long as necesssary. Otherwise wait up to the specified number of ticks before timing out.

void nano_isr_lifo_put(struct nano_lifo *lifo, void *data)

Prepend an element to a LIFO without a context switch.

This routine adds an element to the LIFOs’ object head; it may be called from an ISR context. A fiber pending on the LIFO object will be made ready, but will NOT be scheduled to execute.

Return

N/A

Parameters

• lifo -

  LIFO on which to put.

• data -

  Data to insert.

void *nano_isr_lifo_get(struct nano_lifo *lifo, int32_t timeout_in_ticks)

Remove the first element from a LIFO linked list.

Removes the first element from the specified nanokernel LIFO linked list; it can only be called from an ISR context.

If no elements are available, NULL is returned. The first word in the element contains invalid data because its memory location was used to store a pointer to the next element in the linked list.

Return

Pointer to head element in the list when available. NULL Otherwise.

Parameters

• lifo -

  LIFO from which to receive.

• timeout_in_ticks -

  Always use TICKS_NONE.

void nano_fiber_lifo_put(struct nano_lifo *lifo, void *data)

Prepend an element to a LIFO without a context switch.

This routine adds an element to the LIFOs’ object head; it can only be called from a fiber. A fiber pending on the LIFO object will be made ready, but will NOT be scheduled to execute.

Return

N/A

Parameters

• lifo -

  LIFO from which to put.

• data -

  Data to insert.

void *nano_fiber_lifo_get(struct nano_lifo *lifo, int32_t timeout_in_ticks)

Remove the first element from a LIFO linked list.

Removes the first element from the specified nanokernel LIFO linked list; it can only be called from a fiber.

If no elements are available, NULL is returned. The first word in the element contains invalid data because its memory location was used to store a pointer to the next element in the linked list.

Return

Pointer to head element in the list when available. NULL Otherwise.

See

TICKS_NONE, TICKS_UNLIMITED

Parameters

• lifo -

  LIFO from which to receive.

• timeout_in_ticks -

  Affects the action taken should the LIFO be empty. If TICKS_NONE, then return immediately. If TICKS_UNLIMITED, then wait as long as necessary. Otherwise wait up to the specified number of ticks before timing out.

void nano_task_lifo_put(struct nano_lifo *lifo, void *data)

Add an element to the LIFO’s linked list head.

This routine adds an element to the head of a LIFO object; it can only be called only from a task. A fiber pending on the LIFO object will be made ready and will preempt the running task immediately.

This API can only be called by a task.

Return

N/A

Parameters

• lifo -

  LIFO from which to put.

• data -

  Data to insert.

void *nano_task_lifo_get(struct nano_lifo *lifo, int32_t timeout_in_ticks)

Remove the first element from a LIFO linked list.

Removes the first element from the specified nanokernel LIFO linked list; it can only be called from a task.

If no elements are available, NULL is returned. The first word in the element contains invalid data because its memory location was used to store a pointer to the next element in the linked list.

Return

Pointer to head element in the list when available. NULL Otherwise.

See

TICKS_NONE, TICKS_UNLIMITED

Parameters

• lifo -

  LIFO from which to receive.

• timeout_in_ticks -

  Affects the action taken should the LIFO be empty. If TICKS_NONE, then return immediately. If TICKS_UNLIMITED, then wait as long as necessary. Otherwise wait up to the specified number of ticks before timing out.

FIFOs

void nano_fifo_init(struct nano_fifo *fifo)

Initialize a nanokernel FIFO (fifo) object.

This function initializes a nanokernel FIFO (fifo) object structure.

It can be called from either a fiber or task.

The wait queue and data queue occupy the same space since there cannot be both queued data and pending fibers in the FIFO. Ensure that, when one of the queues becomes empty, the FIFO is reset to a state that reflects an empty queue to both the data and wait queues.

If the ‘stat’ field is a positive value, it indicates how many data elements reside in the FIFO. If the ‘stat’ field is a negative value, its absolute value indicates how many fibers are pending on the FIFO object. Thus a value of ‘0’ indicates that there are no data elements in the FIFO and there are no pending fibers.

Return

N/A

Parameters

• fifo -

  FIFO to initialize.

void nano_fifo_put(struct nano_fifo *fifo, void *data)

Add an element to the end of a FIFO.

This routine is a convenience wrapper for the execution of context-specific APIs. It is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Return

N/A

Parameters

• fifo -

  FIFO on which to interact.

• data -

  Data to send.

void *nano_fifo_get(struct nano_fifo *fifo, int32_t timeout_in_ticks)

Get an element from the head a FIFO.

This routine is a convenience wrapper for the execution of context-specific APIs. It is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

If no element is available, the function returns NULL. The first word in the element contains invalid data because its memory location was used to store a pointer to the next element in the linked list.

Warning

If it is to be called from the context of an ISR, then timeout_in_ticks must be set to TICKS_NONE.

Return

Pointer to head element in the list when available. NULL Otherwise.

See

TICKS_NONE, TICKS_UNLIMITED

Parameters

• fifo -

  FIFO on which to interact.

• timeout_in_ticks -

  Affects the action taken should the FIFO be empty. If TICKS_NONE, then return immediately. If TICKS_UNLIMITED, then wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.

void nano_isr_fifo_put(struct nano_fifo *fifo, void *data)

Add an element to the end of a FIFO from an ISR context.

This is an alias for the execution context-specific API. This is helpful whenever the exact execution context is known. Its use avoids unnecessary overhead.

Return

N/A

Parameters

• fifo -

  FIFO on which to interact.

• data -

  Data to send.

void *nano_isr_fifo_get(struct nano_fifo *fifo, int32_t timeout_in_ticks)

Get an element from the head of a FIFO from an ISR context.

Remove the head element from the specified nanokernel FIFO linked list FIFO. It can only be called from an ISR context.

The first word in the element contains invalid data because its memory location was used to store a pointer to the next element in the linked list.

Return

Pointer to head element in the list when available. NULL Otherwise.

Parameters

• fifo -

  FIFO on which to interact.

• timeout_in_ticks -

  Always use TICKS_NONE.

void nano_fiber_fifo_put(struct nano_fifo *fifo, void *data)

Add an element to the end of a FIFO from a fiber.

This is an alias for the execution context-specific API. This is helpful whenever the exact execution context is known. Its use avoids unnecessary overhead.

Return

N/A

Parameters

• fifo -

  FIFO on which to interact.

• data -

  Data to send.

void *nano_fiber_fifo_get(struct nano_fifo *fifo, int32_t timeout_in_ticks)

Get an element from the head of a FIFO from a fiber.

Remove the head element from the specified nanokernel FIFO linked list. It can only be called from a fiber.

The first word in the element contains invalid data because its memory location was used to store a pointer to the next element in the linked list.

Return

Pointer to head element in the list when available. NULL Otherwise.

See

TICKS_NONE, TICKS_UNLIMITED

Parameters

• fifo -

  FIFO on which to interact.

• timeout_in_ticks -

  Affects the action taken should the FIFO be empty. If TICKS_NONE, then return immediately. If TICKS_UNLIMITED, then wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.

void nano_task_fifo_put(struct nano_fifo *fifo, void *data)

Add an element to the end of a FIFO.

This routine adds an element to the end of a FIFO object. It can only be called from a task. If a fiber is pending on the FIFO object, it becomes ready and will preempt the running task immediately.

If a fiber is waiting on the FIFO, the address of the element is returned to the waiting fiber. Otherwise, the element is linked to the end of the list.

Return

N/A

Parameters

• fifo -

  FIFO on which to interact.

• data -

  Data to send.

void *nano_task_fifo_get(struct nano_fifo *fifo, int32_t timeout_in_ticks)

Get an element from a FIFO’s head that comes from a task, poll if empty.

Removes the head element from the specified nanokernel FIFO linked list. It can only be called from a task.

The first word in the element contains invalid data because its memory location was used to store a pointer to the next element in the linked list.

Return

Pointer to head element in the list when available. NULL Otherwise.

See

TICKS_NONE, TICKS_UNLIMITED

Parameters

• fifo -

  FIFO on which to interact.

• timeout_in_ticks -

  Affects the action taken should the FIFO be empty. If TICKS_NONE, then return immediately. If TICKS_UNLIMITED, then poll as long as necessary. Otherwise poll up to the specified number of ticks have elapsed before timing out.

union

Public Members

Ring Buffers

static void sys_ring_buf_init(struct ring_buf *buf, uint32_t size, uint32_t *data)

Initialize a ring buffer, in cases where DECLARE_RING_BUF_STATIC isn’t used.

For optimal performance, use size values that are a power of 2 as they don’t require expensive modulo operations when maintaining the buffer.

Parameters

• buf -

  Ring buffer to initialize

• size -

  Size of the provided buffer in 32-bit chunks

• data -

  Data area for the ring buffer, typically uint32_t data[size]

static int sys_ring_buf_is_empty(struct ring_buf *buf)

Determine if a ring buffer is empty.

Return

nonzero if the buffer is empty

static int sys_ring_buf_space_get(struct ring_buf *buf)

Obtain available space in a ring buffer.

Return

Available space in the buffer in 32-bit chunks

Parameters

• buf -

  Ring buffer to examine

int sys_ring_buf_put(struct ring_buf *buf, uint16_t type, uint8_t value, uint32_t *data, uint8_t size32)

Place an entry into the ring buffer.

Concurrency control is not implemented, however no synchronization is needed between put() and get() operations as they independently work on the tail and head values, respectively. Any use-cases involving multiple producers will need to synchronize use of this function, by either disabling preemption or using a mutex.

Return

0 on success, -ENOSPC if there isn’t sufficient space

Parameters

• buf -

  Ring buffer to insert data to

• type -

  Application-specific type identifier

• value -

  Integral data to include, application specific

• data -

  Pointer to a buffer containing data to enqueue

• size32 -

  Size of data buffer, in 32-bit chunks (not bytes)

int sys_ring_buf_get(struct ring_buf *buf, uint16_t *type, uint8_t *value, uint32_t *data, uint8_t *size32)

Fetch data from the ring buffer.

Return

0 on success, -EAGAIN if the ring buffer is empty, -EMSGSIZE if the supplied buffer is too small (size32 will be updated with the actual size needed)

Parameters

• buf -

  Ring buffer to extract data from

• type -

  Return storage of the retrieved event type

• value -

  Return storage of the data value

• data -

  Buffer to copy data into

• size32 -

  Indicates the size of the data buffer. On return, updated with the actual amount of 32-bit chunks written to the buffer

SIZE32_OF(x)

SYS_RING_BUF_DECLARE_POW2(name, pow)

Declare a power-of-two sized ring buffer.

Use of this macro is preferred over SYS_RING_BUF_DECLARE_SIZE() as it will not need to use expensive modulo operations.

Parameters

• name -

  File-scoped name of the ring buffer to declare

• pow -

  Create a buffer of 2^pow 32-bit elements

SYS_RING_BUF_DECLARE_SIZE(name, size32)

Declare an arbitrary sized ring buffer.

A ring buffer declared in this way has more flexibility on buffer size but will use more expensive modulo operations to maintain itself.

Parameters

• name -

  File-scoped name of the ring buffer to declare

• size32 -

  Size of buffer in 32-bit elements

struct ring_buf

#include <ring_buffer.h>

A structure to represent a ring buffer.

Stacks

void nano_stack_init(struct nano_stack *stack, uint32_t *data)

Initialize a nanokernel stack object.

This function initializes a nanokernel stack object structure.

It is called from either a fiber or a task.

Return

N/A

void nano_stack_push(struct nano_stack *stack, uint32_t data)

Push data onto a stack.

This routine is a convenience wrapper for the execution of context-specific APIs. It is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Return

N/A

Parameters

• stack -

  Stack on which to interact.

• data -

  Data to push on stack.

int nano_stack_pop(struct nano_stack *stack, uint32_t *data, int32_t timeout_in_ticks)

Pop data from a nanokernel stack.

This routine is a convenience wrapper for the execution of context-specific APIs. It is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Warning

If called from the context of an ISR, then timeout_in_ticks must be TICKS_NONE.

See

TICKS_NONE, TICKS_UNLIMITED

Parameters

• stack -

  Stack on which to interact.

• data -

  Container for data to pop.

• timeout_in_ticks -

  Determines 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

• 1 -

  When data is popped from the stack.

• 0 -

  Otherwise.

void nano_isr_stack_push(struct nano_stack *stack, uint32_t data)

Push data onto a stack (no context switch).

This routine pushes a data item onto a stack object. It can only be called from an ISR context. A fiber that pends on the stack object becomes ready but will NOT be scheduled to execute.

Return

N/A

Parameters

• stack -

  Stack on which to interact.

• data -

  Data to push on stack.

int nano_isr_stack_pop(struct nano_stack *stack, uint32_t *data, int32_t timeout_in_ticks)

Pop data from a nanokernel stack.

Pops the first data word from a nanokernel stack object. It can only be called from an ISR context.

When the stack is not empty, a data word is popped and copied to the provided address data and a non-zero value is returned. When the routine finds an empty stack, zero is returned.

Parameters

• stack -

  Stack on which to interact.

• data -

  Container for data to pop.

• timeout_in_ticks -

  Must be TICKS_NONE.

Return Value

• 1 -

  When data is popped from the stack

• 0 -

  Otherwise.

void nano_fiber_stack_push(struct nano_stack *stack, uint32_t data)

Push data onto a stack (no context switch).

This routine pushes a data item onto a stack object. It can only be called from a fiber context. A fiber that pends on the stack object becomes ready but will NOT be scheduled to execute.

Return

N/A

Parameters

• stack -

  Stack on which to interact.

• data -

  Data to push on stack.

int nano_fiber_stack_pop(struct nano_stack *stack, uint32_t *data, int32_t timeout_in_ticks)

Pop data from a nanokernel stack.

Pops the first data word from a nanokernel stack object. It can only be called from a fiber context.

When the stack is not empty, a data word is popped and copied to the provided address data and a non-zero value is returned. When the routine finds an empty stack, zero is returned.

See

TICKS_NONE, TICKS_UNLIMITED

Parameters

• stack -

  Stack on which to interact.

• data -

  Container for data to pop.

• timeout_in_ticks -

  Determines 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

• 1 -

  When data is popped from the stack

• 0 -

  Otherwise.

void nano_task_stack_push(struct nano_stack *stack, uint32_t data)

Push data onto a nanokernel stack.

This routine pushes a data item onto a stack object. It can only be called from a task. A fiber that pends on the stack object becomes ready and preempts the running task immediately.

Return

N/A

Parameters

• stack -

  Stack on which to interact.

• data -

  Data to push on stack.

int nano_task_stack_pop(struct nano_stack *stack, uint32_t *data, int32_t timeout_in_ticks)

Pop data from a nanokernel stack.

Pops the first data word from a nanokernel stack object. It can only be called from a task context.

When the stack is not empty, a data word is popped and copied to the provided address data and a non-zero value is returned. When the routine finds an empty stack, zero is returned.

See

TICKS_NONE, TICKS_UNLIMITED

Parameters

• stack -

  Stack on which to interact.

• data -

  Container for data to pop.

• timeout_in_ticks -

  Determines 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

• 1 -

  When data is popped from the stack

• 0 -

  Otherwise.

Timers

void nano_timer_init(struct nano_timer *timer, void *data)

Initialize a nanokernel timer object.

This function initializes a nanokernel timer object structure.

It can be called from either a fiber or task.

The data passed to this function is a pointer to a data structure defined by the user. It contains data that the user wishes to store when initializing the timer and recover when the timer expires. However, the first field of this data structure must be a pointer reserved for the API’s use that can be overwritten by the API and, as such, should not contain user data.

Return

N/A

Parameters

• timer -

  Timer.

• data -

  User Data.

void nano_timer_start(struct nano_timer *timer, int ticks)

Start a nanokernel timer.

This routine is a convenience wrapper for the execution of context-specific APIs. It is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Return

N/A

Parameters

• timer -

  Timer.

• ticks -

  Number of ticks.

static void *nano_timer_test(struct nano_timer *timer, int32_t timeout_in_ticks)

Wait for a nanokernel timer to expire.

This routine is a convenience wrapper for the execution of context-specific APIs. It is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Return

N/A

Warning

If called from an ISR, then timeout_in_ticks must be TICKS_NONE.

See

TICKS_NONE, TICKS_UNLIMITED

Parameters

• timer -

  Timer.

• timeout_in_ticks -

  Determines the action to take when the timer has not expired. 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.

void nano_timer_stop(struct nano_timer *timer)

Stop a nanokernel timer.

This routine is a convenience wrapper for the execution of context-specific APIs. It is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Return

pointer to timer initialization data.

Parameters

• timer -

  Timer to stop.

void nano_isr_timer_start(struct nano_timer *timer, int ticks)

Start a nanokernel timer from an ISR.

This function starts a previously initialized nanokernel timer object. The timer will expire in ticks system clock ticks.

Return

N/A

Parameters

• timer -

  Timer.

• ticks -

  Number of ticks.

static void *nano_isr_timer_test(struct nano_timer *timer, int32_t timeout_in_ticks)

Make the current ISR check for a timer expiry.

This function checks if a previously started nanokernel timer object has expired.

Return

Pointer to timer initialization data.

Parameters

• timer -

  Timer to check.

• timeout_in_ticks -

  Always use TICKS_NONE.

Return Value

• NULL -

  If timer not expired.

void nano_isr_timer_stop(struct nano_timer *timer)

Stop a nanokernel timer from an ISR.

This function stops a previously started nanokernel timer object.

Return

N/A

Parameters

• timer -

  Timer to stop.

void nano_fiber_timer_start(struct nano_timer *timer, int ticks)

Start a nanokernel timer from a fiber.

This function starts a previously-initialized nanokernel timer object. The timer expires after ticks system clock ticks.

Return

N/A

Parameters

• timer -

  Timer.

• ticks -

  Number of ticks.

static void *nano_fiber_timer_test(struct nano_timer *timer, int32_t timeout_in_ticks)

Make the current fiber check for a timer expiry.

This function tests whether or not a previously started nanokernel timer object has expired, or waits until it does.

Return

Pointer to timer initialization data

See

TICKS_NONE, TICKS_UNLIMITED

Parameters

• timer -

  Timer to check.

• timeout_in_ticks -

  Determines the action to take when the timer has not expired. 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

• NULL -

  If timer has not expired.

void nano_fiber_timer_stop(struct nano_timer *timer)

Stop a nanokernel timer.

This function stops a previously started nanokernel timer object. It can only be called from a fiber.

Return

N/A

Parameters

• timer -

  Timer to stop.

void nano_task_timer_start(struct nano_timer *timer, int ticks)

Start a nanokernel timer from a task.

This function starts a previously initialized nanokernel timer object. The timer expires after ticks system clock ticks.

Return

N/A

Parameters

• timer -

  Timer.

• ticks -

  Number of ticks.

static void *nano_task_timer_test(struct nano_timer *timer, int32_t timeout_in_ticks)

Make the current task check for a timer expiry.

This function tests whether or not a previously started nanokernel timer object has expired, or waits until it does.

Return

Pointer to timer initialization data.

See

TICKS_NONE, TICKS_UNLIMITED

Parameters

• timer -

  Timer to check.

• timeout_in_ticks -

  Determines the action to take when the timer has not expired. 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

• NULL -

  If timer has not expired.

void nano_task_timer_stop(struct nano_timer *timer)

Stop a nanokernel timer from a task.

This function stops a previously-started nanokernel timer object.

Return

N/A

Parameters

• timer -

  Timer to stop.

int64_t sys_tick_get(void)

Return the current system tick count.

Return

The current system tick count.

uint32_t sys_tick_get_32(void)

Return the lower part of the current system tick count.

Return

The current system tick count.

uint32_t sys_cycle_get_32(void)

Return a time stamp in high-resolution format.

This routine reads the counter register on the processor’s high precision timer device. This counter register increments at a relatively high rate (e.g. 20 MHz), and is thus considered a high-resolution timer. This is in contrast to sys_tick_get_32() which returns the value of the system ticks variable.

Return

The current high-precision clock value.

int64_t sys_tick_delta(int64_t *reftime)

Return number of ticks elapsed since a reference time.

Return

The tick count since reference time; undefined for first invocation.

Parameters

• reftime -

  Reference time.

uint32_t sys_tick_delta_32(int64_t *reftime)

Return 32-bit number of ticks since a reference time.

Return

A 32-bit tick count since reference time. Undefined for first invocation.

Parameters

• reftime -

  Reference time.

DEBUG_TRACING_OBJ_INIT(type, obj, list)

Kernel Event Logger

struct event_logger sys_k_event_logger

Global variable of the ring buffer that allows user to implement their own reading routine.

void sys_k_event_logger_put_timed(uint16_t event_id)

Sends a event message to the kernel event logger with the current timestamp.

Sends a event message to the kernel event logger and informs that there messages available. The timestamp when the event occurred is stored as part of the event message.

Return

No return value.

Parameters

• event_id -

  The identification of the event.

static void sys_k_event_logger_register_as_collector(void)

static void _sys_k_event_logger_enter_sleep(void)

sys_k_event_logger_put(event_id, data, data_size)

Sends a event message to the kernel event logger.

Sends a event message to the kernel event logger and informs that there are messages available.

Return

No return value.

Parameters

• event_id -

  The identification of the event.

• data -

  Pointer to the data of the message.

• data_size -

  Size of the data in 32-bit words.

sys_k_event_logger_get(event_id, dropped, buffer, buffer_size)

Retrieves a kernel event message.

Retrieves a kernel event message copying it to the provided buffer. If the buffer is smaller than the message size the function returns an error. The function retrieves messages in FIFO order.

Return

-EMSGSIZE if the buffer size is smaller than the message size, the amount of 32-bit words copied or zero if there are no kernel event messages available.

Parameters

• event_id -

  Pointer to the id of the event fetched

• dropped -

  Pointer to how many events were dropped

• buffer -

  Pointer to the buffer where the message will be copied.

• buffer_size -

  Size of the buffer in 32-bit words.

sys_k_event_logger_get_wait(event_id, dropped, buffer, buffer_size)

Retrieves a kernel event message, wait if there is no message available.

Retrieves a kernel event message copying it to the provided buffer. If the buffer is smaller than the message size the function returns an error. The function retrieves messages in FIFO order. If there is no kernel event message available the caller pends until a new message is logged.

Return

-EMSGSIZE if the buffer size is smaller than the message size, or the amount of 32-bit words copied.

Parameters

• event_id -

  Pointer to the id of the event fetched

• dropped -

  Pointer to how many events were dropped

• buffer -

  Pointer to the buffer where the message will be copied.

• buffer_size -

  Size of the buffer in 32-bit words.

sys_k_event_logger_get_wait_timeout(event_id, dropped, buffer, buffer_size, timeout)

Retrieves a kernel event message, wait with a timeout if there is no profiling event messages available.

Retrieves a kernel event message copying it to the provided buffer. If the buffer is smaller than the message size the function returns an error. The function retrieves messages in FIFO order. If there are no kernel event messages available the caller pends until a new message is logged or the timeout expires.

Return

-EMSGSIZE if the buffer size is smaller than the message size, the amount of 32-bit words copied or zero if the timeout expires and the was no message available.

Parameters

• event_id -

  Pointer to the id of the event fetched

• dropped -

  Pointer to how many events were dropped

• buffer -

  Pointer to the buffer where the message will be copied.

• buffer_size -

  Size of the buffer in 32-bit words.

• timeout -

  Timeout in ticks.