From 65ecca80ee7b3e63998d2207f28fdc8847169eb3 Mon Sep 17 00:00:00 2001 From: Meco Man <920369182@qq.com> Date: Fri, 14 Jan 2022 12:24:12 -0500 Subject: [PATCH] [kernel] improve comments --- src/device.c | 21 +++++++++++++++------ src/ipc.c | 13 +++++++------ src/thread.c | 16 ++++++++-------- src/timer.c | 12 ++++++------ 4 files changed, 36 insertions(+), 26 deletions(-) diff --git a/src/device.c b/src/device.c index ebb8f26854..9bfaf776d6 100644 --- a/src/device.c +++ b/src/device.c @@ -82,6 +82,7 @@ RTM_EXPORT(rt_device_register); */ rt_err_t rt_device_unregister(rt_device_t dev) { + /* parameter check */ RT_ASSERT(dev != RT_NULL); RT_ASSERT(rt_object_get_type(&dev->parent) == RT_Object_Class_Device); RT_ASSERT(rt_object_is_systemobject(&dev->parent)); @@ -143,6 +144,7 @@ RTM_EXPORT(rt_device_create); */ void rt_device_destroy(rt_device_t dev) { + /* parameter check */ RT_ASSERT(dev != RT_NULL); RT_ASSERT(rt_object_get_type(&dev->parent) == RT_Object_Class_Device); RT_ASSERT(rt_object_is_systemobject(&dev->parent) == RT_FALSE); @@ -202,6 +204,7 @@ rt_err_t rt_device_open(rt_device_t dev, rt_uint16_t oflag) { rt_err_t result = RT_EOK; + /* parameter check */ RT_ASSERT(dev != RT_NULL); RT_ASSERT(rt_object_get_type(&dev->parent) == RT_Object_Class_Device); @@ -267,6 +270,7 @@ rt_err_t rt_device_close(rt_device_t dev) { rt_err_t result = RT_EOK; + /* parameter check */ RT_ASSERT(dev != RT_NULL); RT_ASSERT(rt_object_get_type(&dev->parent) == RT_Object_Class_Device); @@ -312,6 +316,7 @@ rt_size_t rt_device_read(rt_device_t dev, void *buffer, rt_size_t size) { + /* parameter check */ RT_ASSERT(dev != RT_NULL); RT_ASSERT(rt_object_get_type(&dev->parent) == RT_Object_Class_Device); @@ -354,6 +359,7 @@ rt_size_t rt_device_write(rt_device_t dev, const void *buffer, rt_size_t size) { + /* parameter check */ RT_ASSERT(dev != RT_NULL); RT_ASSERT(rt_object_get_type(&dev->parent) == RT_Object_Class_Device); @@ -389,6 +395,7 @@ RTM_EXPORT(rt_device_write); */ rt_err_t rt_device_control(rt_device_t dev, int cmd, void *arg) { + /* parameter check */ RT_ASSERT(dev != RT_NULL); RT_ASSERT(rt_object_get_type(&dev->parent) == RT_Object_Class_Device); @@ -412,10 +419,11 @@ RTM_EXPORT(rt_device_control); * * @return RT_EOK */ -rt_err_t -rt_device_set_rx_indicate(rt_device_t dev, - rt_err_t (*rx_ind)(rt_device_t dev, rt_size_t size)) +rt_err_t rt_device_set_rx_indicate(rt_device_t dev, + rt_err_t (*rx_ind)(rt_device_t dev, + rt_size_t size)) { + /* parameter check */ RT_ASSERT(dev != RT_NULL); RT_ASSERT(rt_object_get_type(&dev->parent) == RT_Object_Class_Device); @@ -435,10 +443,11 @@ RTM_EXPORT(rt_device_set_rx_indicate); * * @return RT_EOK */ -rt_err_t -rt_device_set_tx_complete(rt_device_t dev, - rt_err_t (*tx_done)(rt_device_t dev, void *buffer)) +rt_err_t rt_device_set_tx_complete(rt_device_t dev, + rt_err_t (*tx_done)(rt_device_t dev, + void *buffer)) { + /* parameter check */ RT_ASSERT(dev != RT_NULL); RT_ASSERT(rt_object_get_type(&dev->parent) == RT_Object_Class_Device); diff --git a/src/ipc.c b/src/ipc.c index 09cc74e103..aea149a67a 100755 --- a/src/ipc.c +++ b/src/ipc.c @@ -725,8 +725,7 @@ RTM_EXPORT(rt_sem_control); * * @param flag is the mutex flag, which determines the queuing way of how multiple threads wait * when the mutex is not available. - * NOTE: The mutex flag can ONLY be RT_IPC_FLAG_PRIO. Using RT_IPC_FLAG_FIFO will seriously affect - * the real-time performance of the system. + * NOTE: This parameter has been obsoleted. It can be RT_IPC_FLAG_PRIO, RT_IPC_FLAG_FIFO or RT_NULL. * * @return Return the operation status. When the return value is RT_EOK, the initialization is successful. * If the return value is any other values, it represents the initialization failed. @@ -735,7 +734,8 @@ RTM_EXPORT(rt_sem_control); */ rt_err_t rt_mutex_init(rt_mutex_t mutex, const char *name, rt_uint8_t flag) { - (void)flag; + /* flag parameter has been obsoleted */ + RT_UNUSED(flag); /* parameter check */ RT_ASSERT(mutex != RT_NULL); @@ -807,8 +807,7 @@ RTM_EXPORT(rt_mutex_detach); * * @param flag is the mutex flag, which determines the queuing way of how multiple threads wait * when the mutex is not available. - * NOTE: The mutex flag can ONLY be RT_IPC_FLAG_PRIO. Using RT_IPC_FLAG_FIFO will seriously affect - * the real-time performance of the system. + * NOTE: This parameter has been obsoleted. It can be RT_IPC_FLAG_PRIO, RT_IPC_FLAG_FIFO or RT_NULL. * * @return Return a pointer to the mutex object. When the return value is RT_NULL, it means the creation failed. * @@ -817,7 +816,9 @@ RTM_EXPORT(rt_mutex_detach); rt_mutex_t rt_mutex_create(const char *name, rt_uint8_t flag) { struct rt_mutex *mutex; - (void)flag; + + /* flag parameter has been obsoleted */ + RT_UNUSED(flag); RT_DEBUG_NOT_IN_INTERRUPT; diff --git a/src/thread.c b/src/thread.c index 6c221c1f29..bf1f2482a9 100644 --- a/src/thread.c +++ b/src/thread.c @@ -130,7 +130,7 @@ static void _thread_timeout(void *parameter) thread = (struct rt_thread *)parameter; - /* thread check */ + /* parameter check */ RT_ASSERT(thread != RT_NULL); RT_ASSERT((thread->stat & RT_THREAD_STAT_MASK) == RT_THREAD_SUSPEND); RT_ASSERT(rt_object_get_type((rt_object_t)thread) == RT_Object_Class_Thread); @@ -289,7 +289,7 @@ rt_err_t rt_thread_init(struct rt_thread *thread, rt_uint8_t priority, rt_uint32_t tick) { - /* thread check */ + /* parameter check */ RT_ASSERT(thread != RT_NULL); RT_ASSERT(stack_start != RT_NULL); @@ -340,7 +340,7 @@ RTM_EXPORT(rt_thread_self); */ rt_err_t rt_thread_startup(rt_thread_t thread) { - /* thread check */ + /* parameter check */ RT_ASSERT(thread != RT_NULL); RT_ASSERT((thread->stat & RT_THREAD_STAT_MASK) == RT_THREAD_INIT); RT_ASSERT(rt_object_get_type((rt_object_t)thread) == RT_Object_Class_Thread); @@ -383,7 +383,7 @@ rt_err_t rt_thread_detach(rt_thread_t thread) { rt_base_t lock; - /* thread check */ + /* parameter check */ RT_ASSERT(thread != RT_NULL); RT_ASSERT(rt_object_get_type((rt_object_t)thread) == RT_Object_Class_Thread); RT_ASSERT(rt_object_is_systemobject((rt_object_t)thread)); @@ -486,7 +486,7 @@ rt_err_t rt_thread_delete(rt_thread_t thread) { rt_base_t lock; - /* thread check */ + /* parameter check */ RT_ASSERT(thread != RT_NULL); RT_ASSERT(rt_object_get_type((rt_object_t)thread) == RT_Object_Class_Thread); RT_ASSERT(rt_object_is_systemobject((rt_object_t)thread) == RT_FALSE); @@ -703,7 +703,7 @@ rt_err_t rt_thread_control(rt_thread_t thread, int cmd, void *arg) { register rt_base_t temp; - /* thread check */ + /* parameter check */ RT_ASSERT(thread != RT_NULL); RT_ASSERT(rt_object_get_type((rt_object_t)thread) == RT_Object_Class_Thread); @@ -821,7 +821,7 @@ rt_err_t rt_thread_suspend(rt_thread_t thread) register rt_base_t stat; register rt_base_t temp; - /* thread check */ + /* parameter check */ RT_ASSERT(thread != RT_NULL); RT_ASSERT(rt_object_get_type((rt_object_t)thread) == RT_Object_Class_Thread); RT_ASSERT(thread == rt_thread_self()); @@ -867,7 +867,7 @@ rt_err_t rt_thread_resume(rt_thread_t thread) { register rt_base_t temp; - /* thread check */ + /* parameter check */ RT_ASSERT(thread != RT_NULL); RT_ASSERT(rt_object_get_type((rt_object_t)thread) == RT_Object_Class_Thread); diff --git a/src/timer.c b/src/timer.c index 6ef9a4ed3f..577dd5ae47 100644 --- a/src/timer.c +++ b/src/timer.c @@ -257,7 +257,7 @@ void rt_timer_init(rt_timer_t timer, rt_tick_t time, rt_uint8_t flag) { - /* timer check */ + /* parameter check */ RT_ASSERT(timer != RT_NULL); /* timer object initialization */ @@ -278,7 +278,7 @@ rt_err_t rt_timer_detach(rt_timer_t timer) { register rt_base_t level; - /* timer check */ + /* parameter check */ RT_ASSERT(timer != RT_NULL); RT_ASSERT(rt_object_get_type(&timer->parent) == RT_Object_Class_Timer); RT_ASSERT(rt_object_is_systemobject(&timer->parent)); @@ -347,7 +347,7 @@ rt_err_t rt_timer_delete(rt_timer_t timer) { register rt_base_t level; - /* timer check */ + /* parameter check */ RT_ASSERT(timer != RT_NULL); RT_ASSERT(rt_object_get_type(&timer->parent) == RT_Object_Class_Timer); RT_ASSERT(rt_object_is_systemobject(&timer->parent) == RT_FALSE); @@ -386,7 +386,7 @@ rt_err_t rt_timer_start(rt_timer_t timer) unsigned int tst_nr; static unsigned int random_nr; - /* timer check */ + /* parameter check */ RT_ASSERT(timer != RT_NULL); RT_ASSERT(rt_object_get_type(&timer->parent) == RT_Object_Class_Timer); @@ -511,7 +511,7 @@ rt_err_t rt_timer_stop(rt_timer_t timer) { register rt_base_t level; - /* timer check */ + /* parameter check */ RT_ASSERT(timer != RT_NULL); RT_ASSERT(rt_object_get_type(&timer->parent) == RT_Object_Class_Timer); @@ -547,7 +547,7 @@ rt_err_t rt_timer_control(rt_timer_t timer, int cmd, void *arg) { register rt_base_t level; - /* timer check */ + /* parameter check */ RT_ASSERT(timer != RT_NULL); RT_ASSERT(rt_object_get_type(&timer->parent) == RT_Object_Class_Timer);