From e6f5282f6e547c2924c8921dcfacfb13de4f9e60 Mon Sep 17 00:00:00 2001 From: guozhanxin Date: Fri, 10 Sep 2021 18:08:30 +0800 Subject: [kernel] Improve the code comment of the cpu.c --- src/cpu.c | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 50 insertions(+), 3 deletions(-) (limited to 'src/cpu.c') diff --git a/src/cpu.c b/src/cpu.c index fc1fed5a06..5466a350ae 100644 --- a/src/cpu.c +++ b/src/cpu.c @@ -65,12 +65,26 @@ static void _cpu_preempt_enable(void) rt_hw_local_irq_enable(level); } +/** + * @brief Initialize a static spinlock object. + * + * @param lock is a pointer to the spinlock to initialize. + * It is assumed that storage for the spinlock will be allocated in your application. + */ void rt_spin_lock_init(struct rt_spinlock *lock) { rt_hw_spin_lock_init(&lock->lock); } RTM_EXPORT(rt_spin_lock_init) +/** + * @brief This function will lock the spinlock. + * + * @note If the spinlock is locked, the current CPU will keep polling the spinlock state + * until the spinlock is unlocked. + * + * @param lock is a pointer to the spinlock. + */ void rt_spin_lock(struct rt_spinlock *lock) { _cpu_preempt_disable(); @@ -78,6 +92,11 @@ void rt_spin_lock(struct rt_spinlock *lock) } RTM_EXPORT(rt_spin_lock) +/** + * @brief This function will unlock the spinlock. + * + * @param lock is a pointer to the spinlock. + */ void rt_spin_unlock(struct rt_spinlock *lock) { rt_hw_spin_unlock(&lock->lock); @@ -85,6 +104,16 @@ void rt_spin_unlock(struct rt_spinlock *lock) } RTM_EXPORT(rt_spin_unlock) +/** + * @brief This function will disable the local interrupt and then lock the spinlock. + * + * @note If the spinlock is locked, the current CPU will keep polling the spinlock state + * until the spinlock is unlocked. + * + * @param lock is a pointer to the spinlock. + * + * @return Return current cpu interrupt status. + */ rt_base_t rt_spin_lock_irqsave(struct rt_spinlock *lock) { unsigned long level; @@ -98,6 +127,13 @@ rt_base_t rt_spin_lock_irqsave(struct rt_spinlock *lock) } RTM_EXPORT(rt_spin_lock_irqsave) +/** + * @brief This function will unlock the spinlock and then restore current cpu interrupt status. + * + * @param lock is a pointer to the spinlock. + * + * @param level is interrupt status returned by rt_spin_lock_irqsave(). + */ void rt_spin_unlock_irqrestore(struct rt_spinlock *lock, rt_base_t level) { rt_hw_spin_unlock(&lock->lock); @@ -108,20 +144,29 @@ void rt_spin_unlock_irqrestore(struct rt_spinlock *lock, rt_base_t level) RTM_EXPORT(rt_spin_unlock_irqrestore) /** - * This fucntion will return current cpu. + * @brief This fucntion will return current cpu object. + * + * @return Return a pointer to the current cpu object. */ struct rt_cpu *rt_cpu_self(void) { return &_cpus[rt_hw_cpu_id()]; } +/** + * @brief This fucntion will return the cpu object corresponding to index. + * + * @return Return a pointer to the cpu object corresponding to index. + */ struct rt_cpu *rt_cpu_index(int index) { return &_cpus[index]; } /** - * This function will lock all cpus's scheduler and disable local irq. + * @brief This function will lock all cpus's scheduler and disable local irq. + * + * @return Return current cpu interrupt status. */ rt_base_t rt_cpus_lock(void) { @@ -148,7 +193,9 @@ rt_base_t rt_cpus_lock(void) RTM_EXPORT(rt_cpus_lock); /** - * This function will restore all cpus's scheduler and restore local irq. + * @brief This function will restore all cpus's scheduler and restore local irq. + * + * @param level is interrupt status returned by rt_cpus_lock(). */ void rt_cpus_unlock(rt_base_t level) { -- cgit v1.3.1 From 6cb093aa272a0b1ef908cbd8e103cbd94120b3c6 Mon Sep 17 00:00:00 2001 From: guozhanxin Date: Sat, 11 Sep 2021 18:29:37 +0800 Subject: [kernel] Improve code comments. --- src/clock.c | 2 +- src/components.c | 9 +++++---- src/cpu.c | 1 - 3 files changed, 6 insertions(+), 6 deletions(-) (limited to 'src/cpu.c') diff --git a/src/clock.c b/src/clock.c index e49df94aae..fb7ee447d2 100644 --- a/src/clock.c +++ b/src/clock.c @@ -130,7 +130,7 @@ RTM_EXPORT(rt_tick_from_millisecond); /** * @brief This function will return the passed millisecond from boot. * - * @note When the value of RT_TICK_PER_SECOND is lower than 1000 or + * @note if the value of RT_TICK_PER_SECOND is lower than 1000 or * is not an integral multiple of 1000, this function will not * provide the correct 1ms-based tick. * diff --git a/src/components.c b/src/components.c index 87e76091f2..9433b7457c 100644 --- a/src/components.c +++ b/src/components.c @@ -78,7 +78,9 @@ static int rti_end(void) INIT_EXPORT(rti_end, "6.end"); /** - * @brief RT-Thread Components Initialization for board. + * @brief Onboard components initialization. In this function, the board-level + * initialization function will be called to complete the initialization + * of the on-board peripherals. */ void rt_components_board_init(void) { @@ -225,9 +227,8 @@ void rt_application_init(void) } /** - * @brief RT-Thread startup function. This function will call all levels of initialization - * functions to complete the initialization of the system, and finally start the - * scheduler. + * @brief This function will call all levels of initialization functions to complete + * the initialization of the system, and finally start the scheduler. */ int rtthread_startup(void) { diff --git a/src/cpu.c b/src/cpu.c index 5466a350ae..b689ecf2d7 100644 --- a/src/cpu.c +++ b/src/cpu.c @@ -69,7 +69,6 @@ static void _cpu_preempt_enable(void) * @brief Initialize a static spinlock object. * * @param lock is a pointer to the spinlock to initialize. - * It is assumed that storage for the spinlock will be allocated in your application. */ void rt_spin_lock_init(struct rt_spinlock *lock) { -- cgit v1.3.1