/* * Copyright (c) 2016, Wind River Systems, Inc. * * SPDX-License-Identifier: Apache-2.0 */ /** * @file * * @brief Public kernel APIs. */ #ifndef ZEPHYR_INCLUDE_KERNEL_H_ #define ZEPHYR_INCLUDE_KERNEL_H_ #if !defined(_ASMLANGUAGE) #include #include #include #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) #ifdef CONFIG_WAITQ_SCALABLE typedef struct { struct _priq_rb waitq; } _wait_q_t; extern bool _priq_rb_lessthan(struct rbnode *a, struct rbnode *b); #define _WAIT_Q_INIT(wait_q) { { { .lessthan_fn = _priq_rb_lessthan } } } #else typedef struct { sys_dlist_t waitq; } _wait_q_t; #define _WAIT_Q_INIT(wait_q) { SYS_DLIST_STATIC_INIT(&(wait_q)->waitq) } #endif #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_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, /** @cond * Doxygen should ignore this build-time generated include file * when genrating API documentation. Enumeration values are * generated during build by gen_kobject_list.py. It includes * basic kernel objects (e.g. pipes and mutexes) and driver types. */ #include /** @endcond */ K_OBJ_LAST }; /** * @defgroup usermode_apis User Mode APIs * @ingroup kernel_apis * @{ */ #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 __aligned(4); 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) #define K_OBJ_FLAG_ALLOC BIT(2) /** * 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 obj Address of the kernel object */ void _k_object_init(void *obj); #else #define K_THREAD_ACCESS_GRANT(thread, ...) /** * @internal */ static inline void _k_object_init(void *obj) { ARG_UNUSED(obj); } /** * @internal */ static inline void _impl_k_object_access_grant(void *object, struct k_thread *thread) { ARG_UNUSED(object); ARG_UNUSED(thread); } /** * @internal */ static inline void k_object_access_revoke(void *object, struct k_thread *thread) { ARG_UNUSED(object); ARG_UNUSED(thread); } /** * @internal */ static inline void _impl_k_object_release(void *object) { ARG_UNUSED(object); } 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 */ void k_object_access_revoke(void *object, struct k_thread *thread); __syscall void k_object_release(void *object); /** * 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); /** * Allocate a kernel object of a designated type * * This will instantiate at runtime a kernel object of the specified type, * returning a pointer to it. The object will be returned in an uninitialized * state, with the calling thread being granted permission on it. The memory * for the object will be allocated out of the calling thread's resource pool. * * Currently, allocation of thread stacks is not supported. * * @param otype Requested kernel object type * @return A pointer to the allocated kernel object, or NULL if memory wasn't * available */ __syscall void *k_object_alloc(enum k_objects otype); #ifdef CONFIG_DYNAMIC_OBJECTS /** * Free a kernel object previously allocated with k_object_alloc() * * This will return memory for a kernel object back to resource pool it was * allocated from. Care must be exercised that the object will not be used * during or after when this call is made. * * @param obj Pointer to the kernel object memory address. */ void k_object_free(void *obj); #else static inline void *_impl_k_object_alloc(enum k_objects otype) { ARG_UNUSED(otype); return NULL; } static inline void k_obj_free(void *obj) { ARG_UNUSED(obj); } #endif /* CONFIG_DYNAMIC_OBJECTS */ /** @} */ /* 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; /** * @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 */ union { sys_dnode_t qnode_dlist; struct rbnode qnode_rb; }; /* wait queue on which the thread is pended (needed only for * trees, not dumb lists) */ _wait_q_t *pended_on; /* 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; }; #ifdef CONFIG_SCHED_DEADLINE int prio_deadline; #endif u32_t order_key; #ifdef CONFIG_SMP /* True for the per-CPU idle threads */ u8_t is_idle; /* CPU index on which thread was last run */ u8_t cpu; /* Recursive count of irq_lock() calls */ u8_t global_lock_count; #endif #ifdef CONFIG_SCHED_CPU_MASK /* "May run on" bits for each CPU */ u8_t cpu_mask; #endif /* 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 - Identical to K_THREAD_STACK_BUFFER() on the stack * object. Represents thread-writable stack area without any extras. */ u32_t start; /* Stack Size - Thread writable stack buffer size. Represents * the size of the actual area, starting from the start member, * that should be writable by the thread */ 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 */ #ifdef CONFIG_THREAD_USERSPACE_LOCAL_DATA struct _thread_userspace_local_data { int errno_var; }; #endif /** * @ingroup thread_apis * Thread Structure */ struct k_thread { struct _thread_base base; /** defined by the architecture, but all archs need these */ struct _caller_saved caller_saved; /** defined by the architecture, but all archs need these */ struct _callee_saved callee_saved; /** static thread init data */ void *init_data; /** * abort function * @req K-THREAD-002 * */ 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 #if defined(CONFIG_THREAD_NAME) /* Thread name */ const char *name; #endif #ifdef CONFIG_THREAD_CUSTOM_DATA /** crude thread-local storage */ void *custom_data; #endif #ifdef CONFIG_THREAD_USERSPACE_LOCAL_DATA struct _thread_userspace_local_data *userspace_local_data; #endif #ifdef CONFIG_ERRNO #ifndef CONFIG_USERSPACE /** per-thread errno variable */ int errno_var; #endif #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 */ #if defined(CONFIG_USE_SWITCH) /* When using __switch() a few previously arch-specific items * become part of the core OS */ /** _Swap() return value */ int swap_retval; /** Context handle returned via _arch_switch() */ void *switch_handle; #endif /** resource pool */ struct k_mem_pool *resource_pool; /** 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; enum execution_context_types { K_ISR = 0, K_COOP_THREAD, K_PREEMPT_THREAD, }; /** * @addtogroup thread_apis * @{ */ typedef void (*k_thread_user_cb_t)(const struct k_thread *thread, void *user_data); /** * @brief Iterate over all the threads in the system. * * This routine iterates over all the threads in the system and * calls the user_cb function for each thread. * * @param user_cb Pointer to the user callback function. * @param user_data Pointer to user data. * * @note CONFIG_THREAD_MONITOR must be set for this function * to be effective. Also this API uses irq_lock to protect the * _kernel.threads list which means creation of new threads and * terminations of existing threads are blocked until this * API returns. * * @return N/A */ extern void k_thread_foreach(k_thread_user_cb_t user_cb, void *user_data); /** @} */ /** * @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. */ /** * @brief system thread that must not abort * @req K-THREAD-000 * */ #define K_ESSENTIAL (BIT(0)) #if defined(CONFIG_FP_SHARING) /** * @brief thread uses floating point registers */ #define K_FP_REGS (BIT(1)) #endif /** * @brief user mode thread * * This thread has dropped from supervisor mode to user mode and consequently * has additional restrictions */ #define K_USER (BIT(2)) /** * @brief Inherit Permissions * * @details * 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 (BIT(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 (BIT(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. * * @req K-THREAD-001 */ __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 * @req K-THREAD-003 */ 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 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 thread object must be initialized (i.e. running). The objects don't * need to be. * Note that NULL shouldn't be passed as an argument. * * @param thread Thread to grant access to objects * @param ... list of kernel object pointers * @req K-THREAD-004 */ #define k_thread_access_grant(thread, ...) \ FOR_EACH_FIXED_ARG(k_object_access_grant, thread, __VA_ARGS__) /** * @brief Assign a resource memory pool to a thread * * By default, threads have no resource pool assigned unless their parent * thread has a resource pool, in which case it is inherited. Multiple * threads may be assigned to the same memory pool. * * Changing a thread's resource pool will not migrate allocations from the * previous pool. * * @param thread Target thread to assign a memory pool for resource requests, * or NULL if the thread should no longer have a memory pool. * @param pool Memory pool to use for resources. * @req K-THREAD-005 */ static inline void k_thread_resource_pool_assign(struct k_thread *thread, struct k_mem_pool *pool) { thread->resource_pool = pool; } #if (CONFIG_HEAP_MEM_POOL_SIZE > 0) /** * @brief Assign the system heap as a thread's resource pool * * Similar to k_thread_resource_pool_assign(), but the thread will use * the kernel heap to draw memory. * * Use with caution, as a malicious thread could perform DoS attacks on the * kernel heap. * * @param thread Target thread to assign the system heap for resource requests * * @req K-THREAD-004 */ void k_thread_system_pool_assign(struct k_thread *thread); #endif /* (CONFIG_HEAP_MEM_POOL_SIZE > 0) */ /** * @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 Zero if the requested time has elapsed or the number of milliseconds * left to sleep, if thread was woken up by \ref k_wakeup call. * */ __syscall s32_t 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 */ __syscall 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 * @req K-THREAD-015 */ __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 * @req K-THREAD-014 */ __syscall void k_wakeup(k_tid_t thread); /** * @brief Get thread ID of the current thread. * * @return ID of current thread. * * @req K-THREAD-013 */ __syscall k_tid_t k_current_get(void); /** * @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 * @req K-THREAD-012 */ __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 * @req K-THREAD-011 */ __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) 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); const char *init_name; }; #define _THREAD_INITIALIZER(thread, stack, stack_size, \ entry, p1, p2, p3, \ prio, options, delay, abort, tname) \ { \ .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), \ .init_name = STRINGIFY(tname), \ } /** * 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 ; @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). * * @req K-THREAD-010 * * @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 _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, name); \ 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. * @req K-THREAD-009 */ __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 * @req K-THREAD-008 */ __syscall void k_thread_priority_set(k_tid_t thread, int prio); #ifdef CONFIG_SCHED_DEADLINE /** * @brief Set deadline expiration time for scheduler * * This sets the "deadline" expiration as a time delta from the * current time, in the same units used by k_cycle_get_32(). The * scheduler (when deadline scheduling is enabled) will choose the * next expiring thread when selecting between threads at the same * static priority. Threads at different priorities will be scheduled * according to their static priority. * * @note Deadlines that are negative (i.e. in the past) are still seen * as higher priority than others, even if the thread has "finished" * its work. If you don't want it scheduled anymore, you have to * reset the deadline into the future, block/pend the thread, or * modify its priority with k_thread_priority_set(). * * @note Despite the API naming, the scheduler makes no guarantees the * the thread WILL be scheduled within that deadline, nor does it take * extra metadata (like e.g. the "runtime" and "period" parameters in * Linux sched_setattr()) that allows the kernel to validate the * scheduling for achievability. Such features could be implemented * above this call, which is simply input to the priority selection * logic. * * @param thread A thread on which to set the deadline * @param deadline A time delta, in cycle units * * @req K-THREAD-007 */ __syscall void k_thread_deadline_set(k_tid_t thread, int deadline); #endif #ifdef CONFIG_SCHED_CPU_MASK /** * @brief Sets all CPU enable masks to zero * * After this returns, the thread will no longer be schedulable on any * CPUs. The thread must not be currently runnable. * * @param thread Thread to operate upon * @return Zero on success, otherwise error code */ int k_thread_cpu_mask_clear(k_tid_t thread); /** * @brief Sets all CPU enable masks to one * * After this returns, the thread will be schedulable on any CPU. The * thread must not be currently runnable. * * @param thread Thread to operate upon * @return Zero on success, otherwise error code */ int k_thread_cpu_mask_enable_all(k_tid_t thread); /** * @brief Enable thread to run on specified CPU * * The thread must not be currently runnable. * * @param thread Thread to operate upon * @param cpu CPU index * @return Zero on success, otherwise error code */ int k_thread_cpu_mask_enable(k_tid_t thread, int cpu); /** * @brief Prevent thread to run on specified CPU * * The thread must not be currently runnable. * * @param thread Thread to operate upon * @param cpu CPU index * @return Zero on success, otherwise error code */ int k_thread_cpu_mask_disable(k_tid_t thread, int cpu); #endif /** * @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 * @req K-THREAD-005 */ __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 * @req K-THREAD-006 */ __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); /** @} */ /** * @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 false if invoked by a thread. * @return true if invoked by an ISR. */ extern bool 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); /** * @} */ /** * @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 * * @req K-THREAD-016 */ __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. * @req K-THREAD-007 */ __syscall void *k_thread_custom_data_get(void); /** * @brief Set current thread name * * Set the name of the thread to be used when THREAD_MONITOR is enabled for * tracing and debugging. * */ __syscall void k_thread_name_set(k_tid_t thread_id, const char *value); /** * @brief Get thread name * * Get the name of a thread * * @param thread_id Thread ID * */ __syscall const char *k_thread_name_get(k_tid_t thread_id); /** * @} */ /** * @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) /** * @} */ /** * @cond INTERNAL_HIDDEN */ 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 *timer); /* runs in the context of the thread that calls k_timer_stop() */ void (*stop_fn)(struct k_timer *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 = { \ .node = {},\ .dticks = 0, \ .fn = _timer_expiration_handler \ }, \ .wait_q = _WAIT_Q_INIT(&obj.wait_q), \ .expiry_fn = expiry, \ .stop_fn = stop, \ .period = 0, \ .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 ; @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); extern s32_t z_timeout_remaining(struct _timeout *timeout); /** * @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 u32_t k_timer_remaining_get(struct k_timer *timer); static inline u32_t _impl_k_timer_remaining_get(struct k_timer *timer) { return (u32_t)__ticks_to_ms(z_timeout_remaining(&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); /** * @internal */ 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; } /** @} */ /** * @addtogroup clock_apis * @{ */ /** * @brief Get system uptime. * * This routine returns the elapsed time since the system booted, * in milliseconds. * * @note While this function returns time in milliseconds, it does not mean it * has millisecond resolution. The actual resolution depends on * :option:`CONFIG_SYS_CLOCK_TICKS_PER_SEC` config option, and with the default * setting of 100, system time is updated in increments of 10ms. * * @return Current uptime in milliseconds. */ __syscall s64_t k_uptime_get(void); /** * @brief Enable clock always on in tickless kernel * * This routine enables keeping the clock running (that is, it always * keeps an active timer interrupt scheduled) when there are no timer * events programmed in tickless kernel scheduling. This is necessary * if the clock is used to track passage of time (e.g. via * k_uptime_get_32()), otherwise the internal hardware counter may * roll over between interrupts. * * @retval prev_status Previous status of always on flag */ int k_enable_sys_clock_always_on(void); /** * @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. */ void k_disable_sys_clock_always_on(void); /** * @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. * * @note While this function returns time in milliseconds, it does not mean it * has millisecond resolution. The actual resolution depends on * :option:`CONFIG_SYS_CLOCK_TICKS_PER_SEC` config option, and with the default * setting of 100, system time is updated in increments of 10ms. * * @return Current uptime in milliseconds. */ __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. */ static inline s64_t k_uptime_delta(s64_t *reftime) { s64_t uptime, delta; uptime = k_uptime_get(); delta = uptime - *reftime; *reftime = uptime; return delta; } /** * @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. */ static inline u32_t k_uptime_delta_32(s64_t *reftime) { return (u32_t)k_uptime_delta(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() /** * @} */ /** * @cond INTERNAL_HIDDEN */ struct k_queue { sys_sflist_t data_q; struct k_spinlock lock; union { _wait_q_t wait_q; _POLL_EVENT; }; _OBJECT_TRACING_NEXT_PTR(k_queue) }; #define _K_QUEUE_INITIALIZER(obj) \ { \ .data_q = SYS_SLIST_STATIC_INIT(&obj.data_q), \ .wait_q = _WAIT_Q_INIT(&obj.wait_q), \ _POLL_EVENT_OBJ_INIT(obj) \ _OBJECT_TRACING_INIT \ } #define K_QUEUE_INITIALIZER DEPRECATED_MACRO _K_QUEUE_INITIALIZER extern void *z_queue_node_peek(sys_sfnode_t *node, bool needs_free); /** * 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 */ __syscall 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). * If the queue is being waited on by k_poll(), it will return with * -EINTR and K_POLL_STATE_CANCELLED state (and per above, subsequent * k_queue_get() will return NULL). * * @note Can be called by ISRs. * * @param queue Address of the queue. * * @return N/A */ __syscall 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 Append an element to a queue. * * This routine appends a data item to @a queue. There is an implicit * memory allocation from the calling thread's resource pool, which is * automatically freed when the item is removed from the queue. * * @note Can be called by ISRs. * * @param queue Address of the queue. * @param data Address of the data item. * * @retval 0 on success * @retval -ENOMEM if there isn't sufficient RAM in the caller's resource pool */ __syscall s32_t k_queue_alloc_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 Prepend an element to a queue. * * This routine prepends a data item to @a queue. There is an implicit * memory allocation from the calling thread's resource pool, which is * automatically freed when the item is removed from the queue. * * @note Can be called by ISRs. * * @param queue Address of the queue. * @param data Address of the data item. * * @retval 0 on success * @retval -ENOMEM if there isn't sufficient RAM in the caller's resource pool */ __syscall s32_t k_queue_alloc_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. */ __syscall 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_sflist_find_and_remove(&queue->data_q, (sys_sfnode_t *)data); } /** * @brief Append an element to a queue only if it's not present already. * * This routine appends data item to @a queue. The first 32 bits of the * data item are reserved for the kernel's use. Appending elements to k_queue * relies on sys_slist_is_node_in_list 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 added, false if not */ static inline bool k_queue_unique_append(struct k_queue *queue, void *data) { sys_sfnode_t *test; SYS_SFLIST_FOR_EACH_NODE(&queue->data_q, test) { if (test == (sys_sfnode_t *) data) { return false; } } k_queue_append(queue, data); return true; } /** * @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. */ __syscall int k_queue_is_empty(struct k_queue *queue); static inline int _impl_k_queue_is_empty(struct k_queue *queue) { return (int)sys_sflist_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. */ __syscall void *k_queue_peek_head(struct k_queue *queue); static inline void *_impl_k_queue_peek_head(struct k_queue *queue) { return z_queue_node_peek(sys_sflist_peek_head(&queue->data_q), false); } /** * @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. */ __syscall void *k_queue_peek_tail(struct k_queue *queue); static inline void *_impl_k_queue_peek_tail(struct k_queue *queue) { return z_queue_node_peek(sys_sflist_peek_tail(&queue->data_q), false); } /** * @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 ; @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) /** @} */ struct k_fifo { struct k_queue _queue; }; /** * @cond INTERNAL_HIDDEN */ #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 queue. * * This routine initializes a FIFO queue, prior to its first use. * * @param fifo Address of the FIFO queue. * * @return N/A * @req K-FIFO-001 */ #define k_fifo_init(fifo) \ k_queue_init((struct k_queue *) fifo) /** * @brief Cancel waiting on a FIFO queue. * * 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 queue. * * @return N/A * @req K-FIFO-001 */ #define k_fifo_cancel_wait(fifo) \ k_queue_cancel_wait((struct k_queue *) fifo) /** * @brief Add an element to a FIFO queue. * * 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 * @req K-FIFO-001 */ #define k_fifo_put(fifo, data) \ k_queue_append((struct k_queue *) fifo, data) /** * @brief Add an element to a FIFO queue. * * This routine adds a data item to @a fifo. There is an implicit * memory allocation from the calling thread's resource pool, which is * automatically freed when the item is removed. * * @note Can be called by ISRs. * * @param fifo Address of the FIFO. * @param data Address of the data item. * * @retval 0 on success * @retval -ENOMEM if there isn't sufficient RAM in the caller's resource pool * @req K-FIFO-001 */ #define k_fifo_alloc_put(fifo, data) \ k_queue_alloc_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 queue. * @param head Pointer to first node in singly-linked list. * @param tail Pointer to last node in singly-linked list. * * @return N/A * @req K-FIFO-001 */ #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 queue. * * 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 queue. * @param list Pointer to sys_slist_t object. * * @return N/A * @req K-FIFO-001 */ #define k_fifo_put_slist(fifo, list) \ k_queue_merge_slist((struct k_queue *) fifo, list) /** * @brief Get an element from a FIFO queue. * * 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 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. * @req K-FIFO-001 */ #define k_fifo_get(fifo, timeout) \ k_queue_get((struct k_queue *) fifo, timeout) /** * @brief Query a FIFO 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 is also trying to read from the FIFO. * * @note Can be called by ISRs. * * @param fifo Address of the FIFO queue. * * @return Non-zero if the FIFO queue is empty. * @return 0 if data is available. * @req K-FIFO-001 */ #define k_fifo_is_empty(fifo) \ k_queue_is_empty((struct k_queue *) fifo) /** * @brief Peek element at the head of a FIFO queue. * * Return element from the head of FIFO queue without removing it. A usecase * for this is if elements of the FIFO object 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 queue. * * @param fifo Address of the FIFO queue. * * @return Head element, or NULL if the FIFO queue is empty. * @req K-FIFO-001 */ #define k_fifo_peek_head(fifo) \ k_queue_peek_head((struct k_queue *) fifo) /** * @brief Peek element at the tail of FIFO queue. * * Return element from the tail of FIFO queue (without removing it). A usecase * for this is if elements of the FIFO queue are themselves containers. Then * it may be useful to add more data to the last container in a FIFO queue. * * @param fifo Address of the FIFO queue. * * @return Tail element, or NULL if a FIFO queue is empty. * @req K-FIFO-001 */ #define k_fifo_peek_tail(fifo) \ k_queue_peek_tail((struct k_queue *) fifo) /** * @brief Statically define and initialize a FIFO queue. * * The FIFO queue can be accessed outside the module where it is defined using: * * @code extern struct k_fifo ; @endcode * * @param name Name of the FIFO queue. * @req K-FIFO-002 */ #define K_FIFO_DEFINE(name) \ struct k_fifo name \ __in_section(_k_queue, static, name) = \ _K_FIFO_INITIALIZER(name) /** @} */ struct k_lifo { struct k_queue _queue; }; /** * @cond INTERNAL_HIDDEN */ #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 queue. * * This routine initializes a LIFO queue object, prior to its first use. * * @param lifo Address of the LIFO queue. * * @return N/A * @req K-LIFO-001 */ #define k_lifo_init(lifo) \ k_queue_init((struct k_queue *) lifo) /** * @brief Add an element to a LIFO queue. * * This routine adds a data item to @a lifo. A LIFO 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 lifo Address of the LIFO queue. * @param data Address of the data item. * * @return N/A * @req K-LIFO-001 */ #define k_lifo_put(lifo, data) \ k_queue_prepend((struct k_queue *) lifo, data) /** * @brief Add an element to a LIFO queue. * * This routine adds a data item to @a lifo. There is an implicit * memory allocation from the calling thread's resource pool, which is * automatically freed when the item is removed. * * @note Can be called by ISRs. * * @param lifo Address of the LIFO. * @param data Address of the data item. * * @retval 0 on success * @retval -ENOMEM if there isn't sufficient RAM in the caller's resource pool * @req K-LIFO-001 */ #define k_lifo_alloc_put(lifo, data) \ k_queue_alloc_prepend((struct k_queue *) lifo, data) /** * @brief Get an element from a LIFO queue. * * 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 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. * @req K-LIFO-001 */ #define k_lifo_get(lifo, timeout) \ k_queue_get((struct k_queue *) lifo, timeout) /** * @brief Statically define and initialize a LIFO queue. * * The LIFO queue can be accessed outside the module where it is defined using: * * @code extern struct k_lifo ; @endcode * * @param name Name of the fifo. * @req K-LIFO-002 */ #define K_LIFO_DEFINE(name) \ struct k_lifo name \ __in_section(_k_queue, static, name) = \ _K_LIFO_INITIALIZER(name) /** @} */ /** * @cond INTERNAL_HIDDEN */ #define K_STACK_FLAG_ALLOC ((u8_t)1) /* Buffer was allocated */ struct k_stack { _wait_q_t wait_q; struct k_spinlock lock; u32_t *base, *next, *top; _OBJECT_TRACING_NEXT_PTR(k_stack) u8_t flags; }; #define _K_STACK_INITIALIZER(obj, stack_buffer, stack_num_entries) \ { \ .wait_q = _WAIT_Q_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 * @req K-STACK-001 */ void k_stack_init(struct k_stack *stack, u32_t *buffer, u32_t num_entries); /** * @brief Initialize a stack. * * This routine initializes a stack object, prior to its first use. Internal * buffers will be allocated from the calling thread's resource pool. * This memory will be released if k_stack_cleanup() is called, or * userspace is enabled and the stack object loses all references to it. * * @param stack Address of the stack. * @param num_entries Maximum number of values that can be stacked. * * @return -ENOMEM if memory couldn't be allocated * @req K-STACK-001 */ __syscall s32_t k_stack_alloc_init(struct k_stack *stack, u32_t num_entries); /** * @brief Release a stack's allocated buffer * * If a stack object was given a dynamically allocated buffer via * k_stack_alloc_init(), this will free it. This function does nothing * if the buffer wasn't dynamically allocated. * * @param stack Address of the stack. * @req K-STACK-001 */ void k_stack_cleanup(struct k_stack *stack); /** * @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 * @req K-STACK-001 */ __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. * @req K-STACK-001 */ __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 ; @endcode * * @param name Name of the stack. * @param stack_num_entries Maximum number of values that can be stacked. * @req K-STACK-002 */ #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) /** @} */ struct k_work; /** * @addtogroup thread_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 * @req K-WORK-001 */ 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; struct k_spinlock lock; }; 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(, ); @endcode * * @param work Symbol name for work item object * @param work_handler Function to invoke each time work item is processed. * @req K-WORK-002 */ #define K_WORK_DEFINE(work, work_handler) \ struct k_work 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 * @req K-WORK-001 */ static inline void k_work_init(struct k_work *work, k_work_handler_t handler) { *work = (struct k_work)_K_WORK_INITIALIZER(handler); } /** * @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 * @req K-WORK-001 */ 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 Submit a work item to a user mode workqueue * * Submits a work item to a workqueue that runs in user mode. A temporary * memory allocation is made from the caller's resource pool which is freed * once the worker thread consumes the k_work item. The workqueue * thread must have memory access to the k_work item being submitted. The caller * must have permission granted on the work_q parameter's queue object. * * Otherwise this works the same as k_work_submit_to_queue(). * * @note Can be called by ISRs. * * @param work_q Address of workqueue. * @param work Address of work item. * * @retval -EBUSY if the work item was already in some workqueue * @retval -ENOMEM if no memory for thread resource pool allocation * @retval 0 Success * @req K-WORK-001 */ static inline int k_work_submit_to_user_queue(struct k_work_q *work_q, struct k_work *work) { int ret = -EBUSY; if (!atomic_test_and_set_bit(work->flags, K_WORK_STATE_PENDING)) { ret = k_queue_alloc_append(&work_q->queue, work); /* Couldn't insert into the queue. Clear the pending bit * so the work item can be submitted again */ if (ret != 0) { atomic_clear_bit(work->flags, K_WORK_STATE_PENDING); } } return ret; } /** * @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 true if work item is pending, or false if it is not pending. * @req K-WORK-001 */ static inline bool 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 * @req K-WORK-001 */ extern void k_work_q_start(struct k_work_q *work_q, k_thread_stack_t *stack, size_t stack_size, int prio); /** * @brief Start a workqueue in user mode * * This works identically to k_work_q_start() except it is callable from user * mode, and the worker thread created will run in user mode. * The caller must have permissions granted on both the work_q parameter's * thread and queue objects, and the same restrictions on priority apply as * k_thread_create(). * * @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 * @req K-WORK-001 */ extern void k_work_q_user_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 * @req K-DWORK-001 */ 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. Note that this behavior is * inherently subject to race conditions with the pre-existing * timeouts and work queue, so care must be taken to synchronize such * resubmissions externally. * * @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. * @req K-DWORK-001 */ 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. * @req K-DWORK-001 */ 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 * @req K-WORK-001 */ 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. * @req K-DWORK-001 */ 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 * scheduled, it returns zero. * * @param work Delayed work item. * * @return Remaining time (in milliseconds). * @req K-DWORK-001 */ static inline s32_t k_delayed_work_remaining_get(struct k_delayed_work *work) { return __ticks_to_ms(z_timeout_remaining(&work->timeout)); } /** @} */ /** * @defgroup mutex_apis Mutex APIs * @ingroup kernel_apis * @{ */ /** * Mutex Structure * @ingroup mutex_apis */ struct k_mutex { _wait_q_t wait_q; /** Mutex owner */ struct k_thread *owner; u32_t lock_count; int owner_orig_prio; _OBJECT_TRACING_NEXT_PTR(k_mutex) }; /** * @cond INTERNAL_HIDDEN */ #define _K_MUTEX_INITIALIZER(obj) \ { \ .wait_q = _WAIT_Q_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 */ /** * @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 ; @endcode * * @param name Name of the mutex. * @req K-MUTEX-001 */ #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 * @req K-MUTEX-002 */ __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. * @req K-MUTEX-002 */ __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 * @req K-MUTEX-002 */ __syscall void k_mutex_unlock(struct k_mutex *mutex); /** * @} */ /** * @cond INTERNAL_HIDDEN */ struct k_sem { _wait_q_t wait_q; u32_t count; u32_t limit; _POLL_EVENT; _OBJECT_TRACING_NEXT_PTR(k_sem) }; #define _K_SEM_INITIALIZER(obj, initial_count, count_limit) \ { \ .wait_q = _WAIT_Q_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 * @req K-SEM-001 */ __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. * @req K-SEM-001 */ __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 * @req K-SEM-001 */ __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 * @req K-SEM-001 */ __syscall void k_sem_reset(struct k_sem *sem); /** * @internal */ 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. * @req K-SEM-001 */ __syscall unsigned int k_sem_count_get(struct k_sem *sem); /** * @internal */ 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 ; @endcode * * @param name Name of the semaphore. * @param initial_count Initial semaphore count. * @param count_limit Maximum permitted semaphore count. * @req K-SEM-002 */ #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); \ BUILD_ASSERT(((count_limit) != 0) && \ ((initial_count) <= (count_limit))); /** @} */ /** * @defgroup msgq_apis Message Queue APIs * @ingroup kernel_apis * @{ */ /** * @brief Message Queue Structure */ struct k_msgq { _wait_q_t wait_q; struct k_spinlock lock; 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) u8_t flags; }; /** * @cond INTERNAL_HIDDEN */ #define _K_MSGQ_INITIALIZER(obj, q_buffer, q_msg_size, q_max_msgs) \ { \ .wait_q = _WAIT_Q_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 */ #define K_MSGQ_FLAG_ALLOC BIT(0) /** * @brief Message Queue Attributes */ struct k_msgq_attrs { size_t msg_size; u32_t max_msgs; u32_t used_msgs; }; /** * @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 ; @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. * * @req K-MSGQ-001 */ #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 * @req K-MSGQ-002 */ void k_msgq_init(struct k_msgq *q, char *buffer, size_t msg_size, u32_t max_msgs); /** * @brief Initialize a message queue. * * This routine initializes a message queue object, prior to its first use, * allocating its internal ring buffer from the calling thread's resource * pool. * * Memory allocated for the ring buffer can be released by calling * k_msgq_cleanup(), or if userspace is enabled and the msgq object loses * all of its references. * * @param q Address of the message queue. * @param msg_size Message size (in bytes). * @param max_msgs Maximum number of messages that can be queued. * * @return 0 on success, -ENOMEM if there was insufficient memory in the * thread's resource pool, or -EINVAL if the size parameters cause * an integer overflow. * @req K-MSGQ-002 */ __syscall int k_msgq_alloc_init(struct k_msgq *q, size_t msg_size, u32_t max_msgs); void k_msgq_cleanup(struct k_msgq *q); /** * @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. * @req K-MSGQ-002 */ __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. * @req K-MSGQ-002 */ __syscall int k_msgq_get(struct k_msgq *q, void *data, s32_t timeout); /** * @brief Peek/read a message from a message queue. * * This routine reads a message from message queue @a q in a "first in, * first out" manner and leaves the message in the queue. * * @note Can be called by ISRs. * * @param q Address of the message queue. * @param data Address of area to hold the message read from the queue. * * @retval 0 Message read. * @retval -ENOMSG Returned when the queue has no message. * @req K-MSGQ-002 */ __syscall int k_msgq_peek(struct k_msgq *q, void *data); /** * @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 * @req K-MSGQ-002 */ __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. * @req K-MSGQ-002 */ __syscall u32_t k_msgq_num_free_get(struct k_msgq *q); /** * @brief Get basic attributes of a message queue. * * This routine fetches basic attributes of message queue into attr argument. * * @param q Address of the message queue. * @param attrs pointer to message queue attribute structure. * * @return N/A * @req K-MSGQ-003 */ __syscall void k_msgq_get_attrs(struct k_msgq *q, struct k_msgq_attrs *attrs); 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. * @req K-MSGQ-002 */ __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; } /** @} */ /** * @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; }; /** @} */ /** * @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 }; struct k_mbox { _wait_q_t tx_msg_queue; _wait_q_t rx_msg_queue; struct k_spinlock lock; _OBJECT_TRACING_NEXT_PTR(k_mbox) }; /** * @cond INTERNAL_HIDDEN */ #define _K_MBOX_INITIALIZER(obj) \ { \ .tx_msg_queue = _WAIT_Q_INIT(&obj.tx_msg_queue), \ .rx_msg_queue = _WAIT_Q_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 ; @endcode * * @param name Name of the mailbox. * @req K-MBOX-001 */ #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 * @req K-MBOX-002 */ 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. * @req K-MBOX-002 */ 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 * @req K-MBOX-002 */ 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. * @req K-MBOX-002 */ 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 * @req K-MBOX-002 */ 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. * @req K-MBOX-002 */ 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); /** @} */ /** * @defgroup pipe_apis Pipe APIs * @ingroup kernel_apis * @{ */ /** Pipe Structure */ 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 k_spinlock lock; /**< Synchronization lock */ struct { _wait_q_t readers; /**< Reader wait queue */ _wait_q_t writers; /**< Writer wait queue */ } wait_q; _OBJECT_TRACING_NEXT_PTR(k_pipe) u8_t flags; /**< Flags */ }; /** * @cond INTERNAL_HIDDEN */ #define K_PIPE_FLAG_ALLOC BIT(0) /** Buffer was allocated */ #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, \ .lock = {}, \ .wait_q = { \ .readers = _WAIT_Q_INIT(&obj.wait_q.readers), \ .writers = _WAIT_Q_INIT(&obj.wait_q.writers) \ }, \ _OBJECT_TRACING_INIT \ .flags = 0 \ } #define K_PIPE_INITIALIZER DEPRECATED_MACRO _K_PIPE_INITIALIZER /** * INTERNAL_HIDDEN @endcond */ /** * @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 ; @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). * * @req K-PIPE-001 */ #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 * @req K-PIPE-002 */ void k_pipe_init(struct k_pipe *pipe, unsigned char *buffer, size_t size); /** * @brief Release a pipe's allocated buffer * * If a pipe object was given a dynamically allocated buffer via * k_pipe_alloc_init(), this will free it. This function does nothing * if the buffer wasn't dynamically allocated. * * @param pipe Address of the pipe. * @req K-PIPE-002 */ void k_pipe_cleanup(struct k_pipe *pipe); /** * @brief Initialize a pipe and allocate a buffer for it * * Storage for the buffer region will be allocated from the calling thread's * resource pool. This memory will be released if k_pipe_cleanup() is called, * or userspace is enabled and the pipe object loses all references to it. * * This function should only be called on uninitialized pipe objects. * * @param pipe Address of the pipe. * @param size Size of the pipe's ring buffer (in bytes), or zero if no ring * buffer is used. * @retval 0 on success * @retval -ENOMEM if memory couldn't be allocated * @req K-PIPE-002 */ __syscall int k_pipe_alloc_init(struct k_pipe *pipe, 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. * @req K-PIPE-002 */ __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. * @req K-PIPE-002 */ __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 * @req K-PIPE-002 */ extern void k_pipe_block_put(struct k_pipe *pipe, struct k_mem_block *block, size_t size, struct k_sem *sem); /** @} */ /** * @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 = _WAIT_Q_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 ; @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). * @req K-MSLAB-001 */ #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 * @req K-MSLAB-002 */ 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. * @req K-MSLAB-002 */ 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 * @req K-MSLAB-002 */ 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. * @req K-MSLAB-002 */ 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. * @req K-MSLAB-002 */ static inline u32_t k_mem_slab_num_free_get(struct k_mem_slab *slab) { return slab->num_blocks - slab->num_used; } /** @} */ /** * @cond INTERNAL_HIDDEN */ struct k_mem_pool { struct sys_mem_pool_base base; _wait_q_t wait_q; }; /** * 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 ; @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). * @req K-MPOOL-001 */ #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 sys_mem_pool_lvl _mpool_lvls_##name[_MPOOL_LVLS(maxsz, minsz)]; \ struct k_mem_pool name __in_section(_k_mem_pool, static, name) = { \ .base = { \ .buf = _mpool_buf_##name, \ .max_sz = maxsz, \ .n_max = nmax, \ .n_levels = _MPOOL_LVLS(maxsz, minsz), \ .levels = _mpool_lvls_##name, \ .flags = SYS_MEM_POOL_KERNEL \ } \ } /** * @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. * @req K-MPOOL-002 */ extern int k_mem_pool_alloc(struct k_mem_pool *pool, struct k_mem_block *block, size_t size, s32_t timeout); /** * @brief Allocate memory from a memory pool with malloc() semantics * * Such memory must be released using k_free(). * * @param pool Address of the memory pool. * @param size Amount of memory to allocate (in bytes). * @return Address of the allocated memory if successful, otherwise NULL * @req K-MPOOL-002 */ extern void *k_mem_pool_malloc(struct k_mem_pool *pool, size_t size); /** * @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 * @req K-MPOOL-002 */ extern void k_mem_pool_free(struct k_mem_block *block); /** * @brief Free memory allocated from a memory pool. * * This routine releases a previously allocated memory block back to its * memory pool * * @param id Memory block identifier. * * @return N/A * @req K-MPOOL-002 */ extern void k_mem_pool_free_id(struct k_mem_block_id *id); /** * @} */ /** * @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. * @req K-HEAP-001 */ 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 or * k_mem_pool_malloc(). * * If @a ptr is NULL, no operation is performed. * * @param ptr Pointer to previously allocated memory. * * @return N/A * @req K-HEAP-001 */ 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. * @req K-HEAP-001 */ extern void *k_calloc(size_t nmemb, size_t size); /** @} */ /* polling API - PRIVATE */ #ifdef CONFIG_POLL #define _INIT_OBJ_POLL_EVENT(obj) do { (obj)->poll_event = NULL; } while (false) #else #define _INIT_OBJ_POLL_EVENT(obj) do { } while (false) #endif /* private - implementation data created as needed, per-type */ struct _poller { struct k_thread *thread; volatile bool is_polling; }; /* 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_raise() */ _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_raise() */ _POLL_STATE_SIGNALED, /* semaphore is available */ _POLL_STATE_SEM_AVAILABLE, /* data is available to read on queue/fifo/lifo */ _POLL_STATE_DATA_AVAILABLE, /* queue/fifo/lifo wait was cancelled */ _POLL_STATE_CANCELLED, _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 #define K_POLL_STATE_CANCELLED _POLL_STATE_BIT(_POLL_STATE_CANCELLED) /* 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_raise() if needed */ int result; }; #define K_POLL_SIGNAL_INITIALIZER(obj) \ { \ .poll_events = SYS_DLIST_STATIC_INIT(&obj.poll_events), \ .signaled = 0, \ .result = 0, \ } struct k_poll_event { /* PRIVATE - DO NOT TOUCH */ sys_dnode_t _node; /* PRIVATE - DO NOT TOUCH */ struct _poller *poller; /* optional user-specified tag, opaque, untouched by the API */ u32_t tag:8; /* bitfield of event types (bitwise-ORed K_POLL_TYPE_xxx values) */ u32_t type:_POLL_NUM_TYPES; /* bitfield of event states (bitwise-ORed K_POLL_STATE_xxx values) */ u32_t state:_POLL_NUM_STATES; /* mode of operation, from enum k_poll_modes */ u32_t mode:1; /* unused bits in 32-bit word */ u32_t unused:_POLL_EVENT_NUM_UNUSED_BITS; /* per-type data */ union { void *obj; struct k_poll_signal *signal; struct k_sem *sem; struct k_fifo *fifo; struct k_queue *queue; }; }; #define K_POLL_EVENT_INITIALIZER(event_type, event_mode, event_obj) \ { \ .poller = NULL, \ .type = event_type, \ .state = K_POLL_STATE_NOT_READY, \ .mode = event_mode, \ .unused = 0, \ { .obj = event_obj }, \ } #define K_POLL_EVENT_STATIC_INITIALIZER(event_type, event_mode, event_obj, \ event_tag) \ { \ .type = event_type, \ .tag = event_tag, \ .state = K_POLL_STATE_NOT_READY, \ .mode = event_mode, \ .unused = 0, \ { .obj = event_obj }, \ } /** * @brief Initialize one struct k_poll_event instance * * After this routine is called on a poll event, the event it ready to be * placed in an event array to be passed to k_poll(). * * @param event The event to initialize. * @param type A bitfield of the types of event, from the K_POLL_TYPE_xxx * values. Only values that apply to the same object being polled * can be used together. Choosing K_POLL_TYPE_IGNORE disables the * event. * @param mode Future. Use K_POLL_MODE_NOTIFY_ONLY. * @param obj Kernel object or poll signal. * * @return N/A * @req K-POLL-001 */ extern void k_poll_event_init(struct k_poll_event *event, u32_t type, int mode, void *obj); /** * @brief Wait for one or many of multiple poll events to occur * * This routine allows a thread to wait concurrently for one or many of * multiple poll events to have occurred. Such events can be a kernel object * being available, like a semaphore, or a poll signal event. * * When an event notifies that a kernel object is available, the kernel object * is not "given" to the thread calling k_poll(): it merely signals the fact * that the object was available when the k_poll() call was in effect. Also, * all threads trying to acquire an object the regular way, i.e. by pending on * the object, have precedence over the thread polling on the object. This * means that the polling thread will never get the poll event on an object * until the object becomes available and its pend queue is empty. For this * reason, the k_poll() call is more effective when the objects being polled * only have one thread, the polling thread, trying to acquire them. * * When k_poll() returns 0, the caller should loop on all the events that were * passed to k_poll() and check the state field for the values that were * expected and take the associated actions. * * Before being reused for another call to k_poll(), the user has to reset the * state field to K_POLL_STATE_NOT_READY. * * When called from user mode, a temporary memory allocation is required from * the caller's resource pool. * * @param events An array of pointers to events to be polled for. * @param num_events The number of events in the array. * @param timeout Waiting period for an event to be ready (in milliseconds), * or one of the special values K_NO_WAIT and K_FOREVER. * * @retval 0 One or more events are ready. * @retval -EAGAIN Waiting period timed out. * @retval -EINTR Polling has been interrupted, e.g. with * k_queue_cancel_wait(). All output events are still set and valid, * cancelled event(s) will be set to K_POLL_STATE_CANCELLED. In other * words, -EINTR status means that at least one of output events is * K_POLL_STATE_CANCELLED. * @retval -ENOMEM Thread resource pool insufficient memory (user mode only) * @retval -EINVAL Bad parameters (user mode only) * @req K-POLL-001 */ __syscall int k_poll(struct k_poll_event *events, int num_events, s32_t timeout); /** * @brief Initialize a poll signal object. * * Ready a poll signal object to be signaled via k_poll_signal_raise(). * * @param signal A poll signal. * * @return N/A * @req K-POLL-001 */ __syscall void k_poll_signal_init(struct k_poll_signal *signal); /* * @brief Reset a poll signal object's state to unsignaled. * * @param signal A poll signal object * @req K-POLL-001 */ __syscall void k_poll_signal_reset(struct k_poll_signal *signal); static inline void _impl_k_poll_signal_reset(struct k_poll_signal *signal) { signal->signaled = 0; } /** * @brief Fetch the signaled state and result value of a poll signal * * @param signal A poll signal object * @param signaled An integer buffer which will be written nonzero if the * object was signaled * @param result An integer destination buffer which will be written with the * result value if the object was signaled, or an undefined * value if it was not. * @req K-POLL-001 */ __syscall void k_poll_signal_check(struct k_poll_signal *signal, unsigned int *signaled, int *result); /** * @brief Signal a poll signal object. * * This routine makes ready a poll signal, which is basically a poll event of * type K_POLL_TYPE_SIGNAL. If a thread was polling on that event, it will be * made ready to run. A @a result value can be specified. * * The poll signal contains a 'signaled' field that, when set by * k_poll_signal_raise(), stays set until the user sets it back to 0 with * k_poll_signal_reset(). It thus has to be reset by the user before being * passed again to k_poll() or k_poll() will consider it being signaled, and * will return immediately. * * @param signal A poll signal. * @param result The value to store in the result field of the signal. * * @retval 0 The signal was delivered successfully. * @retval -EAGAIN The polling thread's timeout is in the process of expiring. * @req K-POLL-001 */ __syscall int k_poll_signal_raise(struct k_poll_signal *signal, int result); /** * @internal */ extern void _handle_obj_poll_events(sys_dlist_t *events, u32_t state); /** @} */ /** * @defgroup cpu_idle_apis CPU Idling APIs * @ingroup kernel_apis * @{ */ /** * @brief Make the CPU idle. * * This function makes the CPU idle until an event wakes it up. * * In a regular system, the idle thread should be the only thread responsible * for making the CPU idle and triggering any type of power management. * However, in some more constrained systems, such as a single-threaded system, * the only thread would be responsible for this if needed. * * @return N/A * @req K-CPU-IDLE-001 */ extern void k_cpu_idle(void); /** * @brief Make the CPU idle in an atomic fashion. * * Similar to k_cpu_idle(), but called with interrupts locked if operations * must be done atomically before making the CPU idle. * * @param key Interrupt locking key obtained from irq_lock(). * * @return N/A * @req K-CPU-IDLE-002 */ extern void k_cpu_atomic_idle(unsigned int key); /** * @} */ /** * @internal */ extern void _sys_power_save_idle_exit(s32_t ticks); #ifdef _ARCH_EXCEPT /* This archtecture has direct support for triggering a CPU exception */ #define _k_except_reason(reason) _ARCH_EXCEPT(reason) #else /* NOTE: This is the implementation for arches that do not implement * _ARCH_EXCEPT() to generate a real CPU exception. * * We won't have a real exception frame to determine the PC value when * the oops occurred, so print file and line number before we jump into * the fatal error handler. */ #define _k_except_reason(reason) do { \ printk("@ %s:%d:\n", __FILE__, __LINE__); \ _NanoFatalErrorHandler(reason, &_default_esf); \ CODE_UNREACHABLE; \ } while (false) #endif /* _ARCH__EXCEPT */ /** * @brief Fatally terminate a thread * * This should be called when a thread has encountered an unrecoverable * runtime condition and needs to terminate. What this ultimately * means is determined by the _fatal_error_handler() implementation, which * will be called will reason code _NANO_ERR_KERNEL_OOPS. * * If this is called from ISR context, the default system fatal error handler * will treat it as an unrecoverable system error, just like k_panic(). * @req K-MISC-003 */ #define k_oops() _k_except_reason(_NANO_ERR_KERNEL_OOPS) /** * @brief Fatally terminate the system * * This should be called when the Zephyr kernel has encountered an * unrecoverable runtime condition and needs to terminate. What this ultimately * means is determined by the _fatal_error_handler() implementation, which * will be called will reason code _NANO_ERR_KERNEL_PANIC. * @req K-MISC-004 */ #define k_panic() _k_except_reason(_NANO_ERR_KERNEL_PANIC) /* * private APIs that are utilized by one or more public APIs */ #ifdef CONFIG_MULTITHREADING /** * @internal */ extern void _init_static_threads(void); #else /** * @internal */ #define _init_static_threads() do { } while (false) #endif /** * @internal */ extern bool _is_thread_essential(void); /** * @internal */ extern void _timer_expiration_handler(struct _timeout *t); /* arch/cpu.h may declare an architecture or platform-specific macro * for properly declaring stacks, compatible with MMU/MPU constraints if * enabled */ /** * @brief Obtain an extern reference to a stack * * This macro properly brings the symbol of a thread stack declared * elsewhere into scope. * * @param sym Thread stack symbol name * @req K-MISC-005 */ #define K_THREAD_STACK_EXTERN(sym) extern k_thread_stack_t sym[] #ifdef _ARCH_THREAD_STACK_DEFINE #define K_THREAD_STACK_DEFINE(sym, size) _ARCH_THREAD_STACK_DEFINE(sym, size) #define K_THREAD_STACK_ARRAY_DEFINE(sym, nmemb, size) \ _ARCH_THREAD_STACK_ARRAY_DEFINE(sym, nmemb, size) #define K_THREAD_STACK_LEN(size) _ARCH_THREAD_STACK_LEN(size) #define K_THREAD_STACK_MEMBER(sym, size) _ARCH_THREAD_STACK_MEMBER(sym, size) #define K_THREAD_STACK_SIZEOF(sym) _ARCH_THREAD_STACK_SIZEOF(sym) static inline char *K_THREAD_STACK_BUFFER(k_thread_stack_t *sym) { return _ARCH_THREAD_STACK_BUFFER(sym); } #else /** * @brief Declare a toplevel thread stack memory region * * This declares a region of memory suitable for use as a thread's stack. * * This is the generic, historical definition. Align to STACK_ALIGN and put in * 'noinit' section so that it isn't zeroed at boot * * The declared symbol will always be a k_thread_stack_t which can be passed to * k_thread_create(), but should otherwise not be manipulated. If the buffer * inside needs to be examined, use K_THREAD_STACK_BUFFER(). * * It is legal to precede this definition with the 'static' keyword. * * It is NOT legal to take the sizeof(sym) and pass that to the stackSize * parameter of k_thread_create(), it may not be the same as the * 'size' parameter. Use K_THREAD_STACK_SIZEOF() instead. * * Some arches may round the size of the usable stack region up to satisfy * alignment constraints. K_THREAD_STACK_SIZEOF() will return the aligned * size. * * @param sym Thread stack symbol name * @param size Size of the stack memory region * @req K-TSTACK-001 */ #define K_THREAD_STACK_DEFINE(sym, size) \ struct _k_thread_stack_element __noinit __aligned(STACK_ALIGN) sym[size] /** * @brief Calculate size of stacks to be allocated in a stack array * * This macro calculates the size to be allocated for the stacks * inside a stack array. It accepts the indicated "size" as a parameter * and if required, pads some extra bytes (e.g. for MPU scenarios). Refer * K_THREAD_STACK_ARRAY_DEFINE definition to see how this is used. * * @param size Size of the stack memory region * @req K-TSTACK-001 */ #define K_THREAD_STACK_LEN(size) (size) /** * @brief Declare a toplevel array of thread stack memory regions * * Create an array of equally sized stacks. See K_THREAD_STACK_DEFINE * definition for additional details and constraints. * * This is the generic, historical definition. Align to STACK_ALIGN and put in * 'noinit' section so that it isn't zeroed at boot * * @param sym Thread stack symbol name * @param nmemb Number of stacks to declare * @param size Size of the stack memory region * @req K-TSTACK-001 */ #define K_THREAD_STACK_ARRAY_DEFINE(sym, nmemb, size) \ struct _k_thread_stack_element __noinit \ __aligned(STACK_ALIGN) sym[nmemb][K_THREAD_STACK_LEN(size)] /** * @brief Declare an embedded stack memory region * * Used for stacks embedded within other data structures. Use is highly * discouraged but in some cases necessary. For memory protection scenarios, * it is very important that any RAM preceding this member not be writable * by threads else a stack overflow will lead to silent corruption. In other * words, the containing data structure should live in RAM owned by the kernel. * * @param sym Thread stack symbol name * @param size Size of the stack memory region * @req K-TSTACK-001 */ #define K_THREAD_STACK_MEMBER(sym, size) \ struct _k_thread_stack_element __aligned(STACK_ALIGN) sym[size] /** * @brief Return the size in bytes of a stack memory region * * Convenience macro for passing the desired stack size to k_thread_create() * since the underlying implementation may actually create something larger * (for instance a guard area). * * The value returned here is not guaranteed to match the 'size' parameter * passed to K_THREAD_STACK_DEFINE and may be larger. * * @param sym Stack memory symbol * @return Size of the stack * @req K-TSTACK-001 */ #define K_THREAD_STACK_SIZEOF(sym) sizeof(sym) /** * @brief Get a pointer to the physical stack buffer * * Convenience macro to get at the real underlying stack buffer used by * the CPU. Guaranteed to be a character pointer of size K_THREAD_STACK_SIZEOF. * This is really only intended for diagnostic tools which want to examine * stack memory contents. * * @param sym Declared stack symbol name * @return The buffer itself, a char * * @req K-TSTACK-001 */ static inline char *K_THREAD_STACK_BUFFER(k_thread_stack_t *sym) { return (char *)sym; } #endif /* _ARCH_DECLARE_STACK */ /** * @defgroup mem_domain_apis Memory domain APIs * @ingroup kernel_apis * @{ */ /** * @def K_MEM_PARTITION_DEFINE * @brief Used to declare a memory partition * @req K-MP-001 */ #ifdef _ARCH_MEM_PARTITION_ALIGN_CHECK #define K_MEM_PARTITION_DEFINE(name, start, size, attr) \ _ARCH_MEM_PARTITION_ALIGN_CHECK(start, size); \ struct k_mem_partition name =\ { (u32_t)start, size, attr} #else #define K_MEM_PARTITION_DEFINE(name, start, size, attr) \ struct k_mem_partition name =\ { (u32_t)start, size, attr} #endif /* _ARCH_MEM_PARTITION_ALIGN_CHECK */ /* memory partition */ struct k_mem_partition { /* start address of memory partition */ u32_t start; /* size of memory partition */ u32_t size; #if defined(CONFIG_MEMORY_PROTECTION) /* attribute of memory partition */ k_mem_partition_attr_t attr; #endif /* CONFIG_MEMORY_PROTECTION */ }; /* memory domain */ struct k_mem_domain { #ifdef CONFIG_USERSPACE /* partitions in the domain */ struct k_mem_partition partitions[CONFIG_MAX_DOMAIN_PARTITIONS]; #endif /* CONFIG_USERSPACE */ /* domain q */ sys_dlist_t mem_domain_q; /* number of partitions in the domain */ u8_t num_partitions; }; /** * @brief Initialize a memory domain. * * Initialize a memory domain with given name and memory partitions. * * @param domain The memory domain to be initialized. * @param num_parts The number of array items of "parts" parameter. * @param parts An array of pointers to the memory partitions. Can be NULL * if num_parts is zero. * @req K-MD-001 */ extern void k_mem_domain_init(struct k_mem_domain *domain, u8_t num_parts, struct k_mem_partition *parts[]); /** * @brief Destroy a memory domain. * * Destroy a memory domain. * * @param domain The memory domain to be destroyed. * @req K-MD-001 */ extern void k_mem_domain_destroy(struct k_mem_domain *domain); /** * @brief Add a memory partition into a memory domain. * * Add a memory partition into a memory domain. * * @param domain The memory domain to be added a memory partition. * @param part The memory partition to be added * @req K-MD-001 */ extern void k_mem_domain_add_partition(struct k_mem_domain *domain, struct k_mem_partition *part); /** * @brief Remove a memory partition from a memory domain. * * Remove a memory partition from a memory domain. * * @param domain The memory domain to be removed a memory partition. * @param part The memory partition to be removed * @req K-MD-001 */ extern void k_mem_domain_remove_partition(struct k_mem_domain *domain, struct k_mem_partition *part); /** * @brief Add a thread into a memory domain. * * Add a thread into a memory domain. * * @param domain The memory domain that the thread is going to be added into. * @param thread ID of thread going to be added into the memory domain. * * @req K-MD-001 */ extern void k_mem_domain_add_thread(struct k_mem_domain *domain, k_tid_t thread); /** * @brief Remove a thread from its memory domain. * * Remove a thread from its memory domain. * * @param thread ID of thread going to be removed from its memory domain. * @req K-MD-001 */ extern void k_mem_domain_remove_thread(k_tid_t thread); /** @} */ /** * @brief Emit a character buffer to the console device * * @param c String of characters to print * @param n The length of the string * * @req K-MISC-006 */ __syscall void k_str_out(char *c, size_t n); /** * @brief Start a numbered CPU on a MP-capable system * This starts and initializes a specific CPU. The main thread on * startup is running on CPU zero, other processors are numbered * sequentially. On return from this function, the CPU is known to * have begun operating and will enter the provided function. Its * interrupts will be initialized but disabled such that irq_unlock() * with the provided key will work to enable them. * * Normally, in SMP mode this function will be called by the kernel * initialization and should not be used as a user API. But it is * defined here for special-purpose apps which want Zephyr running on * one core and to use others for design-specific processing. * * @param cpu_num Integer number of the CPU * @param stack Stack memory for the CPU * @param sz Stack buffer size, in bytes * @param fn Function to begin running on the CPU. First argument is * an irq_unlock() key. * @param arg Untyped argument to be passed to "fn" */ extern void _arch_start_cpu(int cpu_num, k_thread_stack_t *stack, int sz, void (*fn)(int key, void *data), void *arg); #ifdef __cplusplus } #endif #include #include #endif /* !_ASMLANGUAGE */ #endif /* ZEPHYR_INCLUDE_KERNEL_H_ */