From 09a31ce18cee1b683c87755e9cbfab9dfce6fe48 Mon Sep 17 00:00:00 2001 From: Peter Bigot Date: Thu, 4 Mar 2021 11:21:46 -0600 Subject: [PATCH] kernel: deprecate old k_work API Several functions and macros have been replaced with new ones that conform to current naming conventions, or provide more functionality, mostly through using new representations for delayable work. Mark these functions deprecated. Signed-off-by: Peter Bigot --- doc/releases/release-notes-2.6.rst | 26 ++++++++++++++++++++++++++ include/kernel.h | 27 +++++++++++++-------------- 2 files changed, 39 insertions(+), 14 deletions(-) diff --git a/doc/releases/release-notes-2.6.rst b/doc/releases/release-notes-2.6.rst index 97a63757356..10a4e5647f5 100644 --- a/doc/releases/release-notes-2.6.rst +++ b/doc/releases/release-notes-2.6.rst @@ -113,6 +113,32 @@ Deprecated in this release ``pm_device_state_set`` and ``pm_device_state_get`` in order to align with the naming of other device PM APIs. +* The following functions, macros, and structures related to the kernel + work queue API: + + * :c:func:`k_work_pending()` replace with :c:func:`k_work_is_pending()` + * :c:func:`k_work_q_start()` replace with :c:func:`k_work_queue_start()` + * :c:struct:`k_delayed_work` replace with :c:struct:`k_work_delayable` + * :c:func:`k_delayed_work_init()` replace with + :c:func:`k_work_init_delayable` + * :c:func:`k_delayed_work_submit_to_queue()` replace with + :c:func:`k_work_schedule_for_queue()` or + :c:func:`k_work_reschedule_for_queue()` + * :c:func:`k_delayed_work_submit()` replace with :c:func:`k_work_schedule()` + or :c:func:`k_work_reschedule()` + * :c:func:`k_delayed_work_pending()` replace with + :c:func:`k_work_delayable_is_pending()` + * :c:func:`k_delayed_work_cancel()` replace with + :c:func:`k_work_cancel_delayable()` + * :c:func:`k_delayed_work_remaining_get()` replace with + :c:func:`k_work_delayable_remaining_get()` + * :c:func:`k_delayed_work_expires_ticks()` replace with + :c:func:`k_work_delayable_expires_get()` + * :c:func:`k_delayed_work_remaining_ticks()` replace with + :c:func:`k_work_delayable_remaining_get()` + * :c:macro:`K_DELAYED_WORK_DEFINE` replace with + :c:macro:`K_WORK_DELAYABLE_DEFINE` + ========================== Removed APIs in this release diff --git a/include/kernel.h b/include/kernel.h index 35dc1459f2e..5f1d2d37343 100644 --- a/include/kernel.h +++ b/include/kernel.h @@ -3658,13 +3658,13 @@ static inline k_tid_t k_work_queue_thread_get(struct k_work_q *queue) /* Legacy wrappers */ -/* to be deprecated */ +__deprecated static inline bool k_work_pending(const struct k_work *work) { return k_work_is_pending(work); } -/* to be deprecated */ +__deprecated static inline void k_work_q_start(struct k_work_q *work_q, k_thread_stack_t *stack, size_t stack_size, int prio) @@ -3672,24 +3672,23 @@ static inline void k_work_q_start(struct k_work_q *work_q, k_work_queue_start(work_q, stack, stack_size, prio, NULL); } -/* to be deprecated */ +/* deprecated, remove when corresponding deprecated API is removed. */ struct k_delayed_work { struct k_work_delayable work; }; -/* to be deprecated */ -#define Z_DELAYED_WORK_INITIALIZER(work_handler) { \ +#define Z_DELAYED_WORK_INITIALIZER(work_handler) __DEPRECATED_MACRO { \ .work = Z_WORK_DELAYABLE_INITIALIZER(work_handler), \ } -/* to be deprecated */ +__deprecated static inline void k_delayed_work_init(struct k_delayed_work *work, k_work_handler_t handler) { k_work_init_delayable(&work->work, handler); } -/* to be deprecated */ +__deprecated static inline int k_delayed_work_submit_to_queue(struct k_work_q *work_q, struct k_delayed_work *work, k_timeout_t delay) @@ -3700,7 +3699,7 @@ static inline int k_delayed_work_submit_to_queue(struct k_work_q *work_q, return (rc >= 0) ? 0 : rc; } -/* to be deprecated */ +__deprecated static inline int k_delayed_work_submit(struct k_delayed_work *work, k_timeout_t delay) { @@ -3710,7 +3709,7 @@ static inline int k_delayed_work_submit(struct k_delayed_work *work, return (rc >= 0) ? 0 : rc; } -/* to be deprecated */ +__deprecated static inline int k_delayed_work_cancel(struct k_delayed_work *work) { bool pending = k_work_delayable_is_pending(&work->work); @@ -3751,13 +3750,13 @@ static inline int k_delayed_work_cancel(struct k_delayed_work *work) return -EALREADY; } -/* to be deprecated */ +__deprecated static inline bool k_delayed_work_pending(struct k_delayed_work *work) { return k_work_delayable_is_pending(&work->work); } -/* to be deprecated */ +__deprecated static inline int32_t k_delayed_work_remaining_get(struct k_delayed_work *work) { k_ticks_t rem = k_work_delayable_remaining_get(&work->work); @@ -3766,14 +3765,14 @@ static inline int32_t k_delayed_work_remaining_get(struct k_delayed_work *work) return k_ticks_to_ms_floor32(rem); } -/* to be deprecated, not used in-tree */ +__deprecated static inline k_ticks_t k_delayed_work_expires_ticks( struct k_delayed_work *work) { return k_work_delayable_expires_get(&work->work); } -/* to be deprecated, not used in-tree */ +__deprecated static inline k_ticks_t k_delayed_work_remaining_ticks( struct k_delayed_work *work) { @@ -3998,7 +3997,7 @@ struct k_work_poll { * @param work Symbol name for delayed work item object * @param work_handler Function to invoke each time work item is processed. */ -#define K_DELAYED_WORK_DEFINE(work, work_handler) \ +#define K_DELAYED_WORK_DEFINE(work, work_handler) __DEPRECATED_MACRO \ struct k_delayed_work work = Z_DELAYED_WORK_INITIALIZER(work_handler) /**