diff --git a/documentation/0.doxygen/core/thread.h b/documentation/0.doxygen/core/thread.h deleted file mode 100644 index 99a05e9c3e7..00000000000 --- a/documentation/0.doxygen/core/thread.h +++ /dev/null @@ -1,89 +0,0 @@ -/* - * This file is only used for doxygen document generation. - */ - -/** - * @addtogroup group_thread_management - * @{ - */ - -/** - * @brief This function will handle IPI interrupt and do a scheduling in system. - * - * @param vector is the number of IPI interrupt for system scheduling. - * - * @param param is not used, and can be set to RT_NULL. - * - * @note this function should be invoke or register as ISR in BSP. - * - * @note this function is only implemented in scheduler_mp.c. - */ -void rt_scheduler_ipi_handler(int vector, void *param); - -/** - * @brief This function will perform one scheduling. It will select one thread - * with the highest priority level in global ready queue or local ready queue, - * then switch to it. - * - * @note this function is implemented in both scheduler_up.c and scheduler_mp.c. - */ -void rt_schedule(void); - -/** - * @brief This function checks whether a scheduling is needed after an IRQ context switching. If yes, - * it will select one thread with the highest priority level, and then switch - * to it. - * - * @param context is the context to be switched to. - * - * @note this function is only implemented in scheduler_mp.c. - */ -void rt_scheduler_do_irq_switch(void *context); - -/** - * @brief This function will insert a thread to the system ready queue. The state of - * thread will be set as READY and the thread will be removed from suspend queue. - * - * @param thread is the thread to be inserted. - * - * @note Please do not invoke this function in user application. - * - * @note this function is implemented in both scheduler_up.c and scheduler_mp.c. - */ -void rt_schedule_insert_thread(struct rt_thread *thread); - -/** - * @brief This function will remove a thread from system ready queue. - * - * @param thread is the thread to be removed. - * - * @note Please do not invoke this function in user application. - * - * @note this function is implemented in both scheduler_up.c and scheduler_mp.c. - */ -void rt_schedule_remove_thread(struct rt_thread *thread); - -/** - * @brief This function will lock the thread scheduler. - * - * @note this function is implemented in both scheduler_up.c and scheduler_mp.c. - */ -void rt_enter_critical(void); - -/** - * @brief This function will unlock the thread scheduler. - * - * @note this function is implemented in both scheduler_up.c and scheduler_mp.c. - */ -void rt_exit_critical(void); - -/** - * @brief Get the scheduler lock level. - * - * @return the level of the scheduler lock. 0 means unlocked. - * - * @note this function is implemented in both scheduler_up.c and scheduler_mp.c. - */ -rt_uint16_t rt_critical_level(void); - -/**@}*/ diff --git a/src/scheduler_mp.c b/src/scheduler_mp.c index 1ef452cab88..c0a546cf08c 100644 --- a/src/scheduler_mp.c +++ b/src/scheduler_mp.c @@ -175,6 +175,14 @@ void rt_scheduler_switch_sethook(void (*hook)(struct rt_thread *tid)) /**@}*/ #endif /* RT_USING_HOOK */ +/** + * @addtogroup group_thread_management + * + * @cond DOXYGEN_SMP + * + * @{ + */ + #if RT_THREAD_PRIORITY_MAX > 32 rt_inline rt_base_t _get_global_highest_ready_prio(void) @@ -400,6 +408,13 @@ static void _sched_remove_thread_locked(struct rt_thread *thread) /** * @brief Initialize the system scheduler. * + * @note This function must be called before any thread scheduling can occur. + * It prepares the scheduler data structures for multi-core operation. + * + * @note This function has both MP version and UP version. + */ +/* + * Don't include below in doxygen document due to they are MP version only. * @details This function performs the following initialization tasks: * - Initializes the global scheduler spinlock for multi-core synchronization. * - Initializes the global priority table for saving ready threads of all priority levels. @@ -409,9 +424,6 @@ static void _sched_remove_thread_locked(struct rt_thread *thread) * * Initializes per-CPU ready tables (if priority > 32) * * Initializes per-CPU spinlock (if RT_USING_SMART is defined) * - Initializes the global ready priority group and tables (if priority > 32) as bitmaps for all priorities. - * - * @note This function must be called before any thread scheduling can occur. - * It prepares the scheduler data structures for multi-core operation. */ void rt_system_scheduler_init(void) { @@ -462,6 +474,14 @@ void rt_system_scheduler_init(void) /** * @brief Start the system scheduler and switch to the highest priority thread. * + * @note This function will not return after successful execution. + * It performs the initial thread switch during system startup. + * The scheduler must be initialized before calling this function. + * + * @note This function has both MP version and UP version. + */ +/* + * Don't include below in doxygen document due to they are MP version only. * @details This function performs the following operations: * - Releases legacy CPU lock (if any) * - Disables interrupts to ensure atomic operation @@ -470,17 +490,13 @@ void rt_system_scheduler_init(void) * - Removes the selected thread from ready queue * - Assigns current CPU core to the selected thread * - Performs context switch to the selected thread - * - * @note This function will not return after successful execution. - * It performs the initial thread switch during system startup. - * The scheduler must be initialized before calling this function. */ void rt_system_scheduler_start(void) { struct rt_thread *to_thread; rt_ubase_t highest_ready_priority; - /** + /* * legacy rt_cpus_lock. some bsp codes still use it as for it's critical * region. Since scheduler is never touching this, here we just release it * on the entry. @@ -490,7 +506,7 @@ void rt_system_scheduler_start(void) /* ISR will corrupt the coherency of running frame */ rt_hw_local_irq_disable(); - /** + /* * for the accessing of the scheduler context. Noted that we don't have * current_thread at this point */ @@ -519,21 +535,16 @@ void rt_system_scheduler_start(void) /* never come back */ } -/** - * @addtogroup group_thread_management - * @cond - */ - -/**@{*/ - /** * @brief This function will handle IPI interrupt and do a scheduling in system. * - * @param vector is the number of IPI interrupt for system scheduling. + * This function should be invoke or register as ISR in BSP. * - * @param param is not used, and can be set to RT_NULL. + * @param vector The number of IPI interrupt for system scheduling. * - * @note this function should be invoke or register as ISR in BSP. + * @param param Not used, and can be set to RT_NULL. + * + * @note This function only has MP version. */ void rt_scheduler_ipi_handler(int vector, void *param) { @@ -543,9 +554,13 @@ void rt_scheduler_ipi_handler(int vector, void *param) /** * @brief Lock the system scheduler * - * @param plvl pointer to the object where lock level stores to + * @param plvl Pointer to the object where lock level stores to * - * @return rt_err_t RT_EOK + * @return rt_err_t + * - RT_EOK on success + * - -RT_EINVAL if plvl is NULL + * + * @note This function has both MP version and UP version. */ rt_err_t rt_sched_lock(rt_sched_lock_level_t *plvl) { @@ -560,12 +575,13 @@ rt_err_t rt_sched_lock(rt_sched_lock_level_t *plvl) } /** - * @brief Unlock the system scheduler - * @note this will not cause the scheduler to do a reschedule + * @brief Unlock the scheduler and restore the interrupt level + * + * @param level The interrupt level to restore (previously saved by rt_sched_lock) * - * @param level the lock level of previous call to rt_sched_lock() + * @return rt_err_t Always returns RT_EOK * - * @return rt_err_t RT_EOK + * @note This function has both MP version and UP version. */ rt_err_t rt_sched_unlock(rt_sched_lock_level_t level) { @@ -577,10 +593,12 @@ rt_err_t rt_sched_unlock(rt_sched_lock_level_t level) /** * @brief Check if the scheduler is currently locked * + * This function checks the scheduler lock status in a thread-safe manner + * by temporarily disabling interrupts to get consistent state. + * * @return rt_bool_t Returns RT_TRUE if scheduler is locked, RT_FALSE otherwise * - * @note This function checks the scheduler lock status in a thread-safe manner - * by temporarily disabling interrupts to get consistent state. + * @note This function only has MP version. */ rt_bool_t rt_sched_is_locked(void) { @@ -797,6 +815,8 @@ static void _sched_thread_process_signal(struct rt_thread *current_thread) * * @note Must be called in pair with rt_sched_lock() * May trigger context switch if conditions met + * + * @note This function has both MP version and UP version. */ rt_err_t rt_sched_unlock_n_resched(rt_sched_lock_level_t level) { @@ -884,6 +904,11 @@ rt_err_t rt_sched_unlock_n_resched(rt_sched_lock_level_t level) * with the highest priority level in global ready queue or local ready queue, * then switch to it. * + * @note This function has both MP version and UP version. + */ + +/* + * NOTE: not in doxygen due to these info. are special for MP version * @details This function performs the following operations: * - Disables interrupts to enter critical section * - Gets current CPU and thread context @@ -938,7 +963,7 @@ void rt_schedule(void) CLR_CRITICAL_SWITCH_FLAG(pcpu, current_thread); pcpu->irq_switch_flag = 0; - /** + /* * take the context lock before we do the real scheduling works. Context * lock will be released before returning from this _schedule_locked() */ @@ -985,6 +1010,8 @@ void rt_schedule(void) * - Performs context switch to new thread if available * - Handles cases where scheduler is locked or still in interrupt context * - Processes pending signals before scheduling + * + * @note This function only has MP version. */ void rt_scheduler_do_irq_switch(void *context) { @@ -1062,10 +1089,12 @@ void rt_scheduler_do_irq_switch(void *context) * @brief This function will insert a thread to the system ready queue. The state of * thread will be set as READY and the thread will be removed from suspend queue. * - * @param thread is the thread to be inserted. + * @param thread The thread to be inserted. * * @note Please do not invoke this function in user application. * Caller must hold the scheduler lock + * + * @note This function has both MP version and UP version. */ void rt_sched_insert_thread(struct rt_thread *thread) { @@ -1079,9 +1108,11 @@ void rt_sched_insert_thread(struct rt_thread *thread) /** * @brief This function will remove a thread from system ready queue. * - * @param thread is the thread to be removed. + * @param thread The thread to be removed. * * @note Please do not invoke this function in user application. + * + * @note This function has both MP version and UP version. */ void rt_sched_remove_thread(struct rt_thread *thread) { @@ -1107,6 +1138,8 @@ void rt_sched_remove_thread(struct rt_thread *thread) * - Initializes priority bitmasks (handles >32 priorities if needed) * - Sets initial time slice values * - For SMP systems, initializes critical section nesting counter + * + * @note This function has both MP version and UP version. */ void rt_sched_thread_init_priv(struct rt_thread *thread, rt_uint32_t tick, rt_uint8_t priority) { @@ -1151,6 +1184,8 @@ void rt_sched_thread_init_priv(struct rt_thread *thread, rt_uint32_t tick, rt_ui * * @note This is a lockless operation as it's called during thread creation * when no concurrent access is possible + * + * @note This function has both MP version and UP version. */ void rt_sched_thread_startup(struct rt_thread *thread) { @@ -1180,6 +1215,8 @@ void rt_sched_thread_startup(struct rt_thread *thread) * @note this operation is taken as an atomic operation of the update of SP. * Since the local irq is disabled, it's okay to assume that the stack * will not be modified meanwhile. + * + * @note This function only has MP version. */ void rt_sched_post_ctx_switch(struct rt_thread *thread) { @@ -1218,6 +1255,8 @@ static volatile int _critical_error_occurred = 0; * - Always calls rt_exit_critical() to ensure critical section is exited * * @note This is primarily used for debugging critical section mismatches. + * + * @note This function has both MP version and UP version. */ void rt_exit_critical_safe(rt_base_t critical_level) { @@ -1251,6 +1290,8 @@ void rt_exit_critical_safe(rt_base_t critical_level) * * @details This is the non-debug version that simply calls rt_exit_critical(). * The critical_level parameter is ignored in this implementation. + * + * @note This function has both MP version and UP version. */ void rt_exit_critical_safe(rt_base_t critical_level) { @@ -1288,6 +1329,8 @@ RTM_EXPORT(rt_exit_critical_safe); * * @note Must be paired with rt_exit_critical() * Can be nested, each call must have matching exit call + * + * @note This function has both MP version and UP version. */ rt_base_t rt_enter_critical(void) { @@ -1342,6 +1385,8 @@ RTM_EXPORT(rt_enter_critical); * @note Must be called in pair with rt_enter_critical() * Handles both hardware-assisted and software thread context cases * May trigger rescheduling if conditions met + * + * @note This function has both MP version and UP version. */ void rt_exit_critical(void) { @@ -1397,7 +1442,9 @@ RTM_EXPORT(rt_exit_critical); /** * @brief Get the scheduler lock level. * - * @return the level of the scheduler lock. 0 means unlocked. + * @return The level of the scheduler lock. 0 means unlocked. + * + * @note This function has both MP version and UP version. */ rt_uint16_t rt_critical_level(void) { @@ -1447,6 +1494,9 @@ RTM_EXPORT(rt_critical_level); * * @note Caller must ensure scheduler is not locked before calling * This function will acquire scheduler lock internally + * + * @note This function has both MP version and UP version, but UP version does + * nothing and always returns -RT_EINVAL. */ rt_err_t rt_sched_thread_bind_cpu(struct rt_thread *thread, int cpu) { @@ -1531,5 +1581,8 @@ rt_err_t rt_sched_thread_bind_cpu(struct rt_thread *thread, int cpu) return RT_EOK; } -/**@}*/ -/**@endcond*/ \ No newline at end of file +/** + * @} + * + * @endcond + */ diff --git a/src/scheduler_up.c b/src/scheduler_up.c index 5dedb33d36d..8099d3d9f35 100644 --- a/src/scheduler_up.c +++ b/src/scheduler_up.c @@ -93,6 +93,14 @@ void rt_scheduler_switch_sethook(void (*hook)(struct rt_thread *tid)) /**@}*/ #endif /* RT_USING_HOOK */ +/** + * @addtogroup group_thread_management + * + * @cond + * + * @{ + */ + static struct rt_thread* _scheduler_get_highest_priority_thread(rt_ubase_t *highest_prio) { struct rt_thread *highest_priority_thread; @@ -256,13 +264,6 @@ void rt_system_scheduler_start(void) /* never come back */ } -/** - * @addtogroup group_thread_management - * @cond - */ - -/**@{*/ - /** * @brief Perform thread scheduling once. Select the highest priority thread and switch to it. * @@ -719,5 +720,8 @@ rt_err_t rt_sched_thread_bind_cpu(struct rt_thread *thread, int cpu) return -RT_EINVAL; } -/**@}*/ -/**@endcond*/ \ No newline at end of file +/** + * @} + * + * @endcond + */