From 9a563b43b820284f6be12b2bd427f0151349a274 Mon Sep 17 00:00:00 2001 From: Gerard Marull-Paretas Date: Thu, 4 Mar 2021 19:48:14 +0100 Subject: [PATCH 1/2] doc: doxygen: add support for function properties Add aliases for setting function properties. A function may have 0, one or more function properties. Example usage: @funcprops \isr_ok, \async These aliases will translate to API Terminology references when Doxygen is rendered on Sphinx. On the Doxygen side they will just translate to plain text. Signed-off-by: Gerard Marull-Paretas --- doc/zephyr.doxyfile.in | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/zephyr.doxyfile.in b/doc/zephyr.doxyfile.in index 3ee6cee14e21c2..f6266c471d9c79 100644 --- a/doc/zephyr.doxyfile.in +++ b/doc/zephyr.doxyfile.in @@ -228,6 +228,15 @@ ALIASES += req{1}="\ref ZEPH_\1 \"ZEPH-\1\" " ALIASES += satisfy{1}="\xrefitem satisfy \"Satisfies requirement\" \"Requirement Implementation\" \1" ALIASES += verify{1}="\xrefitem verify \"Verifies requirement\" \"Requirement Verification\" \1" +ALIASES += "funcprops=\par \"Function properties (list may not be complete)\"" +ALIASES += "reschedule=\htmlonly reschedule \endhtmlonly \xmlonly embed:rst:inline :ref:`api_term_reschedule` \endxmlonly" +ALIASES += "sleep=\htmlonly sleep \endhtmlonly \xmlonly embed:rst:inline :ref:`api_term_sleep` \endxmlonly" +ALIASES += "no_wait=\htmlonly no-wait \endhtmlonly \xmlonly embed:rst:inline :ref:`api_term_no-wait` \endxmlonly" +ALIASES += "isr_ok=\htmlonly isr-ok \endhtmlonly \xmlonly embed:rst:inline :ref:`api_term_isr-ok` \endxmlonly" +ALIASES += "pre_kernel_ok=\htmlonly pre-kernel-ok \endhtmlonly \xmlonly embed:rst:inline :ref:`api_term_pre-kernel-ok` \endxmlonly" +ALIASES += "async=\htmlonly async \endhtmlonly \xmlonly embed:rst:inline :ref:`api_term_async` \endxmlonly" +ALIASES += "supervisor=\htmlonly supervisor \endhtmlonly \xmlonly embed:rst:inline :ref:`api_term_supervisor` \endxmlonly" + # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For # instance, some of the names that are used will be different. The list of all From 0dc2e886239cf18d1023107df3fe3d22d2366bc1 Mon Sep 17 00:00:00 2001 From: Gerard Marull-Paretas Date: Thu, 4 Mar 2021 19:50:02 +0100 Subject: [PATCH 2/2] kernel: flag isr-ok functions using funcprops Replace old notes marking ISR safe functions with the recently introduced funcprops. Signed-off-by: Gerard Marull-Paretas --- include/kernel.h | 151 +++++++++++++++++++++++++++-------------------- 1 file changed, 87 insertions(+), 64 deletions(-) diff --git a/include/kernel.h b/include/kernel.h index a276db374c487e..b26c300f862568 100644 --- a/include/kernel.h +++ b/include/kernel.h @@ -901,7 +901,7 @@ extern void k_sched_time_slice_set(int32_t slice, int prio); * This routine allows the caller to customize its actions, depending on * whether it is a thread or an ISR. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @return false if invoked by a thread. * @return true if invoked by an ISR. @@ -919,7 +919,7 @@ extern bool k_is_in_isr(void); * - The thread's priority is in the preemptible range. * - The thread has not locked the scheduler. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @return 0 if invoked by an ISR or by a cooperative thread. * @return Non-zero if invoked by a preemptible thread. @@ -932,7 +932,7 @@ __syscall int k_is_preempt_thread(void); * This routine allows the caller to customize its actions, depending on * whether it being invoked before the kernel is fully active. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @return true if invoked before post-kernel initialization * @return false if invoked during/after post-kernel initialization @@ -1413,8 +1413,10 @@ __syscall void k_timer_start(struct k_timer *timer, * Attempting to stop a timer that is not running is permitted, but has no * effect on the timer. * - * @note Can be called by ISRs. The stop handler has to be callable from ISRs - * if @a k_timer_stop is to be called from ISRs. + * @note The stop handler has to be callable from ISRs if @a k_timer_stop is to + * be called from ISRs. + * + * @funcprops \isr_ok * * @param timer Address of timer. * @@ -1700,7 +1702,7 @@ __syscall void k_queue_init(struct k_queue *queue); * -EINTR and K_POLL_STATE_CANCELLED state (and per above, subsequent * k_queue_get() will return NULL). * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param queue Address of the queue. * @@ -1715,7 +1717,7 @@ __syscall void k_queue_cancel_wait(struct k_queue *queue); * aligned on a word boundary, and the first word of the item is reserved * for the kernel's use. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param queue Address of the queue. * @param data Address of the data item. @@ -1732,7 +1734,7 @@ extern void k_queue_append(struct k_queue *queue, void *data); * the calling thread's resource pool, which is automatically freed when the * item is removed. The data itself is not copied. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param queue Address of the queue. * @param data Address of the data item. @@ -1749,7 +1751,7 @@ __syscall int32_t k_queue_alloc_append(struct k_queue *queue, void *data); * aligned on a word boundary, and the first word of the item is reserved * for the kernel's use. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param queue Address of the queue. * @param data Address of the data item. @@ -1766,7 +1768,7 @@ extern void k_queue_prepend(struct k_queue *queue, void *data); * the calling thread's resource pool, which is automatically freed when the * item is removed. The data itself is not copied. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param queue Address of the queue. * @param data Address of the data item. @@ -1783,7 +1785,7 @@ __syscall int32_t k_queue_alloc_prepend(struct k_queue *queue, void *data); * data item must be aligned on a word boundary, and the first word of * the item is reserved for the kernel's use. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param queue Address of the queue. * @param prev Address of the previous data item. @@ -1801,7 +1803,7 @@ extern void k_queue_insert(struct k_queue *queue, void *prev, void *data); * in each data item pointing to the next data item; the list must be * NULL-terminated. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param queue Address of the queue. * @param head Pointer to first node in singly-linked list. @@ -1820,7 +1822,7 @@ extern int k_queue_append_list(struct k_queue *queue, void *head, void *tail); * The data items must be in a singly-linked list implemented using a * sys_slist_t object. Upon completion, the original list is empty. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param queue Address of the queue. * @param list Pointer to sys_slist_t object. @@ -1836,7 +1838,9 @@ extern int k_queue_merge_slist(struct k_queue *queue, sys_slist_t *list); * This routine removes first data item from @a queue. The first word of the * data item is reserved for the kernel's use. * - * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT. + * @note @a timeout must be set to K_NO_WAIT if called from ISR. + * + * @funcprops \isr_ok * * @param queue Address of the queue. * @param timeout Non-negative waiting period to obtain a data item @@ -1855,7 +1859,9 @@ __syscall void *k_queue_get(struct k_queue *queue, k_timeout_t timeout); * data item is reserved for the kernel's use. Removing elements from k_queue * rely on sys_slist_find_and_remove which is not a constant time operation. * - * @note Can be called by ISRs + * @note @a timeout must be set to K_NO_WAIT if called from ISR. + * + * @funcprops \isr_ok * * @param queue Address of the queue. * @param data Address of the data item. @@ -1874,7 +1880,7 @@ static inline bool k_queue_remove(struct k_queue *queue, void *data) * item is reserved for the kernel's use. Appending elements to k_queue * relies on sys_slist_is_node_in_list which is not a constant time operation. * - * @note Can be called by ISRs + * @funcprops \isr_ok * * @param queue Address of the queue. * @param data Address of the data item. @@ -1901,7 +1907,7 @@ static inline bool k_queue_unique_append(struct k_queue *queue, void *data) * Note that the data might be already gone by the time this function returns * if other threads are also trying to read from the queue. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param queue Address of the queue. * @@ -2081,7 +2087,7 @@ struct k_fifo { * return from k_fifo_get() call with NULL value (as if timeout * expired). * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param fifo Address of the FIFO queue. * @@ -2097,7 +2103,7 @@ struct k_fifo { * aligned on a word boundary, and the first word of the item is reserved * for the kernel's use. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param fifo Address of the FIFO. * @param data Address of the data item. @@ -2115,7 +2121,7 @@ struct k_fifo { * the calling thread's resource pool, which is automatically freed when the * item is removed. The data itself is not copied. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param fifo Address of the FIFO. * @param data Address of the data item. @@ -2134,7 +2140,7 @@ struct k_fifo { * each data item pointing to the next data item; the list must be * NULL-terminated. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param fifo Address of the FIFO queue. * @param head Pointer to first node in singly-linked list. @@ -2153,7 +2159,7 @@ struct k_fifo { * sys_slist_t object. Upon completion, the sys_slist_t object is invalid * and must be re-initialized via sys_slist_init(). * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param fifo Address of the FIFO queue. * @param list Pointer to sys_slist_t object. @@ -2169,7 +2175,9 @@ struct k_fifo { * This routine removes a data item from @a fifo in a "first in, first out" * manner. The first word of the data item is reserved for the kernel's use. * - * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT. + * @note @a timeout must be set to K_NO_WAIT if called from ISR. + * + * @funcprops \isr_ok * * @param fifo Address of the FIFO queue. * @param timeout Waiting period to obtain a data item, @@ -2187,7 +2195,7 @@ struct k_fifo { * Note that the data might be already gone by the time this function returns * if other threads is also trying to read from the FIFO. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param fifo Address of the FIFO queue. * @@ -2284,7 +2292,7 @@ struct k_lifo { * aligned on a word boundary, and the first word of the item is * reserved for the kernel's use. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param lifo Address of the LIFO queue. * @param data Address of the data item. @@ -2302,7 +2310,7 @@ struct k_lifo { * the calling thread's resource pool, which is automatically freed when the * item is removed. The data itself is not copied. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param lifo Address of the LIFO. * @param data Address of the data item. @@ -2319,7 +2327,9 @@ struct k_lifo { * This routine removes a data item from @a LIFO in a "last in, first out" * manner. The first word of the data item is reserved for the kernel's use. * - * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT. + * @note @a timeout must be set to K_NO_WAIT if called from ISR. + * + * @funcprops \isr_ok * * @param lifo Address of the LIFO queue. * @param timeout Waiting period to obtain a data item, @@ -2432,7 +2442,7 @@ int k_stack_cleanup(struct k_stack *stack); * * This routine adds a stack_data_t value @a data to @a stack. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param stack Address of the stack. * @param data Value to push onto the stack. @@ -2448,7 +2458,9 @@ __syscall int k_stack_push(struct k_stack *stack, stack_data_t data); * This routine removes a stack_data_t value from @a stack in a "last in, * first out" manner and stores the value in @a data. * - * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT. + * @note @a timeout must be set to K_NO_WAIT if called from ISR. + * + * @funcprops \isr_ok * * @param stack Address of the stack. * @param data Address of area to hold the value popped from the stack. @@ -2748,7 +2760,9 @@ __syscall int k_sem_init(struct k_sem *sem, unsigned int initial_count, * * This routine takes @a sem. * - * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT. + * @note @a timeout must be set to K_NO_WAIT if called from ISR. + * + * @funcprops \isr_ok * * @param sem Address of the semaphore. * @param timeout Waiting period to take the semaphore, @@ -2766,7 +2780,7 @@ __syscall int k_sem_take(struct k_sem *sem, k_timeout_t timeout); * This routine gives @a sem, unless the semaphore is already at its maximum * permitted count. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param sem Address of the semaphore. * @@ -2862,7 +2876,7 @@ typedef void (*k_work_handler_t)(struct k_work *work); * re-invoked to change the associated handler, but this must be done when the * work item is idle. * - * @note Safe to invoke from ISRs. + * @funcprops \isr_ok * * @param work the work structure to be initialized. * @@ -2875,11 +2889,11 @@ void k_work_init(struct k_work *work, * * A zero return value indicates the work item appears to be idle. * - * @note Safe to invoke from ISRs. - * * @note This is a live snapshot of state, which may change before the result * is checked. Use locks where appropriate. * + * @funcprops \isr_ok + * * @param work pointer to the work item. * * @return a mask of flags K_WORK_DELAYED, K_WORK_QUEUED, @@ -2891,11 +2905,11 @@ int k_work_busy_get(const struct k_work *work); * * Wrapper to determine whether a work item is in a non-idle dstate. * - * @note Safe to invoke from ISRs. - * * @note This is a live snapshot of state, which may change before the result * is checked. Use locks where appropriate. * + * @funcprops \isr_ok + * * @param work pointer to the work item. * * @return true if and only if k_work_busy_get() returns a non-zero value. @@ -2903,12 +2917,12 @@ int k_work_busy_get(const struct k_work *work); static inline bool k_work_is_pending(const struct k_work *work); /** @brief Submit a work item to a queue. - * - * @note Safe to invoke from ISRs. * * @param queue pointer to the work queue on which the item should run. If * NULL the queue from the most recent submission will be used. * + * @funcprops \isr_ok + * * @param work pointer to the work item. * * @retval 0 if work was already submitted to a queue @@ -2926,7 +2940,7 @@ int k_work_submit_to_queue(struct k_work_q *queue, /** @brief Submit a work item to the system queue. * - * @note Safe to invoke from ISRs. + * @funcprops \isr_ok * * @param work pointer to the work item. * @@ -2976,7 +2990,7 @@ bool k_work_flush(struct k_work *work, * * See also k_work_cancel_sync(). * - * @note Safe to invoke from ISRs. + * @funcprops \isr_ok * * @param work pointer to the work item. * @@ -3079,7 +3093,7 @@ int k_work_queue_drain(struct k_work_q *queue, bool plug); * is invoked with the @p plug option enabled. If this is invoked before the * drain completes new items may be submitted as soon as the drain completes. * - * @note Safe to invoke from ISRs. + * @funcprops \isr_ok * * @param queue pointer to the queue structure. * @@ -3095,7 +3109,7 @@ int k_work_queue_unplug(struct k_work_q *queue); * can be re-invoked to change the associated handler, but this must be done * when the work item is idle. * - * @note Safe to invoke from ISRs. + * @funcprops \isr_ok * * @param dwork the delayable work structure to be initialized. * @@ -3120,7 +3134,7 @@ k_work_delayable_from_work(struct k_work *work); /** @brief Busy state flags from the delayable work item. * - * @note Safe to invoke from ISRs. + * @funcprops \isr_ok * * @note This is a live snapshot of state, which may change before the result * can be inspected. Use locks where appropriate. @@ -3137,11 +3151,11 @@ int k_work_delayable_busy_get(const struct k_work_delayable *dwork); * * Wrapper to determine whether a delayed work item is in a non-idle state. * - * @note Safe to invoke from ISRs. - * * @note This is a live snapshot of state, which may change before the result * can be inspected. Use locks where appropriate. * + * @funcprops \isr_ok + * * @param dwork pointer to the delayable work item. * * @return true if and only if k_work_delayable_busy_get() returns a non-zero @@ -3153,11 +3167,11 @@ static inline bool k_work_delayable_is_pending( /** @brief Get the absolute tick count at which a scheduled delayable work * will be submitted. * - * @note Safe to invoke from ISRs. - * * @note This is a live snapshot of state, which may change before the result * can be inspected. Use locks where appropriate. * + * @funcprops \isr_ok + * * @param dwork pointer to the delayable work item. * * @return the tick count when the timer that will schedule the work item will @@ -3169,11 +3183,11 @@ static inline k_ticks_t k_work_delayable_expires_get( /** @brief Get the number of ticks until a scheduled delayable work will be * submitted. * - * @note Safe to invoke from ISRs. - * * @note This is a live snapshot of state, which may change before the result * can be inspected. Use locks where appropriate. * + * @funcprops \isr_ok + * * @param dwork pointer to the delayable work item. * * @return the number of ticks until the timer that will schedule the work @@ -3187,7 +3201,7 @@ static inline k_ticks_t k_work_delayable_remaining_get( * Unlike k_work_reschedule_for_queue() this is a no-op if the work item is * already scheduled or submitted, even if @p delay is @c K_NO_WAIT. * - * @note Safe to invoke from ISRs. + * @funcprops \isr_ok * * @param queue the queue on which the work item should be submitted after the * delay. @@ -3231,7 +3245,7 @@ static inline int k_work_schedule(struct k_work_delayable *dwork, * (e.g. is submitted or running). This function does not affect ("unsubmit") * a work item that has been submitted to a queue. * - * @note Safe to invoke from ISRs. + * @funcprops \isr_ok * * @param queue the queue on which the work item should be submitted after the * delay. @@ -3308,8 +3322,6 @@ bool k_work_flush_delayable(struct k_work_delayable *dwork, * scheduled or submitted it is canceled. This function does not wait for the * cancellation to complete. * - * @note Safe to invoke from ISRs. - * * @note The work may still be running when this returns. Use * k_work_flush_delayable() or k_work_cancel_delayable_sync() to ensure it is * not running. @@ -3317,6 +3329,8 @@ bool k_work_flush_delayable(struct k_work_delayable *dwork, * @note Canceling delayable work does not prevent rescheduling it. It does * prevent submitting it until the cancellation completes. * + * @funcprops \isr_ok + * * @param dwork pointer to the delayable work item. * * @return the k_work_delayable_busy_get() status indicating the state of the @@ -3845,7 +3859,7 @@ static inline void k_work_user_init(struct k_work_user *work, * work will still be pending when this information is used. It is up to * the caller to make sure that this information is used in a safe manner. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param work Address of work item. * @@ -3865,7 +3879,7 @@ static inline bool k_work_user_is_pending(struct k_work_user *work) * thread must have memory access to the k_work item being submitted. The caller * must have permission granted on the work_q parameter's queue object. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param work_q Address of workqueue. * @param work Address of work item. @@ -4004,7 +4018,7 @@ extern void k_work_poll_init(struct k_work_poll *work, * to race conditions with the pre-existing triggered work item and work queue, * so care must be taken to synchronize such resubmissions externally. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @warning * Provided array of events as well as a triggered work item must be placed @@ -4044,7 +4058,7 @@ extern int k_work_poll_submit_to_queue(struct k_work_q *work_q, * to race conditions with the pre-existing triggered work item and work queue, * so care must be taken to synchronize such resubmissions externally. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @warning * Provided array of events as well as a triggered work item must not be @@ -4076,7 +4090,7 @@ static inline int k_work_poll_submit(struct k_work_poll *work, * A triggered work item can only be canceled if no event triggered work * submission. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param work Address of delayed work item. * @@ -4247,11 +4261,12 @@ int k_msgq_cleanup(struct k_msgq *msgq); * * This routine sends a message to message queue @a q. * - * @note Can be called by ISRs. * @note The message content is copied from @a data into @a msgq and the @a data * pointer is not retained, so the message content will not be modified * by this function. * + * @funcprops \isr_ok + * * @param msgq Address of the message queue. * @param data Pointer to the message. * @param timeout Non-negative waiting period to add the message, @@ -4270,7 +4285,9 @@ __syscall int k_msgq_put(struct k_msgq *msgq, const void *data, k_timeout_t time * This routine receives a message from message queue @a q in a "first in, * first out" manner. * - * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT. + * @note @a timeout must be set to K_NO_WAIT if called from ISR. + * + * @funcprops \isr_ok * * @param msgq Address of the message queue. * @param data Address of area to hold the received message. @@ -4290,7 +4307,7 @@ __syscall int k_msgq_get(struct k_msgq *msgq, void *data, k_timeout_t timeout); * This routine reads a message from message queue @a q in a "first in, * first out" manner and leaves the message in the queue. * - * @note Can be called by ISRs. + * @funcprops \isr_ok * * @param msgq Address of the message queue. * @param data Address of area to hold the message read from the queue. @@ -4823,7 +4840,9 @@ extern int k_mem_slab_init(struct k_mem_slab *slab, void *buffer, * * This routine allocates a memory block from a memory slab. * - * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT. + * @note @a timeout must be set to K_NO_WAIT if called from ISR. + * + * @funcprops \isr_ok * * @param slab Address of the memory slab. * @param mem Pointer to block address area. @@ -4941,7 +4960,9 @@ void k_heap_init(struct k_heap *h, void *mem, size_t bytes); * bytes. The resulting memory can be returned to the heap using * k_heap_free(). * - * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT. + * @note @a timeout must be set to K_NO_WAIT if called from ISR. + * + * @funcprops \isr_ok * * @param h Heap from which to allocate * @param align Alignment in bytes, must be a power of two @@ -4962,7 +4983,9 @@ void *k_heap_aligned_alloc(struct k_heap *h, size_t align, size_t bytes, * freed. If the allocation cannot be performed by the expiration of * the timeout, NULL will be returned. * - * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT. + * @note @a timeout must be set to K_NO_WAIT if called from ISR. + * + * @funcprops \isr_ok * * @param h Heap from which to allocate * @param bytes Desired size of block to allocate