From 921e6057aa11e52eafcbcdabbb5765359ba2f286 Mon Sep 17 00:00:00 2001 From: guozhanxin Date: Fri, 10 Sep 2021 15:50:15 +0800 Subject: [PATCH 1/5] [clock] Improve the code comment of the clock.c --- src/clock.c | 34 ++++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/src/clock.c b/src/clock.c index 77516b3775..3b35e98d34 100644 --- a/src/clock.c +++ b/src/clock.c @@ -33,9 +33,9 @@ static volatile rt_tick_t rt_tick = 0; /**@{*/ /** - * This function will return current tick from operating system startup + * @brief This function will return current tick from operating system startup * - * @return current tick + * @return Return current tick */ rt_tick_t rt_tick_get(void) { @@ -45,7 +45,9 @@ rt_tick_t rt_tick_get(void) RTM_EXPORT(rt_tick_get); /** - * This function will set current tick + * @brief This function will set current tick + * + * @param tick is the value that you will set. */ void rt_tick_set(rt_tick_t tick) { @@ -57,8 +59,8 @@ void rt_tick_set(rt_tick_t tick) } /** - * This function will notify kernel there is one tick passed. Normally, - * this function is invoked by clock ISR. + * @brief This function will notify kernel there is one tick passed. + * Normally, this function is invoked by clock ISR. */ void rt_tick_increase(void) { @@ -97,14 +99,14 @@ void rt_tick_increase(void) } /** - * This function will calculate the tick from millisecond. + * @brief This function will calculate the tick from millisecond. * - * @param ms the specified millisecond - * - Negative Number wait forever - * - Zero not wait - * - Max 0x7fffffff + * @param ms is the specified millisecond + * - Negative Number wait forever + * - Zero not wait + * - Max 0x7fffffff * - * @return the calculated tick + * @return Return the calculated tick */ rt_tick_t rt_tick_from_millisecond(rt_int32_t ms) { @@ -126,9 +128,13 @@ rt_tick_t rt_tick_from_millisecond(rt_int32_t ms) RTM_EXPORT(rt_tick_from_millisecond); /** - * This function will provide the passed millisecond from boot. - * - * @return passed millisecond from boot + * @brief This function will return the passed millisecond from boot. + * + * @note When 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. + * + * @return Return passed millisecond from boot */ RT_WEAK rt_tick_t rt_tick_get_millisecond(void) { From ce1402f773314f5c9b1465bb6f8838b0d68188a9 Mon Sep 17 00:00:00 2001 From: guozhanxin Date: Fri, 10 Sep 2021 15:52:37 +0800 Subject: [PATCH 2/5] [kernel] Improve the code comment of the components.c --- src/components.c | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/src/components.c b/src/components.c index e156b783e4..2a4affdefb 100644 --- a/src/components.c +++ b/src/components.c @@ -78,7 +78,7 @@ static int rti_end(void) INIT_EXPORT(rti_end, "6.end"); /** - * RT-Thread Components Initialization for board + * @brief RT-Thread Components Initialization for board. */ void rt_components_board_init(void) { @@ -102,7 +102,7 @@ void rt_components_board_init(void) } /** - * RT-Thread Components Initialization + * @brief RT-Thread Components Initialization. */ void rt_components_init(void) { @@ -169,7 +169,11 @@ static rt_uint8_t main_stack[RT_MAIN_THREAD_STACK_SIZE]; struct rt_thread main_thread; #endif /* RT_USING_HEAP */ -/* the system main thread */ +/** + * @brief The system main thread. In this thread will call the rt_components_init() + * for initialization of RT-Thread Components and call the user's programming + * entry main(). + */ void main_thread_entry(void *parameter) { extern int main(void); @@ -193,6 +197,10 @@ void main_thread_entry(void *parameter) #endif } +/** + * @brief This function will create and start the main thread, but this thread + * will not run until the scheduler starts. + */ void rt_application_init(void) { rt_thread_t tid; @@ -216,6 +224,11 @@ void rt_application_init(void) rt_thread_startup(tid); } +/** + * @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. + */ int rtthread_startup(void) { rt_hw_interrupt_disable(); From e562c6f24bf3f857f11aa0bd82d46a6b4767464a Mon Sep 17 00:00:00 2001 From: guozhanxin Date: Fri, 10 Sep 2021 16:31:29 +0800 Subject: [PATCH 3/5] =?UTF-8?q?[kernel]=20=E8=A3=81=E5=89=AA=E5=B0=BE?= =?UTF-8?q?=E9=9A=8F=E7=A9=BA=E6=A0=BC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/clock.c | 6 +++--- src/components.c | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/clock.c b/src/clock.c index 3b35e98d34..e49df94aae 100644 --- a/src/clock.c +++ b/src/clock.c @@ -46,7 +46,7 @@ RTM_EXPORT(rt_tick_get); /** * @brief This function will set current tick - * + * * @param tick is the value that you will set. */ void rt_tick_set(rt_tick_t tick) @@ -129,11 +129,11 @@ 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 * is not an integral multiple of 1000, this function will not * provide the correct 1ms-based tick. - * + * * @return Return passed millisecond from boot */ RT_WEAK rt_tick_t rt_tick_get_millisecond(void) diff --git a/src/components.c b/src/components.c index 2a4affdefb..87e76091f2 100644 --- a/src/components.c +++ b/src/components.c @@ -199,7 +199,7 @@ void main_thread_entry(void *parameter) /** * @brief This function will create and start the main thread, but this thread - * will not run until the scheduler starts. + * will not run until the scheduler starts. */ void rt_application_init(void) { From e6f5282f6e547c2924c8921dcfacfb13de4f9e60 Mon Sep 17 00:00:00 2001 From: guozhanxin Date: Fri, 10 Sep 2021 18:08:30 +0800 Subject: [PATCH 4/5] [kernel] Improve the code comment of the cpu.c --- src/cpu.c | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 50 insertions(+), 3 deletions(-) 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) { From 6cb093aa272a0b1ef908cbd8e103cbd94120b3c6 Mon Sep 17 00:00:00 2001 From: guozhanxin Date: Sat, 11 Sep 2021 18:29:37 +0800 Subject: [PATCH 5/5] [kernel] Improve code comments. --- src/clock.c | 2 +- src/components.c | 9 +++++---- src/cpu.c | 1 - 3 files changed, 6 insertions(+), 6 deletions(-) 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) {