| /* |
| * Copyright (c) 2016, Wind River Systems, Inc. |
| * |
| * SPDX-License-Identifier: Apache-2.0 |
| */ |
| |
| /** |
| * @file |
| * |
| * @brief Public kernel APIs. |
| */ |
| |
| #ifndef _kernel__h_ |
| #define _kernel__h_ |
| |
| #if !defined(_ASMLANGUAGE) |
| #include <stddef.h> |
| #include <zephyr/types.h> |
| #include <limits.h> |
| #include <toolchain.h> |
| #include <linker/sections.h> |
| #include <atomic.h> |
| #include <errno.h> |
| #include <misc/__assert.h> |
| #include <misc/dlist.h> |
| #include <misc/slist.h> |
| #include <misc/util.h> |
| #include <kernel_version.h> |
| #include <random/rand32.h> |
| #include <kernel_arch_thread.h> |
| #include <syscall.h> |
| #include <misc/printk.h> |
| #include <arch/cpu.h> |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| /** |
| * @brief Kernel APIs |
| * @defgroup kernel_apis Kernel APIs |
| * @{ |
| * @} |
| */ |
| |
| #ifdef CONFIG_KERNEL_DEBUG |
| #define K_DEBUG(fmt, ...) printk("[%s] " fmt, __func__, ##__VA_ARGS__) |
| #else |
| #define K_DEBUG(fmt, ...) |
| #endif |
| |
| #if defined(CONFIG_COOP_ENABLED) && defined(CONFIG_PREEMPT_ENABLED) |
| #define _NUM_COOP_PRIO (CONFIG_NUM_COOP_PRIORITIES) |
| #define _NUM_PREEMPT_PRIO (CONFIG_NUM_PREEMPT_PRIORITIES + 1) |
| #elif defined(CONFIG_COOP_ENABLED) |
| #define _NUM_COOP_PRIO (CONFIG_NUM_COOP_PRIORITIES + 1) |
| #define _NUM_PREEMPT_PRIO (0) |
| #elif defined(CONFIG_PREEMPT_ENABLED) |
| #define _NUM_COOP_PRIO (0) |
| #define _NUM_PREEMPT_PRIO (CONFIG_NUM_PREEMPT_PRIORITIES + 1) |
| #else |
| #error "invalid configuration" |
| #endif |
| |
| #define K_PRIO_COOP(x) (-(_NUM_COOP_PRIO - (x))) |
| #define K_PRIO_PREEMPT(x) (x) |
| |
| #define K_ANY NULL |
| #define K_END NULL |
| |
| #if defined(CONFIG_COOP_ENABLED) && defined(CONFIG_PREEMPT_ENABLED) |
| #define K_HIGHEST_THREAD_PRIO (-CONFIG_NUM_COOP_PRIORITIES) |
| #elif defined(CONFIG_COOP_ENABLED) |
| #define K_HIGHEST_THREAD_PRIO (-CONFIG_NUM_COOP_PRIORITIES - 1) |
| #elif defined(CONFIG_PREEMPT_ENABLED) |
| #define K_HIGHEST_THREAD_PRIO 0 |
| #else |
| #error "invalid configuration" |
| #endif |
| |
| #ifdef CONFIG_PREEMPT_ENABLED |
| #define K_LOWEST_THREAD_PRIO CONFIG_NUM_PREEMPT_PRIORITIES |
| #else |
| #define K_LOWEST_THREAD_PRIO -1 |
| #endif |
| |
| #define K_IDLE_PRIO K_LOWEST_THREAD_PRIO |
| |
| #define K_HIGHEST_APPLICATION_THREAD_PRIO (K_HIGHEST_THREAD_PRIO) |
| #define K_LOWEST_APPLICATION_THREAD_PRIO (K_LOWEST_THREAD_PRIO - 1) |
| |
| typedef sys_dlist_t _wait_q_t; |
| |
| #ifdef CONFIG_OBJECT_TRACING |
| #define _OBJECT_TRACING_NEXT_PTR(type) struct type *__next |
| #define _OBJECT_TRACING_INIT .__next = NULL, |
| #else |
| #define _OBJECT_TRACING_INIT |
| #define _OBJECT_TRACING_NEXT_PTR(type) |
| #endif |
| |
| #ifdef CONFIG_POLL |
| #define _POLL_EVENT_OBJ_INIT(obj) \ |
| .poll_events = SYS_DLIST_STATIC_INIT(&obj.poll_events), |
| #define _POLL_EVENT sys_dlist_t poll_events |
| #else |
| #define _POLL_EVENT_OBJ_INIT(obj) |
| #define _POLL_EVENT |
| #endif |
| |
| struct k_thread; |
| struct k_mutex; |
| struct k_sem; |
| struct k_alert; |
| struct k_msgq; |
| struct k_mbox; |
| struct k_pipe; |
| struct k_queue; |
| struct k_fifo; |
| struct k_lifo; |
| struct k_stack; |
| struct k_mem_slab; |
| struct k_mem_pool; |
| struct k_timer; |
| struct k_poll_event; |
| struct k_poll_signal; |
| struct k_mem_domain; |
| struct k_mem_partition; |
| |
| /* This enumeration needs to be kept in sync with the lists of kernel objects |
| * and subsystems in scripts/gen_kobject_list.py, as well as the otype_to_str() |
| * function in kernel/userspace.c |
| */ |
| enum k_objects { |
| K_OBJ_ANY, |
| |
| /* Core kernel objects */ |
| K_OBJ_ALERT, |
| K_OBJ_MSGQ, |
| K_OBJ_MUTEX, |
| K_OBJ_PIPE, |
| K_OBJ_SEM, |
| K_OBJ_STACK, |
| K_OBJ_THREAD, |
| K_OBJ_TIMER, |
| K_OBJ__THREAD_STACK_ELEMENT, |
| |
| /* Driver subsystems */ |
| K_OBJ_DRIVER_ADC, |
| K_OBJ_DRIVER_AIO_CMP, |
| K_OBJ_DRIVER_COUNTER, |
| K_OBJ_DRIVER_CRYPTO, |
| K_OBJ_DRIVER_FLASH, |
| K_OBJ_DRIVER_GPIO, |
| K_OBJ_DRIVER_I2C, |
| K_OBJ_DRIVER_I2S, |
| K_OBJ_DRIVER_IPM, |
| K_OBJ_DRIVER_PINMUX, |
| K_OBJ_DRIVER_PWM, |
| K_OBJ_DRIVER_ENTROPY, |
| K_OBJ_DRIVER_RTC, |
| K_OBJ_DRIVER_SENSOR, |
| K_OBJ_DRIVER_SPI, |
| K_OBJ_DRIVER_UART, |
| |
| K_OBJ_LAST |
| }; |
| |
| #ifdef CONFIG_USERSPACE |
| /* Table generated by gperf, these objects are retrieved via |
| * _k_object_find() */ |
| struct _k_object { |
| char *name; |
| u8_t perms[CONFIG_MAX_THREAD_BYTES]; |
| u8_t type; |
| u8_t flags; |
| u32_t data; |
| } __packed; |
| |
| struct _k_object_assignment { |
| struct k_thread *thread; |
| void * const *objects; |
| }; |
| |
| /** |
| * @brief Grant a static thread access to a list of kernel objects |
| * |
| * For threads declared with K_THREAD_DEFINE(), grant the thread access to |
| * a set of kernel objects. These objects do not need to be in an initialized |
| * state. The permissions will be granted when the threads are initialized |
| * in the early boot sequence. |
| * |
| * All arguments beyond the first must be pointers to kernel objects. |
| * |
| * @param name_ Name of the thread, as passed to K_THREAD_DEFINE() |
| */ |
| #define K_THREAD_ACCESS_GRANT(name_, ...) \ |
| static void * const _CONCAT(_object_list_, name_)[] = \ |
| { __VA_ARGS__, NULL }; \ |
| static __used __in_section_unique(object_access) \ |
| const struct _k_object_assignment \ |
| _CONCAT(_object_access_, name_) = \ |
| { (&_k_thread_obj_ ## name_), \ |
| (_CONCAT(_object_list_, name_)) } |
| |
| #define K_OBJ_FLAG_INITIALIZED BIT(0) |
| #define K_OBJ_FLAG_PUBLIC BIT(1) |
| |
| /** |
| * Lookup a kernel object and init its metadata if it exists |
| * |
| * Calling this on an object will make it usable from userspace. |
| * Intended to be called as the last statement in kernel object init |
| * functions. |
| * |
| * @param object Address of the kernel object |
| */ |
| void _k_object_init(void *obj); |
| #else |
| |
| #define K_THREAD_ACCESS_GRANT(thread, ...) |
| |
| static inline void _k_object_init(void *obj) |
| { |
| ARG_UNUSED(obj); |
| } |
| |
| static inline void _impl_k_object_access_grant(void *object, |
| struct k_thread *thread) |
| { |
| ARG_UNUSED(object); |
| ARG_UNUSED(thread); |
| } |
| |
| static inline void _impl_k_object_access_revoke(void *object, |
| struct k_thread *thread) |
| { |
| ARG_UNUSED(object); |
| ARG_UNUSED(thread); |
| } |
| |
| static inline void k_object_access_all_grant(void *object) |
| { |
| ARG_UNUSED(object); |
| } |
| #endif /* !CONFIG_USERSPACE */ |
| |
| /** |
| * grant a thread access to a kernel object |
| * |
| * The thread will be granted access to the object if the caller is from |
| * supervisor mode, or the caller is from user mode AND has permissions |
| * on both the object and the thread whose access is being granted. |
| * |
| * @param object Address of kernel object |
| * @param thread Thread to grant access to the object |
| */ |
| __syscall void k_object_access_grant(void *object, struct k_thread *thread); |
| |
| /** |
| * grant a thread access to a kernel object |
| * |
| * The thread will lose access to the object if the caller is from |
| * supervisor mode, or the caller is from user mode AND has permissions |
| * on both the object and the thread whose access is being revoked. |
| * |
| * @param object Address of kernel object |
| * @param thread Thread to remove access to the object |
| */ |
| __syscall void k_object_access_revoke(void *object, struct k_thread *thread); |
| |
| /** |
| * grant all present and future threads access to an object |
| * |
| * If the caller is from supervisor mode, or the caller is from user mode and |
| * have sufficient permissions on the object, then that object will have |
| * permissions granted to it for *all* current and future threads running in |
| * the system, effectively becoming a public kernel object. |
| * |
| * Use of this API should be avoided on systems that are running untrusted code |
| * as it is possible for such code to derive the addresses of kernel objects |
| * and perform unwanted operations on them. |
| * |
| * It is not possible to revoke permissions on public objects; once public, |
| * any thread may use it. |
| * |
| * @param object Address of kernel object |
| */ |
| void k_object_access_all_grant(void *object); |
| |
| /* Using typedef deliberately here, this is quite intended to be an opaque |
| * type. K_THREAD_STACK_BUFFER() should be used to access the data within. |
| * |
| * The purpose of this data type is to clearly distinguish between the |
| * declared symbol for a stack (of type k_thread_stack_t) and the underlying |
| * buffer which composes the stack data actually used by the underlying |
| * thread; they cannot be used interchangably as some arches precede the |
| * stack buffer region with guard areas that trigger a MPU or MMU fault |
| * if written to. |
| * |
| * APIs that want to work with the buffer inside should continue to use |
| * char *. |
| * |
| * Stacks should always be created with K_THREAD_STACK_DEFINE(). |
| */ |
| struct __packed _k_thread_stack_element { |
| char data; |
| }; |
| typedef struct _k_thread_stack_element k_thread_stack_t; |
| |
| /* timeouts */ |
| |
| struct _timeout; |
| typedef void (*_timeout_func_t)(struct _timeout *t); |
| |
| struct _timeout { |
| sys_dnode_t node; |
| struct k_thread *thread; |
| sys_dlist_t *wait_q; |
| s32_t delta_ticks_from_prev; |
| _timeout_func_t func; |
| }; |
| |
| extern s32_t _timeout_remaining_get(struct _timeout *timeout); |
| |
| /** |
| * @typedef k_thread_entry_t |
| * @brief Thread entry point function type. |
| * |
| * A thread's entry point function is invoked when the thread starts executing. |
| * Up to 3 argument values can be passed to the function. |
| * |
| * The thread terminates execution permanently if the entry point function |
| * returns. The thread is responsible for releasing any shared resources |
| * it may own (such as mutexes and dynamically allocated memory), prior to |
| * returning. |
| * |
| * @param p1 First argument. |
| * @param p2 Second argument. |
| * @param p3 Third argument. |
| * |
| * @return N/A |
| */ |
| typedef void (*k_thread_entry_t)(void *p1, void *p2, void *p3); |
| |
| #ifdef CONFIG_THREAD_MONITOR |
| struct __thread_entry { |
| k_thread_entry_t pEntry; |
| void *parameter1; |
| void *parameter2; |
| void *parameter3; |
| }; |
| #endif |
| |
| /* can be used for creating 'dummy' threads, e.g. for pending on objects */ |
| struct _thread_base { |
| |
| /* this thread's entry in a ready/wait queue */ |
| sys_dnode_t k_q_node; |
| |
| /* user facing 'thread options'; values defined in include/kernel.h */ |
| u8_t user_options; |
| |
| /* thread state */ |
| u8_t thread_state; |
| |
| /* |
| * scheduler lock count and thread priority |
| * |
| * These two fields control the preemptibility of a thread. |
| * |
| * When the scheduler is locked, sched_locked is decremented, which |
| * means that the scheduler is locked for values from 0xff to 0x01. A |
| * thread is coop if its prio is negative, thus 0x80 to 0xff when |
| * looked at the value as unsigned. |
| * |
| * By putting them end-to-end, this means that a thread is |
| * non-preemptible if the bundled value is greater than or equal to |
| * 0x0080. |
| */ |
| union { |
| struct { |
| #if __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__ |
| u8_t sched_locked; |
| s8_t prio; |
| #else /* LITTLE and PDP */ |
| s8_t prio; |
| u8_t sched_locked; |
| #endif |
| }; |
| u16_t preempt; |
| }; |
| |
| /* data returned by APIs */ |
| void *swap_data; |
| |
| #ifdef CONFIG_SYS_CLOCK_EXISTS |
| /* this thread's entry in a timeout queue */ |
| struct _timeout timeout; |
| #endif |
| }; |
| |
| typedef struct _thread_base _thread_base_t; |
| |
| #if defined(CONFIG_THREAD_STACK_INFO) |
| /* Contains the stack information of a thread */ |
| struct _thread_stack_info { |
| /* Stack Start */ |
| u32_t start; |
| /* Stack Size */ |
| u32_t size; |
| }; |
| |
| typedef struct _thread_stack_info _thread_stack_info_t; |
| #endif /* CONFIG_THREAD_STACK_INFO */ |
| |
| #if defined(CONFIG_USERSPACE) |
| struct _mem_domain_info { |
| /* memory domain queue node */ |
| sys_dnode_t mem_domain_q_node; |
| /* memory domain of the thread */ |
| struct k_mem_domain *mem_domain; |
| }; |
| |
| #endif /* CONFIG_USERSPACE */ |
| |
| struct k_thread { |
| |
| struct _thread_base base; |
| |
| /* defined by the architecture, but all archs need these */ |
| struct _caller_saved caller_saved; |
| struct _callee_saved callee_saved; |
| |
| /* static thread init data */ |
| void *init_data; |
| |
| /* abort function */ |
| void (*fn_abort)(void); |
| |
| #if defined(CONFIG_THREAD_MONITOR) |
| /* thread entry and parameters description */ |
| struct __thread_entry *entry; |
| |
| /* next item in list of all threads */ |
| struct k_thread *next_thread; |
| #endif |
| |
| #ifdef CONFIG_THREAD_CUSTOM_DATA |
| /* crude thread-local storage */ |
| void *custom_data; |
| #endif |
| |
| #ifdef CONFIG_ERRNO |
| /* per-thread errno variable */ |
| int errno_var; |
| #endif |
| |
| #if defined(CONFIG_THREAD_STACK_INFO) |
| /* Stack Info */ |
| struct _thread_stack_info stack_info; |
| #endif /* CONFIG_THREAD_STACK_INFO */ |
| |
| #if defined(CONFIG_USERSPACE) |
| /* memory domain info of the thread */ |
| struct _mem_domain_info mem_domain_info; |
| /* Base address of thread stack */ |
| k_thread_stack_t *stack_obj; |
| #endif /* CONFIG_USERSPACE */ |
| |
| /* arch-specifics: must always be at the end */ |
| struct _thread_arch arch; |
| }; |
| |
| typedef struct k_thread _thread_t; |
| typedef struct k_thread *k_tid_t; |
| #define tcs k_thread |
| |
| enum execution_context_types { |
| K_ISR = 0, |
| K_COOP_THREAD, |
| K_PREEMPT_THREAD, |
| }; |
| |
| /** |
| * @defgroup profiling_apis Profiling APIs |
| * @ingroup kernel_apis |
| * @{ |
| */ |
| |
| /** |
| * @brief Analyze the main, idle, interrupt and system workqueue call stacks |
| * |
| * This routine calls @ref STACK_ANALYZE on the 4 call stacks declared and |
| * maintained by the kernel. The sizes of those 4 call stacks are defined by: |
| * |
| * CONFIG_MAIN_STACK_SIZE |
| * CONFIG_IDLE_STACK_SIZE |
| * CONFIG_ISR_STACK_SIZE |
| * CONFIG_SYSTEM_WORKQUEUE_STACK_SIZE |
| * |
| * @note CONFIG_INIT_STACKS and CONFIG_PRINTK must be set for this function to |
| * produce output. |
| * |
| * @return N/A |
| */ |
| extern void k_call_stacks_analyze(void); |
| |
| /** |
| * @} end defgroup profiling_apis |
| */ |
| |
| /** |
| * @defgroup thread_apis Thread APIs |
| * @ingroup kernel_apis |
| * @{ |
| */ |
| |
| #endif /* !_ASMLANGUAGE */ |
| |
| |
| /* |
| * Thread user options. May be needed by assembly code. Common part uses low |
| * bits, arch-specific use high bits. |
| */ |
| |
| /* system thread that must not abort */ |
| #define K_ESSENTIAL (1 << 0) |
| |
| #if defined(CONFIG_FP_SHARING) |
| /* thread uses floating point registers */ |
| #define K_FP_REGS (1 << 1) |
| #endif |
| |
| /* This thread has dropped from supervisor mode to user mode and consequently |
| * has additional restrictions |
| */ |
| #define K_USER (1 << 2) |
| |
| /* Indicates that the thread being created should inherit all kernel object |
| * permissions from the thread that created it. No effect if CONFIG_USERSPACE |
| * is not enabled. |
| */ |
| #define K_INHERIT_PERMS (1 << 3) |
| |
| #ifdef CONFIG_X86 |
| /* x86 Bitmask definitions for threads user options */ |
| |
| #if defined(CONFIG_FP_SHARING) && defined(CONFIG_SSE) |
| /* thread uses SSEx (and also FP) registers */ |
| #define K_SSE_REGS (1 << 7) |
| #endif |
| #endif |
| |
| /* end - thread options */ |
| |
| #if !defined(_ASMLANGUAGE) |
| /** |
| * @brief Create a thread. |
| * |
| * This routine initializes a thread, then schedules it for execution. |
| * |
| * The new thread may be scheduled for immediate execution or a delayed start. |
| * If the newly spawned thread does not have a delayed start the kernel |
| * scheduler may preempt the current thread to allow the new thread to |
| * execute. |
| * |
| * Thread options are architecture-specific, and can include K_ESSENTIAL, |
| * K_FP_REGS, and K_SSE_REGS. Multiple options may be specified by separating |
| * them using "|" (the logical OR operator). |
| * |
| * Historically, users often would use the beginning of the stack memory region |
| * to store the struct k_thread data, although corruption will occur if the |
| * stack overflows this region and stack protection features may not detect this |
| * situation. |
| * |
| * @param new_thread Pointer to uninitialized struct k_thread |
| * @param stack Pointer to the stack space. |
| * @param stack_size Stack size in bytes. |
| * @param entry Thread entry function. |
| * @param p1 1st entry point parameter. |
| * @param p2 2nd entry point parameter. |
| * @param p3 3rd entry point parameter. |
| * @param prio Thread priority. |
| * @param options Thread options. |
| * @param delay Scheduling delay (in milliseconds), or K_NO_WAIT (for no delay). |
| * |
| * @return ID of new thread. |
| */ |
| __syscall k_tid_t k_thread_create(struct k_thread *new_thread, |
| k_thread_stack_t *stack, |
| size_t stack_size, |
| k_thread_entry_t entry, |
| void *p1, void *p2, void *p3, |
| int prio, u32_t options, s32_t delay); |
| |
| /** |
| * @brief Drop a thread's privileges permanently to user mode |
| * |
| * @param entry Function to start executing from |
| * @param p1 1st entry point parameter |
| * @param p2 2nd entry point parameter |
| * @param p3 3rd entry point parameter |
| */ |
| extern FUNC_NORETURN void k_thread_user_mode_enter(k_thread_entry_t entry, |
| void *p1, void *p2, |
| void *p3); |
| |
| /** |
| * @brief Grant a thread access to a NULL-terminated set of kernel objects |
| * |
| * This is a convenience function. For the provided thread, grant access to |
| * the remaining arguments, which must be pointers to kernel objects. |
| * The final argument must be a NULL. |
| * |
| * The thread object must be initialized (i.e. running). The objects don't |
| * need to be. |
| * |
| * @param thread Thread to grant access to objects |
| * @param ... NULL-terminated list of kernel object pointers |
| */ |
| extern void __attribute__((sentinel)) |
| k_thread_access_grant(struct k_thread *thread, ...); |
| |
| /** |
| * @brief Put the current thread to sleep. |
| * |
| * This routine puts the current thread to sleep for @a duration |
| * milliseconds. |
| * |
| * @param duration Number of milliseconds to sleep. |
| * |
| * @return N/A |
| */ |
| __syscall void k_sleep(s32_t duration); |
| |
| /** |
| * @brief Cause the current thread to busy wait. |
| * |
| * This routine causes the current thread to execute a "do nothing" loop for |
| * @a usec_to_wait microseconds. |
| * |
| * @return N/A |
| */ |
| extern void k_busy_wait(u32_t usec_to_wait); |
| |
| /** |
| * @brief Yield the current thread. |
| * |
| * This routine causes the current thread to yield execution to another |
| * thread of the same or higher priority. If there are no other ready threads |
| * of the same or higher priority, the routine returns immediately. |
| * |
| * @return N/A |
| */ |
| __syscall void k_yield(void); |
| |
| /** |
| * @brief Wake up a sleeping thread. |
| * |
| * This routine prematurely wakes up @a thread from sleeping. |
| * |
| * If @a thread is not currently sleeping, the routine has no effect. |
| * |
| * @param thread ID of thread to wake. |
| * |
| * @return N/A |
| */ |
| __syscall void k_wakeup(k_tid_t thread); |
| |
| /** |
| * @brief Get thread ID of the current thread. |
| * |
| * @return ID of current thread. |
| */ |
| __syscall k_tid_t k_current_get(void); |
| |
| /** |
| * @brief Cancel thread performing a delayed start. |
| * |
| * This routine prevents @a thread from executing if it has not yet started |
| * execution. The thread must be re-spawned before it will execute. |
| * |
| * @param thread ID of thread to cancel. |
| * |
| * @retval 0 Thread spawning canceled. |
| * @retval -EINVAL Thread has already started executing. |
| */ |
| __syscall int k_thread_cancel(k_tid_t thread); |
| |
| /** |
| * @brief Abort a thread. |
| * |
| * This routine permanently stops execution of @a thread. The thread is taken |
| * off all kernel queues it is part of (i.e. the ready queue, the timeout |
| * queue, or a kernel object wait queue). However, any kernel resources the |
| * thread might currently own (such as mutexes or memory blocks) are not |
| * released. It is the responsibility of the caller of this routine to ensure |
| * all necessary cleanup is performed. |
| * |
| * @param thread ID of thread to abort. |
| * |
| * @return N/A |
| */ |
| __syscall void k_thread_abort(k_tid_t thread); |
| |
| |
| /** |
| * @brief Start an inactive thread |
| * |
| * If a thread was created with K_FOREVER in the delay parameter, it will |
| * not be added to the scheduling queue until this function is called |
| * on it. |
| * |
| * @param thread thread to start |
| */ |
| __syscall void k_thread_start(k_tid_t thread); |
| |
| /** |
| * @cond INTERNAL_HIDDEN |
| */ |
| |
| /* timeout has timed out and is not on _timeout_q anymore */ |
| #define _EXPIRED (-2) |
| |
| /* timeout is not in use */ |
| #define _INACTIVE (-1) |
| |
| struct _static_thread_data { |
| struct k_thread *init_thread; |
| k_thread_stack_t *init_stack; |
| unsigned int init_stack_size; |
| k_thread_entry_t init_entry; |
| void *init_p1; |
| void *init_p2; |
| void *init_p3; |
| int init_prio; |
| u32_t init_options; |
| s32_t init_delay; |
| void (*init_abort)(void); |
| }; |
| |
| #define _THREAD_INITIALIZER(thread, stack, stack_size, \ |
| entry, p1, p2, p3, \ |
| prio, options, delay, abort, groups) \ |
| { \ |
| .init_thread = (thread), \ |
| .init_stack = (stack), \ |
| .init_stack_size = (stack_size), \ |
| .init_entry = (k_thread_entry_t)entry, \ |
| .init_p1 = (void *)p1, \ |
| .init_p2 = (void *)p2, \ |
| .init_p3 = (void *)p3, \ |
| .init_prio = (prio), \ |
| .init_options = (options), \ |
| .init_delay = (delay), \ |
| .init_abort = (abort), \ |
| } |
| |
| /** |
| * INTERNAL_HIDDEN @endcond |
| */ |
| |
| /** |
| * @brief Statically define and initialize a thread. |
| * |
| * The thread may be scheduled for immediate execution or a delayed start. |
| * |
| * Thread options are architecture-specific, and can include K_ESSENTIAL, |
| * K_FP_REGS, and K_SSE_REGS. Multiple options may be specified by separating |
| * them using "|" (the logical OR operator). |
| * |
| * The ID of the thread can be accessed using: |
| * |
| * @code extern const k_tid_t <name>; @endcode |
| * |
| * @param name Name of the thread. |
| * @param stack_size Stack size in bytes. |
| * @param entry Thread entry function. |
| * @param p1 1st entry point parameter. |
| * @param p2 2nd entry point parameter. |
| * @param p3 3rd entry point parameter. |
| * @param prio Thread priority. |
| * @param options Thread options. |
| * @param delay Scheduling delay (in milliseconds), or K_NO_WAIT (for no delay). |
| * |
| * @internal It has been observed that the x86 compiler by default aligns |
| * these _static_thread_data structures to 32-byte boundaries, thereby |
| * wasting space. To work around this, force a 4-byte alignment. |
| */ |
| #define K_THREAD_DEFINE(name, stack_size, \ |
| entry, p1, p2, p3, \ |
| prio, options, delay) \ |
| K_THREAD_STACK_DEFINE(_k_thread_stack_##name, stack_size); \ |
| struct k_thread __kernel _k_thread_obj_##name; \ |
| struct _static_thread_data _k_thread_data_##name __aligned(4) \ |
| __in_section(_static_thread_data, static, name) = \ |
| _THREAD_INITIALIZER(&_k_thread_obj_##name, \ |
| _k_thread_stack_##name, stack_size, \ |
| entry, p1, p2, p3, prio, options, delay, \ |
| NULL, 0); \ |
| const k_tid_t name = (k_tid_t)&_k_thread_obj_##name |
| |
| /** |
| * @brief Get a thread's priority. |
| * |
| * This routine gets the priority of @a thread. |
| * |
| * @param thread ID of thread whose priority is needed. |
| * |
| * @return Priority of @a thread. |
| */ |
| __syscall int k_thread_priority_get(k_tid_t thread); |
| |
| /** |
| * @brief Set a thread's priority. |
| * |
| * This routine immediately changes the priority of @a thread. |
| * |
| * Rescheduling can occur immediately depending on the priority @a thread is |
| * set to: |
| * |
| * - If its priority is raised above the priority of the caller of this |
| * function, and the caller is preemptible, @a thread will be scheduled in. |
| * |
| * - If the caller operates on itself, it lowers its priority below that of |
| * other threads in the system, and the caller is preemptible, the thread of |
| * highest priority will be scheduled in. |
| * |
| * Priority can be assigned in the range of -CONFIG_NUM_COOP_PRIORITIES to |
| * CONFIG_NUM_PREEMPT_PRIORITIES-1, where -CONFIG_NUM_COOP_PRIORITIES is the |
| * highest priority. |
| * |
| * @param thread ID of thread whose priority is to be set. |
| * @param prio New priority. |
| * |
| * @warning Changing the priority of a thread currently involved in mutex |
| * priority inheritance may result in undefined behavior. |
| * |
| * @return N/A |
| */ |
| __syscall void k_thread_priority_set(k_tid_t thread, int prio); |
| |
| /** |
| * @brief Suspend a thread. |
| * |
| * This routine prevents the kernel scheduler from making @a thread the |
| * current thread. All other internal operations on @a thread are still |
| * performed; for example, any timeout it is waiting on keeps ticking, |
| * kernel objects it is waiting on are still handed to it, etc. |
| * |
| * If @a thread is already suspended, the routine has no effect. |
| * |
| * @param thread ID of thread to suspend. |
| * |
| * @return N/A |
| */ |
| __syscall void k_thread_suspend(k_tid_t thread); |
| |
| /** |
| * @brief Resume a suspended thread. |
| * |
| * This routine allows the kernel scheduler to make @a thread the current |
| * thread, when it is next eligible for that role. |
| * |
| * If @a thread is not currently suspended, the routine has no effect. |
| * |
| * @param thread ID of thread to resume. |
| * |
| * @return N/A |
| */ |
| __syscall void k_thread_resume(k_tid_t thread); |
| |
| /** |
| * @brief Set time-slicing period and scope. |
| * |
| * This routine specifies how the scheduler will perform time slicing of |
| * preemptible threads. |
| * |
| * To enable time slicing, @a slice must be non-zero. The scheduler |
| * ensures that no thread runs for more than the specified time limit |
| * before other threads of that priority are given a chance to execute. |
| * Any thread whose priority is higher than @a prio is exempted, and may |
| * execute as long as desired without being preempted due to time slicing. |
| * |
| * Time slicing only limits the maximum amount of time a thread may continuously |
| * execute. Once the scheduler selects a thread for execution, there is no |
| * minimum guaranteed time the thread will execute before threads of greater or |
| * equal priority are scheduled. |
| * |
| * When the current thread is the only one of that priority eligible |
| * for execution, this routine has no effect; the thread is immediately |
| * rescheduled after the slice period expires. |
| * |
| * To disable timeslicing, set both @a slice and @a prio to zero. |
| * |
| * @param slice Maximum time slice length (in milliseconds). |
| * @param prio Highest thread priority level eligible for time slicing. |
| * |
| * @return N/A |
| */ |
| extern void k_sched_time_slice_set(s32_t slice, int prio); |
| |
| /** |
| * @} end defgroup thread_apis |
| */ |
| |
| /** |
| * @addtogroup isr_apis |
| * @{ |
| */ |
| |
| /** |
| * @brief Determine if code is running at interrupt level. |
| * |
| * This routine allows the caller to customize its actions, depending on |
| * whether it is a thread or an ISR. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @return 0 if invoked by a thread. |
| * @return Non-zero if invoked by an ISR. |
| */ |
| extern int k_is_in_isr(void); |
| |
| /** |
| * @brief Determine if code is running in a preemptible thread. |
| * |
| * This routine allows the caller to customize its actions, depending on |
| * whether it can be preempted by another thread. The routine returns a 'true' |
| * value if all of the following conditions are met: |
| * |
| * - The code is running in a thread, not at ISR. |
| * - The thread's priority is in the preemptible range. |
| * - The thread has not locked the scheduler. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @return 0 if invoked by an ISR or by a cooperative thread. |
| * @return Non-zero if invoked by a preemptible thread. |
| */ |
| __syscall int k_is_preempt_thread(void); |
| |
| /** |
| * @} end addtogroup isr_apis |
| */ |
| |
| /** |
| * @addtogroup thread_apis |
| * @{ |
| */ |
| |
| /** |
| * @brief Lock the scheduler. |
| * |
| * This routine prevents the current thread from being preempted by another |
| * thread by instructing the scheduler to treat it as a cooperative thread. |
| * If the thread subsequently performs an operation that makes it unready, |
| * it will be context switched out in the normal manner. When the thread |
| * again becomes the current thread, its non-preemptible status is maintained. |
| * |
| * This routine can be called recursively. |
| * |
| * @note k_sched_lock() and k_sched_unlock() should normally be used |
| * when the operation being performed can be safely interrupted by ISRs. |
| * However, if the amount of processing involved is very small, better |
| * performance may be obtained by using irq_lock() and irq_unlock(). |
| * |
| * @return N/A |
| */ |
| extern void k_sched_lock(void); |
| |
| /** |
| * @brief Unlock the scheduler. |
| * |
| * This routine reverses the effect of a previous call to k_sched_lock(). |
| * A thread must call the routine once for each time it called k_sched_lock() |
| * before the thread becomes preemptible. |
| * |
| * @return N/A |
| */ |
| extern void k_sched_unlock(void); |
| |
| /** |
| * @brief Set current thread's custom data. |
| * |
| * This routine sets the custom data for the current thread to @ value. |
| * |
| * Custom data is not used by the kernel itself, and is freely available |
| * for a thread to use as it sees fit. It can be used as a framework |
| * upon which to build thread-local storage. |
| * |
| * @param value New custom data value. |
| * |
| * @return N/A |
| */ |
| __syscall void k_thread_custom_data_set(void *value); |
| |
| /** |
| * @brief Get current thread's custom data. |
| * |
| * This routine returns the custom data for the current thread. |
| * |
| * @return Current custom data value. |
| */ |
| __syscall void *k_thread_custom_data_get(void); |
| |
| /** |
| * @} end addtogroup thread_apis |
| */ |
| |
| #include <sys_clock.h> |
| |
| /** |
| * @addtogroup clock_apis |
| * @{ |
| */ |
| |
| /** |
| * @brief Generate null timeout delay. |
| * |
| * This macro generates a timeout delay that that instructs a kernel API |
| * not to wait if the requested operation cannot be performed immediately. |
| * |
| * @return Timeout delay value. |
| */ |
| #define K_NO_WAIT 0 |
| |
| /** |
| * @brief Generate timeout delay from milliseconds. |
| * |
| * This macro generates a timeout delay that that instructs a kernel API |
| * to wait up to @a ms milliseconds to perform the requested operation. |
| * |
| * @param ms Duration in milliseconds. |
| * |
| * @return Timeout delay value. |
| */ |
| #define K_MSEC(ms) (ms) |
| |
| /** |
| * @brief Generate timeout delay from seconds. |
| * |
| * This macro generates a timeout delay that that instructs a kernel API |
| * to wait up to @a s seconds to perform the requested operation. |
| * |
| * @param s Duration in seconds. |
| * |
| * @return Timeout delay value. |
| */ |
| #define K_SECONDS(s) K_MSEC((s) * MSEC_PER_SEC) |
| |
| /** |
| * @brief Generate timeout delay from minutes. |
| * |
| * This macro generates a timeout delay that that instructs a kernel API |
| * to wait up to @a m minutes to perform the requested operation. |
| * |
| * @param m Duration in minutes. |
| * |
| * @return Timeout delay value. |
| */ |
| #define K_MINUTES(m) K_SECONDS((m) * 60) |
| |
| /** |
| * @brief Generate timeout delay from hours. |
| * |
| * This macro generates a timeout delay that that instructs a kernel API |
| * to wait up to @a h hours to perform the requested operation. |
| * |
| * @param h Duration in hours. |
| * |
| * @return Timeout delay value. |
| */ |
| #define K_HOURS(h) K_MINUTES((h) * 60) |
| |
| /** |
| * @brief Generate infinite timeout delay. |
| * |
| * This macro generates a timeout delay that that instructs a kernel API |
| * to wait as long as necessary to perform the requested operation. |
| * |
| * @return Timeout delay value. |
| */ |
| #define K_FOREVER (-1) |
| |
| /** |
| * @} end addtogroup clock_apis |
| */ |
| |
| /** |
| * @cond INTERNAL_HIDDEN |
| */ |
| |
| /* kernel clocks */ |
| |
| #if (sys_clock_ticks_per_sec == 1000) || \ |
| (sys_clock_ticks_per_sec == 500) || \ |
| (sys_clock_ticks_per_sec == 250) || \ |
| (sys_clock_ticks_per_sec == 125) || \ |
| (sys_clock_ticks_per_sec == 100) || \ |
| (sys_clock_ticks_per_sec == 50) || \ |
| (sys_clock_ticks_per_sec == 25) || \ |
| (sys_clock_ticks_per_sec == 20) || \ |
| (sys_clock_ticks_per_sec == 10) || \ |
| (sys_clock_ticks_per_sec == 1) |
| |
| #define _ms_per_tick (MSEC_PER_SEC / sys_clock_ticks_per_sec) |
| #else |
| /* yields horrible 64-bit math on many architectures: try to avoid */ |
| #define _NON_OPTIMIZED_TICKS_PER_SEC |
| #endif |
| |
| #ifdef _NON_OPTIMIZED_TICKS_PER_SEC |
| extern s32_t _ms_to_ticks(s32_t ms); |
| #else |
| static ALWAYS_INLINE s32_t _ms_to_ticks(s32_t ms) |
| { |
| return (s32_t)ceiling_fraction((u32_t)ms, _ms_per_tick); |
| } |
| #endif |
| |
| /* added tick needed to account for tick in progress */ |
| #ifdef CONFIG_TICKLESS_KERNEL |
| #define _TICK_ALIGN 0 |
| #else |
| #define _TICK_ALIGN 1 |
| #endif |
| |
| static inline s64_t __ticks_to_ms(s64_t ticks) |
| { |
| #ifdef CONFIG_SYS_CLOCK_EXISTS |
| |
| #ifdef _NON_OPTIMIZED_TICKS_PER_SEC |
| return (MSEC_PER_SEC * (u64_t)ticks) / sys_clock_ticks_per_sec; |
| #else |
| return (u64_t)ticks * _ms_per_tick; |
| #endif |
| |
| #else |
| __ASSERT(ticks == 0, ""); |
| return 0; |
| #endif |
| } |
| |
| struct k_timer { |
| /* |
| * _timeout structure must be first here if we want to use |
| * dynamic timer allocation. timeout.node is used in the double-linked |
| * list of free timers |
| */ |
| struct _timeout timeout; |
| |
| /* wait queue for the (single) thread waiting on this timer */ |
| _wait_q_t wait_q; |
| |
| /* runs in ISR context */ |
| void (*expiry_fn)(struct k_timer *); |
| |
| /* runs in the context of the thread that calls k_timer_stop() */ |
| void (*stop_fn)(struct k_timer *); |
| |
| /* timer period */ |
| s32_t period; |
| |
| /* timer status */ |
| u32_t status; |
| |
| /* user-specific data, also used to support legacy features */ |
| void *user_data; |
| |
| _OBJECT_TRACING_NEXT_PTR(k_timer); |
| }; |
| |
| #define _K_TIMER_INITIALIZER(obj, expiry, stop) \ |
| { \ |
| .timeout.delta_ticks_from_prev = _INACTIVE, \ |
| .timeout.wait_q = NULL, \ |
| .timeout.thread = NULL, \ |
| .timeout.func = _timer_expiration_handler, \ |
| .wait_q = SYS_DLIST_STATIC_INIT(&obj.wait_q), \ |
| .expiry_fn = expiry, \ |
| .stop_fn = stop, \ |
| .status = 0, \ |
| .user_data = 0, \ |
| _OBJECT_TRACING_INIT \ |
| } |
| |
| #define K_TIMER_INITIALIZER DEPRECATED_MACRO _K_TIMER_INITIALIZER |
| |
| /** |
| * INTERNAL_HIDDEN @endcond |
| */ |
| |
| /** |
| * @defgroup timer_apis Timer APIs |
| * @ingroup kernel_apis |
| * @{ |
| */ |
| |
| /** |
| * @typedef k_timer_expiry_t |
| * @brief Timer expiry function type. |
| * |
| * A timer's expiry function is executed by the system clock interrupt handler |
| * each time the timer expires. The expiry function is optional, and is only |
| * invoked if the timer has been initialized with one. |
| * |
| * @param timer Address of timer. |
| * |
| * @return N/A |
| */ |
| typedef void (*k_timer_expiry_t)(struct k_timer *timer); |
| |
| /** |
| * @typedef k_timer_stop_t |
| * @brief Timer stop function type. |
| * |
| * A timer's stop function is executed if the timer is stopped prematurely. |
| * The function runs in the context of the thread that stops the timer. |
| * The stop function is optional, and is only invoked if the timer has been |
| * initialized with one. |
| * |
| * @param timer Address of timer. |
| * |
| * @return N/A |
| */ |
| typedef void (*k_timer_stop_t)(struct k_timer *timer); |
| |
| /** |
| * @brief Statically define and initialize a timer. |
| * |
| * The timer can be accessed outside the module where it is defined using: |
| * |
| * @code extern struct k_timer <name>; @endcode |
| * |
| * @param name Name of the timer variable. |
| * @param expiry_fn Function to invoke each time the timer expires. |
| * @param stop_fn Function to invoke if the timer is stopped while running. |
| */ |
| #define K_TIMER_DEFINE(name, expiry_fn, stop_fn) \ |
| struct k_timer name \ |
| __in_section(_k_timer, static, name) = \ |
| _K_TIMER_INITIALIZER(name, expiry_fn, stop_fn) |
| |
| /** |
| * @brief Initialize a timer. |
| * |
| * This routine initializes a timer, prior to its first use. |
| * |
| * @param timer Address of timer. |
| * @param expiry_fn Function to invoke each time the timer expires. |
| * @param stop_fn Function to invoke if the timer is stopped while running. |
| * |
| * @return N/A |
| */ |
| extern void k_timer_init(struct k_timer *timer, |
| k_timer_expiry_t expiry_fn, |
| k_timer_stop_t stop_fn); |
| |
| /** |
| * @brief Start a timer. |
| * |
| * This routine starts a timer, and resets its status to zero. The timer |
| * begins counting down using the specified duration and period values. |
| * |
| * Attempting to start a timer that is already running is permitted. |
| * The timer's status is reset to zero and the timer begins counting down |
| * using the new duration and period values. |
| * |
| * @param timer Address of timer. |
| * @param duration Initial timer duration (in milliseconds). |
| * @param period Timer period (in milliseconds). |
| * |
| * @return N/A |
| */ |
| __syscall void k_timer_start(struct k_timer *timer, |
| s32_t duration, s32_t period); |
| |
| /** |
| * @brief Stop a timer. |
| * |
| * This routine stops a running timer prematurely. The timer's stop function, |
| * if one exists, is invoked by the caller. |
| * |
| * Attempting to stop a timer that is not running is permitted, but has no |
| * effect on the timer. |
| * |
| * @note Can be called by ISRs. The stop handler has to be callable from ISRs |
| * if @a k_timer_stop is to be called from ISRs. |
| * |
| * @param timer Address of timer. |
| * |
| * @return N/A |
| */ |
| __syscall void k_timer_stop(struct k_timer *timer); |
| |
| /** |
| * @brief Read timer status. |
| * |
| * This routine reads the timer's status, which indicates the number of times |
| * it has expired since its status was last read. |
| * |
| * Calling this routine resets the timer's status to zero. |
| * |
| * @param timer Address of timer. |
| * |
| * @return Timer status. |
| */ |
| __syscall u32_t k_timer_status_get(struct k_timer *timer); |
| |
| /** |
| * @brief Synchronize thread to timer expiration. |
| * |
| * This routine blocks the calling thread until the timer's status is non-zero |
| * (indicating that it has expired at least once since it was last examined) |
| * or the timer is stopped. If the timer status is already non-zero, |
| * or the timer is already stopped, the caller continues without waiting. |
| * |
| * Calling this routine resets the timer's status to zero. |
| * |
| * This routine must not be used by interrupt handlers, since they are not |
| * allowed to block. |
| * |
| * @param timer Address of timer. |
| * |
| * @return Timer status. |
| */ |
| __syscall u32_t k_timer_status_sync(struct k_timer *timer); |
| |
| /** |
| * @brief Get time remaining before a timer next expires. |
| * |
| * This routine computes the (approximate) time remaining before a running |
| * timer next expires. If the timer is not running, it returns zero. |
| * |
| * @param timer Address of timer. |
| * |
| * @return Remaining time (in milliseconds). |
| */ |
| __syscall s32_t k_timer_remaining_get(struct k_timer *timer); |
| |
| static inline s32_t _impl_k_timer_remaining_get(struct k_timer *timer) |
| { |
| return _timeout_remaining_get(&timer->timeout); |
| } |
| |
| /** |
| * @brief Associate user-specific data with a timer. |
| * |
| * This routine records the @a user_data with the @a timer, to be retrieved |
| * later. |
| * |
| * It can be used e.g. in a timer handler shared across multiple subsystems to |
| * retrieve data specific to the subsystem this timer is associated with. |
| * |
| * @param timer Address of timer. |
| * @param user_data User data to associate with the timer. |
| * |
| * @return N/A |
| */ |
| __syscall void k_timer_user_data_set(struct k_timer *timer, void *user_data); |
| |
| static inline void _impl_k_timer_user_data_set(struct k_timer *timer, |
| void *user_data) |
| { |
| timer->user_data = user_data; |
| } |
| |
| /** |
| * @brief Retrieve the user-specific data from a timer. |
| * |
| * @param timer Address of timer. |
| * |
| * @return The user data. |
| */ |
| __syscall void *k_timer_user_data_get(struct k_timer *timer); |
| |
| static inline void *_impl_k_timer_user_data_get(struct k_timer *timer) |
| { |
| return timer->user_data; |
| } |
| |
| /** |
| * @} end defgroup timer_apis |
| */ |
| |
| /** |
| * @addtogroup clock_apis |
| * @{ |
| */ |
| |
| /** |
| * @brief Get system uptime. |
| * |
| * This routine returns the elapsed time since the system booted, |
| * in milliseconds. |
| * |
| * @return Current uptime. |
| */ |
| __syscall s64_t k_uptime_get(void); |
| |
| #ifdef CONFIG_TICKLESS_KERNEL |
| /** |
| * @brief Enable clock always on in tickless kernel |
| * |
| * This routine enables keeping the clock running when |
| * there are no timer events programmed in tickless kernel |
| * scheduling. This is necessary if the clock is used to track |
| * passage of time. |
| * |
| * @retval prev_status Previous status of always on flag |
| */ |
| static inline int k_enable_sys_clock_always_on(void) |
| { |
| int prev_status = _sys_clock_always_on; |
| |
| _sys_clock_always_on = 1; |
| _enable_sys_clock(); |
| |
| return prev_status; |
| } |
| |
| /** |
| * @brief Disable clock always on in tickless kernel |
| * |
| * This routine disables keeping the clock running when |
| * there are no timer events programmed in tickless kernel |
| * scheduling. To save power, this routine should be called |
| * immediately when clock is not used to track time. |
| */ |
| static inline void k_disable_sys_clock_always_on(void) |
| { |
| _sys_clock_always_on = 0; |
| } |
| #else |
| #define k_enable_sys_clock_always_on() do { } while ((0)) |
| #define k_disable_sys_clock_always_on() do { } while ((0)) |
| #endif |
| |
| /** |
| * @brief Get system uptime (32-bit version). |
| * |
| * This routine returns the lower 32-bits of the elapsed time since the system |
| * booted, in milliseconds. |
| * |
| * This routine can be more efficient than k_uptime_get(), as it reduces the |
| * need for interrupt locking and 64-bit math. However, the 32-bit result |
| * cannot hold a system uptime time larger than approximately 50 days, so the |
| * caller must handle possible rollovers. |
| * |
| * @return Current uptime. |
| */ |
| __syscall u32_t k_uptime_get_32(void); |
| |
| /** |
| * @brief Get elapsed time. |
| * |
| * This routine computes the elapsed time between the current system uptime |
| * and an earlier reference time, in milliseconds. |
| * |
| * @param reftime Pointer to a reference time, which is updated to the current |
| * uptime upon return. |
| * |
| * @return Elapsed time. |
| */ |
| extern s64_t k_uptime_delta(s64_t *reftime); |
| |
| /** |
| * @brief Get elapsed time (32-bit version). |
| * |
| * This routine computes the elapsed time between the current system uptime |
| * and an earlier reference time, in milliseconds. |
| * |
| * This routine can be more efficient than k_uptime_delta(), as it reduces the |
| * need for interrupt locking and 64-bit math. However, the 32-bit result |
| * cannot hold an elapsed time larger than approximately 50 days, so the |
| * caller must handle possible rollovers. |
| * |
| * @param reftime Pointer to a reference time, which is updated to the current |
| * uptime upon return. |
| * |
| * @return Elapsed time. |
| */ |
| extern u32_t k_uptime_delta_32(s64_t *reftime); |
| |
| /** |
| * @brief Read the hardware clock. |
| * |
| * This routine returns the current time, as measured by the system's hardware |
| * clock. |
| * |
| * @return Current hardware clock up-counter (in cycles). |
| */ |
| #define k_cycle_get_32() _arch_k_cycle_get_32() |
| |
| /** |
| * @} end addtogroup clock_apis |
| */ |
| |
| /** |
| * @cond INTERNAL_HIDDEN |
| */ |
| |
| struct k_queue { |
| sys_slist_t data_q; |
| union { |
| _wait_q_t wait_q; |
| |
| _POLL_EVENT; |
| }; |
| |
| _OBJECT_TRACING_NEXT_PTR(k_queue); |
| }; |
| |
| #define _K_QUEUE_INITIALIZER(obj) \ |
| { \ |
| .wait_q = SYS_DLIST_STATIC_INIT(&obj.wait_q), \ |
| .data_q = SYS_SLIST_STATIC_INIT(&obj.data_q), \ |
| _POLL_EVENT_OBJ_INIT(obj) \ |
| _OBJECT_TRACING_INIT \ |
| } |
| |
| #define K_QUEUE_INITIALIZER DEPRECATED_MACRO _K_QUEUE_INITIALIZER |
| |
| /** |
| * INTERNAL_HIDDEN @endcond |
| */ |
| |
| /** |
| * @defgroup queue_apis Queue APIs |
| * @ingroup kernel_apis |
| * @{ |
| */ |
| |
| /** |
| * @brief Initialize a queue. |
| * |
| * This routine initializes a queue object, prior to its first use. |
| * |
| * @param queue Address of the queue. |
| * |
| * @return N/A |
| */ |
| extern void k_queue_init(struct k_queue *queue); |
| |
| /** |
| * @brief Cancel waiting on a queue. |
| * |
| * This routine causes first thread pending on @a queue, if any, to |
| * return from k_queue_get() call with NULL value (as if timeout expired). |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param queue Address of the queue. |
| * |
| * @return N/A |
| */ |
| extern void k_queue_cancel_wait(struct k_queue *queue); |
| |
| /** |
| * @brief Append an element to the end of a queue. |
| * |
| * This routine appends a data item to @a queue. A queue data item must be |
| * aligned on a 4-byte boundary, and the first 32 bits of the item are |
| * reserved for the kernel's use. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param queue Address of the queue. |
| * @param data Address of the data item. |
| * |
| * @return N/A |
| */ |
| extern void k_queue_append(struct k_queue *queue, void *data); |
| |
| /** |
| * @brief Prepend an element to a queue. |
| * |
| * This routine prepends a data item to @a queue. A queue data item must be |
| * aligned on a 4-byte boundary, and the first 32 bits of the item are |
| * reserved for the kernel's use. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param queue Address of the queue. |
| * @param data Address of the data item. |
| * |
| * @return N/A |
| */ |
| extern void k_queue_prepend(struct k_queue *queue, void *data); |
| |
| /** |
| * @brief Inserts an element to a queue. |
| * |
| * This routine inserts a data item to @a queue after previous item. A queue |
| * data item must be aligned on a 4-byte boundary, and the first 32 bits of the |
| * item are reserved for the kernel's use. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param queue Address of the queue. |
| * @param prev Address of the previous data item. |
| * @param data Address of the data item. |
| * |
| * @return N/A |
| */ |
| extern void k_queue_insert(struct k_queue *queue, void *prev, void *data); |
| |
| /** |
| * @brief Atomically append a list of elements to a queue. |
| * |
| * This routine adds a list of data items to @a queue in one operation. |
| * The data items must be in a singly-linked list, with the first 32 bits |
| * in each data item pointing to the next data item; the list must be |
| * NULL-terminated. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param queue Address of the queue. |
| * @param head Pointer to first node in singly-linked list. |
| * @param tail Pointer to last node in singly-linked list. |
| * |
| * @return N/A |
| */ |
| extern void k_queue_append_list(struct k_queue *queue, void *head, void *tail); |
| |
| /** |
| * @brief Atomically add a list of elements to a queue. |
| * |
| * This routine adds a list of data items to @a queue in one operation. |
| * The data items must be in a singly-linked list implemented using a |
| * sys_slist_t object. Upon completion, the original list is empty. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param queue Address of the queue. |
| * @param list Pointer to sys_slist_t object. |
| * |
| * @return N/A |
| */ |
| extern void k_queue_merge_slist(struct k_queue *queue, sys_slist_t *list); |
| |
| /** |
| * @brief Get an element from a queue. |
| * |
| * This routine removes first data item from @a queue. The first 32 bits of the |
| * data item are reserved for the kernel's use. |
| * |
| * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT. |
| * |
| * @param queue Address of the queue. |
| * @param timeout Waiting period to obtain a data item (in milliseconds), |
| * or one of the special values K_NO_WAIT and K_FOREVER. |
| * |
| * @return Address of the data item if successful; NULL if returned |
| * without waiting, or waiting period timed out. |
| */ |
| extern void *k_queue_get(struct k_queue *queue, s32_t timeout); |
| |
| /** |
| * @brief Remove an element from a queue. |
| * |
| * This routine removes data item from @a queue. The first 32 bits of the |
| * data item are reserved for the kernel's use. Removing elements from k_queue |
| * rely on sys_slist_find_and_remove which is not a constant time operation. |
| * |
| * @note Can be called by ISRs |
| * |
| * @param queue Address of the queue. |
| * @param data Address of the data item. |
| * |
| * @return true if data item was removed |
| */ |
| static inline bool k_queue_remove(struct k_queue *queue, void *data) |
| { |
| return sys_slist_find_and_remove(&queue->data_q, (sys_snode_t *)data); |
| } |
| |
| /** |
| * @brief Query a queue to see if it has data available. |
| * |
| * Note that the data might be already gone by the time this function returns |
| * if other threads are also trying to read from the queue. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param queue Address of the queue. |
| * |
| * @return Non-zero if the queue is empty. |
| * @return 0 if data is available. |
| */ |
| static inline int k_queue_is_empty(struct k_queue *queue) |
| { |
| return (int)sys_slist_is_empty(&queue->data_q); |
| } |
| |
| /** |
| * @brief Peek element at the head of queue. |
| * |
| * Return element from the head of queue without removing it. |
| * |
| * @param queue Address of the queue. |
| * |
| * @return Head element, or NULL if queue is empty. |
| */ |
| static inline void *k_queue_peek_head(struct k_queue *queue) |
| { |
| return sys_slist_peek_head(&queue->data_q); |
| } |
| |
| /** |
| * @brief Peek element at the tail of queue. |
| * |
| * Return element from the tail of queue without removing it. |
| * |
| * @param queue Address of the queue. |
| * |
| * @return Tail element, or NULL if queue is empty. |
| */ |
| static inline void *k_queue_peek_tail(struct k_queue *queue) |
| { |
| return sys_slist_peek_tail(&queue->data_q); |
| } |
| |
| /** |
| * @brief Statically define and initialize a queue. |
| * |
| * The queue can be accessed outside the module where it is defined using: |
| * |
| * @code extern struct k_queue <name>; @endcode |
| * |
| * @param name Name of the queue. |
| */ |
| #define K_QUEUE_DEFINE(name) \ |
| struct k_queue name \ |
| __in_section(_k_queue, static, name) = \ |
| _K_QUEUE_INITIALIZER(name) |
| |
| /** |
| * @} end defgroup queue_apis |
| */ |
| |
| /** |
| * @cond INTERNAL_HIDDEN |
| */ |
| |
| struct k_fifo { |
| struct k_queue _queue; |
| }; |
| |
| #define _K_FIFO_INITIALIZER(obj) \ |
| { \ |
| ._queue = _K_QUEUE_INITIALIZER(obj._queue) \ |
| } |
| |
| #define K_FIFO_INITIALIZER DEPRECATED_MACRO _K_FIFO_INITIALIZER |
| |
| /** |
| * INTERNAL_HIDDEN @endcond |
| */ |
| |
| /** |
| * @defgroup fifo_apis Fifo APIs |
| * @ingroup kernel_apis |
| * @{ |
| */ |
| |
| /** |
| * @brief Initialize a fifo. |
| * |
| * This routine initializes a fifo object, prior to its first use. |
| * |
| * @param fifo Address of the fifo. |
| * |
| * @return N/A |
| */ |
| #define k_fifo_init(fifo) \ |
| k_queue_init((struct k_queue *) fifo) |
| |
| /** |
| * @brief Cancel waiting on a fifo. |
| * |
| * This routine causes first thread pending on @a fifo, if any, to |
| * return from k_fifo_get() call with NULL value (as if timeout |
| * expired). |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param fifo Address of the fifo. |
| * |
| * @return N/A |
| */ |
| #define k_fifo_cancel_wait(fifo) \ |
| k_queue_cancel_wait((struct k_queue *) fifo) |
| |
| /** |
| * @brief Add an element to a fifo. |
| * |
| * This routine adds a data item to @a fifo. A fifo data item must be |
| * aligned on a 4-byte boundary, and the first 32 bits of the item are |
| * reserved for the kernel's use. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param fifo Address of the fifo. |
| * @param data Address of the data item. |
| * |
| * @return N/A |
| */ |
| #define k_fifo_put(fifo, data) \ |
| k_queue_append((struct k_queue *) fifo, data) |
| |
| /** |
| * @brief Atomically add a list of elements to a fifo. |
| * |
| * This routine adds a list of data items to @a fifo in one operation. |
| * The data items must be in a singly-linked list, with the first 32 bits |
| * each data item pointing to the next data item; the list must be |
| * NULL-terminated. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param fifo Address of the fifo. |
| * @param head Pointer to first node in singly-linked list. |
| * @param tail Pointer to last node in singly-linked list. |
| * |
| * @return N/A |
| */ |
| #define k_fifo_put_list(fifo, head, tail) \ |
| k_queue_append_list((struct k_queue *) fifo, head, tail) |
| |
| /** |
| * @brief Atomically add a list of elements to a fifo. |
| * |
| * This routine adds a list of data items to @a fifo in one operation. |
| * The data items must be in a singly-linked list implemented using a |
| * sys_slist_t object. Upon completion, the sys_slist_t object is invalid |
| * and must be re-initialized via sys_slist_init(). |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param fifo Address of the fifo. |
| * @param list Pointer to sys_slist_t object. |
| * |
| * @return N/A |
| */ |
| #define k_fifo_put_slist(fifo, list) \ |
| k_queue_merge_slist((struct k_queue *) fifo, list) |
| |
| /** |
| * @brief Get an element from a fifo. |
| * |
| * This routine removes a data item from @a fifo in a "first in, first out" |
| * manner. The first 32 bits of the data item are reserved for the kernel's use. |
| * |
| * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT. |
| * |
| * @param fifo Address of the fifo. |
| * @param timeout Waiting period to obtain a data item (in milliseconds), |
| * or one of the special values K_NO_WAIT and K_FOREVER. |
| * |
| * @return Address of the data item if successful; NULL if returned |
| * without waiting, or waiting period timed out. |
| */ |
| #define k_fifo_get(fifo, timeout) \ |
| k_queue_get((struct k_queue *) fifo, timeout) |
| |
| /** |
| * @brief Query a fifo to see if it has data available. |
| * |
| * Note that the data might be already gone by the time this function returns |
| * if other threads is also trying to read from the fifo. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param fifo Address of the fifo. |
| * |
| * @return Non-zero if the fifo is empty. |
| * @return 0 if data is available. |
| */ |
| #define k_fifo_is_empty(fifo) \ |
| k_queue_is_empty((struct k_queue *) fifo) |
| |
| /** |
| * @brief Peek element at the head of fifo. |
| * |
| * Return element from the head of fifo without removing it. A usecase |
| * for this is if elements of the fifo are themselves containers. Then |
| * on each iteration of processing, a head container will be peeked, |
| * and some data processed out of it, and only if the container is empty, |
| * it will be completely remove from the fifo. |
| * |
| * @param fifo Address of the fifo. |
| * |
| * @return Head element, or NULL if the fifo is empty. |
| */ |
| #define k_fifo_peek_head(fifo) \ |
| k_queue_peek_head((struct k_queue *) fifo) |
| |
| /** |
| * @brief Peek element at the tail of fifo. |
| * |
| * Return element from the tail of fifo (without removing it). A usecase |
| * for this is if elements of the fifo are themselves containers. Then |
| * it may be useful to add more data to the last container in fifo. |
| * |
| * @param fifo Address of the fifo. |
| * |
| * @return Tail element, or NULL if fifo is empty. |
| */ |
| #define k_fifo_peek_tail(fifo) \ |
| k_queue_peek_tail((struct k_queue *) fifo) |
| |
| /** |
| * @brief Statically define and initialize a fifo. |
| * |
| * The fifo can be accessed outside the module where it is defined using: |
| * |
| * @code extern struct k_fifo <name>; @endcode |
| * |
| * @param name Name of the fifo. |
| */ |
| #define K_FIFO_DEFINE(name) \ |
| struct k_fifo name \ |
| __in_section(_k_queue, static, name) = \ |
| _K_FIFO_INITIALIZER(name) |
| |
| /** |
| * @} end defgroup fifo_apis |
| */ |
| |
| /** |
| * @cond INTERNAL_HIDDEN |
| */ |
| |
| struct k_lifo { |
| struct k_queue _queue; |
| }; |
| |
| #define _K_LIFO_INITIALIZER(obj) \ |
| { \ |
| ._queue = _K_QUEUE_INITIALIZER(obj._queue) \ |
| } |
| |
| #define K_LIFO_INITIALIZER DEPRECATED_MACRO _K_LIFO_INITIALIZER |
| |
| /** |
| * INTERNAL_HIDDEN @endcond |
| */ |
| |
| /** |
| * @defgroup lifo_apis Lifo APIs |
| * @ingroup kernel_apis |
| * @{ |
| */ |
| |
| /** |
| * @brief Initialize a lifo. |
| * |
| * This routine initializes a lifo object, prior to its first use. |
| * |
| * @param lifo Address of the lifo. |
| * |
| * @return N/A |
| */ |
| #define k_lifo_init(lifo) \ |
| k_queue_init((struct k_queue *) lifo) |
| |
| /** |
| * @brief Add an element to a lifo. |
| * |
| * This routine adds a data item to @a lifo. A lifo data item must be |
| * aligned on a 4-byte boundary, and the first 32 bits of the item are |
| * reserved for the kernel's use. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param lifo Address of the lifo. |
| * @param data Address of the data item. |
| * |
| * @return N/A |
| */ |
| #define k_lifo_put(lifo, data) \ |
| k_queue_prepend((struct k_queue *) lifo, data) |
| |
| /** |
| * @brief Get an element from a lifo. |
| * |
| * This routine removes a data item from @a lifo in a "last in, first out" |
| * manner. The first 32 bits of the data item are reserved for the kernel's use. |
| * |
| * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT. |
| * |
| * @param lifo Address of the lifo. |
| * @param timeout Waiting period to obtain a data item (in milliseconds), |
| * or one of the special values K_NO_WAIT and K_FOREVER. |
| * |
| * @return Address of the data item if successful; NULL if returned |
| * without waiting, or waiting period timed out. |
| */ |
| #define k_lifo_get(lifo, timeout) \ |
| k_queue_get((struct k_queue *) lifo, timeout) |
| |
| /** |
| * @brief Statically define and initialize a lifo. |
| * |
| * The lifo can be accessed outside the module where it is defined using: |
| * |
| * @code extern struct k_lifo <name>; @endcode |
| * |
| * @param name Name of the fifo. |
| */ |
| #define K_LIFO_DEFINE(name) \ |
| struct k_lifo name \ |
| __in_section(_k_queue, static, name) = \ |
| _K_LIFO_INITIALIZER(name) |
| |
| /** |
| * @} end defgroup lifo_apis |
| */ |
| |
| /** |
| * @cond INTERNAL_HIDDEN |
| */ |
| |
| struct k_stack { |
| _wait_q_t wait_q; |
| u32_t *base, *next, *top; |
| |
| _OBJECT_TRACING_NEXT_PTR(k_stack); |
| }; |
| |
| #define _K_STACK_INITIALIZER(obj, stack_buffer, stack_num_entries) \ |
| { \ |
| .wait_q = SYS_DLIST_STATIC_INIT(&obj.wait_q), \ |
| .base = stack_buffer, \ |
| .next = stack_buffer, \ |
| .top = stack_buffer + stack_num_entries, \ |
| _OBJECT_TRACING_INIT \ |
| } |
| |
| #define K_STACK_INITIALIZER DEPRECATED_MACRO _K_STACK_INITIALIZER |
| |
| /** |
| * INTERNAL_HIDDEN @endcond |
| */ |
| |
| /** |
| * @defgroup stack_apis Stack APIs |
| * @ingroup kernel_apis |
| * @{ |
| */ |
| |
| /** |
| * @brief Initialize a stack. |
| * |
| * This routine initializes a stack object, prior to its first use. |
| * |
| * @param stack Address of the stack. |
| * @param buffer Address of array used to hold stacked values. |
| * @param num_entries Maximum number of values that can be stacked. |
| * |
| * @return N/A |
| */ |
| __syscall void k_stack_init(struct k_stack *stack, |
| u32_t *buffer, unsigned int num_entries); |
| |
| /** |
| * @brief Push an element onto a stack. |
| * |
| * This routine adds a 32-bit value @a data to @a stack. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param stack Address of the stack. |
| * @param data Value to push onto the stack. |
| * |
| * @return N/A |
| */ |
| __syscall void k_stack_push(struct k_stack *stack, u32_t data); |
| |
| /** |
| * @brief Pop an element from a stack. |
| * |
| * This routine removes a 32-bit value from @a stack in a "last in, first out" |
| * manner and stores the value in @a data. |
| * |
| * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT. |
| * |
| * @param stack Address of the stack. |
| * @param data Address of area to hold the value popped from the stack. |
| * @param timeout Waiting period to obtain a value (in milliseconds), |
| * or one of the special values K_NO_WAIT and K_FOREVER. |
| * |
| * @retval 0 Element popped from stack. |
| * @retval -EBUSY Returned without waiting. |
| * @retval -EAGAIN Waiting period timed out. |
| */ |
| __syscall int k_stack_pop(struct k_stack *stack, u32_t *data, s32_t timeout); |
| |
| /** |
| * @brief Statically define and initialize a stack |
| * |
| * The stack can be accessed outside the module where it is defined using: |
| * |
| * @code extern struct k_stack <name>; @endcode |
| * |
| * @param name Name of the stack. |
| * @param stack_num_entries Maximum number of values that can be stacked. |
| */ |
| #define K_STACK_DEFINE(name, stack_num_entries) \ |
| u32_t __noinit \ |
| _k_stack_buf_##name[stack_num_entries]; \ |
| struct k_stack name \ |
| __in_section(_k_stack, static, name) = \ |
| _K_STACK_INITIALIZER(name, _k_stack_buf_##name, \ |
| stack_num_entries) |
| |
| /** |
| * @} end defgroup stack_apis |
| */ |
| |
| struct k_work; |
| |
| /** |
| * @defgroup workqueue_apis Workqueue Thread APIs |
| * @ingroup kernel_apis |
| * @{ |
| */ |
| |
| /** |
| * @typedef k_work_handler_t |
| * @brief Work item handler function type. |
| * |
| * A work item's handler function is executed by a workqueue's thread |
| * when the work item is processed by the workqueue. |
| * |
| * @param work Address of the work item. |
| * |
| * @return N/A |
| */ |
| typedef void (*k_work_handler_t)(struct k_work *work); |
| |
| /** |
| * @cond INTERNAL_HIDDEN |
| */ |
| |
| struct k_work_q { |
| struct k_queue queue; |
| struct k_thread thread; |
| }; |
| |
| enum { |
| K_WORK_STATE_PENDING, /* Work item pending state */ |
| }; |
| |
| struct k_work { |
| void *_reserved; /* Used by k_queue implementation. */ |
| k_work_handler_t handler; |
| atomic_t flags[1]; |
| }; |
| |
| struct k_delayed_work { |
| struct k_work work; |
| struct _timeout timeout; |
| struct k_work_q *work_q; |
| }; |
| |
| extern struct k_work_q k_sys_work_q; |
| |
| /** |
| * INTERNAL_HIDDEN @endcond |
| */ |
| |
| #define _K_WORK_INITIALIZER(work_handler) \ |
| { \ |
| ._reserved = NULL, \ |
| .handler = work_handler, \ |
| .flags = { 0 } \ |
| } |
| |
| #define K_WORK_INITIALIZER DEPRECATED_MACRO _K_WORK_INITIALIZER |
| |
| /** |
| * @brief Initialize a statically-defined work item. |
| * |
| * This macro can be used to initialize a statically-defined workqueue work |
| * item, prior to its first use. For example, |
| * |
| * @code static K_WORK_DEFINE(<work>, <work_handler>); @endcode |
| * |
| * @param work Symbol name for work item object |
| * @param work_handler Function to invoke each time work item is processed. |
| */ |
| #define K_WORK_DEFINE(work, work_handler) \ |
| struct k_work work \ |
| __in_section(_k_work, static, work) = \ |
| _K_WORK_INITIALIZER(work_handler) |
| |
| /** |
| * @brief Initialize a work item. |
| * |
| * This routine initializes a workqueue work item, prior to its first use. |
| * |
| * @param work Address of work item. |
| * @param handler Function to invoke each time work item is processed. |
| * |
| * @return N/A |
| */ |
| static inline void k_work_init(struct k_work *work, k_work_handler_t handler) |
| { |
| atomic_clear_bit(work->flags, K_WORK_STATE_PENDING); |
| work->handler = handler; |
| _k_object_init(work); |
| } |
| |
| /** |
| * @brief Submit a work item. |
| * |
| * This routine submits work item @a work to be processed by workqueue |
| * @a work_q. If the work item is already pending in the workqueue's queue |
| * as a result of an earlier submission, this routine has no effect on the |
| * work item. If the work item has already been processed, or is currently |
| * being processed, its work is considered complete and the work item can be |
| * resubmitted. |
| * |
| * @warning |
| * A submitted work item must not be modified until it has been processed |
| * by the workqueue. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param work_q Address of workqueue. |
| * @param work Address of work item. |
| * |
| * @return N/A |
| */ |
| static inline void k_work_submit_to_queue(struct k_work_q *work_q, |
| struct k_work *work) |
| { |
| if (!atomic_test_and_set_bit(work->flags, K_WORK_STATE_PENDING)) { |
| k_queue_append(&work_q->queue, work); |
| } |
| } |
| |
| /** |
| * @brief Check if a work item is pending. |
| * |
| * This routine indicates if work item @a work is pending in a workqueue's |
| * queue. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param work Address of work item. |
| * |
| * @return 1 if work item is pending, or 0 if it is not pending. |
| */ |
| static inline int k_work_pending(struct k_work *work) |
| { |
| return atomic_test_bit(work->flags, K_WORK_STATE_PENDING); |
| } |
| |
| /** |
| * @brief Start a workqueue. |
| * |
| * This routine starts workqueue @a work_q. The workqueue spawns its work |
| * processing thread, which runs forever. |
| * |
| * @param work_q Address of workqueue. |
| * @param stack Pointer to work queue thread's stack space, as defined by |
| * K_THREAD_STACK_DEFINE() |
| * @param stack_size Size of the work queue thread's stack (in bytes), which |
| * should either be the same constant passed to |
| * K_THREAD_STACK_DEFINE() or the value of K_THREAD_STACK_SIZEOF(). |
| * @param prio Priority of the work queue's thread. |
| * |
| * @return N/A |
| */ |
| extern void k_work_q_start(struct k_work_q *work_q, |
| k_thread_stack_t *stack, |
| size_t stack_size, int prio); |
| |
| /** |
| * @brief Initialize a delayed work item. |
| * |
| * This routine initializes a workqueue delayed work item, prior to |
| * its first use. |
| * |
| * @param work Address of delayed work item. |
| * @param handler Function to invoke each time work item is processed. |
| * |
| * @return N/A |
| */ |
| extern void k_delayed_work_init(struct k_delayed_work *work, |
| k_work_handler_t handler); |
| |
| /** |
| * @brief Submit a delayed work item. |
| * |
| * This routine schedules work item @a work to be processed by workqueue |
| * @a work_q after a delay of @a delay milliseconds. The routine initiates |
| * an asynchronous countdown for the work item and then returns to the caller. |
| * Only when the countdown completes is the work item actually submitted to |
| * the workqueue and becomes pending. |
| * |
| * Submitting a previously submitted delayed work item that is still |
| * counting down cancels the existing submission and restarts the countdown |
| * using the new delay. If the work item is currently pending on the |
| * workqueue's queue because the countdown has completed it is too late to |
| * resubmit the item, and resubmission fails without impacting the work item. |
| * If the work item has already been processed, or is currently being processed, |
| * its work is considered complete and the work item can be resubmitted. |
| * |
| * @warning |
| * A delayed work item must not be modified until it has been processed |
| * by the workqueue. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param work_q Address of workqueue. |
| * @param work Address of delayed work item. |
| * @param delay Delay before submitting the work item (in milliseconds). |
| * |
| * @retval 0 Work item countdown started. |
| * @retval -EINPROGRESS Work item is already pending. |
| * @retval -EINVAL Work item is being processed or has completed its work. |
| * @retval -EADDRINUSE Work item is pending on a different workqueue. |
| */ |
| extern int k_delayed_work_submit_to_queue(struct k_work_q *work_q, |
| struct k_delayed_work *work, |
| s32_t delay); |
| |
| /** |
| * @brief Cancel a delayed work item. |
| * |
| * This routine cancels the submission of delayed work item @a work. |
| * A delayed work item can only be canceled while its countdown is still |
| * underway. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param work Address of delayed work item. |
| * |
| * @retval 0 Work item countdown canceled. |
| * @retval -EINPROGRESS Work item is already pending. |
| * @retval -EINVAL Work item is being processed or has completed its work. |
| */ |
| extern int k_delayed_work_cancel(struct k_delayed_work *work); |
| |
| /** |
| * @brief Submit a work item to the system workqueue. |
| * |
| * This routine submits work item @a work to be processed by the system |
| * workqueue. If the work item is already pending in the workqueue's queue |
| * as a result of an earlier submission, this routine has no effect on the |
| * work item. If the work item has already been processed, or is currently |
| * being processed, its work is considered complete and the work item can be |
| * resubmitted. |
| * |
| * @warning |
| * Work items submitted to the system workqueue should avoid using handlers |
| * that block or yield since this may prevent the system workqueue from |
| * processing other work items in a timely manner. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param work Address of work item. |
| * |
| * @return N/A |
| */ |
| static inline void k_work_submit(struct k_work *work) |
| { |
| k_work_submit_to_queue(&k_sys_work_q, work); |
| } |
| |
| /** |
| * @brief Submit a delayed work item to the system workqueue. |
| * |
| * This routine schedules work item @a work to be processed by the system |
| * workqueue after a delay of @a delay milliseconds. The routine initiates |
| * an asynchronous countdown for the work item and then returns to the caller. |
| * Only when the countdown completes is the work item actually submitted to |
| * the workqueue and becomes pending. |
| * |
| * Submitting a previously submitted delayed work item that is still |
| * counting down cancels the existing submission and restarts the countdown |
| * using the new delay. If the work item is currently pending on the |
| * workqueue's queue because the countdown has completed it is too late to |
| * resubmit the item, and resubmission fails without impacting the work item. |
| * If the work item has already been processed, or is currently being processed, |
| * its work is considered complete and the work item can be resubmitted. |
| * |
| * @warning |
| * Work items submitted to the system workqueue should avoid using handlers |
| * that block or yield since this may prevent the system workqueue from |
| * processing other work items in a timely manner. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param work Address of delayed work item. |
| * @param delay Delay before submitting the work item (in milliseconds). |
| * |
| * @retval 0 Work item countdown started. |
| * @retval -EINPROGRESS Work item is already pending. |
| * @retval -EINVAL Work item is being processed or has completed its work. |
| * @retval -EADDRINUSE Work item is pending on a different workqueue. |
| */ |
| static inline int k_delayed_work_submit(struct k_delayed_work *work, |
| s32_t delay) |
| { |
| return k_delayed_work_submit_to_queue(&k_sys_work_q, work, delay); |
| } |
| |
| /** |
| * @brief Get time remaining before a delayed work gets scheduled. |
| * |
| * This routine computes the (approximate) time remaining before a |
| * delayed work gets executed. If the delayed work is not waiting to be |
| * schedules, it returns zero. |
| * |
| * @param work Delayed work item. |
| * |
| * @return Remaining time (in milliseconds). |
| */ |
| static inline s32_t k_delayed_work_remaining_get(struct k_delayed_work *work) |
| { |
| return _timeout_remaining_get(&work->timeout); |
| } |
| |
| /** |
| * @} end defgroup workqueue_apis |
| */ |
| |
| /** |
| * @cond INTERNAL_HIDDEN |
| */ |
| |
| struct k_mutex { |
| _wait_q_t wait_q; |
| struct k_thread *owner; |
| u32_t lock_count; |
| int owner_orig_prio; |
| |
| _OBJECT_TRACING_NEXT_PTR(k_mutex); |
| }; |
| |
| #define _K_MUTEX_INITIALIZER(obj) \ |
| { \ |
| .wait_q = SYS_DLIST_STATIC_INIT(&obj.wait_q), \ |
| .owner = NULL, \ |
| .lock_count = 0, \ |
| .owner_orig_prio = K_LOWEST_THREAD_PRIO, \ |
| _OBJECT_TRACING_INIT \ |
| } |
| |
| #define K_MUTEX_INITIALIZER DEPRECATED_MACRO _K_MUTEX_INITIALIZER |
| |
| /** |
| * INTERNAL_HIDDEN @endcond |
| */ |
| |
| /** |
| * @defgroup mutex_apis Mutex APIs |
| * @ingroup kernel_apis |
| * @{ |
| */ |
| |
| /** |
| * @brief Statically define and initialize a mutex. |
| * |
| * The mutex can be accessed outside the module where it is defined using: |
| * |
| * @code extern struct k_mutex <name>; @endcode |
| * |
| * @param name Name of the mutex. |
| */ |
| #define K_MUTEX_DEFINE(name) \ |
| struct k_mutex name \ |
| __in_section(_k_mutex, static, name) = \ |
| _K_MUTEX_INITIALIZER(name) |
| |
| /** |
| * @brief Initialize a mutex. |
| * |
| * This routine initializes a mutex object, prior to its first use. |
| * |
| * Upon completion, the mutex is available and does not have an owner. |
| * |
| * @param mutex Address of the mutex. |
| * |
| * @return N/A |
| */ |
| __syscall void k_mutex_init(struct k_mutex *mutex); |
| |
| /** |
| * @brief Lock a mutex. |
| * |
| * This routine locks @a mutex. If the mutex is locked by another thread, |
| * the calling thread waits until the mutex becomes available or until |
| * a timeout occurs. |
| * |
| * A thread is permitted to lock a mutex it has already locked. The operation |
| * completes immediately and the lock count is increased by 1. |
| * |
| * @param mutex Address of the mutex. |
| * @param timeout Waiting period to lock the mutex (in milliseconds), |
| * or one of the special values K_NO_WAIT and K_FOREVER. |
| * |
| * @retval 0 Mutex locked. |
| * @retval -EBUSY Returned without waiting. |
| * @retval -EAGAIN Waiting period timed out. |
| */ |
| __syscall int k_mutex_lock(struct k_mutex *mutex, s32_t timeout); |
| |
| /** |
| * @brief Unlock a mutex. |
| * |
| * This routine unlocks @a mutex. The mutex must already be locked by the |
| * calling thread. |
| * |
| * The mutex cannot be claimed by another thread until it has been unlocked by |
| * the calling thread as many times as it was previously locked by that |
| * thread. |
| * |
| * @param mutex Address of the mutex. |
| * |
| * @return N/A |
| */ |
| __syscall void k_mutex_unlock(struct k_mutex *mutex); |
| |
| /** |
| * @} end defgroup mutex_apis |
| */ |
| |
| /** |
| * @cond INTERNAL_HIDDEN |
| */ |
| |
| struct k_sem { |
| _wait_q_t wait_q; |
| unsigned int count; |
| unsigned int limit; |
| _POLL_EVENT; |
| |
| _OBJECT_TRACING_NEXT_PTR(k_sem); |
| }; |
| |
| #define _K_SEM_INITIALIZER(obj, initial_count, count_limit) \ |
| { \ |
| .wait_q = SYS_DLIST_STATIC_INIT(&obj.wait_q), \ |
| .count = initial_count, \ |
| .limit = count_limit, \ |
| _POLL_EVENT_OBJ_INIT(obj) \ |
| _OBJECT_TRACING_INIT \ |
| } |
| |
| #define K_SEM_INITIALIZER DEPRECATED_MACRO _K_SEM_INITIALIZER |
| |
| /** |
| * INTERNAL_HIDDEN @endcond |
| */ |
| |
| /** |
| * @defgroup semaphore_apis Semaphore APIs |
| * @ingroup kernel_apis |
| * @{ |
| */ |
| |
| /** |
| * @brief Initialize a semaphore. |
| * |
| * This routine initializes a semaphore object, prior to its first use. |
| * |
| * @param sem Address of the semaphore. |
| * @param initial_count Initial semaphore count. |
| * @param limit Maximum permitted semaphore count. |
| * |
| * @return N/A |
| */ |
| __syscall void k_sem_init(struct k_sem *sem, unsigned int initial_count, |
| unsigned int limit); |
| |
| /** |
| * @brief Take a semaphore. |
| * |
| * This routine takes @a sem. |
| * |
| * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT. |
| * |
| * @param sem Address of the semaphore. |
| * @param timeout Waiting period to take the semaphore (in milliseconds), |
| * or one of the special values K_NO_WAIT and K_FOREVER. |
| * |
| * @note When porting code from the nanokernel legacy API to the new API, be |
| * careful with the return value of this function. The return value is the |
| * reverse of the one of nano_sem_take family of APIs: 0 means success, and |
| * non-zero means failure, while the nano_sem_take family returns 1 for success |
| * and 0 for failure. |
| * |
| * @retval 0 Semaphore taken. |
| * @retval -EBUSY Returned without waiting. |
| * @retval -EAGAIN Waiting period timed out. |
| */ |
| __syscall int k_sem_take(struct k_sem *sem, s32_t timeout); |
| |
| /** |
| * @brief Give a semaphore. |
| * |
| * This routine gives @a sem, unless the semaphore is already at its maximum |
| * permitted count. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param sem Address of the semaphore. |
| * |
| * @return N/A |
| */ |
| __syscall void k_sem_give(struct k_sem *sem); |
| |
| /** |
| * @brief Reset a semaphore's count to zero. |
| * |
| * This routine sets the count of @a sem to zero. |
| * |
| * @param sem Address of the semaphore. |
| * |
| * @return N/A |
| */ |
| __syscall void k_sem_reset(struct k_sem *sem); |
| |
| static inline void _impl_k_sem_reset(struct k_sem *sem) |
| { |
| sem->count = 0; |
| } |
| |
| /** |
| * @brief Get a semaphore's count. |
| * |
| * This routine returns the current count of @a sem. |
| * |
| * @param sem Address of the semaphore. |
| * |
| * @return Current semaphore count. |
| */ |
| __syscall unsigned int k_sem_count_get(struct k_sem *sem); |
| |
| static inline unsigned int _impl_k_sem_count_get(struct k_sem *sem) |
| { |
| return sem->count; |
| } |
| |
| /** |
| * @brief Statically define and initialize a semaphore. |
| * |
| * The semaphore can be accessed outside the module where it is defined using: |
| * |
| * @code extern struct k_sem <name>; @endcode |
| * |
| * @param name Name of the semaphore. |
| * @param initial_count Initial semaphore count. |
| * @param count_limit Maximum permitted semaphore count. |
| */ |
| #define K_SEM_DEFINE(name, initial_count, count_limit) \ |
| struct k_sem name \ |
| __in_section(_k_sem, static, name) = \ |
| _K_SEM_INITIALIZER(name, initial_count, count_limit) |
| |
| /** |
| * @} end defgroup semaphore_apis |
| */ |
| |
| /** |
| * @defgroup alert_apis Alert APIs |
| * @ingroup kernel_apis |
| * @{ |
| */ |
| |
| /** |
| * @typedef k_alert_handler_t |
| * @brief Alert handler function type. |
| * |
| * An alert's alert handler function is invoked by the system workqueue |
| * when the alert is signaled. The alert handler function is optional, |
| * and is only invoked if the alert has been initialized with one. |
| * |
| * @param alert Address of the alert. |
| * |
| * @return 0 if alert has been consumed; non-zero if alert should pend. |
| */ |
| typedef int (*k_alert_handler_t)(struct k_alert *alert); |
| |
| /** |
| * @} end defgroup alert_apis |
| */ |
| |
| /** |
| * @cond INTERNAL_HIDDEN |
| */ |
| |
| #define K_ALERT_DEFAULT NULL |
| #define K_ALERT_IGNORE ((void *)(-1)) |
| |
| struct k_alert { |
| k_alert_handler_t handler; |
| atomic_t send_count; |
| struct k_work work_item; |
| struct k_sem sem; |
| |
| _OBJECT_TRACING_NEXT_PTR(k_alert); |
| }; |
| |
| extern void _alert_deliver(struct k_work *work); |
| |
| #define _K_ALERT_INITIALIZER(obj, alert_handler, max_num_pending_alerts) \ |
| { \ |
| .handler = (k_alert_handler_t)alert_handler, \ |
| .send_count = ATOMIC_INIT(0), \ |
| .work_item = _K_WORK_INITIALIZER(_alert_deliver), \ |
| .sem = _K_SEM_INITIALIZER(obj.sem, 0, max_num_pending_alerts), \ |
| _OBJECT_TRACING_INIT \ |
| } |
| |
| #define K_ALERT_INITIALIZER DEPRECATED_MACRO _K_ALERT_INITIALIZER |
| |
| /** |
| * INTERNAL_HIDDEN @endcond |
| */ |
| |
| /** |
| * @addtogroup alert_apis |
| * @{ |
| */ |
| |
| /** |
| * @brief Statically define and initialize an alert. |
| * |
| * The alert can be accessed outside the module where it is defined using: |
| * |
| * @code extern struct k_alert <name>; @endcode |
| * |
| * @param name Name of the alert. |
| * @param alert_handler Action to take when alert is sent. Specify either |
| * the address of a function to be invoked by the system workqueue |
| * thread, K_ALERT_IGNORE (which causes the alert to be ignored), or |
| * K_ALERT_DEFAULT (which causes the alert to pend). |
| * @param max_num_pending_alerts Maximum number of pending alerts. |
| */ |
| #define K_ALERT_DEFINE(name, alert_handler, max_num_pending_alerts) \ |
| struct k_alert name \ |
| __in_section(_k_alert, static, name) = \ |
| _K_ALERT_INITIALIZER(name, alert_handler, \ |
| max_num_pending_alerts) |
| |
| /** |
| * @brief Initialize an alert. |
| * |
| * This routine initializes an alert object, prior to its first use. |
| * |
| * @param alert Address of the alert. |
| * @param handler Action to take when alert is sent. Specify either the address |
| * of a function to be invoked by the system workqueue thread, |
| * K_ALERT_IGNORE (which causes the alert to be ignored), or |
| * K_ALERT_DEFAULT (which causes the alert to pend). |
| * @param max_num_pending_alerts Maximum number of pending alerts. |
| * |
| * @return N/A |
| */ |
| extern void k_alert_init(struct k_alert *alert, k_alert_handler_t handler, |
| unsigned int max_num_pending_alerts); |
| |
| /** |
| * @brief Receive an alert. |
| * |
| * This routine receives a pending alert for @a alert. |
| * |
| * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT. |
| * |
| * @param alert Address of the alert. |
| * @param timeout Waiting period to receive the alert (in milliseconds), |
| * or one of the special values K_NO_WAIT and K_FOREVER. |
| * |
| * @retval 0 Alert received. |
| * @retval -EBUSY Returned without waiting. |
| * @retval -EAGAIN Waiting period timed out. |
| */ |
| __syscall int k_alert_recv(struct k_alert *alert, s32_t timeout); |
| |
| /** |
| * @brief Signal an alert. |
| * |
| * This routine signals @a alert. The action specified for @a alert will |
| * be taken, which may trigger the execution of an alert handler function |
| * and/or cause the alert to pend (assuming the alert has not reached its |
| * maximum number of pending alerts). |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param alert Address of the alert. |
| * |
| * @return N/A |
| */ |
| __syscall void k_alert_send(struct k_alert *alert); |
| |
| /** |
| * @} end addtogroup alert_apis |
| */ |
| |
| /** |
| * @cond INTERNAL_HIDDEN |
| */ |
| |
| struct k_msgq { |
| _wait_q_t wait_q; |
| size_t msg_size; |
| u32_t max_msgs; |
| char *buffer_start; |
| char *buffer_end; |
| char *read_ptr; |
| char *write_ptr; |
| u32_t used_msgs; |
| |
| _OBJECT_TRACING_NEXT_PTR(k_msgq); |
| }; |
| |
| #define _K_MSGQ_INITIALIZER(obj, q_buffer, q_msg_size, q_max_msgs) \ |
| { \ |
| .wait_q = SYS_DLIST_STATIC_INIT(&obj.wait_q), \ |
| .max_msgs = q_max_msgs, \ |
| .msg_size = q_msg_size, \ |
| .buffer_start = q_buffer, \ |
| .buffer_end = q_buffer + (q_max_msgs * q_msg_size), \ |
| .read_ptr = q_buffer, \ |
| .write_ptr = q_buffer, \ |
| .used_msgs = 0, \ |
| _OBJECT_TRACING_INIT \ |
| } |
| |
| #define K_MSGQ_INITIALIZER DEPRECATED_MACRO _K_MSGQ_INITIALIZER |
| |
| /** |
| * INTERNAL_HIDDEN @endcond |
| */ |
| |
| /** |
| * @defgroup msgq_apis Message Queue APIs |
| * @ingroup kernel_apis |
| * @{ |
| */ |
| |
| /** |
| * @brief Statically define and initialize a message queue. |
| * |
| * The message queue's ring buffer contains space for @a q_max_msgs messages, |
| * each of which is @a q_msg_size bytes long. The buffer is aligned to a |
| * @a q_align -byte boundary, which must be a power of 2. To ensure that each |
| * message is similarly aligned to this boundary, @a q_msg_size must also be |
| * a multiple of @a q_align. |
| * |
| * The message queue can be accessed outside the module where it is defined |
| * using: |
| * |
| * @code extern struct k_msgq <name>; @endcode |
| * |
| * @param q_name Name of the message queue. |
| * @param q_msg_size Message size (in bytes). |
| * @param q_max_msgs Maximum number of messages that can be queued. |
| * @param q_align Alignment of the message queue's ring buffer. |
| */ |
| #define K_MSGQ_DEFINE(q_name, q_msg_size, q_max_msgs, q_align) \ |
| static char __noinit __aligned(q_align) \ |
| _k_fifo_buf_##q_name[(q_max_msgs) * (q_msg_size)]; \ |
| struct k_msgq q_name \ |
| __in_section(_k_msgq, static, q_name) = \ |
| _K_MSGQ_INITIALIZER(q_name, _k_fifo_buf_##q_name, \ |
| q_msg_size, q_max_msgs) |
| |
| /** |
| * @brief Initialize a message queue. |
| * |
| * This routine initializes a message queue object, prior to its first use. |
| * |
| * The message queue's ring buffer must contain space for @a max_msgs messages, |
| * each of which is @a msg_size bytes long. The buffer must be aligned to an |
| * N-byte boundary, where N is a power of 2 (i.e. 1, 2, 4, ...). To ensure |
| * that each message is similarly aligned to this boundary, @a q_msg_size |
| * must also be a multiple of N. |
| * |
| * @param q Address of the message queue. |
| * @param buffer Pointer to ring buffer that holds queued messages. |
| * @param msg_size Message size (in bytes). |
| * @param max_msgs Maximum number of messages that can be queued. |
| * |
| * @return N/A |
| */ |
| __syscall void k_msgq_init(struct k_msgq *q, char *buffer, |
| size_t msg_size, u32_t max_msgs); |
| |
| /** |
| * @brief Send a message to a message queue. |
| * |
| * This routine sends a message to message queue @a q. |
| * |
| * @note Can be called by ISRs. |
| * |
| * @param q Address of the message queue. |
| * @param data Pointer to the message. |
| * @param timeout Waiting period to add the message (in milliseconds), |
| * or one of the special values K_NO_WAIT and K_FOREVER. |
| * |
| * @retval 0 Message sent. |
| * @retval -ENOMSG Returned without waiting or queue purged. |
| * @retval -EAGAIN Waiting period timed out. |
| */ |
| __syscall int k_msgq_put(struct k_msgq *q, void *data, s32_t timeout); |
| |
| /** |
| * @brief Receive a message from a message queue. |
| * |
| * This routine receives a message from message queue @a q in a "first in, |
| * first out" manner. |
| * |
| * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT. |
| * |
| * @param q Address of the message queue. |
| * @param data Address of area to hold the received message. |
| * @param timeout Waiting period to receive the message (in milliseconds), |
| * or one of the special values K_NO_WAIT and K_FOREVER. |
| * |
| * @retval 0 Message received. |
| * @retval -ENOMSG Returned without waiting. |
| * @retval -EAGAIN Waiting period timed out. |
| */ |
| __syscall int k_msgq_get(struct k_msgq *q, void *data, s32_t timeout); |
| |
| /** |
| * @brief Purge a message queue. |
| * |
| * This routine discards all unreceived messages in a message queue's ring |
| * buffer. Any threads that are blocked waiting to send a message to the |
| * message queue are unblocked and see an -ENOMSG error code. |
| * |
| * @param q Address of the message queue. |
| * |
| * @return N/A |
| */ |
| __syscall void k_msgq_purge(struct k_msgq *q); |
| |
| /** |
| * @brief Get the amount of free space in a message queue. |
| * |
| * This routine returns the number of unused entries in a message queue's |
| * ring buffer. |
| * |
| * @param q Address of the message queue. |
| * |
| * @return Number of unused ring buffer entries. |
| */ |
| __syscall u32_t k_msgq_num_free_get(struct k_msgq *q); |
| |
| static inline u32_t _impl_k_msgq_num_free_get(struct k_msgq *q) |
| { |
| return q->max_msgs - q->used_msgs; |
| } |
| |
| /** |
| * @brief Get the number of messages in a message queue. |
| * |
| * This routine returns the number of messages in a message queue's ring buffer. |
| * |
| * @param q Address of the message queue. |
| * |
| * @return Number of messages. |
| */ |
| __syscall u32_t k_msgq_num_used_get(struct k_msgq *q); |
| |
| static inline u32_t _impl_k_msgq_num_used_get(struct k_msgq *q) |
| { |
| return q->used_msgs; |
| } |
| |
| /** |
| * @} end defgroup msgq_apis |
| */ |
| |
| /** |
| * @defgroup mem_pool_apis Memory Pool APIs |
| * @ingroup kernel_apis |
| * @{ |
| */ |
| |
| /* Note on sizing: the use of a 20 bit field for block means that, |
| * assuming a reasonable minimum block size of 16 bytes, we're limited |
| * to 16M of memory managed by a single pool. Long term it would be |
| * good to move to a variable bit size based on configuration. |
| */ |
| struct k_mem_block_id { |
| u32_t pool : 8; |
| u32_t level : 4; |
| u32_t block : 20; |
| }; |
| |
| struct k_mem_block { |
| void *data; |
| struct k_mem_block_id id; |
| }; |
| |
| /** |
| * @} end defgroup mem_pool_apis |
| */ |
| |
| /** |
| * @defgroup mailbox_apis Mailbox APIs |
| * @ingroup kernel_apis |
| * @{ |
| */ |
| |
| struct k_mbox_msg { |
| /** internal use only - needed for legacy API support */ |
| u32_t _mailbox; |
| /** size of message (in bytes) */ |
| size_t size; |
| /** application-defined information value */ |
| u32_t info; |
| /** sender's message data buffer */ |
| void *tx_data; |
| /** internal use only - needed for legacy API support */ |
| void *_rx_data; |
| /** message data block descriptor */ |
| struct k_mem_block tx_block; |
| /** source thread id */ |
| k_tid_t rx_source_thread; |
| /** target thread id */ |
| k_tid_t tx_target_thread; |
| /** internal use only - thread waiting on send (may be a dummy) */ |
| k_tid_t _syncing_thread; |
| #if (CONFIG_NUM_MBOX_ASYNC_MSGS > 0) |
| /** internal use only - semaphore used during asynchronous send */ |
| struct k_sem *_async_sem; |
| #endif |
| }; |
| |
| /** |
| * @cond INTERNAL_HIDDEN |
| */ |
| |
| struct k_mbox { |
| _wait_q_t tx_msg_queue; |
| _wait_q_t rx_msg_queue; |
| |
| _OBJECT_TRACING_NEXT_PTR(k_mbox); |
| }; |
| |
| #define _K_MBOX_INITIALIZER(obj) \ |
| { \ |
| .tx_msg_queue = SYS_DLIST_STATIC_INIT(&obj.tx_msg_queue), \ |
| .rx_msg_queue = SYS_DLIST_STATIC_INIT(&obj.rx_msg_queue), \ |
| _OBJECT_TRACING_INIT \ |
| } |
| |
| #define K_MBOX_INITIALIZER DEPRECATED_MACRO _K_MBOX_INITIALIZER |
| |
| /** |
| * INTERNAL_HIDDEN @endcond |
| */ |
| |
| /** |
| * @brief Statically define and initialize a mailbox. |
| * |
| * The mailbox is to be accessed outside the module where it is defined using: |
| * |
| * @code extern struct k_mbox <name>; @endcode |
| * |
| * @param name Name of the mailbox. |
| */ |
| #define K_MBOX_DEFINE(name) \ |
| struct k_mbox name \ |
| __in_section(_k_mbox, static, name) = \ |
| _K_MBOX_INITIALIZER(name) \ |
| |
| /** |
| * @brief Initialize a mailbox. |
| * |
| * This routine initializes a mailbox object, prior to its first use. |
| * |
| * @param mbox Address of the mailbox. |
| * |
| * @return N/A |
| */ |
| extern void k_mbox_init(struct k_mbox *mbox); |
| |
| /** |
| * @brief Send a mailbox message in a synchronous manner. |
| * |
| * This routine sends a message to @a mbox and waits for a receiver to both |
| * receive and process it. The message data may be in a buffer, in a memory |
| * pool block, or non-existent (i.e. an empty message). |
| * |
| * @param mbox Address of the mailbox. |
| * @param tx_msg Address of the transmit message descriptor. |
| * @param timeout Waiting period for the message to be received (in |
| * milliseconds), or one of the special values K_NO_WAIT |
| * and K_FOREVER. Once the message has been received, |
| * this routine waits as long as necessary for the message |
| * to be completely processed. |
| * |
| * @retval 0 Message sent. |
| * @retval -ENOMSG Returned without waiting. |
| * @retval -EAGAIN Waiting period timed out. |
| */ |
| extern int k_mbox_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg, |
| s32_t timeout); |
| |
| /** |
| * @brief Send a mailbox message in an asynchronous manner. |
| * |
| * This routine sends a message to @a mbox without waiting for a receiver |
| * to process it. The message data may be in a buffer, in a memory pool block, |
| * or non-existent (i.e. an empty message). Optionally, the semaphore @a sem |
| * will be given when the message has been both received and completely |
| * processed by the receiver. |
| * |
| * @param mbox Address of the mailbox. |
| * @param tx_msg Address of the transmit message descriptor. |
| * @param sem Address of a semaphore, or NULL if none is needed. |
| * |
| * @return N/A |
| */ |
| extern void k_mbox_async_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg, |
| struct k_sem *sem); |
| |
| /** |
| * @brief Receive a mailbox message. |
| * |
| * This routine receives a message from @a mbox, then optionally retrieves |
| * its data and disposes of the message. |
| * |
| * @param mbox Address of the mailbox. |
| * @param rx_msg Address of the receive message descriptor. |
| * @param buffer Address of the buffer to receive data, or NULL to defer data |
| * retrieval and message disposal until later. |
| * @param timeout Waiting period for a message to be received (in |
| * milliseconds), or one of the special values K_NO_WAIT |
| * and K_FOREVER. |
| * |
| * @retval 0 Message received. |
| * @retval -ENOMSG Returned without waiting. |
| * @retval -EAGAIN Waiting period timed out. |
| */ |
| extern int k_mbox_get(struct k_mbox *mbox, struct k_mbox_msg *rx_msg, |
| void *buffer, s32_t timeout); |
| |
| /** |
| * @brief Retrieve mailbox message data into a buffer. |
| * |
| * This routine completes the processing of a received message by retrieving |
| * its data into a buffer, then disposing of the message. |
| * |
| * Alternatively, this routine can be used to dispose of a received message |
| * without retrieving its data. |
| * |
| * @param rx_msg Address of the receive message descriptor. |
| * @param buffer Address of the buffer to receive data, or NULL to discard |
| * the data. |
| * |
| * @return N/A |
| */ |
| extern void k_mbox_data_get(struct k_mbox_msg *rx_msg, void *buffer); |
| |
| /** |
| * @brief Retrieve mailbox message data into a memory pool block. |
| * |
| * This routine completes the processing of a received message by retrieving |
| * its data into a memory pool block, then disposing of the message. |
| * The memory pool block that results from successful retrieval must be |
| * returned to the pool once the data has been processed, even in cases |
| * where zero bytes of data are retrieved. |
| * |
| * Alternatively, this routine can be used to dispose of a received message |
| * without retrieving its data. In this case there is no need to return a |
| * memory pool block to the pool. |
| * |
| * This routine allocates a new memory pool block for the data only if the |
| * data is not already in one. If a new block cannot be allocated, the routine |
| * returns a failure code and the received message is left unchanged. This |
| * permits the caller to reattempt data retrieval at a later time or to dispose |
| * of the received message without retrieving its data. |
| * |
| * @param rx_msg Address of a receive message descriptor. |
| * @param pool Address of memory pool, or NULL to discard data. |
| * @param block Address of the area to hold memory pool block info. |
| * @param timeout Waiting period to wait for a memory pool block (in |
| * milliseconds), or one of the special values K_NO_WAIT |
| * and K_FOREVER. |
| * |
| * @retval 0 Data retrieved. |
| * @retval -ENOMEM Returned without waiting. |
| * @retval -EAGAIN Waiting period timed out. |
| */ |
| extern int k_mbox_data_block_get(struct k_mbox_msg *rx_msg, |
| struct k_mem_pool *pool, |
| struct k_mem_block *block, s32_t timeout); |
| |
| /** |
| * @} end defgroup mailbox_apis |
| */ |
| |
| /** |
| * @cond INTERNAL_HIDDEN |
| */ |
| |
| struct k_pipe { |
| unsigned char *buffer; /* Pipe buffer: may be NULL */ |
| size_t size; /* Buffer size */ |
| size_t bytes_used; /* # bytes used in buffer */ |
| size_t read_index; /* Where in buffer to read from */ |
| size_t write_index; /* Where in buffer to write */ |
| |
| struct { |
| _wait_q_t readers; /* Reader wait queue */ |
| _wait_q_t writers; /* Writer wait queue */ |
| } wait_q; |
| |
| _OBJECT_TRACING_NEXT_PTR(k_pipe); |
| }; |
| |
| #define _K_PIPE_INITIALIZER(obj, pipe_buffer, pipe_buffer_size) \ |
| { \ |
| .buffer = pipe_buffer, \ |
| .size = pipe_buffer_size, \ |
| .bytes_used = 0, \ |
| .read_index = 0, \ |
| .write_index = 0, \ |
| .wait_q.writers = SYS_DLIST_STATIC_INIT(&obj.wait_q.writers), \ |
| .wait_q.readers = SYS_DLIST_STATIC_INIT(&obj.wait_q.readers), \ |
| _OBJECT_TRACING_INIT \ |
| } |
| |
| #define K_PIPE_INITIALIZER DEPRECATED_MACRO _K_PIPE_INITIALIZER |
| |
| /** |
| * INTERNAL_HIDDEN @endcond |
| */ |
| |
| /** |
| * @defgroup pipe_apis Pipe APIs |
| * @ingroup kernel_apis |
| * @{ |
| */ |
| |
| /** |
| * @brief Statically define and initialize a pipe. |
| * |
| * The pipe can be accessed outside the module where it is defined using: |
| * |
| * @code extern struct k_pipe <name>; @endcode |
| * |
| * @param name Name of the pipe. |
| * @param pipe_buffer_size Size of the pipe's ring buffer (in bytes), |
| * or zero if no ring buffer is used. |
| * @param pipe_align Alignment of the pipe's ring buffer (power of 2). |
| */ |
| #define K_PIPE_DEFINE(name, pipe_buffer_size, pipe_align) \ |
| static unsigned char __noinit __aligned(pipe_align) \ |
| _k_pipe_buf_##name[pipe_buffer_size]; \ |
| struct k_pipe name \ |
| __in_section(_k_pipe, static, name) = \ |
| _K_PIPE_INITIALIZER(name, _k_pipe_buf_##name, pipe_buffer_size) |
| |
| /** |
| * @brief Initialize a pipe. |
| * |
| * This routine initializes a pipe object, prior to its first use. |
| * |
| * @param pipe Address of the pipe. |
| * @param buffer Address of the pipe's ring buffer, or NULL if no ring buffer |
| * is used. |
| * @param size Size of the pipe's ring buffer (in bytes), or zero if no ring |
| * buffer is used. |
| * |
| * @return N/A |
| */ |
| __syscall void k_pipe_init(struct k_pipe *pipe, unsigned char *buffer, |
| size_t size); |
| |
| /** |
| * @brief Write data to a pipe. |
| * |
| * This routine writes up to @a bytes_to_write bytes of data to @a pipe. |
| * |
| * @param pipe Address of the pipe. |
| * @param data Address of data to write. |
| * @param bytes_to_write Size of data (in bytes). |
| * @param bytes_written Address of area to hold the number of bytes written. |
| * @param min_xfer Minimum number of bytes to write. |
| * @param timeout Waiting period to wait for the data to be written (in |
| * milliseconds), or one of the special values K_NO_WAIT |
| * and K_FOREVER. |
| * |
| * @retval 0 At least @a min_xfer bytes of data were written. |
| * @retval -EIO Returned without waiting; zero data bytes were written. |
| * @retval -EAGAIN Waiting period timed out; between zero and @a min_xfer |
| * minus one data bytes were written. |
| */ |
| __syscall int k_pipe_put(struct k_pipe *pipe, void *data, |
| size_t bytes_to_write, size_t *bytes_written, |
| size_t min_xfer, s32_t timeout); |
| |
| /** |
| * @brief Read data from a pipe. |
| * |
| * This routine reads up to @a bytes_to_read bytes of data from @a pipe. |
| * |
| * @param pipe Address of the pipe. |
| * @param data Address to place the data read from pipe. |
| * @param bytes_to_read Maximum number of data bytes to read. |
| * @param bytes_read Address of area to hold the number of bytes read. |
| * @param min_xfer Minimum number of data bytes to read. |
| * @param timeout Waiting period to wait for the data to be read (in |
| * milliseconds), or one of the special values K_NO_WAIT |
| * and K_FOREVER. |
| * |
| * @retval 0 At least @a min_xfer bytes of data were read. |
| * @retval -EIO Returned without waiting; zero data bytes were read. |
| * @retval -EAGAIN Waiting period timed out; between zero and @a min_xfer |
| * minus one data bytes were read. |
| */ |
| __syscall int k_pipe_get(struct k_pipe *pipe, void *data, |
| size_t bytes_to_read, size_t *bytes_read, |
| size_t min_xfer, s32_t timeout); |
| |
| /** |
| * @brief Write memory block to a pipe. |
| * |
| * This routine writes the data contained in a memory block to @a pipe. |
| * Once all of the data in the block has been written to the pipe, it will |
| * free the memory block @a block and give the semaphore @a sem (if specified). |
| * |
| * @param pipe Address of the pipe. |
| * @param block Memory block containing data to send |
| * @param size Number of data bytes in memory block to send |
| * @param sem Semaphore to signal upon completion (else NULL) |
| * |
| * @return N/A |
| */ |
| extern void k_pipe_block_put(struct k_pipe *pipe, struct k_mem_block *block, |
| size_t size, struct k_sem *sem); |
| |
| /** |
| * @} end defgroup pipe_apis |
| */ |
| |
| /** |
| * @cond INTERNAL_HIDDEN |
| */ |
| |
| struct k_mem_slab { |
| _wait_q_t wait_q; |
| u32_t num_blocks; |
| size_t block_size; |
| char *buffer; |
| char *free_list; |
| u32_t num_used; |
| |
| _OBJECT_TRACING_NEXT_PTR(k_mem_slab); |
| }; |
| |
| #define _K_MEM_SLAB_INITIALIZER(obj, slab_buffer, slab_block_size, \ |
| slab_num_blocks) \ |
| { \ |
| .wait_q = SYS_DLIST_STATIC_INIT(&obj.wait_q), \ |
| .num_blocks = slab_num_blocks, \ |
| .block_size = slab_block_size, \ |
| .buffer = slab_buffer, \ |
| .free_list = NULL, \ |
| .num_used = 0, \ |
| _OBJECT_TRACING_INIT \ |
| } |
| |
| #define K_MEM_SLAB_INITIALIZER DEPRECATED_MACRO _K_MEM_SLAB_INITIALIZER |
| |
| |
| /** |
| * INTERNAL_HIDDEN @endcond |
| */ |
| |
| /** |
| * @defgroup mem_slab_apis Memory Slab APIs |
| * @ingroup kernel_apis |
| * @{ |
| */ |
| |
| /** |
| * @brief Statically define and initialize a memory slab. |
| * |
| * The memory slab's buffer contains @a slab_num_blocks memory blocks |
| * that are @a slab_block_size bytes long. The buffer is aligned to a |
| * @a slab_align -byte boundary. To ensure that each memory block is similarly |
| * aligned to this boundary, @a slab_block_size must also be a multiple of |
| * @a slab_align. |
| * |
| * The memory slab can be accessed outside the module where it is defined |
| * using: |
| * |
| * @code extern struct k_mem_slab <name>; @endcode |
| * |
| * @param name Name of the memory slab. |
| * @param slab_block_size Size of each memory block (in bytes). |
| * @param slab_num_blocks Number memory blocks. |
| * @param slab_align Alignment of the memory slab's buffer (power of 2). |
| */ |
| #define K_MEM_SLAB_DEFINE(name, slab_block_size, slab_num_blocks, slab_align) \ |
| char __noinit __aligned(slab_align) \ |
| _k_mem_slab_buf_##name[(slab_num_blocks) * (slab_block_size)]; \ |
| struct k_mem_slab name \ |
| __in_section(_k_mem_slab, static, name) = \ |
| _K_MEM_SLAB_INITIALIZER(name, _k_mem_slab_buf_##name, \ |
| slab_block_size, slab_num_blocks) |
| |
| /** |
| * @brief Initialize a memory slab. |
| * |
| * Initializes a memory slab, prior to its first use. |
| * |
| * The memory slab's buffer contains @a slab_num_blocks memory blocks |
| * that are @a slab_block_size bytes long. The buffer must be aligned to an |
| * N-byte boundary, where N is a power of 2 larger than 2 (i.e. 4, 8, 16, ...). |
| * To ensure that each memory block is similarly aligned to this boundary, |
| * @a slab_block_size must also be a multiple of N. |
| * |
| * @param slab Address of the memory slab. |
| * @param buffer Pointer to buffer used for the memory blocks. |
| * @param block_size Size of each memory block (in bytes). |
| * @param num_blocks Number of memory blocks. |
| * |
| * @return N/A |
| */ |
| extern void k_mem_slab_init(struct k_mem_slab *slab, void *buffer, |
| size_t block_size, u32_t num_blocks); |
| |
| /** |
| * @brief Allocate memory from a memory slab. |
| * |
| * This routine allocates a memory block from a memory slab. |
| * |
| * @param slab Address of the memory slab. |
| * @param mem Pointer to block address area. |
| * @param timeout Maximum time to wait for operation to complete |
| * (in milliseconds). Use K_NO_WAIT to return without waiting, |
| * or K_FOREVER to wait as long as necessary. |
| * |
| * @retval 0 Memory allocated. The block address area pointed at by @a mem |
| * is set to the starting address of the memory block. |
| * @retval -ENOMEM Returned without waiting. |
| * @retval -EAGAIN Waiting period timed out. |
| */ |
| extern int k_mem_slab_alloc(struct k_mem_slab *slab, void **mem, |
| s32_t timeout); |
| |
| /** |
| * @brief Free memory allocated from a memory slab. |
| * |
| * This routine releases a previously allocated memory block back to its |
| * associated memory slab. |
| * |
| * @param slab Address of the memory slab. |
| * @param mem Pointer to block address area (as set by k_mem_slab_alloc()). |
| * |
| * @return N/A |
| */ |
| extern void k_mem_slab_free(struct k_mem_slab *slab, void **mem); |
| |
| /** |
| * @brief Get the number of used blocks in a memory slab. |
| * |
| * This routine gets the number of memory blocks that are currently |
| * allocated in @a slab. |
| * |
| * @param slab Address of the memory slab. |
| * |
| * @return Number of allocated memory blocks. |
| */ |
| static inline u32_t k_mem_slab_num_used_get(struct k_mem_slab *slab) |
| { |
| return slab->num_used; |
| } |
| |
| /** |
| * @brief Get the number of unused blocks in a memory slab. |
| * |
| * This routine gets the number of memory blocks that are currently |
| * unallocated in @a slab. |
| * |
| * @param slab Address of the memory slab. |
| * |
| * @return Number of unallocated memory blocks. |
| */ |
| static inline u32_t k_mem_slab_num_free_get(struct k_mem_slab *slab) |
| { |
| return slab->num_blocks - slab->num_used; |
| } |
| |
| /** |
| * @} end defgroup mem_slab_apis |
| */ |
| |
| /** |
| * @cond INTERNAL_HIDDEN |
| */ |
| |
| struct k_mem_pool_lvl { |
| union { |
| u32_t *bits_p; |
| u32_t bits; |
| }; |
| sys_dlist_t free_list; |
| }; |
| |
| struct k_mem_pool { |
| void *buf; |
| size_t max_sz; |
| u16_t n_max; |
| u8_t n_levels; |
| u8_t max_inline_level; |
| struct k_mem_pool_lvl *levels; |
| _wait_q_t wait_q; |
| }; |
| |
| #define _ALIGN4(n) ((((n)+3)/4)*4) |
| |
| #define _MPOOL_HAVE_LVL(max, min, l) (((max) >> (2*(l))) >= (min) ? 1 : 0) |
| |
| #define __MPOOL_LVLS(maxsz, minsz) \ |
| (_MPOOL_HAVE_LVL((maxsz), (minsz), 0) + \ |
| _MPOOL_HAVE_LVL((maxsz), (minsz), 1) + \ |
| _MPOOL_HAVE_LVL((maxsz), (minsz), 2) + \ |
| _MPOOL_HAVE_LVL((maxsz), (minsz), 3) + \ |
| _MPOOL_HAVE_LVL((maxsz), (minsz), 4) + \ |
| _MPOOL_HAVE_LVL((maxsz), (minsz), 5) + \ |
| _MPOOL_HAVE_LVL((maxsz), (minsz), 6) + \ |
| _MPOOL_HAVE_LVL((maxsz), (minsz), 7) + \ |
| _MPOOL_HAVE_LVL((maxsz), (minsz), 8) + \ |
| _MPOOL_HAVE_LVL((maxsz), (minsz), 9) + \ |
| _MPOOL_HAVE_LVL((maxsz), (minsz), 10) + \ |
| _MPOOL_HAVE_LVL((maxsz), (minsz), 11) + \ |
| _MPOOL_HAVE_LVL((maxsz), (minsz), 12) + \ |
| _MPOOL_HAVE_LVL((maxsz), (minsz), 13) + \ |
| _MPOOL_HAVE_LVL((maxsz), (minsz), 14) + \ |
| _MPOOL_HAVE_LVL((maxsz), (minsz), 15)) |
| |
| #define _MPOOL_MINBLK sizeof(sys_dnode_t) |
| |
| #define _MPOOL_LVLS(max, min) \ |
| __MPOOL_LVLS((max), (min) >= _MPOOL_MINBLK ? (min) : _MPOOL_MINBLK) |
| |
| /* Rounds the needed bits up to integer multiples of u32_t */ |
| #define _MPOOL_LBIT_WORDS_UNCLAMPED(n_max, l) \ |
| ((((n_max) << (2*(l))) + 31) / 32) |
| |
| /* One word gets stored free unioned with the pointer, otherwise the |
| * calculated unclamped value |
| */ |
| #define _MPOOL_LBIT_WORDS(n_max, l) \ |
| (_MPOOL_LBIT_WORDS_UNCLAMPED(n_max, l) < 2 ? 0 \ |
| : _MPOOL_LBIT_WORDS_UNCLAMPED(n_max, l)) |
| |
| /* How many bytes for the bitfields of a single level? */ |
| #define _MPOOL_LBIT_BYTES(maxsz, minsz, l, n_max) \ |
| (_MPOOL_LVLS((maxsz), (minsz)) >= (l) ? \ |
| 4 * _MPOOL_LBIT_WORDS((n_max), l) : 0) |
| |
| /* Size of the bitmap array that follows the buffer in allocated memory */ |
| #define _MPOOL_BITS_SIZE(maxsz, minsz, n_max) \ |
| (_MPOOL_LBIT_BYTES(maxsz, minsz, 0, n_max) + \ |
| _MPOOL_LBIT_BYTES(maxsz, minsz, 1, n_max) + \ |
| _MPOOL_LBIT_BYTES(maxsz, minsz, 2, n_max) + \ |
| _MPOOL_LBIT_BYTES(maxsz, minsz, 3, n_max) + \ |
| _MPOOL_LBIT_BYTES(maxsz, minsz, 4, n_max) + \ |
| _MPOOL_LBIT_BYTES(maxsz, minsz, 5, n_max) + \ |
| _MPOOL_LBIT_BYTES(maxsz, minsz, 6, n_max) + \ |
| _MPOOL_LBIT_BYTES(maxsz, minsz, 7, n_max) + \ |
| _MPOOL_LBIT_BYTES(maxsz, minsz, 8, n_max) + \ |
| _MPOOL_LBIT_BYTES(maxsz, minsz, 9, n_max) + \ |
| _MPOOL_LBIT_BYTES(maxsz, minsz, 10, n_max) + \ |
| _MPOOL_LBIT_BYTES(maxsz, minsz, 11, n_max) + \ |
| _MPOOL_LBIT_BYTES(maxsz, minsz, 12, n_max) + \ |
| _MPOOL_LBIT_BYTES(maxsz, minsz, 13, n_max) + \ |
| _MPOOL_LBIT_BYTES(maxsz, minsz, 14, n_max) + \ |
| _MPOOL_LBIT_BYTES(maxsz, minsz, 15, n_max)) |
| |
| /** |
| * INTERNAL_HIDDEN @endcond |
| */ |
| |
| /** |
| * @addtogroup mem_pool_apis |
| * @{ |
| */ |
| |
| /** |
| * @brief Statically define and initialize a memory pool. |
| * |
| * The memory pool's buffer contains @a n_max blocks that are @a max_size bytes |
| * long. The memory pool allows blocks to be repeatedly partitioned into |
| * quarters, down to blocks of @a min_size bytes long. The buffer is aligned |
| * to a @a align -byte boundary. |
| * |
| * If the pool is to be accessed outside the module where it is defined, it |
| * can be declared via |
| * |
| * @code extern struct k_mem_pool <name>; @endcode |
| * |
| * @param name Name of the memory pool. |
| * @param minsz Size of the smallest blocks in the pool (in bytes). |
| * @param maxsz Size of the largest blocks in the pool (in bytes). |
| * @param nmax Number of maximum sized blocks in the pool. |
| * @param align Alignment of the pool's buffer (power of 2). |
| */ |
| #define K_MEM_POOL_DEFINE(name, minsz, maxsz, nmax, align) \ |
| char __aligned(align) _mpool_buf_##name[_ALIGN4(maxsz * nmax) \ |
| + _MPOOL_BITS_SIZE(maxsz, minsz, nmax)]; \ |
| struct k_mem_pool_lvl _mpool_lvls_##name[_MPOOL_LVLS(maxsz, minsz)]; \ |
| struct k_mem_pool name __in_section(_k_mem_pool, static, name) = { \ |
| .buf = _mpool_buf_##name, \ |
| .max_sz = maxsz, \ |
| .n_max = nmax, \ |
| .n_levels = _MPOOL_LVLS(maxsz, minsz), \ |
| .levels = _mpool_lvls_##name, \ |
| } |
| |
| /** |
| * @brief Allocate memory from a memory pool. |
| * |
| * This routine allocates a memory block from a memory pool. |
| * |
| * @param pool Address of the memory pool. |
| * @param block Pointer to block descriptor for the allocated memory. |
| * @param size Amount of memory to allocate (in bytes). |
| * @param timeout Maximum time to wait for operation to complete |
| * (in milliseconds). Use K_NO_WAIT to return without waiting, |
| * or K_FOREVER to wait as long as necessary. |
| * |
| * @retval 0 Memory allocated. The @a data field of the block descriptor |
| * is set to the starting address of the memory block. |
| * @retval -ENOMEM Returned without waiting. |
| * @retval -EAGAIN Waiting period timed out. |
| */ |
| extern int k_mem_pool_alloc(struct k_mem_pool *pool, struct k_mem_block *block, |
| size_t size, s32_t timeout); |
| |
| /** |
| * @brief Free memory allocated from a memory pool. |
| * |
| * This routine releases a previously allocated memory block back to its |
| * memory pool. |
| * |
| * @param block Pointer to block descriptor for the allocated memory. |
| * |
| * @return N/A |
| */ |
| extern void k_mem_pool_free(struct k_mem_block *block); |
| |
| /** |
| * @} end addtogroup mem_pool_apis |
| */ |
| |
| /** |
| * @defgroup heap_apis Heap Memory Pool APIs |
| * @ingroup kernel_apis |
| * @{ |
| */ |
| |
| /** |
| * @brief Allocate memory from heap. |
| * |
| * This routine provides traditional malloc() semantics. Memory is |
| * allocated from the heap memory pool. |
| * |
| * @param size Amount of memory requested (in bytes). |
| * |
| * @return Address of the allocated memory if successful; otherwise NULL. |
| */ |
| extern void *k_malloc(size_t size); |
| |
| /** |
| * @brief Free memory allocated from heap. |
| * |
| * This routine provides traditional free() semantics. The memory being |
| * returned must have been allocated from the heap memory pool. |
| * |
| * If @a ptr is NULL, no operation is performed. |
| * |
| * @param ptr Pointer to previously allocated memory. |
| * |
| * @return N/A |
| */ |
| extern void k_free(void *ptr); |
| |
| /** |
| * @brief Allocate memory from heap, array style |
| * |
| * This routine provides traditional calloc() semantics. Memory is |
| * allocated from the heap memory pool and zeroed. |
| * |
| * @param nmemb Number of elements in the requested array |
| * @param size Size of each array element (in bytes). |
| * |
| * @return Address of the allocated memory if successful; otherwise NULL. |
| */ |
| extern void *k_calloc(size_t nmemb, size_t size); |
| |
| /** |
| * @} end defgroup heap_apis |
| */ |
| |
| /* polling API - PRIVATE */ |
| |
| #ifdef CONFIG_POLL |
| #define _INIT_OBJ_POLL_EVENT(obj) do { (obj)->poll_event = NULL; } while ((0)) |
| #else |
| #define _INIT_OBJ_POLL_EVENT(obj) do { } while ((0)) |
| #endif |
| |
| /* private - implementation data created as needed, per-type */ |
| struct _poller { |
| struct k_thread *thread; |
| }; |
| |
| /* private - types bit positions */ |
| enum _poll_types_bits { |
| /* can be used to ignore an event */ |
| _POLL_TYPE_IGNORE, |
| |
| /* to be signaled by k_poll_signal() */ |
| _POLL_TYPE_SIGNAL, |
| |
| /* semaphore availability */ |
| _POLL_TYPE_SEM_AVAILABLE, |
| |
| /* queue/fifo/lifo data availability */ |
| _POLL_TYPE_DATA_AVAILABLE, |
| |
| _POLL_NUM_TYPES |
| }; |
| |
| #define _POLL_TYPE_BIT(type) (1 << ((type) - 1)) |
| |
| /* private - states bit positions */ |
| enum _poll_states_bits { |
| /* default state when creating event */ |
| _POLL_STATE_NOT_READY, |
| |
| /* signaled by k_poll_signal() */ |
| _POLL_STATE_SIGNALED, |
| |
| /* semaphore is available */ |
| _POLL_STATE_SEM_AVAILABLE, |
| |
| /* data is available to read on queue/fifo/lifo */ |
| _POLL_STATE_DATA_AVAILABLE, |
| |
| _POLL_NUM_STATES |
| }; |
| |
| #define _POLL_STATE_BIT(state) (1 << ((state) - 1)) |
| |
| #define _POLL_EVENT_NUM_UNUSED_BITS \ |
| (32 - (0 \ |
| + 8 /* tag */ \ |
| + _POLL_NUM_TYPES \ |
| + _POLL_NUM_STATES \ |
| + 1 /* modes */ \ |
| )) |
| |
| /* end of polling API - PRIVATE */ |
| |
| |
| /** |
| * @defgroup poll_apis Async polling APIs |
| * @ingroup kernel_apis |
| * @{ |
| */ |
| |
| /* Public polling API */ |
| |
| /* public - values for k_poll_event.type bitfield */ |
| #define K_POLL_TYPE_IGNORE 0 |
| #define K_POLL_TYPE_SIGNAL _POLL_TYPE_BIT(_POLL_TYPE_SIGNAL) |
| #define K_POLL_TYPE_SEM_AVAILABLE _POLL_TYPE_BIT(_POLL_TYPE_SEM_AVAILABLE) |
| #define K_POLL_TYPE_DATA_AVAILABLE _POLL_TYPE_BIT(_POLL_TYPE_DATA_AVAILABLE) |
| #define K_POLL_TYPE_FIFO_DATA_AVAILABLE K_POLL_TYPE_DATA_AVAILABLE |
| |
| /* public - polling modes */ |
| enum k_poll_modes { |
| /* polling thread does not take ownership of objects when available */ |
| K_POLL_MODE_NOTIFY_ONLY = 0, |
| |
| K_POLL_NUM_MODES |
| }; |
| |
| /* public - values for k_poll_event.state bitfield */ |
| #define K_POLL_STATE_NOT_READY 0 |
| #define K_POLL_STATE_SIGNALED _POLL_STATE_BIT(_POLL_STATE_SIGNALED) |
| #define K_POLL_STATE_SEM_AVAILABLE _POLL_STATE_BIT(_POLL_STATE_SEM_AVAILABLE) |
| #define K_POLL_STATE_DATA_AVAILABLE _POLL_STATE_BIT(_POLL_STATE_DATA_AVAILABLE) |
| #define K_POLL_STATE_FIFO_DATA_AVAILABLE K_POLL_STATE_DATA_AVAILABLE |
| |
| /* public - poll signal object */ |
| struct k_poll_signal { |
| /* PRIVATE - DO NOT TOUCH */ |
| sys_dlist_t poll_events; |
| |
| /* |
| * 1 if the event has been signaled, 0 otherwise. Stays set to 1 until |
| * user resets it to 0. |
| */ |
| unsigned int signaled; |
| |
| /* custom result value passed to k_poll_signal() if needed */ |
| int result; |
| }; |
| |
| #define K_POLL_SIGNAL_INITIALIZER(obj) \ |
| { \ |
| .poll_events = SYS_DLIST_STATIC_INIT(&obj.poll_events), \ |
| .signaled = 0, \ |
| .result = 0, \ |
| } |
| |
| |