This is an automated email from the ASF dual-hosted git repository. janc pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/mynewt-core.git
commit c0c9e1eaea229755d89846ee17f8b9ea82b83e5b Author: Wojciech Pietraszewski <[email protected]> AuthorDate: Wed Jun 26 11:14:32 2024 +0200 kernel/os_sched: Update doxygen comments in the header file Adds missing documentation for functions and removes it from the source file. Adjusts the formatting for better readability. --- kernel/os/include/os/os_sched.h | 102 ++++++++++++++++++++++++++++++++++++---- kernel/os/src/os_sched.c | 95 ------------------------------------- 2 files changed, 94 insertions(+), 103 deletions(-) diff --git a/kernel/os/include/os/os_sched.h b/kernel/os/include/os/os_sched.h index a4c1d86f3..2bc8cb1cc 100644 --- a/kernel/os/include/os/os_sched.h +++ b/kernel/os/include/os/os_sched.h @@ -51,10 +51,29 @@ void os_sched_ctx_sw_hook(struct os_task *next_t); * Returns the currently running task. Note that this task may or may not be * the highest priority task ready to run. * - * @return The currently running task. + * @return The currently running task. */ struct os_task *os_sched_get_current_task(void); + +/** + * Sets the currently running task to 't'. Note that this function simply sets + * the global variable holding the currently running task. It does not perform + * a context switch or change the os run or sleep list. + * + * @param t Pointer to currently running task. + */ void os_sched_set_current_task(struct os_task *t); + +/** + * Returns the task that we should be running. This is the task at the head + * of the run list. + * + * @note If you want to guarantee that the os run list + * does not change after calling this function, + * you have to call it with interrupts disabled. + * + * @return The task at the head of the list + */ struct os_task *os_sched_next_task(void); /** @@ -73,9 +92,9 @@ void os_sched_suspend(void); * Resume task scheduling * * Resumes the scheduler after it was suspended with os_sched_suspend(). - * @returns 0 when scheduling resumed - * @returns non-0 when scheduling is still locked and more calls - * to os_sched_resume() are needed + * @return 0 when scheduling resumed; + * non-0 when scheduling is still locked and more + * calls to os_sched_resume() are needed */ int os_sched_resume(void); @@ -87,11 +106,9 @@ int os_sched_resume(void); * * This function will call the architecture specific routine to swap in the new task. * - * @param next_t Pointer to task which must run next (optional) + * @param next_t Pointer to task which must run next (optional) * - * @return n/a - * - * @note Interrupts must be disabled when calling this. + * @note Interrupts must be disabled when calling this. * * @code{.c} * // example @@ -114,12 +131,81 @@ int os_sched_resume(void); void os_sched(struct os_task *next_t); /** @cond INTERNAL_HIDDEN */ + +/** + * Called when the OS tick timer expires. Search the sleep list for any tasks + * that need waking up. This occurs when the current OS time exceeds the next + * wakeup time stored in the task. Any tasks that need waking up will be + * removed from the sleep list and added to the run list. + */ void os_sched_os_timer_exp(void); + +/** + * Insert a task into the scheduler list. This causes the task to be evaluated + * for running when os_sched is called. + * + * @param t Pointer to task to insert in run list + * + * @return OS_OK: task was inserted into run list; + * OS_EINVAL: Task was not in ready state. + */ os_error_t os_sched_insert(struct os_task *t); + +/** + * Removes the task from the run list and puts it on the sleep list. + * + * @param t Task to put to sleep + * @param nticks Number of ticks to put task to sleep + * + * @return Zero on success + * + * @note Must be called with interrupts disabled! This + * function does not call the scheduler. + */ int os_sched_sleep(struct os_task *t, os_time_t nticks); + +/** + * Called to wake up a task. Waking up a task consists of setting the task state + * to READY and moving it from the sleep list to the run list. + * + * @param t Pointer to task to wake up. + * + * @return Zero on success + * + * @note This function must be called with interrupts + * disabled. + */ int os_sched_wakeup(struct os_task *t); + +/** + * @note This routine is currently experimental and not ready for common use + * + * Stops a task and removes it from the task list. + * + * @return int + * + * @note Must be called with interrupts disabled! + * This function does not call the scheduler. + */ int os_sched_remove(struct os_task *t); + +/** + * Resort a task that is in the ready list as its priority has + * changed. If the task is not in the ready state, there is + * nothing to do. + * + * @param t Pointer to task to insert back into ready to run + * list. + * + * @note This function expects interrupts to be disabled, + * so they are not disabled here. + */ void os_sched_resort(struct os_task *t); + +/** + * Return the number of ticks until the first sleep timer expires. If there are + * no such tasks then return OS_TIMEOUT_NEVER instead. + */ os_time_t os_sched_wakeup_ticks(os_time_t now); /** @endcond */ diff --git a/kernel/os/src/os_sched.c b/kernel/os/src/os_sched.c index e76978539..f4c59ef8f 100644 --- a/kernel/os/src/os_sched.c +++ b/kernel/os/src/os_sched.c @@ -30,17 +30,6 @@ extern os_time_t g_os_time; os_time_t g_os_last_ctx_sw_time; static uint8_t os_sched_lock_count; -/** - * os sched insert - * - * Insert a task into the scheduler list. This causes the task to be evaluated - * for running when os_sched is called. - * - * @param t Pointer to task to insert in run list - * - * @return int OS_OK: task was inserted into run list - * OS_EINVAL: Task was not in ready state. - */ os_error_t os_sched_insert(struct os_task *t) { @@ -102,15 +91,6 @@ os_sched_get_current_task(void) return (g_current_task); } -/** - * os sched set current task - * - * Sets the currently running task to 't'. Note that this function simply sets - * the global variable holding the currently running task. It does not perform - * a context switch or change the os run or sleep list. - * - * @param t Pointer to currently running task. - */ void os_sched_set_current_task(struct os_task *t) { @@ -162,19 +142,6 @@ os_sched_resume(void) return ret; } -/** - * os sched sleep - * - * Removes the task from the run list and puts it on the sleep list. - * - * @param t Task to put to sleep - * @param nticks Number of ticks to put task to sleep - * - * @return int - * - * NOTE: must be called with interrupts disabled! This function does not call - * the scheduler - */ int os_sched_sleep(struct os_task *t, os_time_t nticks) { @@ -209,19 +176,6 @@ os_sched_sleep(struct os_task *t, os_time_t nticks) return (0); } -/** - * os sched remove - * - * XXX - * NOTE - This routine is currently experimental and not ready for common use - * - * Stops a task and removes it from the task list. - * - * @return int - * - * NOTE: must be called with interrupts disabled! This function does not call - * the scheduler - */ int os_sched_remove(struct os_task *t) { @@ -240,18 +194,6 @@ os_sched_remove(struct os_task *t) return OS_OK; } -/** - * os sched wakeup - * - * Called to wake up a task. Waking up a task consists of setting the task state - * to READY and moving it from the sleep list to the run list. - * - * @param t Pointer to task to wake up. - * - * @return int - * - * NOTE: This function must be called with interrupts disabled. - */ int os_sched_wakeup(struct os_task *t) { @@ -280,15 +222,6 @@ os_sched_wakeup(struct os_task *t) return (0); } -/** - * os sched os timer exp - * - * Called when the OS tick timer expires. Search the sleep list for any tasks - * that need waking up. This occurs when the current OS time exceeds the next - * wakeup time stored in the task. Any tasks that need waking up will be - * removed from the sleep list and added to the run list. - * - */ void os_sched_os_timer_exp(void) { @@ -322,10 +255,6 @@ os_sched_os_timer_exp(void) OS_EXIT_CRITICAL(sr); } -/* - * Return the number of ticks until the first sleep timer expires.If there are - * no such tasks then return OS_TIMEOUT_NEVER instead. - */ os_time_t os_sched_wakeup_ticks(os_time_t now) { @@ -345,36 +274,12 @@ os_sched_wakeup_ticks(os_time_t now) return (rt); } -/** - * os sched next task - * - * Returns the task that we should be running. This is the task at the head - * of the run list. - * - * NOTE: if you want to guarantee that the os run list does not change after - * calling this function you have to call it with interrupts disabled. - * - * @return struct os_task* - */ struct os_task * os_sched_next_task(void) { return (TAILQ_FIRST(&g_os_run_list)); } -/** - * os sched resort - * - * Resort a task that is in the ready list as its priority has - * changed. If the task is not in the ready state, there is - * nothing to do. - * - * @param t Pointer to task to insert back into ready to run - * list. - * - * NOTE: this function expects interrupts to be disabled so they - * are not disabled here. - */ void os_sched_resort(struct os_task *t) {
