libs/rt-thread
libs
/
rt-thread
4
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[kernel] update comments

This commit is contained in:
yangjie 2021-09-11 16:40:56 +08:00
parent 5de6996670
commit 464d0c5a97
6 changed files with 108 additions and 108 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
src/device.c
View File

@ -39,13 +39,13 @@
#endif /* RT_USING_DEVICE_OPS */ #endif /* RT_USING_DEVICE_OPS */
/** /**
* @brief This function registers a device driver with specified name. * @brief This function registers a device driver with a specified name.
* *
* @param dev the pointer of device driver structure. * @param dev is the pointer of device driver structure.
* *
* @param name the device driver's name. * @param name is the device driver's name.
* *
* @param flags the capabilities flag of device. * @param flags is the capabilities flag of device.
* *
* @return the error code, RT_EOK on initialization successfully. * @return the error code, RT_EOK on initialization successfully.
*/ */
@ -76,7 +76,7 @@ RTM_EXPORT(rt_device_register);
/** /**
* @brief This function removes a previously registered device driver. * @brief This function removes a previously registered device driver.
* *
* @param dev the pointer of device driver structure. * @param dev is the pointer of device driver structure.
* *
* @return the error code, RT_EOK on successfully. * @return the error code, RT_EOK on successfully.
*/ */
@ -95,7 +95,7 @@ RTM_EXPORT(rt_device_unregister);
/** /**
* @brief This function finds a device driver by specified name. * @brief This function finds a device driver by specified name.
* *
* @param name the device driver's name. * @param name is the device driver's name.
* *
* @return the registered device driver on successful, or RT_NULL on failure. * @return the registered device driver on successful, or RT_NULL on failure.
*/ */
@ -109,9 +109,9 @@ RTM_EXPORT(rt_device_find);
/** /**
* @brief This function creates a device object with user data size. * @brief This function creates a device object with user data size.
* *
* @param type the kind type of this device object. * @param type is the type of the device object.
* *
* @param attach_size the size of user data. * @param attach_size is the size of user data.
* *
* @return the allocated device object, or RT_NULL when failed. * @return the allocated device object, or RT_NULL when failed.
*/ */
@ -139,7 +139,7 @@ RTM_EXPORT(rt_device_create);
/** /**
* @brief This function destroy the specific device object. * @brief This function destroy the specific device object.
* *
* @param dev the specific device object. * @param dev is a specific device object.
*/ */
void rt_device_destroy(rt_device_t dev) void rt_device_destroy(rt_device_t dev)
{ {
@ -158,7 +158,7 @@ RTM_EXPORT(rt_device_destroy);
/** /**
* @brief This function will initialize the specified device. * @brief This function will initialize the specified device.
* *
* @param dev the pointer of device driver structure. * @param dev is the pointer of device driver structure.
* *
* @return the result, RT_EOK on successfully. * @return the result, RT_EOK on successfully.
*/ */
@ -192,9 +192,9 @@ rt_err_t rt_device_init(rt_device_t dev)
/** /**
* @brief This function will open a device. * @brief This function will open a device.
* *
* @param dev the pointer of device driver structure. * @param dev is the pointer of device driver structure.
* *
* @param oflag the flags for device open. * @param oflag is the flags for device open.
* *
* @return the result, RT_EOK on successfully. * @return the result, RT_EOK on successfully.
*/ */
@ -259,7 +259,7 @@ RTM_EXPORT(rt_device_open);
/** /**
* @brief This function will close a device. * @brief This function will close a device.
* *
* @param dev the pointer of device driver structure. * @param dev is the pointer of device driver structure.
* *
* @return the result, RT_EOK on successfully. * @return the result, RT_EOK on successfully.
*/ */
@ -295,13 +295,13 @@ RTM_EXPORT(rt_device_close);
/** /**
* @brief This function will read some data from a device. * @brief This function will read some data from a device.
* *
* @param dev the pointer of device driver structure. * @param dev is the pointer of device driver structure.
* *
* @param pos the position of reading. * @param pos is the position when reading.
* *
* @param buffer the data buffer to save read data. * @param buffer is a data buffer to save the read data.
* *
* @param size the size of buffer. * @param size is the size of buffer.
* *
* @return the actually read size on successful, otherwise negative returned. * @return the actually read size on successful, otherwise negative returned.
* *
@ -337,13 +337,13 @@ RTM_EXPORT(rt_device_read);
/** /**
* @brief This function will write some data to a device. * @brief This function will write some data to a device.
* *
* @param dev the pointer of device driver structure. * @param dev is the pointer of device driver structure.
* *
* @param pos the position of written. * @param pos is the position when writing.
* *
* @param buffer the data buffer to be written to device. * @param buffer is the data buffer to be written to device.
* *
* @param size the size of buffer. * @param size is the size of buffer.
* *
* @return the actually written size on successful, otherwise negative returned. * @return the actually written size on successful, otherwise negative returned.
* *
@ -379,11 +379,11 @@ RTM_EXPORT(rt_device_write);
/** /**
* @brief This function will perform a variety of control functions on devices. * @brief This function will perform a variety of control functions on devices.
* *
* @param dev the pointer of device driver structure. * @param dev is the pointer of device driver structure.
* *
* @param cmd the command sent to device. * @param cmd is the command sent to device.
* *
* @param arg the argument of command. * @param arg is the argument of command.
* *
* @return the result, -RT_ENOSYS for failed. * @return the result, -RT_ENOSYS for failed.
*/ */
@ -406,11 +406,11 @@ RTM_EXPORT(rt_device_control);
* @brief This function will set the reception indication callback function. This callback function * @brief This function will set the reception indication callback function. This callback function
* is invoked when this device receives data. * is invoked when this device receives data.
* *
* @param dev the pointer of device driver structure. * @param dev is the pointer of device driver structure.
* *
* @param rx_ind the indication callback function. * @param rx_ind is the indication callback function.
* *
* @return RT_EOK. * @return RT_EOK
*/ */
rt_err_t rt_err_t
rt_device_set_rx_indicate(rt_device_t dev, rt_device_set_rx_indicate(rt_device_t dev,
@ -426,14 +426,14 @@ rt_device_set_rx_indicate(rt_device_t dev,
RTM_EXPORT(rt_device_set_rx_indicate); RTM_EXPORT(rt_device_set_rx_indicate);
/** /**
* @brief This function will set the indication callback function when device has * @brief This function will set a callback function. The callback function
* written data to physical hardware. * will be called when device has written data to physical hardware.
* *
* @param dev the pointer of device driver structure. * @param dev is the pointer of device driver structure.
* *
* @param tx_done the indication callback function. * @param tx_done is the indication callback function.
* *
* @return RT_EOK. * @return RT_EOK
*/ */
rt_err_t rt_err_t
rt_device_set_tx_complete(rt_device_t dev, rt_device_set_tx_complete(rt_device_t dev,

14
src/mem.c
View File

@ -266,7 +266,7 @@ void rt_system_heap_init(void *begin_addr, void *end_addr)
* *
* @param size is the minimum size of the requested block in bytes. * @param size is the minimum size of the requested block in bytes.
* *
* @return pointer to allocated memory or NULL if no free memory was found. * @return the pointer to allocated memory or NULL if no free memory was found.
*/ */
void *rt_malloc(rt_size_t size) void *rt_malloc(rt_size_t size)
{ {
@ -410,11 +410,11 @@ void *rt_malloc(rt_size_t size)
RTM_EXPORT(rt_malloc); RTM_EXPORT(rt_malloc);
/** /**
* @brief This function will change the previously allocated memory block. * @brief This function will change the size of previously allocated memory block.
* *
* @param rmem pointer to memory allocated by rt_malloc. * @param rmem is the pointer to memory allocated by rt_malloc.
* *
* @param newsize the required new size. * @param newsize is the required new size.
* *
* @return the changed memory block address. * @return the changed memory block address.
*/ */
@ -523,9 +523,9 @@ RTM_EXPORT(rt_realloc);
* *
* @note The allocated memory is filled with bytes of value zero. * @note The allocated memory is filled with bytes of value zero.
* *
* @param count number of objects to allocate. * @param count is the number of objects to allocate.
* *
* @param size size of the objects to allocate. * @param size is the size of one object to allocate.
* *
* @return pointer to allocated memory / NULL pointer if there is an error. * @return pointer to allocated memory / NULL pointer if there is an error.
*/ */
@ -548,7 +548,7 @@ RTM_EXPORT(rt_calloc);
* @brief This function will release the previously allocated memory block by * @brief This function will release the previously allocated memory block by
* rt_malloc. The released memory block is taken back to system heap. * rt_malloc. The released memory block is taken back to system heap.
* *
* @param rmem the address of memory which will be released * @param rmem the address of memory which will be released.
*/ */
void rt_free(void *rmem) void rt_free(void *rmem)
{ {

33
src/mempool.c
View File

@ -33,7 +33,7 @@ static void (*rt_mp_free_hook)(struct rt_mempool *mp, void *block);
/** /**
* @brief This function will set a hook function, which will be invoked when a memory * @brief This function will set a hook function, which will be invoked when a memory
* block is allocated from memory pool. * block is allocated from the memory pool.
* *
* @param hook the hook function * @param hook the hook function
*/ */
@ -44,7 +44,7 @@ void rt_mp_alloc_sethook(void (*hook)(struct rt_mempool *mp, void *block))
/** /**
* @brief This function will set a hook function, which will be invoked when a memory * @brief This function will set a hook function, which will be invoked when a memory
* block is released to memory pool. * block is released to the memory pool.
* *
* @param hook the hook function * @param hook the hook function
*/ */
@ -66,15 +66,15 @@ void rt_mp_free_sethook(void (*hook)(struct rt_mempool *mp, void *block))
* @brief This function will initialize a memory pool object, normally which is used * @brief This function will initialize a memory pool object, normally which is used
* for static object. * for static object.
* *
* @param mp the memory pool object * @param mp is the memory pool object.
* *
* @param name the name of memory pool * @param name is the name of the memory pool.
* *
* @param start the star address of memory pool * @param start is the start address of the memory pool.
* *
* @param size the total size of memory pool * @param size is the total size of the memory pool.
* *
* @param block_size the size for each block * @param block_size is the size for each block..
* *
* @return RT_EOK * @return RT_EOK
*/ */
@ -131,7 +131,7 @@ RTM_EXPORT(rt_mp_init);
/** /**
* @brief This function will detach a memory pool from system object management. * @brief This function will detach a memory pool from system object management.
* *
* @param mp the memory pool object. * @param mp is the memory pool object.
* *
* @return RT_EOK * @return RT_EOK
*/ */
@ -179,11 +179,11 @@ RTM_EXPORT(rt_mp_detach);
* @brief This function will create a mempool object and allocate the memory pool from * @brief This function will create a mempool object and allocate the memory pool from
* heap. * heap.
* *
* @param name the name of memory pool * @param name is the name of memory pool.
* *
* @param block_count the count of blocks in memory pool * @param block_count is the count of blocks in memory pool.
* *
* @param block_size the size for each block * @param block_size is the size for each block.
* *
* @return the created mempool object * @return the created mempool object
*/ */
@ -249,7 +249,7 @@ RTM_EXPORT(rt_mp_create);
/** /**
* @brief This function will delete a memory pool and release the object memory. * @brief This function will delete a memory pool and release the object memory.
* *
* @param mp the memory pool object. * @param mp is the memory pool object.
* *
* @return RT_EOK * @return RT_EOK
*/ */
@ -301,9 +301,10 @@ RTM_EXPORT(rt_mp_delete);
/** /**
* @brief This function will allocate a block from memory pool. * @brief This function will allocate a block from memory pool.
* *
* @param mp the memory pool object. * @param mp is the memory pool object.
* *
* @param time the waiting time. * @param time is the maximum waiting time for allocating memory.
* - 0 for not waiting, allocating memory immediately.
* *
* @return the allocated memory block or RT_NULL on allocated failed. * @return the allocated memory block or RT_NULL on allocated failed.
*/ */
@ -399,9 +400,9 @@ void *rt_mp_alloc(rt_mp_t mp, rt_int32_t time)
RTM_EXPORT(rt_mp_alloc); RTM_EXPORT(rt_mp_alloc);
/** /**
* @brief This function will release a memory block * @brief This function will release a memory block.
* *
* @param block the address of memory block to be released * @param block the address of memory block to be released.
*/ */
void rt_mp_free(void *block) void rt_mp_free(void *block)
{ {

40
src/object.c
View File

@ -123,7 +123,7 @@ void (*rt_object_put_hook)(struct rt_object *object);
* @brief This function will set a hook function, which will be invoked when object * @brief This function will set a hook function, which will be invoked when object
* attaches to kernel object system. * 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)) void rt_object_attach_sethook(void (*hook)(struct rt_object *object))
{ {
@ -134,7 +134,7 @@ void rt_object_attach_sethook(void (*hook)(struct rt_object *object))
* @brief This function will set a hook function, which will be invoked when object * @brief This function will set a hook function, which will be invoked when object
* detaches from kernel object system. * 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)) void rt_object_detach_sethook(void (*hook)(struct rt_object *object))
{ {
@ -152,7 +152,7 @@ void rt_object_detach_sethook(void (*hook)(struct rt_object *object))
* mailbox - mail is received by thread * mailbox - mail is received by thread
* message queue - message 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)) void rt_object_trytake_sethook(void (*hook)(struct rt_object *object))
{ {
@ -182,7 +182,7 @@ void rt_object_take_sethook(void (*hook)(struct rt_object *object))
* @brief This function will set a hook function, which will be invoked when object * @brief This function will set a hook function, which will be invoked when object
* is put to kernel object system. * 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)) void rt_object_put_sethook(void (*hook)(struct rt_object *object))
{ {
@ -201,7 +201,7 @@ void rt_object_put_sethook(void (*hook)(struct rt_object *object))
/** /**
* @brief 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 * RT_Object_Class_Thread/Semaphore/Mutex... etc
* *
* @return the object type information or RT_NULL * @return the object type information or RT_NULL
@ -221,7 +221,7 @@ RTM_EXPORT(rt_object_get_information);
/** /**
* @brief 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 * RT_Object_Class_Thread/Semaphore/Mutex... etc
* *
* @return the length of object list * @return the length of object list
@ -252,14 +252,14 @@ RTM_EXPORT(rt_object_get_length);
* @brief This function will copy the object pointer of the specified type, * @brief This function will copy the object pointer of the specified type,
* with the maximum size specified by maxlen. * 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 * RT_Object_Class_Thread/Semaphore/Mutex... etc
* *
* @param pointers the pointers will be saved to * @param pointers is the pointer will be saved to.
* *
* @param maxlen the maximum number of pointers can be saved * @param maxlen is the maximum number of pointers can be saved.
* *
* @return the copied number of object pointers * @return the copied number of object pointers.
*/ */
int rt_object_get_pointers(enum rt_object_class_type type, rt_object_t *pointers, int maxlen) int rt_object_get_pointers(enum rt_object_class_type type, rt_object_t *pointers, int maxlen)
{ {
@ -296,11 +296,11 @@ RTM_EXPORT(rt_object_get_pointers);
* @brief This function will initialize an object and add it to object system * @brief This function will initialize an object and add it to object system
* management. * management.
* *
* @param object the specified object to be initialized. * @param object is the specified object to be initialized.
* *
* @param type the object type. * @param type is 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, void rt_object_init(struct rt_object *object,
enum rt_object_class_type type, enum rt_object_class_type type,
@ -397,9 +397,9 @@ void rt_object_detach(rt_object_t object)
/** /**
* @brief 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 type is the type of object.
* *
* @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.
* *
* @return object * @return object
*/ */
@ -467,7 +467,7 @@ rt_object_t rt_object_allocate(enum rt_object_class_type type, const char *name)
/** /**
* @brief 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) void rt_object_delete(rt_object_t object)
{ {
@ -502,7 +502,7 @@ void rt_object_delete(rt_object_t object)
* @note Normally, the system object is a static object and the type * @note Normally, the system object is a static object and the type
* of object set to RT_Object_Class_Static. * of object set to RT_Object_Class_Static.
* *
* @param object the specified object to be judged. * @param object is the specified object to be judged.
* *
* @return RT_TRUE if a system object, RT_FALSE for others. * @return RT_TRUE if a system object, RT_FALSE for others.
*/ */
@ -521,7 +521,7 @@ rt_bool_t rt_object_is_systemobject(rt_object_t object)
* @brief This function will return the type of object without * @brief This function will return the type of object without
* RT_Object_Class_Static flag. * 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. * @return the type of object.
*/ */
@ -537,9 +537,9 @@ rt_uint8_t rt_object_get_type(rt_object_t object)
* @brief This function will find specified name object from object * @brief This function will find specified name object from object
* container. * container.
* *
* @param name the specified name of object. * @param name is 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 * @return the found object or RT_NULL if there is no this object
* in object container. * in object container.

29
src/scheduler.c
View File

@ -61,7 +61,7 @@ static void (*rt_scheduler_switch_hook)(struct rt_thread *tid);
* @brief This function will set a hook function, which will be invoked when thread * @brief This function will set a hook function, which will be invoked when thread
* switch happens. * switch happens.
* *
* @param hook the hook function. * @param hook is the hook function.
*/ */
void rt_scheduler_sethook(void (*hook)(struct rt_thread *from, struct rt_thread *to)) void rt_scheduler_sethook(void (*hook)(struct rt_thread *from, struct rt_thread *to))
{ {
@ -72,7 +72,7 @@ void rt_scheduler_sethook(void (*hook)(struct rt_thread *from, struct rt_thread
* @brief This function will set a hook function, which will be invoked when context * @brief This function will set a hook function, which will be invoked when context
* switch happens. * switch happens.
* *
* @param hook the hook function. * @param hook is the hook function.
*/ */
void rt_scheduler_switch_sethook(void (*hook)(struct rt_thread *tid)) void rt_scheduler_switch_sethook(void (*hook)(struct rt_thread *tid))
{ {
@ -235,8 +235,7 @@ void rt_system_scheduler_init(void)
} }
/** /**
* @ingroup SystemInit * @brief This function will startup the scheduler. It will select one thread
* This function will startup scheduler. It will select one thread
* with the highest priority level, then switch to it. * with the highest priority level, then switch to it.
*/ */
void rt_system_scheduler_start(void) void rt_system_scheduler_start(void)
@ -276,9 +275,9 @@ void rt_system_scheduler_start(void)
/** /**
* @brief This function will handle IPI interrupt and do a scheduling in system. * @brief This function will handle IPI interrupt and do a scheduling in system.
* *
* @param vector the number of IPI interrupt for system scheduling. * @param vector is the number of IPI interrupt for system scheduling.
* *
* @param param use RT_NULL. * @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 should be invoke or register as ISR in BSP.
*/ */
@ -411,8 +410,8 @@ __exit:
} }
#else #else
/** /**
* @brief This function will perform one schedule. It will select one thread * @brief This function will perform scheduling once. It will select one thread
* with the highest priority level, and switch to it immediately. * with the highest priority, and switch to it immediately.
*/ */
void rt_schedule(void) void rt_schedule(void)
{ {
@ -540,7 +539,7 @@ __exit:
#endif /* RT_USING_SMP */ #endif /* RT_USING_SMP */
/** /**
* @brief This function checks if a scheduling is needed after IRQ context. If yes, * @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 * it will select one thread with the highest priority level, and then switch
* to it. * to it.
*/ */
@ -636,10 +635,10 @@ void rt_scheduler_do_irq_switch(void *context)
#endif /* RT_USING_SMP */ #endif /* RT_USING_SMP */
/** /**
* @brief This function will insert a thread to system ready queue. The state of * @brief This function will insert a thread to the system ready queue. The state of
* thread will be set as READY and remove from suspend queue. * thread will be set as READY and the thread will be removed from suspend queue.
* *
* @param thread the thread to be inserted * @param thread is the thread to be inserted.
* *
* @note Please do not invoke this function in user application. * @note Please do not invoke this function in user application.
*/ */
@ -746,10 +745,10 @@ __exit:
} }
#endif /* RT_USING_SMP */ #endif /* RT_USING_SMP */
/* /**
* This function will remove a thread from system ready queue. * @brief This function will remove a thread from system ready queue.
* *
* @param thread the thread to be removed * @param thread is the thread to be removed.
* *
* @note Please do not invoke this function in user application. * @note Please do not invoke this function in user application.
*/ */

16
src/slab.c
View File

@ -277,9 +277,9 @@ void *rt_page_alloc(rt_size_t npages)
/** /**
* @brief Free memory by page. * @brief Free memory by page.
* *
* @param addr the head address of first page. * @param addr is the head address of first page.
* *
* @param npages the number of pages. * @param npages is the number of pages.
*/ */
void rt_page_free(void *addr, rt_size_t npages) void rt_page_free(void *addr, rt_size_t npages)
{ {
@ -482,7 +482,7 @@ rt_inline int zoneindex(rt_size_t *bytes)
* - the nbytes is less than zero. * - the nbytes is less than zero.
* - there is no nbytes sized memory valid in system. * - there is no nbytes sized memory valid in system.
* *
* @param size the size of memory to be allocated. * @param size is the size of memory to be allocated.
* *
* @return the allocated memory. * @return the allocated memory.
*/ */
@ -681,9 +681,9 @@ RTM_EXPORT(rt_malloc);
/** /**
* @brief This function will change the size of previously allocated memory block. * @brief This function will change the size of previously allocated memory block.
* *
* @param ptr the previously allocated memory block. * @param ptr is the previously allocated memory block.
* *
* @param size the new size of memory block. * @param size is the new size of memory block.
* *
* @return the allocated memory. * @return the allocated memory.
*/ */
@ -754,9 +754,9 @@ RTM_EXPORT(rt_realloc);
* *
* @note The allocated memory is filled with bytes of value zero. * @note The allocated memory is filled with bytes of value zero.
* *
* @param count number of objects to allocate. * @param count is the number of objects to allocate.
* *
* @param size size of the objects to allocate. * @param size is the size of the objects to allocate.
* *
* @return pointer to allocated memory / NULL pointer if there is an error. * @return pointer to allocated memory / NULL pointer if there is an error.
*/ */
@ -780,7 +780,7 @@ RTM_EXPORT(rt_calloc);
* *
* @note The released memory block is taken back to system heap. * @note The released memory block is taken back to system heap.
* *
* @param ptr the address of memory which will be released * @param ptr is the address of memory which will be released
*/ */
void rt_free(void *ptr) void rt_free(void *ptr)
{ {