RT-Thread/rt-thread
1
0
Fork 0
mirror of https://github.com/RT-Thread/rt-thread.git synced 2025-10-20 05:25:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

doxygen: fixed duplicated comments for scheduler APIs

Browse Source 
Similar to PR #10674, `src/scheduler_mp.c` and
`src/scheduler_up.c` also have similar issues.

After investigation, we found: in commit 2c98ce4605
"[HUST CSE][document] Fix some comments, invalid
grouping commands and warnings in Doxygen." This patch
excluded `src/scheduler_mp.c` and `src/scheduler_up.c`
from the Doxygen build and include
`documentation/doxygen/thread.h` (the new file path
after adjustment is `documentation/0.doxygen/core/thread.h`),
placing the Doxygen comments for some functions in this file.

However, this approach has its problems:

- The comments in `documentation/0.doxygen/core/thread.h`
  are separated from the source code, making them
  difficult to maintain. This also results in the
  comments for the newly added functions in
  `src/scheduler_mp.c` and `src/scheduler_up.c` not
  being updated in a timely manner and failing to
  be compiled into Doxygen (becoming HTML).

- For the average programmer, it's unlikely that
  they'll consider the `documentation/0.doxygen/`
  directory for function declarations and comments,
  let alone the need to maintain the Doxygen comments
  in that directory. Currently, the header files under
  `documentation/0.doxygen/` should strictly be used
  only to define Doxygen groups and should not include
  Doxygen comments for the code itself. (Similar
  issues exist in documentation/0.doxygen/3.hardware.h
  and documentation/0.doxygen/core/systeminit.h, which
  require further cleanup.)

The solution is similar to PR #10674, where only MP
documentation is generated by default. For functions
defined in MP but not in UP, we use the "@note"
directive in the function's doxygen comment to indicate
whether the function is supported in both UP and MP,
or only in MP.

After implementing this solution, the file
`documentation/0.doxygen/core/thread.h` can be deleted.

Signed-off-by: Chen Wang <unicorn_wang@outlook.com>
This commit is contained in:
Chen Wang
2025-09-09 11:12:04 +08:00
committed by R b b666
parent b525d2c535
commit 1034e5b4fd
3 changed files with 99 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files

89
documentation/0.doxygen/core/thread.h
View File

@@ -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);
/**@}*/

119
src/scheduler_mp.c
View File

@@ -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 lock level of previous call to rt_sched_lock()
* @param level The interrupt level to restore (previously saved by rt_sched_lock)
*
* @return rt_err_t RT_EOK
* @return rt_err_t Always returns 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*/
/**
* @}
*
* @endcond
*/

22
src/scheduler_up.c
View File

@@ -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*/
/**
* @}
*
* @endcond
*/