Merge branch 'master' into usbh_construct

1 files changed, 82 insertions, 73 deletions

diff --git a/src/object.c b/src/object.c
index 56263618b3..66d5775bd7 100644
--- a/src/object.c
+++ b/src/object.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006-2018, RT-Thread Development Team
+ * Copyright (c) 2006-2021, RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -20,10 +20,10 @@
 
 #ifdef RT_USING_MODULE
 #include <dlmodule.h>
-#endif
+#endif /* RT_USING_MODULE */
 
 /*
- * define object_info for the number of rt_object_container items.
+ * define object_info for the number of _object_container items.
  */
 enum rt_object_info_type
 {
@@ -60,8 +60,9 @@ enum rt_object_info_type
 };
 
 #define _OBJ_CONTAINER_LIST_INIT(c)     \
-    {&(rt_object_container[c].object_list), &(rt_object_container[c].object_list)}
-static struct rt_object_information rt_object_container[RT_Object_Info_Unknown] =
+    {&(_object_container[c].object_list), &(_object_container[c].object_list)}
+
+static struct rt_object_information _object_container[RT_Object_Info_Unknown] =
 {
     /* initialize object container - thread */
     {RT_Object_Class_Thread, _OBJ_CONTAINER_LIST_INIT(RT_Object_Info_Thread), sizeof(struct rt_thread)},
@@ -119,10 +120,10 @@ void (*rt_object_put_hook)(struct rt_object *object);
 /**@{*/
 
 /**
- * This function will set a hook function, which will be invoked when object
- * attaches to kernel object system.
+ * @brief This function will set a hook function, which will be invoked when object
+ *        attaches to kernel object system.
  *
- * @param hook the hook function
+ * @param hook is the hook function.
  */
 void rt_object_attach_sethook(void (*hook)(struct rt_object *object))
 {
@@ -130,10 +131,10 @@ void rt_object_attach_sethook(void (*hook)(struct rt_object *object))
 }
 
 /**
- * This function will set a hook function, which will be invoked when object
- * detaches from kernel object system.
+ * @brief This function will set a hook function, which will be invoked when object
+ *        detaches from kernel object system.
  *
- * @param hook the hook function
+ * @param hook is the hook function
  */
 void rt_object_detach_sethook(void (*hook)(struct rt_object *object))
 {
@@ -141,17 +142,17 @@ void rt_object_detach_sethook(void (*hook)(struct rt_object *object))
 }
 
 /**
- * This function will set a hook function, which will be invoked when object
- * is taken from kernel object system.
+ * @brief This function will set a hook function, which will be invoked when object
+ *        is taken from kernel object system.
  *
- * The object is taken means:
- * semaphore - semaphore is taken by thread
- * mutex - mutex is taken by thread
- * event - event is received by thread
- * mailbox - mail is received by thread
- * message queue - message is received by thread
+ *        The object is taken means:
+ *            semaphore - semaphore is taken by thread
+ *            mutex - mutex is taken by thread
+ *            event - event is received by thread
+ *            mailbox - mail is received by thread
+ *            message queue - message is received by thread
  *
- * @param hook the hook function
+ * @param hook is the hook function.
  */
 void rt_object_trytake_sethook(void (*hook)(struct rt_object *object))
 {
@@ -159,18 +160,18 @@ void rt_object_trytake_sethook(void (*hook)(struct rt_object *object))
 }
 
 /**
- * This function will set a hook function, which will be invoked when object
- * have been taken from kernel object system.
+ * @brief This function will set a hook function, which will be invoked when object
+ *        have been taken from kernel object system.
  *
- * The object have been taken means:
- * semaphore - semaphore have been taken by thread
- * mutex - mutex have been taken by thread
- * event - event have been received by thread
- * mailbox - mail have been received by thread
- * message queue - message have been received by thread
- * timer - timer is started
+ *        The object have been taken means:
+ *            semaphore - semaphore have been taken by thread
+ *            mutex - mutex have been taken by thread
+ *            event - event have been received by thread
+ *            mailbox - mail have been received by thread
+ *            message queue - message have been received by thread
+ *            timer - timer is started
  *
- * @param hook the hook function
+ * @param hook the hook function.
  */
 void rt_object_take_sethook(void (*hook)(struct rt_object *object))
 {
@@ -178,10 +179,10 @@ void rt_object_take_sethook(void (*hook)(struct rt_object *object))
 }
 
 /**
- * This function will set a hook function, which will be invoked when object
- * is put to kernel object system.
+ * @brief This function will set a hook function, which will be invoked when object
+ *        is put to kernel object system.
  *
- * @param hook the hook function
+ * @param hook is the hook function
  */
 void rt_object_put_sethook(void (*hook)(struct rt_object *object))
 {
@@ -189,7 +190,7 @@ void rt_object_put_sethook(void (*hook)(struct rt_object *object))
 }
 
 /**@}*/
-#endif
+#endif /* RT_USING_HOOK */
 
 /**
  * @addtogroup KernelObject
@@ -198,9 +199,9 @@ void rt_object_put_sethook(void (*hook)(struct rt_object *object))
 /**@{*/
 
 /**
- * This function will return the specified type of object information.
+ * @brief This function will return the specified type of object information.
  *
- * @param type the type of object, which can be 
+ * @param type is the type of object, which can be
  *             RT_Object_Class_Thread/Semaphore/Mutex... etc
  *
  * @return the object type information or RT_NULL
@@ -211,17 +212,18 @@ rt_object_get_information(enum rt_object_class_type type)
     int index;
 
     for (index = 0; index < RT_Object_Info_Unknown; index ++)
-        if (rt_object_container[index].type == type) return &rt_object_container[index];
+        if (_object_container[index].type == type) return &_object_container[index];
 
     return RT_NULL;
 }
 RTM_EXPORT(rt_object_get_information);
 
 /**
- * This function will return the length of object list in object container.
+ * @brief This function will return the length of object list in object container.
  *
- * @param type the type of object, which can be 
+ * @param type is the type of object, which can be
  *             RT_Object_Class_Thread/Semaphore/Mutex... etc
+ *
  * @return the length of object list
  */
 int rt_object_get_length(enum rt_object_class_type type)
@@ -247,15 +249,17 @@ int rt_object_get_length(enum rt_object_class_type type)
 RTM_EXPORT(rt_object_get_length);
 
 /**
- * This function will copy the object pointer of the specified type, 
- * with the maximum size specified by maxlen.
+ * @brief This function will copy the object pointer of the specified type,
+ *        with the maximum size specified by maxlen.
  *
- * @param type the type of object, which can be 
+ * @param type is the type of object, which can be
  *             RT_Object_Class_Thread/Semaphore/Mutex... etc
- * @param pointers the pointers will be saved to
- * @param maxlen the maximum number of pointers can be saved
  *
- * @return the copied number of object pointers
+ * @param pointers is the pointer will be saved to.
+ *
+ * @param maxlen is the maximum number of pointers can be saved.
+ *
+ * @return the copied number of object pointers.
  */
 int rt_object_get_pointers(enum rt_object_class_type type, rt_object_t *pointers, int maxlen)
 {
@@ -289,12 +293,14 @@ int rt_object_get_pointers(enum rt_object_class_type type, rt_object_t *pointers
 RTM_EXPORT(rt_object_get_pointers);
 
 /**
- * This function will initialize an object and add it to object system
- * management.
+ * @brief This function will initialize an object and add it to object system
+ *        management.
+ *
+ * @param object is the specified object to be initialized.
+ *
+ * @param type is the object type.
  *
- * @param object the specified object to be initialized.
- * @param type the object type.
- * @param name the object name. In system, the object's name must be unique.
+ * @param name is the object name. In system, the object's name must be unique.
  */
 void rt_object_init(struct rt_object         *object,
                     enum rt_object_class_type type,
@@ -305,7 +311,7 @@ void rt_object_init(struct rt_object         *object,
     struct rt_object_information *information;
 #ifdef RT_USING_MODULE
     struct rt_dlmodule *module = dlmodule_self();
-#endif
+#endif /* RT_USING_MODULE */
 
     /* get object information */
     information = rt_object_get_information(type);
@@ -349,7 +355,7 @@ void rt_object_init(struct rt_object         *object,
         object->module_id = (void *)module;
     }
     else
-#endif
+#endif /* RT_USING_MODULE */
     {
         /* insert object into information object list */
         rt_list_insert_after(&(information->object_list), &(object->list));
@@ -360,8 +366,8 @@ void rt_object_init(struct rt_object         *object,
 }
 
 /**
- * This function will detach a static object from object system,
- * and the memory of static object is not freed.
+ * @brief This function will detach a static object from object system,
+ *        and the memory of static object is not freed.
  *
  * @param object the specified object to be detached.
  */
@@ -389,10 +395,11 @@ void rt_object_detach(rt_object_t object)
 
 #ifdef RT_USING_HEAP
 /**
- * This function will allocate an object from object system
+ * @brief This function will allocate an object from object system.
  *
- * @param type the type of object
- * @param name the object name. In system, the object's name must be unique.
+ * @param type is the type of object.
+ *
+ * @param name is the object name. In system, the object's name must be unique.
  *
  * @return object
  */
@@ -403,7 +410,7 @@ rt_object_t rt_object_allocate(enum rt_object_class_type type, const char *name)
     struct rt_object_information *information;
 #ifdef RT_USING_MODULE
     struct rt_dlmodule *module = dlmodule_self();
-#endif
+#endif /* RT_USING_MODULE */
 
     RT_DEBUG_NOT_IN_INTERRUPT;
 
@@ -444,7 +451,7 @@ rt_object_t rt_object_allocate(enum rt_object_class_type type, const char *name)
         object->module_id = (void *)module;
     }
     else
-#endif
+#endif /* RT_USING_MODULE */
     {
         /* insert object into information object list */
         rt_list_insert_after(&(information->object_list), &(object->list));
@@ -458,9 +465,9 @@ rt_object_t rt_object_allocate(enum rt_object_class_type type, const char *name)
 }
 
 /**
- * This function will delete an object and release object memory.
+ * @brief This function will delete an object and release object memory.
  *
- * @param object the specified object to be deleted.
+ * @param object is the specified object to be deleted.
  */
 void rt_object_delete(rt_object_t object)
 {
@@ -487,14 +494,15 @@ void rt_object_delete(rt_object_t object)
     /* free the memory of object */
     RT_KERNEL_FREE(object);
 }
-#endif
+#endif /* RT_USING_HEAP */
 
 /**
- * This function will judge the object is system object or not.
- * Normally, the system object is a static object and the type
- * of object set to RT_Object_Class_Static.
+ * @brief This function will judge the object is system object or not.
  *
- * @param object the specified object to be judged.
+ * @note  Normally, the system object is a static object and the type
+ *        of object set to RT_Object_Class_Static.
+ *
+ * @param object is the specified object to be judged.
  *
  * @return RT_TRUE if a system object, RT_FALSE for others.
  */
@@ -510,10 +518,10 @@ rt_bool_t rt_object_is_systemobject(rt_object_t object)
 }
 
 /**
- * This function will return the type of object without
- * RT_Object_Class_Static flag.
+ * @brief This function will return the type of object without
+ *        RT_Object_Class_Static flag.
  *
- * @param object the specified object to be get type.
+ * @param object is the specified object to be get type.
  *
  * @return the type of object.
  */
@@ -526,11 +534,12 @@ rt_uint8_t rt_object_get_type(rt_object_t object)
 }
 
 /**
- * This function will find specified name object from object
- * container.
+ * @brief This function will find specified name object from object
+ *        container.
+ *
+ * @param name is the specified name of object.
  *
- * @param name the specified name of object.
- * @param type the type of object
+ * @param type is the type of object
  *
  * @return the found object or RT_NULL if there is no this object
  * in object container.