blob: 68857ad1fb91bf4a50e2681e05d7f3e43b8f8963 [file] [log] [blame]
/*
* Copyright (c) 1997-2015, Wind River Systems, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* @file
*
* @brief Public APIs for the nanokernel.
*/
#ifndef __NANOKERNEL_H__
#define __NANOKERNEL_H__
/**
* @defgroup nanokernel_services Nanokernel Services
*/
/* fundamental include files */
#include <stddef.h>
#include <stdint.h>
#include <toolchain.h>
/* generic kernel public APIs */
#include <kernel_version.h>
#include <sys_clock.h>
#include <drivers/rand32.h>
#ifdef __cplusplus
extern "C" {
#endif
struct tcs;
/*
* @cond internal
* nanokernel private APIs that are exposed via the public API
*
* THESE ITEMS SHOULD NOT BE REFERENCED EXCEPT BY THE KERNEL ITSELF!
*/
struct _nano_queue {
void *head;
void *tail;
};
#include <misc/dlist.h>
struct _nano_timeout;
typedef void (*_nano_timeout_func_t)(struct _nano_timeout *t);
struct _nano_timeout {
sys_dlist_t node;
struct tcs *tcs;
struct _nano_queue *wait_q;
int32_t delta_ticks_from_prev;
_nano_timeout_func_t func;
};
/**
* @endcond
*/
/* architecture-independent nanokernel public APIs */
typedef struct tcs *nano_thread_id_t;
typedef void (*nano_fiber_entry_t)(int i1, int i2);
typedef int nano_context_type_t;
#define NANO_CTX_ISR (0)
#define NANO_CTX_FIBER (1)
#define NANO_CTX_TASK (2)
/* timeout special values */
#define TICKS_UNLIMITED (-1)
#define TICKS_NONE 0
/**
* @brief Execution contexts APIs
* @defgroup execution_contexts Execution Contexts
* @ingroup nanokernel_services
* @{
*/
/**
* @brief Return the ID of the currently executing thread.
*
* This routine returns a pointer to the thread control block of the currently
* executing thread. It is cast to a nano_thread_id_t for public use.
*
* @return The ID of the currently executing thread.
*/
extern nano_thread_id_t sys_thread_self_get(void);
/**
*
* @brief Return the type of the current execution context.
*
* This routine returns the type of execution context currently executing.
*
* @return The type of the current execution context.
* @retval NANO_CTX_ISR (0): executing an interrupt service routine.
* @retval NANO_CTX_FIBER (1): current thread is a fiber.
* @retval NANO_CTX_TASK (2): current thread is a task.
*
*/
extern nano_context_type_t sys_execution_context_type_get(void);
extern int _is_thread_essential(void);
/**
*
* @brief Cause the currently executing thread to busy wait.
*
* This routine causes the current task or fiber to execute a "do nothing"
* loop for a specified period of time.
*
* @warning This routine utilizes the system clock, so it must not be invoked
* until the system clock is fully operational or while interrupts
* are locked.
*
* @param usec_to_wait Number of microseconds to busy wait.
*
* @return N/A
*/
extern void sys_thread_busy_wait(uint32_t usec_to_wait);
/**
* @}
*/
/**
* @brief Nanokernel Fibers
* @defgroup nanokernel_fiber Nanokernel Fibers
* @ingroup nanokernel_services
* @{
*/
/* Execution context-independent methods. (When context is not known.) */
/**
* @brief 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.
*
* @internal
* Given that this routine is _not_ ISR-callable, the following code is used
* to differentiate between a task and fiber:
*
* if ((_nanokernel.current->flags & TASK) == TASK)
*
* Given that the _fiber_start() primitive is not considered real-time
* performance critical, a runtime check to differentiate between a calling
* task or fiber is performed to conserve footprint.
* @endinternal
*
* @param stack Pointer to the stack space.
* @param stack_size Stack size in bytes.
* @param entry Fiber entry.
* @param arg1 1st entry point parameter.
* @param arg2 2nd entry point parameter.
* @param prio The fiber's priority.
* @param options Not used currently.
* @return nanokernel thread identifier
*/
extern nano_thread_id_t fiber_start(char *stack, unsigned stack_size,
nano_fiber_entry_t entry,
int arg1, int arg2, unsigned prio, unsigned options);
/* Methods for fibers */
/**
* @brief Initialize and start a fiber from a fiber.
*
* This routine initializes and starts a fiber. It can only be
* called from a fiber.
*
* @param pStack Pointer to the stack space.
* @param stackSize Stack size in bytes.
* @param entry Fiber entry.
* @param arg1 1st entry point parameter.
* @param arg2 2nd entry point parameter.
* @param prio The fiber's priority.
* @param options Not used currently.
* @return nanokernel thread identifier
*/
extern nano_thread_id_t fiber_fiber_start(char *pStack, unsigned int stackSize,
nano_fiber_entry_t entry, int arg1, int arg2, unsigned prio,
unsigned options);
/**
* @brief 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
*/
extern void fiber_yield(void);
/**
* @brief 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
*/
extern void fiber_abort(void);
/**
* @brief Fiber configuration structure.
*
* Parameters such as stack size and fiber priority are often
* user configurable. This structure makes it simple to specify such a
* configuration.
*/
struct fiber_config {
char *stack;
unsigned stack_size;
unsigned prio;
};
/**
* @brief Start a fiber based on a @ref fiber_config, from fiber context.
*/
static inline nano_thread_id_t
fiber_fiber_start_config(const struct fiber_config *config,
nano_fiber_entry_t entry,
int arg1, int arg2, unsigned options)
{
return fiber_fiber_start(config->stack, config->stack_size,
entry, arg1, arg2, config->prio, options);
}
/**
* @brief Start a fiber based on a @ref fiber_config.
*
* This routine can be called from either a fiber or a task.
*/
static inline nano_thread_id_t
fiber_start_config(const struct fiber_config *config,
nano_fiber_entry_t entry,
int arg1, int arg2, unsigned options)
{
return fiber_start(config->stack, config->stack_size, entry,
arg1, arg2, config->prio, options);
}
#ifdef CONFIG_NANO_TIMEOUTS
/**
* @brief Put the current fiber to sleep.
*
* This routine puts the currently running fiber to sleep
* for the number of system ticks passed in the
* @a timeout_in_ticks parameter.
*
* @param timeout_in_ticks Number of system ticks the fiber sleeps.
*
* @return N/A
*/
extern void fiber_sleep(int32_t timeout_in_ticks);
/**
* @brief Wake the specified fiber from sleep
*
* This routine wakes the fiber specified by @a fiber from its sleep.
* It may only be called from an ISR.
*
* @param fiber Identifies fiber to wake
*
* @return N/A
*/
extern void isr_fiber_wakeup(nano_thread_id_t fiber);
/**
* @brief Wake the specified fiber from sleep
*
* This routine wakes the fiber specified by @a fiber from its sleep.
* It may only be called from a fiber.
*
* @param fiber Identifies fiber to wake
*
* @return N/A
*/
extern void fiber_fiber_wakeup(nano_thread_id_t fiber);
/**
* @brief Wake the specified fiber from sleep
*
* This routine wakes the fiber specified by @a fiber from its sleep.
* It may only be called from a task.
*
* @param fiber Identifies fiber to wake
*
* @return N/A
*/
extern void task_fiber_wakeup(nano_thread_id_t fiber);
/**
* @brief Wake the specified fiber from sleep
*
* 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.
*
* @param fiber Identifies fiber to wake
*
* @return N/A
*/
extern void fiber_wakeup(nano_thread_id_t fiber);
#ifndef CONFIG_MICROKERNEL
/**
* @brief Put the task to sleep.
*
* This routine puts the currently running task to sleep for the number
* of system ticks passed in the @a timeout_in_ticks parameter.
*
* @param timeout_in_ticks Number of system ticks the task sleeps.
*
* @warning A value of TICKS_UNLIMITED is considered invalid and may result in
* unexpected behavior.
*
* @return N/A
* @sa TICKS_UNLIMITED
*/
extern void task_sleep(int32_t timeout_in_ticks);
#endif
/**
* @brief Start a fiber while delaying its execution.
*
* This routine can only be called from a fiber.
*
* @param stack Pointer to the stack space.
* @param stack_size_in_bytes Stack size in bytes.
* @param entry_point The fiber's entry point.
* @param param1 1st entry point parameter.
* @param param2 2nd entry point parameter.
* @param priority The fiber's priority.
* @param options Not used currently.
* @param timeout_in_ticks Timeout duration in ticks.
*
* @return A handle potentially used to cancel the delayed start.
*/
extern nano_thread_id_t 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);
extern nano_thread_id_t 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);
extern void fiber_delayed_start_cancel(nano_thread_id_t handle);
/**
* @brief Cancel a delayed fiber start.
*
* @param handle The handle returned when starting the delayed fiber.
*
* @return N/A
* @sa fiber_fiber_delayed_start
*/
extern void fiber_fiber_delayed_start_cancel(nano_thread_id_t handle);
#endif
/**
* @}
*/
/**
* @brief Nanokernel Task
* @defgroup nanokernel_task Nanokernel Task
* @ingroup nanokernel_services
* @{
*/
/* methods for tasks */
/**
* @brief Initialize and start a fiber from a task.
*
* @sa fiber_fiber_start
*/
extern nano_thread_id_t task_fiber_start(char *pStack, unsigned int stackSize,
nano_fiber_entry_t entry, int arg1, int arg2, unsigned prio,
unsigned options);
/**
* @brief Start a fiber based on a @ref fiber_config, from task context.
*/
static inline nano_thread_id_t
task_fiber_start_config(const struct fiber_config *config,
nano_fiber_entry_t entry,
int arg1, int arg2, unsigned options)
{
return task_fiber_start(config->stack, config->stack_size,
entry, arg1, arg2, config->prio, options);
}
#ifdef CONFIG_NANO_TIMEOUTS
/**
* @brief Start a fiber from a task while delaying its execution.
*
* @sa fiber_fiber_delayed_start
*/
extern nano_thread_id_t 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);
/**
* @brief Cancel a delayed fiber start from a task.
*
* @sa fiber_fiber_delayed_start_cancel
*/
extern void task_fiber_delayed_start_cancel(nano_thread_id_t handle);
#endif
/**
* @}
*/
/**
* @brief Nanokernel FIFOs
* @defgroup nanokernel_fifo Nanokernel FIFO
* @ingroup nanokernel_services
* @{
*/
struct nano_fifo {
struct _nano_queue wait_q; /* waiting fibers */
struct _nano_queue data_q;
#ifdef CONFIG_MICROKERNEL
struct _nano_queue task_q; /* waiting tasks */
#endif
#ifdef CONFIG_DEBUG_TRACING_KERNEL_OBJECTS
struct nano_fifo *__next;
#endif
};
/**
*
* @brief 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.
*
* @param fifo FIFO to initialize.
*
* @return N/A
*/
extern void nano_fifo_init(struct nano_fifo *fifo);
/* execution context-independent methods (when context is not known) */
/**
*
* @brief 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.
*
* @param fifo FIFO on which to interact.
* @param data Data to send.
*
* @return N/A
*/
extern void nano_fifo_put(struct nano_fifo *fifo, void *data);
/**
*
* @brief 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.
*
* @param fifo FIFO on which to interact.
* @param 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.
*
* @warning If it is to be called from the context of an ISR, then @a
* timeout_in_ticks must be set to TICKS_NONE.
*
* @return Pointer to head element in the list when available.
* NULL Otherwise.
*
* @sa TICKS_NONE, TICKS_UNLIMITED
*/
extern void *nano_fifo_get(struct nano_fifo *fifo, int32_t timeout_in_ticks);
/*
* methods for ISRs
*/
/**
*
* @brief 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.
*
* @param fifo FIFO on which to interact.
* @param data Data to send.
*
* @return N/A
*/
extern void nano_isr_fifo_put(struct nano_fifo *fifo, void *data);
/**
* @brief 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.
*
* @param fifo FIFO on which to interact.
* @param timeout_in_ticks Always use TICKS_NONE.
*
* @return Pointer to head element in the list when available.
* NULL Otherwise.
*/
extern void *nano_isr_fifo_get(struct nano_fifo *fifo, int32_t timeout_in_ticks);
/* methods for fibers */
/**
*
* @brief 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.
*
* @param fifo FIFO on which to interact.
* @param data Data to send.
*
* @return N/A
*/
extern void nano_fiber_fifo_put(struct nano_fifo *fifo, void *data);
/**
* @brief 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.
*
* @param fifo FIFO on which to interact.
* @param 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.
*
* @return Pointer to head element in the list when available.
* NULL Otherwise.
*
* @sa TICKS_NONE, TICKS_UNLIMITED
*/
extern void *nano_fiber_fifo_get(struct nano_fifo *fifo,
int32_t timeout_in_ticks);
/* Methods for tasks */
/**
*
* @brief 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.
*
* @param fifo FIFO on which to interact.
* @param data Data to send.
*
* @return N/A
*/
extern void nano_task_fifo_put(struct nano_fifo *fifo, void *data);
/**
* @brief 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.
*
* @param fifo FIFO on which to interact.
* @param 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.
*
* @return Pointer to head element in the list when available.
* NULL Otherwise.
*
* @sa TICKS_NONE, TICKS_UNLIMITED
*/
extern void *nano_task_fifo_get(struct nano_fifo *fifo,
int32_t timeout_in_ticks);
/* LIFO APIs */
/**
* @}
* @brief Nanokernel LIFOs
* @defgroup nanokernel_lifo Nanokernel LIFOs
* @ingroup nanokernel_services
* @{
*/
struct nano_lifo {
struct _nano_queue wait_q;
void *list;
#ifdef CONFIG_MICROKERNEL
struct _nano_queue task_q; /* waiting tasks */
#endif
#ifdef CONFIG_DEBUG_TRACING_KERNEL_OBJECTS
struct nano_lifo *__next;
#endif
};
/**
* @brief 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.
*
* @param lifo LIFO to initialize.
*
* @return N/A
*/
extern void nano_lifo_init(struct nano_lifo *lifo);
/**
* @brief 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.
*
* @param lifo LIFO on which to put.
* @param data Data to insert.
*
* @return N/A
*/
extern void nano_lifo_put(struct nano_lifo *lifo, void *data);
/**
* @brief 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.
*
* @param lifo LIFO on which to receive.
* @param 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.
*
* @warning If it is to be called from the context of an ISR, then @a
* timeout_in_ticks must be set to TICKS_NONE.
*
* @return Pointer to head element in the list when available.
* NULL Otherwise.
*
* @sa TICKS_NONE, TICKS_UNLIMITED
*/
extern void *nano_lifo_get(struct nano_lifo *lifo, int32_t timeout_in_ticks);
/* methods for ISRs */
/**
* @brief 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.
*
* @param lifo LIFO on which to put.
* @param data Data to insert.
*
* @return N/A
*/
extern void nano_isr_lifo_put(struct nano_lifo *lifo, void *data);
/**
* @brief 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.
*
* @param lifo LIFO from which to receive.
* @param timeout_in_ticks Always use TICKS_NONE.
*
* @return Pointer to head element in the list when available.
* NULL Otherwise.
*
*/
extern void *nano_isr_lifo_get(struct nano_lifo *lifo,
int32_t timeout_in_ticks);
/* methods for fibers */
/**
* @brief 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.
*
* @param lifo LIFO from which to put.
* @param data Data to insert.
*
* @return N/A
*/
extern void nano_fiber_lifo_put(struct nano_lifo *lifo, void *data);
/**
* @brief 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.
*
* @param lifo LIFO from which to receive.
* @param 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.
*
* @return Pointer to head element in the list when available.
* NULL Otherwise.
*
* @sa TICKS_NONE, TICKS_UNLIMITED
*/
extern void *nano_fiber_lifo_get(struct nano_lifo *lifo,
int32_t timeout_in_ticks);
/* Methods for tasks */
/**
* @brief 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.
*
* @param lifo LIFO from which to put.
* @param data Data to insert.
*
* @return N/A
*/
extern void nano_task_lifo_put(struct nano_lifo *lifo, void *data);
/**
* @brief 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.
*
* @param lifo LIFO from which to receive.
* @param 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.
*
* @return Pointer to head element in the list when available.
* NULL Otherwise.
*
* @sa TICKS_NONE, TICKS_UNLIMITED
*/
extern void *nano_task_lifo_get(struct nano_lifo *lifo,
int32_t timeout_in_ticks);
/**
* @}
* @brief Nanokernel Semaphores
* @defgroup nanokernel_semaphore Nanokernel Semaphores
* @ingroup nanokernel_services
* @{
*/
struct nano_sem {
struct _nano_queue wait_q;
int nsig;
#ifdef CONFIG_MICROKERNEL
struct _nano_queue task_q; /* waiting tasks */
#endif
#ifdef CONFIG_DEBUG_TRACING_KERNEL_OBJECTS
struct nano_sem *__next;
#endif
};
/**
*
* @brief 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.
*
* @param sem Pointer to a nano_sem structure.
*
* @return N/A
*/
extern void nano_sem_init(struct nano_sem *sem);
/* execution context-independent methods (when context is not known) */
/**
*
* @brief 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.
*
* @param sem Pointer to a nano_sem structure.
*
* @return N/A
*/
extern void nano_sem_give(struct nano_sem *sem);
/**
*
* @brief 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.
*
* @param sem Pointer to a nano_sem structure.
* @param 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.
*
* @warning If it is to be called from the context of an ISR, then @a
* timeout_in_ticks must be set to TICKS_NONE.
*
* @retval 1 When semaphore is available
* @retval 0 Otherwise
* @sa TICKS_NONE, TICKS_UNLIMITED
*/
extern int nano_sem_take(struct nano_sem *sem, int32_t timeout_in_ticks);
/* methods for ISRs */
/**
*
* @brief 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.
*
* @param sem Pointer to a nano_sem structure.
*
* @return N/A
*/
extern void nano_isr_sem_give(struct nano_sem *sem);
/**
*
* @brief 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.
*
* @param sem Pointer to a nano_sem structure.
* @param timeout_in_ticks Always use TICKS_NONE.
*
* @retval 1 When semaphore is available
* @retval 0 Otherwise
*/
extern int nano_isr_sem_take(struct nano_sem *sem, int32_t timeout_in_ticks);
/* methods for fibers */
/**
*
* @brief 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.
*
* @param sem Pointer to a nano_sem structure.
*
* @return N/A
*/
extern void nano_fiber_sem_give(struct nano_sem *sem);
/**
*
* @brief Take a nanokernel semaphore, wait or fail if unavailable.
*
* Attempts to take a nanokernel semaphore. It can only be called from a fiber.
*
* @param sem Pointer to a nano_sem structure.
* @param 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.
*
* @retval 1 When semaphore is available.
* @retval 0 Otherwise.
*/
extern int nano_fiber_sem_take(struct nano_sem *sem, int32_t timeout_in_ticks);
/* methods for tasks */
/**
*
* @brief 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.
*
* @param sem Pointer to a nano_sem structure.
*
* @return N/A
*/
extern void nano_task_sem_give(struct nano_sem *sem);
/**
*
* @brief Take a nanokernel semaphore, fail if unavailable.
*
* Attempts to take a nanokernel semaphore; it can only be called from a task.
*
* @param sem Pointer to a nano_sem structure.
* @param 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.
*
* @retval 1 when the semaphore is available.
* @retval 0 Otherwise.
* @sa TICKS_NONE, TICKS_UNLIMITED
*/
extern int nano_task_sem_take(struct nano_sem *sem, int32_t timeout_in_ticks);
/**
* @}
* @brief Nanokernel Stacks
* @defgroup nanokernel_stack Nanokernel Stacks
* @ingroup nanokernel_services
* @{
*/
struct nano_stack {
nano_thread_id_t fiber;
uint32_t *base;
uint32_t *next;
#ifdef CONFIG_DEBUG_TRACING_KERNEL_OBJECTS
struct nano_stack *__next;
#endif
};
/**
*
* @brief 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
*
*/
extern void nano_stack_init(struct nano_stack *stack, uint32_t *data);
/**
*
* @brief 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.
*
* @param stack Stack on which to interact.
* @param data Data to push on stack.
*
* @return N/A
*
*/
extern void nano_stack_push(struct nano_stack *stack, uint32_t data);
/**
*
* @brief 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.
*
* @param stack Stack on which to interact.
* @param data Container for data to pop.
* @param 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.
*
* @retval 1 When data is popped from the stack.
* @retval 0 Otherwise.
*
* @warning If called from the context of an ISR, then @a timeout_in_ticks
* must be TICKS_NONE.
* @sa TICKS_NONE, TICKS_UNLIMITED
*/
extern int nano_stack_pop(struct nano_stack *stack, uint32_t *data,
int32_t timeout_in_ticks);
/* methods for ISRs */
/**
*
* @brief 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.
*
* @param stack Stack on which to interact.
* @param data Data to push on stack.
*
* @return N/A
*
*/
extern void nano_isr_stack_push(struct nano_stack *stack, uint32_t data);
/**
*
* @brief 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 @a data and a non-zero value is returned. When the routine
* finds an empty stack, zero is returned.
*
* @param stack Stack on which to interact.
* @param data Container for data to pop.
* @param timeout_in_ticks Must be TICKS_NONE.
*
* @retval 1 When data is popped from the stack
* @retval 0 Otherwise.
*/
extern int nano_isr_stack_pop(struct nano_stack *stack, uint32_t *data,
int32_t timeout_in_ticks);
/* methods for fibers */
/**
*
* @brief 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.
*
* @param stack Stack on which to interact.
* @param data Data to push on stack.
*
* @return N/A
*
*/
extern void nano_fiber_stack_push(struct nano_stack *stack, uint32_t data);
/**
*
* @brief 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 @a data and a non-zero value is returned. When the routine
* finds an empty stack, zero is returned.
*
* @param stack Stack on which to interact.
* @param data Container for data to pop.
* @param 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.
*
* @retval 1 When data is popped from the stack
* @retval 0 Otherwise.
* @sa TICKS_NONE, TICKS_UNLIMITED
*/
extern int nano_fiber_stack_pop(struct nano_stack *stack, uint32_t *data, int32_t timeout_in_ticks);
/* Methods for tasks */
/**
*
* @brief 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.
*
* @param stack Stack on which to interact.
* @param data Data to push on stack.
*
* @return N/A
*/
extern void nano_task_stack_push(struct nano_stack *stack, uint32_t data);
/**
*
* @brief 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 @a data and a non-zero value is returned. When the routine
* finds an empty stack, zero is returned.
*
* @param stack Stack on which to interact.
* @param data Container for data to pop.
* @param 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.
*
* @retval 1 When data is popped from the stack
* @retval 0 Otherwise.
* @sa TICKS_NONE, TICKS_UNLIMITED
*/
extern int nano_task_stack_pop(struct nano_stack *stack, uint32_t *data, int32_t timeout_in_ticks);
/* thread custom data APIs */
#ifdef CONFIG_THREAD_CUSTOM_DATA
extern void sys_thread_custom_data_set(void *value);
extern void *sys_thread_custom_data_get(void);
#endif /* CONFIG_THREAD_CUSTOM_DATA */
/**
* @}
* @brief Nanokernel Timers
* @defgroup nanokernel_timer Nanokernel Timers
* @ingroup nanokernel_services
* @{
*/
struct nano_timer {
struct _nano_timeout timeout_data;
void *user_data;
/*
* User data pointer in backup for cases when nanokernel_timer_test()
* has to return NULL
*/
void *user_data_backup;
#ifdef CONFIG_DEBUG_TRACING_KERNEL_OBJECTS
struct nano_timer *__next;
#endif
};
/**
* @brief Initialize a nanokernel timer object.
*
* This function initializes a nanokernel timer object structure.
*
* It can be called from either a fiber or task.
*
* The @a 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.
*
*
* @param timer Timer.
* @param data User Data.
* @return N/A
*/
extern void nano_timer_init(struct nano_timer *timer, void *data);
/**
*
* @brief 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.
*
* @param timer Timer.
* @param ticks Number of ticks.
*
* @return N/A
*
*/
extern void nano_timer_start(struct nano_timer *timer, int ticks);
/**
* @brief 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.
*
* @param timer Timer.
* @param 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.
*
* @return N/A
*
* @warning If called from an ISR, then @a timeout_in_ticks must be TICKS_NONE.
* @sa TICKS_NONE, TICKS_UNLIMITED
*/
extern void *nano_timer_test(struct nano_timer *timer, int32_t timeout_in_ticks);
/**
* @brief 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.
*
* @param timer Timer to stop.
*
* @return pointer to timer initialization data.
*/
extern void nano_timer_stop(struct nano_timer *timer);
/* methods for ISRs */
/**
*
* @brief Start a nanokernel timer from an ISR.
*
* This function starts a previously initialized nanokernel timer object.
* The timer will expire in @a ticks system clock ticks.
*
* @param timer Timer.
* @param ticks Number of ticks.
*
* @return N/A
*/
extern void nano_isr_timer_start(struct nano_timer *timer, int ticks);
/**
* @brief Make the current ISR check for a timer expiry.
*
* This function checks if a previously started nanokernel timer object has
* expired.
*
* @param timer Timer to check.
* @param timeout_in_ticks Always use TICKS_NONE.
*
* @return Pointer to timer initialization data.
* @retval NULL If timer not expired.
*/
extern void *nano_isr_timer_test(struct nano_timer *timer, int32_t timeout_in_ticks);
/**
* @brief Stop a nanokernel timer from an ISR.
*
* This function stops a previously started nanokernel timer object.
*
* @param timer Timer to stop.
*
* @return N/A
*/
extern void nano_isr_timer_stop(struct nano_timer *timer);
/* methods for fibers */
/**
*
* @brief Start a nanokernel timer from a fiber.
*
* This function starts a previously-initialized nanokernel timer object.
* The timer expires after @a ticks system clock ticks.
*
* @param timer Timer.
* @param ticks Number of ticks.
*
* @return N/A
*/
extern void nano_fiber_timer_start(struct nano_timer *timer, int ticks);
/**
* @brief 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.
*
* @param timer Timer to check.
* @param 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.
*
* @return Pointer to timer initialization data
* @retval NULL If timer has not expired.
*
* @sa TICKS_NONE, TICKS_UNLIMITED
*/
extern void *nano_fiber_timer_test(struct nano_timer *timer, int32_t timeout_in_ticks);
/**
* @brief Stop a nanokernel timer.
*
* This function stops a previously started nanokernel timer object.
* It can only be called from a fiber.
*
* @param timer Timer to stop.
*
* @return N/A
*/
extern void nano_fiber_timer_stop(struct nano_timer *timer);
/* methods for tasks */
/**
* @brief Start a nanokernel timer from a task.
*
* This function starts a previously initialized nanokernel timer object.
* The timer expires after @a ticks system clock ticks.
*
* @param timer Timer.
* @param ticks Number of ticks.
*
* @return N/A
*/
extern void nano_task_timer_start(struct nano_timer *timer, int ticks);
/**
* @brief 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.
*
* @param timer Timer to check.
* @param 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.
*
* @return Pointer to timer initialization data.
* @retval NULL If timer has not expired.
*
* @sa TICKS_NONE, TICKS_UNLIMITED
*/
extern void *nano_task_timer_test(struct nano_timer *timer, int32_t timeout_in_ticks);
/**
* @brief Stop a nanokernel timer from a task.
*
* This function stops a previously-started nanokernel timer object.
*
* @param timer Timer to stop.
*
* @return N/A
*/
extern void nano_task_timer_stop(struct nano_timer *timer);
/**
* @brief Get nanokernel timer remaining ticks.
*
* This function returns the remaining ticks of the previously
* started nanokernel timer object.
*
* @return remaining ticks or 0 if the timer has expired
*/
extern int32_t nano_timer_ticks_remain(struct nano_timer *timer);
/* Methods for tasks and fibers for handling time and ticks */
/**
*
* @brief Return the current system tick count.
*
* @return The current system tick count.
*
*/
extern int64_t sys_tick_get(void);
/**
*
* @brief Return the lower part of the current system tick count.
*
* @return The current system tick count.
*
*/
extern uint32_t sys_tick_get_32(void);
/**
* @brief 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.
*/
extern uint32_t sys_cycle_get_32(void);
/**
*
* @brief Return number of ticks elapsed since a reference time.
*
* @param reftime Reference time.
*
* @return The tick count since reference time; undefined for first invocation.
*/
extern int64_t sys_tick_delta(int64_t *reftime);
/**
*
* @brief Return 32-bit number of ticks since a reference time.
*
* @param reftime Reference time.
*
* @return A 32-bit tick count since reference time. Undefined for first invocation.
*/
extern uint32_t sys_tick_delta_32(int64_t *reftime);
/**
* @}
* @} nanokernel services
*/
#ifdef __cplusplus
}
#endif
#if defined(CONFIG_CPLUSPLUS) && defined(__cplusplus)
/*
* Define new and delete operators.
* At this moment, the operators do nothing since objects are supposed
* to be statically allocated.
*/
inline void operator delete(void *ptr)
{
(void)ptr;
}
inline void operator delete[](void *ptr)
{
(void)ptr;
}
inline void *operator new(size_t size)
{
(void)size;
return NULL;
}
inline void *operator new[](size_t size)
{
(void)size;
return NULL;
}
#endif
/* architecture-specific nanokernel public APIs */
#include <arch/cpu.h>
#endif /* __NANOKERNEL_H__ */