/* * Copyright (c) 2016, Wind River Systems, Inc. * * SPDX-License-Identifier: Apache-2.0 */ /** * @file * * @brief Public legacy kernel APIs. */ #ifndef _legacy__h_ #define _legacy__h_ #include #include #include #include #include #include /* nanokernel/microkernel execution context types */ #define NANO_CTX_ISR (K_ISR) #define NANO_CTX_FIBER (K_COOP_THREAD) #define NANO_CTX_TASK (K_PREEMPT_THREAD) /* timeout special values */ #define TICKS_UNLIMITED (K_FOREVER) #define TICKS_NONE (K_NO_WAIT) /* microkernel object return codes */ #define RC_OK 0 #define RC_FAIL 1 #define RC_TIME 2 #define RC_ALIGNMENT 3 #define RC_INCOMPLETE 4 #define ANYTASK K_ANY /* end-of-list, mostly used for semaphore groups */ #define ENDLIST K_END /* pre-defined task groups */ #define K_TASK_GROUP_EXE 0x1 #define K_TASK_GROUP_SYS 0x2 #define K_TASK_GROUP_FPU 0x4 /* the following is for x86 architecture only */ #define K_TASK_GROUP_SSE 0x8 /* pipe amount of content to receive (0+, 1+, all) */ typedef enum { _0_TO_N = 0x0, _1_TO_N = 0x1, _ALL_N = 0x2, } K_PIPE_OPTION; #define kpriority_t uint32_t static inline int32_t _ticks_to_ms(int32_t ticks) { return (ticks == TICKS_UNLIMITED) ? K_FOREVER : __ticks_to_ms(ticks); } static inline int _error_to_rc(int err) { return err == 0 ? RC_OK : err == -EAGAIN ? RC_TIME : RC_FAIL; } static inline int _error_to_rc_no_timeout(int err) { return err == 0 ? RC_OK : RC_FAIL; } /* tasks/fibers/scheduler */ #define ktask_t k_tid_t #define nano_thread_id_t k_tid_t typedef void (*nano_fiber_entry_t)(int i1, int i2); typedef int nano_context_type_t; #define _MDEF_THREAD_DEFINE(name, stack_size, \ entry, p1, p2, p3, \ abort, prio, groups) \ char __noinit __stack _k_thread_obj_##name[stack_size]; \ struct _static_thread_data _k_thread_data_##name __aligned(4) \ _GENERIC_SECTION(._static_thread_data.static.mdef) = \ _THREAD_INITIALIZER(_k_thread_obj_##name, stack_size, \ entry, p1, p2, p3, prio, 0, K_FOREVER, \ abort, groups) /** * @defgroup legacy_apis Legacy API * @ingroup kernel_apis * @{ */ /** * @brief Define a private microkernel task. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This declares and initializes a private task. The new task * can be passed to the microkernel task functions. * * @param name Name of the task. * @param priority Priority of task. * @param entry Entry function. * @param stack_size Size of stack (in bytes) * @param groups Groups this task belong to. */ #define DEFINE_TASK(name, priority, entry, stack_size, groups) \ extern void entry(void); \ char __noinit __stack _k_thread_obj_##name[stack_size]; \ struct _static_thread_data _k_thread_data_##name __aligned(4) \ __in_section(_static_thread_data, static, name) = \ _THREAD_INITIALIZER(_k_thread_obj_##name, stack_size, \ entry, NULL, NULL, NULL, \ priority, 0, K_FOREVER, \ NULL, (uint32_t)(groups)); \ k_tid_t const name = (k_tid_t)_k_thread_obj_##name /** * @brief Return the ID of the currently executing thread. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine returns a pointer to the thread control block of the currently * executing thread. It is cast to a nano_thread_id_t for public use. * * @return The ID of the currently executing thread. */ static inline __deprecated nano_thread_id_t sys_thread_self_get(void) { return k_current_get(); } /** * @brief Cause the currently executing thread to busy wait. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine causes the current task or fiber to execute a "do nothing" * loop for a specified period of time. * * @warning This routine utilizes the system clock, so it must not be invoked * until the system clock is fully operational or while interrupts * are locked. * * @param usec_to_wait Number of microseconds to busy wait. * * @return N/A */ static inline __deprecated void sys_thread_busy_wait(uint32_t usec_to_wait) { k_busy_wait(usec_to_wait); } /** * @brief Return the type of the current execution context. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine returns the type of execution context currently executing. * * @return The type of the current execution context. * @retval NANO_CTX_ISR (0): executing an interrupt service routine. * @retval NANO_CTX_FIBER (1): current thread is a fiber. * @retval NANO_CTX_TASK (2): current thread is a task. */ extern __deprecated int sys_execution_context_type_get(void); /** * @brief Initialize and start a fiber. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine initializes and starts a fiber. It can be called from * either a fiber or a task. When this routine is called from a * task, the newly created fiber will start executing immediately. * * @internal * Given that this routine is _not_ ISR-callable, the following code is used * to differentiate between a task and fiber: * * if ((_kernel.current->flags & TASK) == TASK) * * Given that the _fiber_start() primitive is not considered real-time * performance critical, a runtime check to differentiate between a calling * task or fiber is performed to conserve footprint. * @endinternal * * @param stack Pointer to the stack space. * @param stack_size Stack size in bytes. * @param entry Fiber entry. * @param arg1 1st entry point parameter. * @param arg2 2nd entry point parameter. * @param prio The fiber's priority. * @param options Not used currently. * * @return nanokernel thread identifier */ static inline __deprecated nano_thread_id_t fiber_start(char *stack, unsigned stack_size, nano_fiber_entry_t entry, int arg1, int arg2, unsigned prio, unsigned options) { return k_thread_spawn(stack, stack_size, (k_thread_entry_t)entry, (void *)(intptr_t)arg1, (void *)(intptr_t)arg2, NULL, K_PRIO_COOP(prio), options, 0); } /** * @brief Initialize and start a fiber from a fiber. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like fiber_start(), but may only be called from a fiber. * * @sa fiber_start */ #define fiber_fiber_start fiber_start /** * @brief Initialize and start a fiber from a task. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like fiber_start(), but may only be called from a task. * * @sa fiber_start */ #define task_fiber_start fiber_start /** * @brief Fiber configuration structure. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Parameters such as stack size and fiber priority are often * user configurable. This structure makes it simple to specify such a * configuration. */ struct fiber_config { char *stack; unsigned stack_size; unsigned prio; }; /** * @brief Start a fiber based on a @ref fiber_config. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine can be called from either a fiber or a task. * * @param config Pointer to fiber configuration structure * @param entry Fiber entry. * @param arg1 1st entry point parameter. * @param arg2 2nd entry point parameter. * @param options Not used currently. * * @return thread ID */ #define fiber_start_config(config, entry, arg1, arg2, options) \ fiber_start(config->stack, config->stack_size, \ entry, arg1, arg2, \ config->prio, options) /** * @brief Start a fiber based on a @ref fiber_config, from fiber context. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like fiber_start_config(), but may only be called from a fiber. * * @sa fiber_start_config() */ #define fiber_fiber_start_config fiber_start_config /** * @brief Start a fiber based on a @ref fiber_config, from task context. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like fiber_start_config(), but may only be called from a task. * * @sa fiber_start_config() */ #define task_fiber_start_config fiber_start_config /** * @brief Start a fiber while delaying its execution. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param stack Pointer to the stack space. * @param stack_size_in_bytes Stack size in bytes. * @param entry_point The fiber's entry point. * @param param1 1st entry point parameter. * @param param2 2nd entry point parameter. * @param priority The fiber's priority. * @param options Not used currently. * @param timeout_in_ticks Timeout duration in ticks. * * @return A handle potentially used to cancel the delayed start. */ static inline __deprecated nano_thread_id_t fiber_delayed_start(char *stack, unsigned int stack_size_in_bytes, nano_fiber_entry_t entry_point, int param1, int param2, unsigned int priority, unsigned int options, int32_t timeout_in_ticks) { return k_thread_spawn(stack, stack_size_in_bytes, (k_thread_entry_t)entry_point, (void *)(intptr_t)param1, (void *)(intptr_t)param2, NULL, K_PRIO_COOP(priority), options, _ticks_to_ms(timeout_in_ticks)); } /** * @brief Start a fiber while delaying its execution. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like fiber_delayed_start(), but may only be called from a fiber. * * @sa fiber_delayed_start */ #define fiber_fiber_delayed_start fiber_delayed_start /** * @brief Start a fiber while delaying its execution. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like fiber_delayed_start(), but may only be called from a task. * * @sa fiber_delayed_start */ #define task_fiber_delayed_start fiber_delayed_start /** * @brief Cancel a delayed fiber start. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param handle The handle returned when starting the delayed fiber. * * @return N/A */ static inline __deprecated void fiber_delayed_start_cancel(nano_thread_id_t handle) { k_thread_cancel(handle); } /** * @brief Cancel a delayed fiber start from a fiber * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like fiber_delayed_start_cancel(), but may only be called from a fiber. * * @sa fiber_delayed_start_cancel */ #define fiber_fiber_delayed_start_cancel fiber_delayed_start_cancel /** * @brief Cancel a delayed fiber start from a task * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like fiber_delayed_start_cancel(), but may only be called from a fiber. * * @sa fiber_delayed_start_cancel */ #define task_fiber_delayed_start_cancel fiber_delayed_start_cancel /** * @brief Yield the current fiber. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Calling this routine results in the current fiber yielding to * another fiber of the same or higher priority. If there are no * other runnable fibers of the same or higher priority, the * routine will return immediately. * * This routine can only be called from a fiber. * * @return N/A */ static inline __deprecated void fiber_yield(void) { k_yield(); } /** * @brief Abort the currently executing fiber. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine aborts the currently executing fiber. An abort can occur * because of one of three reasons: * - The fiber has explicitly aborted itself by calling this routine. * - The fiber has implicitly aborted itself by returning from its entry point. * - The fiber has encountered a fatal exception. * * This routine can only be called from a fiber. * * @return N/A */ static inline __deprecated void fiber_abort(void) { k_thread_abort(k_current_get()); } extern void __deprecated _legacy_sleep(int32_t ticks); /** * @brief Put the current fiber to sleep. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine puts the currently running fiber to sleep * for the number of system ticks passed in the * @a timeout_in_ticks parameter. * * @param timeout_in_ticks Number of system ticks the fiber sleeps. * * @return N/A */ #define fiber_sleep _legacy_sleep /** * @brief Put the task to sleep. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine puts the currently running task to sleep for the number * of system ticks passed in the @a timeout_in_ticks parameter. * * @param timeout_in_ticks Number of system ticks the task sleeps. * * @warning A value of TICKS_UNLIMITED is considered invalid and may result in * unexpected behavior. * * @return N/A * * @sa TICKS_UNLIMITED */ #define task_sleep _legacy_sleep /** * @brief Wake the specified fiber from sleep * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine is a convenience wrapper for the execution of context-specific * APIs. It is helpful when the exact execution context is not known. However, * it should be avoided when the context is known up-front to avoid * unnecessary overhead. * * @param fiber Identifies fiber to wake * * @return N/A */ static inline __deprecated void fiber_wakeup(nano_thread_id_t fiber) { k_wakeup(fiber); } /** * @brief Wake the specified fiber from sleep * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like fiber_wakeup(), but may only be called from an ISR. * * @sa fiber_wakeup */ #define isr_fiber_wakeup fiber_wakeup /** * @brief Wake the specified fiber from sleep * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like fiber_wakeup, but may only be called from a fiber. * * @sa fiber_wakeup */ #define fiber_fiber_wakeup fiber_wakeup /** * @brief Wake the specified fiber from sleep * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like fiber_wakeup, but may only be called from a task. * * @sa fiber_wakeup */ #define task_fiber_wakeup fiber_wakeup /** * @brief Yield the CPU to another task. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine yields the processor to the next-equal priority runnable * task. With task_yield(), the effect of round-robin scheduling is * possible. When no task of equal priority is runnable, no task switch * occurs, and the calling task resumes execution. * * @return N/A */ #define task_yield fiber_yield /** * @brief Set the priority of a task. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine changes the priority of the specified task. * * The call has immediate effect. When the calling task no longer is the * highest-priority runnable task, a task switch occurs. * * Priority can be assigned in the range 0 to 62, where 0 is the * highest priority. * * @param task Task whose priority is to be set. * @param prio New priority. * * @return N/A */ static inline __deprecated void task_priority_set(ktask_t task, kpriority_t prio) { k_thread_priority_set(task, (int)prio); } /** * @brief Set the entry point of a task. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine sets the entry point of a task to a given routine. It is * needed only when an entry point differs from what is set in the project * file. To have any effect, it must be called before task_start(), and it * cannot work with members of the EXE group or with any group that starts * automatically on application loading. * * The routine is executed when the task is started. * * @param task Task to operate on. * @param entry Entry point. * * @return N/A */ static inline __deprecated void task_entry_set(ktask_t task, void (*entry)(void)) { __ASSERT(0, "task_entry_set is unsupported"); ARG_UNUSED(task); ARG_UNUSED(entry); /* This is impractical to implement in the new kernel and there are * workarounds. * 1) Set entry point in MDEF files * 2) Set entry point in DEFINE_TASK macro * 3) Set entry point in k_thread_spawn() invocation */ } /** * @brief Install an abort handler. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine installs an abort handler for the calling task. * * The abort handler runs when the calling task is aborted by a _TaskAbort() * or task_group_abort() call. * * Each call to task_abort_handler_set() replaces the previously-installed * handler. * * To remove an abort handler, set the parameter to NULL as below: * task_abort_handler_set (NULL) * * @param handler Abort handler. * * @return N/A */ extern void __deprecated task_abort_handler_set(void (*handler)(void)); /** * @brief Process an "offload" request * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * The routine places the @a func into the work queue. This allows * the task to execute a routine uninterrupted by other tasks. * * Note: this routine can be invoked only from a task. * For the routine to work, the scheduler must be unlocked. * * @param func function to call * @param argp function arguments * * @return result of @a func call */ extern int __deprecated task_offload_to_fiber(int (*func)(), void *argp); /** * @brief Gets task identifier * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @return identifier for current task */ static inline __deprecated ktask_t task_id_get(void) { return k_current_get(); } /** * @brief Gets task priority * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @return priority of current task */ static inline __deprecated kpriority_t task_priority_get(void) { return (kpriority_t)(k_thread_priority_get(k_current_get())); } /** * @brief Abort a task * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param task Task to abort * * @return N/A */ static inline __deprecated void task_abort(ktask_t task) { k_thread_abort(task); } /** * @brief Suspend a task * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param task Task to suspend * * @return N/A */ static inline __deprecated void task_suspend(ktask_t task) { k_thread_suspend(task); } /** * @brief Resume a task * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param task Task to resume * * @return N/A */ static inline __deprecated void task_resume(ktask_t task) { k_thread_resume(task); } /** * @brief Start a task * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param task Task to start * * @return N/A */ extern void __deprecated task_start(ktask_t task); /** * @brief Set time-slicing period and scope * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine controls how task time slicing is performed by the task * scheduler; it specifes the maximum time slice length (in ticks) and * the highest priority task level for which time slicing is performed. * * To enable time slicing, a non-zero time slice length must be specified. * The task scheduler then ensures that no executing task runs for more than * the specified number of ticks before giving other tasks of that priority * a chance to execute. (However, any task whose priority is higher than the * specified task priority level is exempted, and may execute as long as * desired without being pre-empted due to time slicing.) * * Time slicing limits only the maximum amount of time a task may continuously * execute. Once the scheduler selects a task for execution, there is no minimum * guaranteed time the task will execute before tasks of greater or equal * priority are scheduled. * * When the currently-executing task is the only one of that priority eligible * for execution, this routine has no effect; the task is immediately * rescheduled after the slice period expires. * * To disable timeslicing, call the API with both parameters set to zero. * * @param ticks Maximum time slice length in ticks * @param priority Highest priority task level for which time slicing is * performed * * @return N/A */ static inline void __deprecated sys_scheduler_time_slice_set(int32_t ticks, kpriority_t priority) { k_sched_time_slice_set(_ticks_to_ms(ticks), (int)priority); } extern void _k_thread_group_op(uint32_t groups, void (*func)(struct tcs *)); /** * @brief Get task groups for task * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @return task groups associated with current task */ static inline __deprecated uint32_t task_group_mask_get(void) { extern uint32_t _k_thread_group_mask_get(struct tcs *thread); return _k_thread_group_mask_get(k_current_get()); } /** * @brief Get task groups for task * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @return task groups associated with current task */ #define isr_task_group_mask_get task_group_mask_get /** * @brief Add task to task group(s) * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param groups Task Groups * * @return N/A */ static inline __deprecated void task_group_join(uint32_t groups) { extern void _k_thread_group_join(uint32_t groups, struct tcs *thread); _k_thread_group_join(groups, k_current_get()); } /** * @brief Remove task from task group(s) * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param groups Task Groups * * @return N/A */ static inline __deprecated void task_group_leave(uint32_t groups) { extern void _k_thread_group_leave(uint32_t groups, struct tcs *thread); _k_thread_group_leave(groups, k_current_get()); } /** * @brief Start one or more task groups * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param groups Task groups to start * * @return N/A */ static inline __deprecated void task_group_start(uint32_t groups) { extern void _k_thread_single_start(struct tcs *thread); return _k_thread_group_op(groups, _k_thread_single_start); } /** * @brief Suspend one or more task groups * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param groups Task groups to suspend * * @return N/A */ static inline __deprecated void task_group_suspend(uint32_t groups) { extern void _k_thread_single_suspend(struct tcs *thread); return _k_thread_group_op(groups, _k_thread_single_suspend); } /** * @brief Resume one or more task groups * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param groups Task groups to resume * * @return N/A */ static inline __deprecated void task_group_resume(uint32_t groups) { extern void _k_thread_single_resume(struct tcs *thread); return _k_thread_group_op(groups, _k_thread_single_resume); } /** * @brief Abort one or more task groups * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param groups Task groups to abort * * @return N/A */ static inline __deprecated void task_group_abort(uint32_t groups) { extern void _k_thread_single_abort(struct tcs *thread); return _k_thread_group_op(groups, _k_thread_single_abort); } /** * @brief Get task identifier * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @return identifier for current task */ #define isr_task_id_get task_id_get /** * @brief Get task priority * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @return priority of current task */ #define isr_task_priority_get task_priority_get /* mutexes */ #define kmutex_t struct k_mutex * /** * @brief Lock mutex. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine locks mutex @a mutex. When the mutex is locked by another task, * the routine will either wait until it becomes available, or until a specified * time limit is reached. * * A task is permitted to lock a mutex it has already locked; in such a case, * this routine immediately succeeds. * * @param mutex Mutex name. * @param timeout Determine the action to take when the mutex is already locked. * For TICKS_NONE, return immediately. * For TICKS_UNLIMITED, wait as long as necessary. * Otherwise, wait up to the specified number of ticks before timing out. * * @retval RC_OK Successfully locked mutex. * @retval RC_TIME Timed out while waiting for mutex. * @retval RC_FAIL Failed to immediately lock mutex when * @a timeout = TICKS_NONE. * * @sa TICKS_NONE, TICKS_UNLIMITED */ static inline __deprecated int task_mutex_lock(kmutex_t mutex, int32_t timeout) { return _error_to_rc(k_mutex_lock(mutex, _ticks_to_ms(timeout))); } /** * @brief Unlock mutex. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine unlocks mutex @a mutex. The mutex must already be locked by the * requesting task. * * The mutex cannot be claimed by another task until it has been unlocked by * the requesting task as many times as it was locked by that task. * * @param mutex Mutex name. * * @return N/A */ static inline __deprecated void task_mutex_unlock(kmutex_t mutex) { k_mutex_unlock(mutex); } /** * @brief Define a private mutex. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param name Mutex name. */ #define DEFINE_MUTEX(name) \ K_MUTEX_DEFINE(_k_mutex_obj_##name); \ struct k_mutex * const name = &_k_mutex_obj_##name /* semaphores */ #define nano_sem k_sem #define ksem_t struct k_sem * /** * @brief Initialize a nanokernel semaphore object. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This function initializes a nanokernel semaphore object structure. After * initialization, the semaphore count is 0. * * It can be called from either a fiber or task. * * @param sem Pointer to a nano_sem structure. * * @return N/A */ static inline __deprecated void nano_sem_init(struct nano_sem *sem) { k_sem_init(sem, 0, UINT_MAX); } /** * @brief Give a nanokernel semaphore. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine performs a "give" operation on a nanokernel sempahore object. * * It is also a convenience wrapper for the execution of context-specific * APIs and helpful when the exact execution context is not known. However, * it should be avoided when the context is known up-front to avoid unnecessary * overhead. * * @param sem Pointer to a nano_sem structure. * * @return N/A */ static inline __deprecated void nano_sem_give(struct nano_sem *sem) { k_sem_give(sem); } /** * @brief Give a nanokernel semaphore (no context switch). * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_sem_give(), but may only be called from an ISR. A fiber * pending on the semaphore object will be made ready, but will NOT be * scheduled to execute. * * @param sem Pointer to a nano_sem structure. * * @sa nano_sem_give */ #define nano_isr_sem_give nano_sem_give /** * @brief Give a nanokernel semaphore (no context switch). * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_sem_give(), but may only be called from a fiber. * * @param sem Pointer to a nano_sem structure. * * @sa nano_sem_give */ #define nano_fiber_sem_give nano_sem_give /** * @brief Give a nanokernel semaphore. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_sem_give(), but may only be called from a task. A fiber pending * on the semaphore object will be made ready, and will preempt the running * task immediately. * * @param sem Pointer to a nano_sem structure. * * @sa nano_sem_give */ #define nano_task_sem_give nano_sem_give /** * @brief Take a nanokernel semaphore, poll/pend if not available. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine performs a "give" operation on a nanokernel sempahore object. * * It is also a convenience wrapper for the execution of context-specific * APIs and is helpful when the exact execution context is not known. However, * it should be avoided when the context is known up-front to avoid unnecessary * overhead. * * @param sem Pointer to a nano_sem structure. * @param timeout_in_ticks Determines the action to take when the semaphore is * unavailable. * For TICKS_NONE, return immediately. * For TICKS_UNLIMITED, wait as long as necessary. * Otherwise, wait up to the specified number of ticks before timing * out. * * @warning If it is to be called from the context of an ISR, then @a * timeout_in_ticks must be set to TICKS_NONE. * * @retval 1 When semaphore is available * @retval 0 Otherwise * * @sa TICKS_NONE, TICKS_UNLIMITED */ static inline __deprecated int nano_sem_take(struct nano_sem *sem, int32_t timeout_in_ticks) { int32_t ms = _ticks_to_ms(timeout_in_ticks); return k_sem_take((struct k_sem *)sem, ms) == 0 ? 1 : 0; } /** * @brief Take a nanokernel semaphore, fail if unavailable. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_sem_take(), but must only be called from an ISR with a timeout * of TICKS_NONE. * * @sa nano_sem_take */ #define nano_isr_sem_take nano_sem_take /** * @brief Take a nanokernel semaphore, wait or fail if unavailable. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_sem_take(), but may only be called from a fiber. * * @sa nano_sem_take */ #define nano_fiber_sem_take nano_sem_take /** * @brief Take a nanokernel semaphore, fail if unavailable. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_sem_take(), but may only be called from a task. * * @sa nano_sem_take */ #define nano_task_sem_take nano_sem_take /** * @brief Give semaphore from an ISR. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine gives semaphore @a sem from an ISR, rather than a task. * * @param sem Semaphore name. * * @return N/A */ #define isr_sem_give nano_sem_give /** * @brief Give semaphore from a fiber. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine gives semaphore @a sem from a fiber, rather than a task. * * @param sem Semaphore name. * * @return N/A */ #define fiber_sem_give nano_sem_give /** * @brief Give semaphore. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine gives semaphore @a sem. * * @param sem Semaphore name. * * @return N/A */ #define task_sem_give nano_sem_give /** * * @brief Take a semaphore or fail. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine takes the semaphore @a sem. If the semaphore's count is * zero the routine immediately returns a failure indication. * * @param sem Semaphore name. * @param timeout Determines the action to take when the semaphore is * unavailable. * For TICKS_NONE, return immediately. * For TICKS_UNLIMITED, wait as long as necessary. * Otherwise, wait up to the specified number of ticks before timing out. * * @retval RC_OK Successfully took semaphore * @retval RC_TIME Timed out while waiting for semaphore * @retval RC_FAIL Failed to immediately take semaphore when * @a timeout = TICKS_NONE * * @sa TICKS_NONE, TICKS_UNLIMITED */ static inline __deprecated int task_sem_take(ksem_t sem, int32_t timeout) { return _error_to_rc(k_sem_take(sem, _ticks_to_ms(timeout))); } /** * @brief Reset the semaphore's count. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine resets the count of the semaphore @a sem to zero. * * @param sem Semaphore name. * * @return N/A */ static inline __deprecated void task_sem_reset(ksem_t sem) { k_sem_reset(sem); } /** * @brief Read a semaphore's count. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine reads the current count of the semaphore @a sem. * * @param sem Semaphore name. * * @return Semaphore count. */ static inline __deprecated int task_sem_count_get(ksem_t sem) { return k_sem_count_get(sem); } /** * @brief Read a nanokernel semaphore's count. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine reads the current count of the semaphore @a sem. * * @param sem Pointer to a nano_sem structure. * * @return Semaphore count. */ static inline __deprecated int nano_sem_count_get(ksem_t sem) { return k_sem_count_get(sem); } #ifdef CONFIG_SEMAPHORE_GROUPS /* * @internal Take the first available semaphore * * Given a list of semaphore pointers, this routine will attempt to take one * of them, waiting up to a maximum of @a timeout ms to do so. The taken * semaphore is identified by @a sem (set to NULL on error). * * Be aware that the more semaphores specified in the group, the more stack * space is required by the waiting thread. * * @param sem_array Array of semaphore pointers terminated by a K_END entry * @param sem Identifies the semaphore that was taken * @param timeout Number of milliseconds to wait if semaphores are unavailable, * or one of the special values K_NO_WAIT and K_FOREVER. * * @retval 0 A semaphore was successfully taken * @retval -EBUSY No semaphore was available (@a timeout = K_NO_WAIT) * @retval -EAGAIN Time out occurred while waiting for semaphore */ extern int k_sem_group_take(struct k_sem *sem_array[], struct k_sem **sem, int32_t timeout); /* * @internal Give all the semaphores in the group * * This routine will give each semaphore in the array of semaphore pointers. * * @param sem_array Array of semaphore pointers terminated by a K_END entry * * @return N/A */ extern void k_sem_group_give(struct k_sem *sem_array[]); /* * @internal Reset the count to zero on each semaphore in the array * * This routine resets the count of each semaphore in the group to zero. * Note that it does NOT have any impact on any thread that might have * been previously pending on any of the semaphores. * * @param sem_array Array of semaphore pointers terminated by a K_END entry * * @return N/A */ extern void k_sem_group_reset(struct k_sem *sem_array[]); typedef ksem_t *ksemg_t; /** * @brief Wait for a semaphore from the semaphore group. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine waits for the @a timeout ticks to take a semaphore from the * semaphore group @a group. * * @param group Array of semaphore names - terminated by ENDLIST. * @param timeout Determines the action to take when the semaphore is * unavailable. * For TICKS_NONE, return immediately. * For TICKS_UNLIMITED, wait as long as necessary. * Otherwise, wait up to the specified number of ticks before timing out. * * @retval Name of the semaphore that was taken if successful. * @retval ENDLIST Otherwise. * * @sa TICKS_NONE, TICKS_UNLIMITED */ static inline __deprecated ksem_t task_sem_group_take(ksemg_t group, int32_t timeout) { struct k_sem *sem; (void)k_sem_group_take(group, &sem, _ticks_to_ms(timeout)); return sem; } /** * @brief Give a group of semaphores. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine gives each semaphore in a semaphore group @a semagroup. * This method is faster than giving the semaphores individually, and * ensures that all the semaphores are given before any waiting tasks run. * * @param semagroup Array of semaphore names - terminated by ENDLIST. * * @return N/A */ static inline __deprecated void task_sem_group_give(ksemg_t group) { k_sem_group_give(group); } /** * @brief Reset a group of semaphores. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine resets the count for each semaphore in the sempahore group * @a semagroup to zero. This method is faster than resetting the semaphores * individually. * * @param semagroup Array of semaphore names - terminated by ENDLIST. * * @return N/A */ static inline __deprecated void task_sem_group_reset(ksemg_t group) { k_sem_group_reset(group); } #endif /** * @brief Define a private microkernel semaphore * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param name Semaphore name. */ #define DEFINE_SEMAPHORE(name) \ K_SEM_DEFINE(_k_sem_obj_##name, 0, UINT_MAX); \ struct k_sem * const name = &_k_sem_obj_##name /* workqueues */ #define nano_work k_work #define work_handler_t k_work_handler_t /** * A workqueue is a fiber that executes @ref nano_work items that are * queued to it. This is useful for drivers which need to schedule * execution of code which might sleep from ISR context. The actual * fiber identifier is not stored in the structure in order to save * space. */ #define nano_workqueue k_work_q /** * @brief An item which can be scheduled on a @ref nano_workqueue with a delay * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. */ #define nano_delayed_work k_delayed_work /** * @brief Initialize work item * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param work Work item to initialize * @param handler Handler to process work item * * @return N/A */ static inline void nano_work_init(struct nano_work *work, work_handler_t handler) { k_work_init(work, handler); } /** * @brief Submit a work item to a workqueue. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This procedure schedules a work item to be processed. * In the case where the work item has already been submitted and is pending * execution, calling this function will result in a no-op. In this case, the * work item must not be modified externally (e.g. by the caller of this * function), since that could cause the work item to be processed in a * corrupted state. * * @param wq Work queue * @param work Work item * * @return N/A */ static inline __deprecated void nano_work_submit_to_queue(struct nano_workqueue *wq, struct nano_work *work) { k_work_submit_to_queue(wq, work); } /** * @brief Start a new workqueue. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine can be called from either fiber or task context. * * @param wq Work queue * @param config Fiber configuration structure * * @return N/A */ static inline __deprecated void nano_workqueue_start(struct nano_workqueue *wq, const struct fiber_config *config) { k_work_q_start(wq, config->stack, config->stack_size, config->prio); } /** * @brief Start a new workqueue. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Call this from task context. * * @sa nano_workqueue_start */ #define nano_task_workqueue_start nano_workqueue_start /** * @brief Start a new workqueue. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Call this from fiber context. * * @sa nano_workqueue_start */ #define nano_fiber_workqueue_start nano_workqueue_start #if CONFIG_SYS_CLOCK_EXISTS /** * @brief Initialize delayed work * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param work Work item * @param handler Handler to process work item * * @return N/A */ static inline __deprecated void nano_delayed_work_init(struct nano_delayed_work *work, work_handler_t handler) { k_delayed_work_init(work, handler); } /** * @brief Submit a delayed work item to a workqueue. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This procedure schedules a work item to be processed after a delay. * Once the delay has passed, the work item is submitted to the work queue: * at this point, it is no longer possible to cancel it. Once the work item's * handler is about to be executed, the work is considered complete and can be * resubmitted. * * Care must be taken if the handler blocks or yield as there is no implicit * mutual exclusion mechanism. Such usage is not recommended and if necessary, * it should be explicitly done between the submitter and the handler. * * @param wq Workqueue to schedule the work item * @param work Delayed work item * @param ticks Ticks to wait before scheduling the work item * * @return 0 in case of success or negative value in case of error. */ static inline __deprecated int nano_delayed_work_submit_to_queue(struct nano_workqueue *wq, struct nano_delayed_work *work, int ticks) { return k_delayed_work_submit_to_queue(wq, work, _ticks_to_ms(ticks)); } /** * @brief Cancel a delayed work item * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This procedure cancels a scheduled work item. If the work has been completed * or is idle, this will do nothing. The only case where this can fail is when * the work has been submitted to the work queue, but the handler has not run * yet. * * @param work Delayed work item to be canceled * * @return 0 in case of success or negative value in case of error. */ static inline __deprecated int nano_delayed_work_cancel(struct nano_delayed_work *work) { return k_delayed_work_cancel(work); } #endif /** * @brief Submit a work item to the system workqueue. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @ref nano_work_submit_to_queue * * When using the system workqueue it is not recommended to block or yield * on the handler since its fiber is shared system wide it may cause * unexpected behavior. */ static inline __deprecated void nano_work_submit(struct nano_work *work) { k_work_submit(work); } #if CONFIG_SYS_CLOCK_EXISTS /** * @brief Submit a delayed work item to the system workqueue. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @ref nano_delayed_work_submit_to_queue * * When using the system workqueue it is not recommended to block or yield * on the handler since its fiber is shared system wide it may cause * unexpected behavior. */ #define nano_delayed_work_submit(work, ticks) \ nano_delayed_work_submit_to_queue(&k_sys_work_q, work, ticks) #endif /** @cond INTERNAL_HIDDEN */ /* events */ #define kevent_t const struct k_alert * typedef int (*kevent_handler_t)(int event); /** @endcond */ /** * @brief Signal an event from an ISR. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine does @em not validate the specified event number. * * @param event Event to signal. * * @return N/A */ #define isr_event_send task_event_send /** * @brief Signal an event from a fiber. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine does @em not validate the specified event number. * * @param event Event to signal. * * @return N/A */ #define fiber_event_send task_event_send /** * @brief Set event handler request. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine specifies the event handler that runs in the context of the * microkernel server fiber when the associated event is signaled. Specifying * a non-NULL handler installs a new handler, while specifying a NULL event * handler removes the existing event handler. * * A new event handler cannot be installed if one already exists for that event. * The old handler must be removed first. However, the NULL event handler can be * replaced with itself. * * @param legacy_event Event upon which to register. * @param handler Function pointer to handler. * * @retval RC_FAIL If an event handler exists or the event number is invalid. * @retval RC_OK Otherwise. */ static inline __deprecated int task_event_handler_set(kevent_t legacy_event, kevent_handler_t handler) { struct k_alert *alert = (struct k_alert *)legacy_event; if ((alert->handler != NULL) && (handler != NULL)) { /* can't overwrite an existing event handler */ return RC_FAIL; } alert->handler = (k_alert_handler_t)handler; return RC_OK; } /** * @brief Signal an event request. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine signals the specified event from a task. If an event handler * is installed for that event, it will run. If no event handler is installed, * any task waiting on the event is released. * * @param legacy_event Event to signal. * * @retval RC_FAIL If the event number is invalid. * @retval RC_OK Otherwise. */ static inline __deprecated int task_event_send(kevent_t legacy_event) { k_alert_send((struct k_alert *)legacy_event); return RC_OK; } /** * @brief Test for an event request with timeout. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine tests an event to see if it has been signaled. * * @param legacy_event Event to test. * @param timeout Determines the action to take when the event has not yet * been signaled. * For TICKS_NONE, return immediately. * For TICKS_UNLIMITED, wait as long as necessary. * Otherwise, wait up to the specified number of ticks before * timing out. * * @retval RC_OK Successfully received signaled event * @retval RC_TIME Timed out while waiting for signaled event * @retval RC_FAIL Failed to immediately receive signaled event when * timeout = TICKS_NONE */ static inline __deprecated int task_event_recv(kevent_t legacy_event, int32_t timeout) { return _error_to_rc(k_alert_recv((struct k_alert *)legacy_event, _ticks_to_ms(timeout))); } /** * @brief Define a private microkernel event * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This declares and initializes a private event. The new event * can be passed to the microkernel event functions. * * @param name Name of the event * @param event_handler Function to handle the event (can be NULL) */ #define DEFINE_EVENT(name, event_handler) \ K_ALERT_DEFINE(_k_event_obj_##name, event_handler, 1); \ struct k_alert * const name = &(_k_event_obj_##name) /* memory maps */ #define kmemory_map_t struct k_mem_slab * /** * @brief Allocate memory map block. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine allocates a block from memory map @a map, and saves the * block's address in the area indicated by @a mptr. When no block is available, * the routine waits until either one can be allocated, or until the specified * time limit is reached. * * @param map Memory map name. * @param mptr Pointer to memory block address area. * @param timeout Determines the action to take when the memory map is * exhausted. * For TICKS_NONE, return immediately. * For TICKS_UNLIMITED, wait as long as necessary. * Otherwise, wait up to the specified number of ticks before timing out. * * @retval RC_OK Successfully allocated memory block. * @retval RC_TIME Timed out while waiting for memory block. * @retval RC_FAIL Failed to immediately allocate memory block when * @a timeout = TICKS_NONE. * * @sa TICKS_NONE, TICKS_UNLIMITED */ static inline __deprecated int task_mem_map_alloc(kmemory_map_t map, void **mptr, int32_t timeout) { return _error_to_rc(k_mem_slab_alloc(map, mptr, _ticks_to_ms(timeout))); } /** * @brief Return memory slab block. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine returns a block to the specified memory slab. * * @param m Memory slab name. * @param p Memory block address. * * @return N/A */ static inline __deprecated void task_mem_map_free(kmemory_map_t m, void **p) { k_mem_slab_free(m, p); } /** * @brief Read the number of used blocks in a memory map. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine returns the number of blocks in use for the memory map. * * @param map Memory map name. * * @return Number of used blocks. */ static inline __deprecated int task_mem_map_used_get(kmemory_map_t map) { return (int)k_mem_slab_num_used_get(map); } /** * @brief Define a private microkernel memory map. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param name Memory map name. * @param map_num_blocks Number of blocks. * @param map_block_size Size of each block, in bytes. */ #define DEFINE_MEM_MAP(name, map_num_blocks, map_block_size) \ K_MEM_SLAB_DEFINE(_k_mem_map_obj_##name, map_block_size, \ map_num_blocks, 4); \ struct k_mem_slab *const name = &_k_mem_map_obj_##name /* memory pools */ #define k_block k_mem_block #define kmemory_pool_t struct k_mem_pool * #define pool_struct k_mem_pool /** * @brief Allocate memory pool block. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine allocates a block of at least @a reqsize bytes from memory pool * @a pool_id, and saves its information in block descriptor @a blockptr. When * no such block is available, the routine waits either until one can be * allocated, or until the specified time limit is reached. * * @param blockptr Pointer to block descriptor. * @param pool_id Memory pool name. * @param reqsize Requested block size, in bytes. * @param timeout Determines the action to take when the memory pool is * exhausted. * For TICKS_NONE, return immediately. * For TICKS_UNLIMITED, wait as long as necessary. * Otherwise, wait up to the specified number of ticks before timing out. * * @retval RC_OK Successfully allocated memory block * @retval RC_TIME Timed out while waiting for memory block * @retval RC_FAIL Failed to immediately allocate memory block when * @a timeout = TICKS_NONE * * @sa TICKS_NONE, TICKS_UNLIMITED */ static inline __deprecated int task_mem_pool_alloc(struct k_block *blockptr, kmemory_pool_t pool_id, int reqsize, int32_t timeout) { return _error_to_rc(k_mem_pool_alloc(pool_id, blockptr, reqsize, _ticks_to_ms(timeout))); } /** * @brief Return memory pool block. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine returns a block to the memory pool from which it was allocated. * * @param block Pointer to block descriptor. * * @return N/A */ static inline __deprecated void task_mem_pool_free(struct k_block *block) { k_mem_pool_free(block); } /** * @brief Defragment memory pool. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine concatenates unused blocks that can be merged in memory pool * @a p. * * Doing a full defragmentation of a memory pool before allocating a set * of blocks may be more efficient than having the pool do an implicit * partial defragmentation each time a block is allocated. * * @param pool Memory pool name. * * @return N/A */ static inline __deprecated void task_mem_pool_defragment(kmemory_pool_t pool) { k_mem_pool_defrag(pool); } /** * @brief Allocate memory * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine provides traditional malloc semantics and is a wrapper on top * of microkernel pool alloc API. It returns an aligned memory address which * points to the start of a memory block of at least \p size bytes. * This memory comes from heap memory pool, consequently the app should * specify its intention to use a heap pool via the HEAP_SIZE keyword in * MDEF file, if it uses this API. * When not enough free memory is available in the heap pool, it returns NULL * * @param size Size of memory requested by the caller. * * @retval address of the block if successful otherwise returns NULL */ static inline __deprecated void *task_malloc(uint32_t size) { return k_malloc(size); } /** * @brief Free memory allocated through task_malloc * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine provides traditional free semantics and is intended to free * memory allocated using task_malloc API. * * @param ptr pointer to be freed * * @return NA */ static inline __deprecated void task_free(void *ptr) { k_free(ptr); } /* message queues */ #define kfifo_t struct k_msgq * /** * @brief FIFO enqueue request. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine adds an item to the FIFO queue. When the FIFO is full, * the routine will wait either for space to become available, or until the * specified time limit is reached. * * @param queue FIFO queue. * @param data Pointer to data to add to queue. * @param timeout Determines the action to take when the FIFO is full. * For TICKS_NONE, return immediately. * For TICKS_UNLIMITED, wait as long as necessary. * Otherwise, wait up to the specified number of ticks before timing out. * * @retval RC_OK Successfully added item to FIFO. * @retval RC_TIME Timed out while waiting to add item to FIFO. * @retval RC_FAIL Failed to immediately add item to FIFO when * @a timeout = TICKS_NONE. * * @sa TICKS_NONE, TICKS_UNLIMITED */ static inline __deprecated int task_fifo_put(kfifo_t queue, void *data, int32_t timeout) { return _error_to_rc(k_msgq_put(queue, data, _ticks_to_ms(timeout))); } /** * @brief FIFO dequeue request. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine fetches the oldest item from the FIFO queue. When the FIFO is * found empty, the routine will wait either until an item is added to the FIFO * queue or until the specified time limit is reached. * * @param queue FIFO queue. * @param data Pointer to storage location of the FIFO entry. * @param timeout Affects the action to take when the FIFO is empty. * For TICKS_NONE, return immediately. * For TICKS_UNLIMITED, wait as long as necessary. * Otherwise wait up to the specified number of ticks before timing out. * * @retval RC_OK Successfully fetched item from FIFO. * @retval RC_TIME Timed out while waiting to fetch item from FIFO. * @retval RC_FAIL Failed to immediately fetch item from FIFO when * @a timeout = TICKS_NONE. * * @sa TICKS_NONE, TICKS_UNLIMITED */ static inline __deprecated int task_fifo_get(kfifo_t queue, void *data, int32_t timeout) { return _error_to_rc(k_msgq_get(queue, data, _ticks_to_ms(timeout))); } /** * @brief Purge the FIFO of all its entries. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param queue FIFO queue. * * @return RC_OK on purge. */ static inline __deprecated int task_fifo_purge(kfifo_t queue) { k_msgq_purge(queue); return RC_OK; } /** * @brief Query the number of FIFO entries. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param queue FIFO queue. * * @return # of FIFO entries on query. */ static inline __deprecated int task_fifo_size_get(kfifo_t queue) { return queue->used_msgs; } /** * @brief Define a private microkernel FIFO. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This declares and initializes a private FIFO. The new FIFO * can be passed to the microkernel FIFO functions. * * @param name Name of the FIFO. * @param q_depth Depth of the FIFO. * @param q_width Width of the FIFO. */ #define DEFINE_FIFO(name, q_depth, q_width) \ K_MSGQ_DEFINE(_k_fifo_obj_##name, q_width, q_depth, 4); \ struct k_msgq * const name = &_k_fifo_obj_##name /* mailboxes */ #define kmbox_t struct k_mbox * struct k_msg { /** Mailbox ID */ kmbox_t mailbox; /** size of message (bytes) */ uint32_t size; /** information field, free for user */ uint32_t info; /** pointer to message data at sender side */ void *tx_data; /** pointer to message data at receiver */ void *rx_data; /** for async message posting */ struct k_block tx_block; /** sending task */ ktask_t tx_task; /** receiving task */ ktask_t rx_task; /** internal use only */ union { /** for 2-steps data transfer operation */ struct k_args *transfer; /** semaphore to signal when asynchr. call */ ksem_t sema; } extra; }; /** * @brief Send a message to a mailbox. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine sends a message to a mailbox and looks for a matching receiver. * * @param mbox Mailbox. * @param prio Priority of data transfer. * @param msg Pointer to message to send. * @param timeout Determines the action to take when there is no waiting * receiver. * For TICKS_NONE, return immediately. * For TICKS_UNLIMITED, wait as long as necessary. * Otherwise, wait up to the specified number of ticks before timing out. * * @return RC_OK Successfully delivered message. * @return RC_TIME Timed out while waiting to deliver message. * @return RC_FAIL Failed to immediately deliver message when * @a timeout = TICKS_NONE. * * @sa TICKS_NONE, TICKS_UNLIMITED */ __deprecated int task_mbox_put(kmbox_t mbox, kpriority_t prio, struct k_msg *msg, int32_t timeout); /** * @brief Send a message asynchronously to a mailbox. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine sends a message to a mailbox and does not wait for a matching * receiver. No exchange header is returned to the sender. When the data * has been transferred to the receiver, the semaphore signaling is performed. * * @param mbox Mailbox to which to send message. * @param prio Priority of data transfer. * @param msg Pointer to message to send. * @param sema Semaphore to signal when transfer is complete. * * @return N/A */ __deprecated void task_mbox_block_put(kmbox_t mbox, kpriority_t prio, struct k_msg *msg, ksem_t sema); /** * @brief Get @b struct @b k_msg message header structure information from * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * a mailbox and wait with timeout. * * @param mbox Mailbox. * @param msg Pointer to message. * @param timeout Determines the action to take when there is no waiting * receiver. * For TICKS_NONE, return immediately. * For TICKS_UNLIMITED, wait as long as necessary. * Otherwise, wait up to the specified number of ticks before timing out. * * @return RC_OK Successfully received message. * @return RC_TIME Timed out while waiting to receive message. * @return RC_FAIL Failed to immediately receive message when * @a timeout = TICKS_NONE. * * @sa TICKS_NONE, TICKS_UNLIMITED */ __deprecated int task_mbox_get(kmbox_t mbox, struct k_msg *msg, int32_t timeout); /** * @brief Get message data. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Call this routine for one of two reasons: * 1. To transfer data when the call to @b task_mbox_get() yields an existing * field in the @b struct @b k_msg header structure. * 2. To wake up and release a transmitting task currently blocked from calling * @b task_mbox_put(). * * @param msg Message from which to get data. * * @return N/A */ __deprecated void task_mbox_data_get(struct k_msg *msg); /** * @brief Retrieve message data into a block, with time-limited waiting. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param msg Message from which to get data. * @param block Block. * @param pool_id Memory pool name. * @param timeout Determines the action to take when no waiting sender exists. * For TICKS_NONE, return immediately. * For TICKS_UNLIMITED, wait as long as necessary. * Otherwise, wait up to the specified number of ticks before timing out. * * @retval RC_OK Successful retrieval of message data. * @retval RC_TIME Timed out while waiting to receive message data. * @retval RC_FAIL Failed to immediately receive message data when * @a timeout = TICKS_NONE. * * @sa TICKS_NONE, TICKS_UNLIMITED */ __deprecated int task_mbox_data_block_get(struct k_msg *msg, struct k_block *block, kmemory_pool_t pool_id, int32_t timeout); /** * @brief Define a private microkernel mailbox. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine declares and initializes a private mailbox. The new mailbox * can be passed to the microkernel mailbox functions. * * @param name Name of the mailbox */ #define DEFINE_MAILBOX(name) \ K_MBOX_DEFINE(_k_mbox_obj_##name); \ struct k_mbox * const name = &_k_mbox_obj_##name /* pipes */ #define kpipe_t struct k_pipe * /** * @brief Pipe write request. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Attempt to write data from a memory-buffer area to the * specified pipe with a timeout option. * * @param id Pipe ID. * @param buffer Buffer. * @param bytes_to_write Number of bytes to write. * @param bytes_written Pointer to number of bytes written. * @param options Pipe options. * @param timeout Determines the action to take when the pipe is already full. * For TICKS_NONE, return immediately. * For TICKS_UNLIMITED, wait as long as necessary. * Otherwise, wait up to the specified number of ticks before timing out. * * @retval RC_OK Successfully wrote data to pipe. * @retval RC_ALIGNMENT Data is improperly aligned. * @retval RC_INCOMPLETE Only some of the data was written to the pipe when * @a options = _ALL_N. * @retval RC_TIME Timed out while waiting to write to pipe. * @retval RC_FAIL Failed to immediately write to pipe when * @a timeout = TICKS_NONE * * @sa TICKS_NONE, TICKS_UNLIMITED */ static inline __deprecated int task_pipe_put(kpipe_t id, void *buffer, int bytes_to_write, int *bytes_written, K_PIPE_OPTION options, int32_t timeout) { size_t min_xfer = (size_t)options; __ASSERT((options == _0_TO_N) || (options == _1_TO_N) || (options == _ALL_N), "Invalid pipe option"); *bytes_written = 0; if (bytes_to_write == 0) { return RC_FAIL; } if ((options == _0_TO_N) && (timeout != K_NO_WAIT)) { return RC_FAIL; } if (options == _ALL_N) { min_xfer = bytes_to_write; } return _error_to_rc(k_pipe_put(id, buffer, bytes_to_write, (size_t *)bytes_written, min_xfer, _ticks_to_ms(timeout))); } /** * @brief Pipe read request. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Attempt to read data into a memory buffer area from the * specified pipe with a timeout option. * * @param id Pipe ID. * @param buffer Buffer. * @param bytes_to_read Number of bytes to read. * @param bytes_read Pointer to number of bytes read. * @param options Pipe options. * @param timeout Determines the action to take when the pipe is already full. * For TICKS_NONE, return immediately. * For TICKS_UNLIMITED, wait as long as necessary. * Otherwise, wait up to the specified number of ticks before timing out. * * @retval RC_OK Successfully read data from pipe. * @retval RC_ALIGNMENT Data is improperly aligned. * @retval RC_INCOMPLETE Only some of the data was read from the pipe when * @a options = _ALL_N. * @retval RC_TIME Timed out waiting to read from pipe. * @retval RC_FAIL Failed to immediately read from pipe when * @a timeout = TICKS_NONE. * * @sa TICKS_NONE, TICKS_UNLIMITED */ static inline __deprecated int task_pipe_get(kpipe_t id, void *buffer, int bytes_to_read, int *bytes_read, K_PIPE_OPTION options, int32_t timeout) { size_t min_xfer = (size_t)options; __ASSERT((options == _0_TO_N) || (options == _1_TO_N) || (options == _ALL_N), "Invalid pipe option"); *bytes_read = 0; if (bytes_to_read == 0) { return RC_FAIL; } if ((options == _0_TO_N) && (timeout != K_NO_WAIT)) { return RC_FAIL; } if (options == _ALL_N) { min_xfer = bytes_to_read; } return _error_to_rc(k_pipe_get(id, buffer, bytes_to_read, (size_t *)bytes_read, min_xfer, _ticks_to_ms(timeout))); } #if CONFIG_NUM_PIPE_ASYNC_MSGS > 0 /** * @brief Send a block of data asynchronously to a pipe * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine asynchronously sends a message from the pipe specified by * @a id. Once all @a size bytes have been accepted by the pipe, it will * free the memory block @a block and give the semaphore @a sem (if specified). * * @param id Pipe ID. * @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 * * @retval RC_OK Successfully sent data to the pipe. * @retval RC_FAIL Block size is zero */ static inline __deprecated int task_pipe_block_put(kpipe_t id, struct k_block block, int size, ksem_t sem) { if (size == 0) { return RC_FAIL; } k_pipe_block_put(id, &block, size, sem); return RC_OK; } #endif /* CONFIG_NUM_PIPE_ASYNC_MSGS > 0 */ /** * @brief Define a private microkernel pipe. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param name Name of the pipe. * @param pipe_buffer_size Size of the pipe buffer (in bytes) */ #define DEFINE_PIPE(name, pipe_buffer_size) \ K_PIPE_DEFINE(_k_pipe_obj_##name, pipe_buffer_size, 4); \ struct k_pipe * const name = &_k_pipe_obj_##name #define nano_fifo k_fifo /** * @brief Initialize a nanokernel FIFO (fifo) object. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This function initializes a nanokernel FIFO (fifo) object * structure. * * It can be called from either a fiber or task. * * @param fifo FIFO to initialize. * * @return N/A */ static inline __deprecated void nano_fifo_init(struct nano_fifo *fifo) { k_fifo_init(fifo); } /* nanokernel fifos */ /** * @brief Add an element to the end of a FIFO. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine is a convenience wrapper for the execution of context-specific * APIs. It is helpful when the exact execution context is not known. However, * it should be avoided when the context is known up-front to avoid unnecessary * overhead. * * FIFO data items must be aligned on a 4-byte boundary, as the kernel reserves * the first 32 bits of each item for use as a pointer to the next data item in * the FIFO's link list. Each data item added to the FIFO must include and * reserve these first 32 bits. * * @param fifo FIFO on which to interact. * @param data Data to send. * * @return N/A */ static inline __deprecated void nano_fifo_put(struct nano_fifo *fifo, void *data) { k_fifo_put(fifo, data); } /** * @brief Add an element to the end of a FIFO from an ISR context. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_fifo_put(), but may only be called from an ISR. * * @sa nano_fifo_put */ #define nano_isr_fifo_put nano_fifo_put /** * @brief Add an element to the end of a FIFO from a fiber. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_fifo_put(), but may only be called from a fiber. * * @sa nano_fifo_put */ #define nano_fiber_fifo_put nano_fifo_put /** * @brief Add an element to the end of a FIFO. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_fifo_put(), but may only be called from a task. * * @sa nano_fifo_put */ #define nano_task_fifo_put nano_fifo_put #ifdef KERNEL /* XXX ztest layer redefines to a different function */ /** * @brief Atomically add a list of elements to the end of a FIFO. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine adds a list of elements in one shot to the end of a FIFO * object. If fibers are pending on the FIFO object, they become ready to run. * If this API is called from a task, the highest priority one will preempt the * running task once the put operation is complete. * * If enough fibers are waiting on the FIFO, the address of each element given * to fibers is returned to the waiting fiber. The remaining elements are * linked to the end of the list. * * The list must be a singly-linked list, where each element only has a pointer * to the next one. The list must be NULL-terminated. * * Unlike the fiber/ISR versions of this API which is not much different * conceptually than calling nano_fifo_put once for each element to queue, the * behaviour is indeed different for tasks. There is no context switch being * done for each element queued, so the task can enqueue all elements without * being interrupted by a fiber being woken up. * * This routine is a convenience wrapper for the execution of context-specific * APIs. It is helpful when the exact execution context is not known. However, * it should be avoided when the context is known up-front to avoid unnecessary * overhead. * * @param fifo FIFO on which to interact. * @param head head of singly-linked list * @param tail tail of singly-linked list * * @return N/A * * @sa nano_fifo_put_slist, nano_isr_fifo_put_list, nano_fiber_fifo_put_list, * nano_task_fifo_put_list */ static inline __deprecated void nano_fifo_put_list(struct nano_fifo *fifo, void *head, void *tail) { k_fifo_put_list(fifo, head, tail); } #else void nano_fifo_put_list(struct nano_fifo *fifo, void *head, void *tail); #endif /** * @brief Atomically add a list of elements to the end of a FIFO from an ISR. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_fifo_put_list(), but may only be called from an ISR. * * @sa nano_fifo_put_list */ #define nano_isr_fifo_put_list nano_fifo_put_list /** * * @brief Atomically add a list of elements to the end of a FIFO from a fiber. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_fifo_put_list(), but may only be called from a fiber. * * @sa nano_fifo_put_list */ #define nano_fiber_fifo_put_list nano_fifo_put_list /** * @brief Atomically add a list of elements to the end of a FIFO from a fiber. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_fifo_put_list(), but may only be called from a task. * * @sa nano_fifo_put_list */ #define nano_task_fifo_put_list nano_fifo_put_list /** * @brief Atomically add a list of elements to the end of a FIFO. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * See nano_fifo_put_list for the description of the behaviour. * * It takes a pointer to a sys_slist_t object instead of the head and tail of a * custom singly-linked list. The sys_slist_t object is invalid afterwards and * must be re-initialized via sys_slist_init(). * * This routine is a convenience wrapper for the execution of context-specific * APIs. It is helpful when the exact execution context is not known. However, * it should be avoided when the context is known up-front to avoid unnecessary * overhead. * * @param fifo FIFO on which to interact. * @param list pointer to singly-linked list * * @return N/A * * @sa nano_fifo_put_list, nano_isr_fifo_put_slist, nano_fiber_fifo_put_slist, * nano_task_fifo_put_slist */ static inline __deprecated void nano_fifo_put_slist(struct nano_fifo *fifo, sys_slist_t *list) { k_fifo_put_slist(fifo, list); } /** * @brief Atomically add a list of elements to the end of a FIFO from an ISR. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_fifo_put_slist(), but may only be called from an ISR. * * @sa nano_fifo_put_slist */ #define nano_isr_fifo_put_slist nano_fifo_put_slist /** * @brief Atomically add a list of elements to the end of a FIFO from a fiber. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_fifo_put_slist(), but may only be called from a fiber. * * @sa nano_fifo_put_slist */ #define nano_fiber_fifo_put_slist nano_fifo_put_slist /** * @brief Atomically add a list of elements to the end of a FIFO from a fiber. * * Like nano_fifo_put_slist(), but may only be called from a fiber. * * @sa nano_fifo_put_slist */ #define nano_task_fifo_put_slist nano_fifo_put_slist #ifdef KERNEL /* ztest layer redefines to a different function */ /** * @brief Get an element from the head a FIFO. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine is a convenience wrapper for the execution of context-specific * APIs. It is helpful when the exact execution context is not known. However, * it should be avoided when the context is known up-front to avoid unnecessary * overhead. * * If no element is available, the function returns NULL. The first word in * the element contains invalid data because its memory location was used to * store a pointer to the next element in the linked list. * * @param fifo FIFO on which to interact. * @param timeout_in_ticks Affects the action taken should the FIFO be empty. * If TICKS_NONE, then return immediately. If TICKS_UNLIMITED, then wait as * long as necessary. Otherwise, wait up to the specified number of ticks * before timing out. * * @warning If it is to be called from the context of an ISR, then @a * timeout_in_ticks must be set to TICKS_NONE. * * @return Pointer to head element in the list when available. * NULL Otherwise. * * @sa TICKS_NONE, TICKS_UNLIMITED */ static inline __deprecated void *nano_fifo_get(struct nano_fifo *fifo, int32_t timeout_in_ticks) { return k_fifo_get((struct k_fifo *)fifo, _ticks_to_ms(timeout_in_ticks)); } #else void __deprecated *nano_fifo_get(struct nano_fifo *fifo, int32_t timeout_in_ticks); #endif /* KERNEL */ /** * @brief Get an element from the head of a FIFO from an ISR context. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_fifo_get(), but may only be called from an ISR with a timeout * of TICKS_NONE. * * @sa nano_fifo_get */ #define nano_isr_fifo_get nano_fifo_get /** * @brief Get an element from the head of a FIFO from a fiber. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_fifo_get(), but may only be called from a fiber. * * @sa nano_fifo_get */ #define nano_fiber_fifo_get nano_fifo_get /** * @brief Get an element from a FIFO's head that comes from a task, poll if * empty. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_fifo_get(), but may only be called from a task. * * @sa nano_fifo_get */ #define nano_task_fifo_get nano_fifo_get /* nanokernel lifos */ #define nano_lifo k_lifo /** * @brief Initialize a nanokernel linked list LIFO (lifo) object. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This function initializes a nanokernel system-level linked list LIFO * (lifo) object structure. * * It is called from either a fiber or task. * * @param lifo LIFO to initialize. * * @return N/A */ static inline __deprecated void nano_lifo_init(struct nano_lifo *lifo) { k_lifo_init(lifo); } /** * @brief Prepend an element to a LIFO. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine adds an element to the LIFOs' object head * * This routine is a convenience wrapper for the execution of context-specific * APIs. It is helpful when the exact execution context is not known. However, * it should be avoided when the context is known up-front to avoid unnecessary * overhead. * * @param lifo LIFO on which to put. * @param data Data to insert. * * @return N/A */ static inline __deprecated void nano_lifo_put(struct nano_lifo *lifo, void *data) { k_lifo_put(lifo, data); } /** * @brief Prepend an element to a LIFO without a context switch. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_lifo_put(), but may only be called from an ISR. A fiber * pending on the LIFO object will be made ready, but will NOT be scheduled * to execute. * * @sa nano_lifo_put */ #define nano_isr_lifo_put nano_lifo_put /** * @brief Prepend an element to a LIFO without a context switch. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_lifo_put(), but may only be called from a fiber. A fiber * pending on the LIFO object will be made ready, but will NOT be scheduled * to execute. * * @sa nano_lifo_put */ #define nano_fiber_lifo_put nano_lifo_put /** * @brief Add an element to the LIFO's linked list head. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_lifo_put(), but may only be called from a task. A fiber * pending on the LIFO object will be made ready, and will preempty the * running task immediately. * * @sa nano_lifo_put */ #define nano_task_lifo_put nano_lifo_put /** * @brief Get the first element from a LIFO. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine is a convenience wrapper for the execution of context-specific * APIs. It is helpful when the exact execution context is not known. However, * it should be avoided when the context is known up-front to avoid unnecessary * overhead. * * @param lifo LIFO on which to receive. * @param timeout_in_ticks Affects the action taken should the LIFO be empty. * If TICKS_NONE, then return immediately. If TICKS_UNLIMITED, then wait as * long as necesssary. Otherwise wait up to the specified number of ticks * before timing out. * * @warning If it is to be called from the context of an ISR, then @a * timeout_in_ticks must be set to TICKS_NONE. * * @return Pointer to head element in the list when available. * NULL Otherwise. * * @sa TICKS_NONE, TICKS_UNLIMITED */ static inline __deprecated void *nano_lifo_get(struct nano_lifo *lifo, int32_t timeout_in_ticks) { return k_lifo_get((struct k_lifo *)lifo, _ticks_to_ms(timeout_in_ticks)); } /** * @brief Remove the first element from a LIFO linked list. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_lifo_get(), but may only be called from an ISR with a timeout * of TICKS_NONE. * * @sa nano_lifo_get */ #define nano_isr_lifo_get nano_lifo_get /** * @brief Prepend an element to a LIFO without a context switch. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_lifo_get(), but may only be called from a fiber. * * @sa nano_lifo_get */ #define nano_fiber_lifo_get nano_lifo_get /** * @brief Remove the first element from a LIFO linked list. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_lifo_get(), but may only be called from a task. * * @sa nano_lifo_get */ #define nano_task_lifo_get nano_lifo_get /* nanokernel stacks */ #define nano_stack k_stack /** * @brief Initialize a nanokernel stack object. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This function initializes a nanokernel stack object structure. * * It is called from either a fiber or a task. * * @return N/A */ static inline __deprecated void nano_stack_init(struct nano_stack *stack, uint32_t *data) { int entries; /* use max possible number of entries */ entries = min(INT_MAX, UINTPTR_MAX - (uint32_t)data) / sizeof(*data); k_stack_init(stack, data, entries); } /** * @brief Push data onto a stack. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine pushes a data item onto a stack object. It is a convenience * wrapper for the execution of context-specific APIs and is helpful when * the exact execution context is not known. However, it should be avoided * when the context is known up-front to avoid unnecessary overhead. * * @param stack Stack on which to interact. * @param data Data to push on stack. * * @return N/A */ static inline __deprecated void nano_stack_push(struct nano_stack *stack, uint32_t data) { k_stack_push(stack, data); } /** * @brief Push data onto a stack (no context switch). * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_stack_push(), but may only be called from an ISR. A fiber that * pends on the stack object becomes ready but will NOT be scheduled to execute. * * @sa nano_stack_push */ #define nano_isr_stack_push nano_stack_push /** * @brief Push data onto a stack (no context switch). * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_stack_push(), but may only be called from a fiber. A fiber that * pends on the stack object becomes ready but will NOT be scheduled to execute. * * @sa nano_stack_push */ #define nano_fiber_stack_push nano_stack_push /** * @brief Push data onto a nanokernel stack. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_stack_push(), but may only be called from a task. A fiber that * pends on the stack object becomes ready and preempts the running task * immediately. * * @sa nano_stack_push */ #define nano_task_stack_push nano_stack_push /** * @brief Pop data off a stack. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine pops the first data word from a nanokernel stack object. * It is a convenience wrapper for the execution of context-specific APIs * and is helpful when the exact execution context is not known. However, * it should be avoided when the context is known up-front to avoid unnecessary * overhead. * * When the stack is not empty, a data word is popped and copied to the * provided address @a data and a non-zero value is returned. When the routine * finds an empty stack, zero is returned. * * @param stack Stack on which to interact. * @param data Container for data to pop * @param timeout_in_ticks Determines the action to take when the FIFO * is empty. * For TICKS_NONE, return immediately. * For TICKS_UNLIMITED, wait as long as necessary. * Otherwise, wait up to the specified number of ticks before timing * out. * * @retval 1 When data is popped from the stack. * @retval 0 Otherwise. */ static inline __deprecated int nano_stack_pop(struct nano_stack *stack, uint32_t *data, int32_t timeout_in_ticks) { return k_stack_pop((struct k_stack *)stack, data, _ticks_to_ms(timeout_in_ticks)) == 0 ? 1 : 0; } /** * @brief Pop data from a nanokernel stack. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_stack_pop(), but may only be called from an ISR. * * @sa nano_stack_pop */ #define nano_isr_stack_pop nano_stack_pop /** * @brief Pop data from a nanokernel stack. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_stack_pop(), but may only be called from a fiber. * * @sa nano_stack_pop */ #define nano_fiber_stack_pop nano_stack_pop /** * @brief Pop data from a nanokernel stack. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_stack_pop(), but may only be called from a task. * * @sa nano_stack_pop */ #define nano_task_stack_pop nano_stack_pop /** * @brief Return the current system tick count. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @return The current system tick count. */ extern __deprecated int64_t sys_tick_get(void); /** * @brief Return the lower part of the current system tick count. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @return The current system tick count. */ extern __deprecated uint32_t sys_tick_get_32(void); /** * @brief Return number of ticks elapsed since a reference time. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param reftime Reference time. * * @return The tick count since reference time; undefined for first invocation. */ extern __deprecated int64_t sys_tick_delta(int64_t *reftime); /** * * @brief Return 32-bit number of ticks since a reference time. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @param reftime Reference time. * * @return A 32-bit tick count since reference time. Undefined for first * invocation. */ extern __deprecated uint32_t sys_tick_delta_32(int64_t *reftime); /** * @brief Return a time stamp in high-resolution format. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine reads the counter register on the processor's high precision * timer device. This counter register increments at a relatively high rate * (e.g. 20 MHz), and is thus considered a high-resolution timer. This is * in contrast to sys_tick_get_32() which returns the value of the system * ticks variable. * * @return The current high-precision clock value. */ #define sys_cycle_get_32 k_cycle_get_32 /* microkernel timers */ #if (CONFIG_NUM_DYNAMIC_TIMERS > 0) #define CONFIG_NUM_TIMER_PACKETS CONFIG_NUM_DYNAMIC_TIMERS #define ktimer_t struct k_timer * /** * @brief Allocate a timer and return its object identifier. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * @return timer identifier */ extern __deprecated ktimer_t task_timer_alloc(void); /** * @brief Deallocate a timer * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine frees the resources associated with the timer. If a timer was * started, it has to be stopped using task_timer_stop() before it can be freed. * * @param timer Timer to deallocate. * * @return N/A */ extern __deprecated void task_timer_free(ktimer_t timer); /** * @brief Start or restart the specified low-resolution timer * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine starts or restarts the specified low-resolution timer. * * Signals the semaphore after a specified number of ticks set by * @a duration expires. The timer repeats the expiration/signal cycle * each time @a period ticks elapses. * * Setting @a period to 0 stops the timer at the end of the initial delay. * If either @a duration or @a period is passed an invalid value * (@a duration <= 0, * @a period < 0), this kernel API acts like a * task_timer_stop(): if the allocated timer was still running (from a * previous call), it will be cancelled; if not, nothing will happen. * * @param timer Timer to start. * @param duration Initial delay in ticks. * @param period Repetition interval in ticks. * @param sema Semaphore to signal. * * @return N/A */ extern __deprecated void task_timer_start(ktimer_t timer, int32_t duration, int32_t period, ksem_t sema); /** * @brief Restart a timer * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine restarts the timer specified by @a timer. The timer must * have previously been started by a call to task_timer_start(). * * @param timer Timer to restart. * @param duration Initial delay. * @param period Repetition interval. * * @return N/A */ static inline __deprecated void task_timer_restart(ktimer_t timer, int32_t duration, int32_t period) { k_timer_start(timer, _ticks_to_ms(duration), _ticks_to_ms(period)); } /** * @brief Stop a timer * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine stops the specified timer. If the timer period has already * elapsed, the call has no effect. * * @param timer Timer to stop. * * @return N/A */ static inline __deprecated void task_timer_stop(ktimer_t timer) { k_timer_stop(timer); } #endif /* CONFIG_NUM_DYNAMIC_TIMERS > 0 */ /* nanokernel timers */ #define nano_timer k_timer /** * @brief Initialize a nanokernel timer object. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This function initializes a nanokernel timer object structure. * * It can be called from either a fiber or task. * * The @a data passed to this function is a pointer to a data structure defined * by the user. It contains data that the user wishes to store when initializing * the timer and recover when the timer expires. However, the first field of * this data structure must be a pointer reserved for the API's use that can be * overwritten by the API and, as such, should not contain user data. * * @param timer Timer. * @param data User Data. * * @return N/A */ static inline __deprecated void nano_timer_init(struct k_timer *timer, void *data) { k_timer_init(timer, NULL, NULL); timer->user_data = data; } /** * @brief Start a nanokernel timer. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine starts a previously initialized nanokernel timer object. The * timer will expire in @a ticks system clock ticks. It is also a convenience * wrapper for the execution of context-specific APIs and is helpful when the * the exact execution context is not known. However, it should be avoided when * the context is known up-front to avoid unnecessary overhead. * * @param timer Timer. * @param ticks Number of ticks. * * @return N/A */ static inline __deprecated void nano_timer_start(struct nano_timer *timer, int ticks) { k_timer_start(timer, _ticks_to_ms(ticks), 0); } /** * @brief Start a nanokernel timer from an ISR. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_timer_start(), but may only be called from an ISR with a * timeout of TICKS_NONE. * * @sa nano_timer_start */ #define nano_isr_timer_start nano_timer_start /** * @brief Start a nanokernel timer from a fiber. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_timer_start(), but may only be called from a fiber. * * @sa nano_timer_start */ #define nano_fiber_timer_start nano_timer_start /** * @brief Start a nanokernel timer from a task. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_timer_start(), but may only be called from a task. * * @sa nano_timer_start */ #define nano_task_timer_start nano_timer_start /** * @brief Wait for a nanokernel timer to expire. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine checks if a previously started nanokernel timer object has * expired. It is also a convenience wrapper for the execution of context- * specific APIs. It is helpful when the exact execution context is not known. * However, it should be avoided when the context is known up-front to avoid * unnecessary overhead. * * @param timer Timer. * @param timeout_in_ticks Determines the action to take when the timer has * not expired. * For TICKS_NONE, return immediately. * For TICKS_UNLIMITED, wait as long as necessary. * * @retval Pointer to timer initialization data. * @retval NULL If timer not expired. * * @warning If called from an ISR, then @a timeout_in_ticks must be TICKS_NONE. * * @sa TICKS_NONE, TICKS_UNLIMITED */ extern __deprecated void *nano_timer_test(struct nano_timer *timer, int32_t timeout_in_ticks); /** * @brief Make the current ISR check for a timer expiry. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_timer_test(), but may only be called from an ISR with a timeout * of TICKS_NONE. * * @sa nano_timer_test */ #define nano_isr_timer_test nano_timer_test /** * @brief Make the current fiber check for a timer expiry. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_timer_test(), but may only be called from a fiber. * * @sa nano_timer_test */ #define nano_fiber_timer_test nano_timer_test /** * @brief Make the current task check for a timer expiry. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_timer_test(), but may only be called from a task. * * @sa nano_timer_test */ #define nano_task_timer_test nano_timer_test /** * @brief Stop a nanokernel timer * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine stops a previously started nanokernel timer object. It is also * a convenience wrapper for the execution of context-specific APIs. It is * helpful when the exact execution context is not known. However, it should be * avoided when the context is known up-front to avoid unnecessary overhead. * * @param timer Timer to stop. * * @return N/A */ static inline __deprecated void nano_timer_stop(struct nano_timer *timer) { k_timer_stop(timer); } /** * @brief Stop a timer. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine stops the specified timer. If the timer period has already * elapsed, the call has no effect. * * @param timer Timer to stop. * * @return N/A */ #define task_timer_stop nano_timer_stop /** * @brief Stop a nanokernel timer from an ISR. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_timer_stop(), but may only be called from an ISR. * * @sa nano_timer_stop */ #define nano_isr_timer_stop nano_timer_stop /** * @brief Stop a nanokernel timer. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_timer_stop(), but may only be called from a fiber. * * @sa nano_timer_stop */ #define nano_fiber_timer_stop nano_timer_stop /** * @brief Stop a nanokernel timer from a task. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * Like nano_timer_stop(), but may only be called from a task. * * @sa nano_timer_stop */ #define nano_task_timer_stop nano_timer_stop /** * @brief Get nanokernel timer remaining ticks. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This function returns the remaining ticks of the previously * started nanokernel timer object. * * @param timer Timer to query * * @return remaining ticks or 0 if the timer has expired */ static inline __deprecated int32_t nano_timer_ticks_remain(struct nano_timer *timer) { return _ms_to_ticks(k_timer_remaining_get(timer)); } /** * @brief Make the CPU idle. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This function makes the CPU idle until an event wakes it up. * * @return N/A */ static inline __deprecated void nano_cpu_idle(void) { k_cpu_idle(); } /** * @brief Make the CPU idle in an atomic fashion. * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * 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 */ static inline __deprecated void nano_cpu_atomic_idle(unsigned int key) { k_cpu_atomic_idle(key); } #if CONFIG_X86 #if CONFIG_FP_SHARING #include /* floating point services */ #define USE_FP K_FP_REGS #define USE_SSE K_SSE_REGS /** * @brief Enable floating point hardware resources sharing * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine dynamically enables the capability of a thread to share floating * point hardware resources. The same "floating point" options accepted by * fiber_fiber_start() are accepted by this API (i.e. USE_FP and USE_SSE). * * @param thread_id ID of thread that may share the floating point hardware * @param options USE_FP or USE_SSE * * @return N/A */ static inline __deprecated void fiber_float_enable(struct tcs *tcs, unsigned int options) { k_float_enable(tcs, options); } /** * @brief Enable floating point hardware resources sharing * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine dynamically enables the capability of a thread to share * floating point hardware resources. The same "floating point" options * accepted by fiber_fiber_start() are accepted by this API * (i.e. USE_FP and USE_SSE). * * @param thread_id ID of thread that may share the floating point hardware * @param options USE_FP or USE_SSE * * @return N/A */ #define task_float_enable fiber_float_enable /** * @brief Disable floating point hardware resources sharing * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine dynamically disables the capability of a thread to share * floating point hardware resources. The same "floating point" options * accepted by fiber_fiber_start() are accepted by this API * (i.e. USE_FP and USE_SSE). * * @param thread_id ID of thread that may not share the floating point hardware * * @return N/A */ static inline __deprecated void fiber_float_disable(struct tcs *tcs) { k_float_disable(tcs); } /** * @brief Enable floating point hardware resources sharing * * Legacy API: Will be deprecated in Zephyr 1.9 * @deprecated This API will be deprecated. * * This routine dynamically disables the capability of a thread to share * floating point hardware resources. The same "floating point" options * accepted by fiber_fiber_start() are accepted by this API * (i.e. USE_FP and USE_SSE). * * @param thread_id ID of thread that may not share the floating point hardware * * @return N/A */ #define task_float_disable fiber_float_disable #endif /* CONFIG_FP_SHARING */ #endif /* CONFIG_X86 */ /** * @} end legacy_apis */ #endif /* _legacy__h_ */