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

[kernel]Normalized kernel API annotation

This commit is contained in:
yangjie 2021-09-10 15:55:08 +08:00
parent 54b7814880
commit a912a2f88f
7 changed files with 275 additions and 210 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
src/device.c
View File

@ -39,11 +39,13 @@
#endif /* RT_USING_DEVICE_OPS */ #endif /* RT_USING_DEVICE_OPS */
/** /**
* This function registers a device driver with specified name. * @brief This function registers a device driver with specified name.
* *
* @param dev the pointer of device driver structure * @param dev the pointer of device driver structure.
* @param name the device driver's name *
* @param flags the capabilities flag of device * @param name the device driver's name.
*
* @param flags the capabilities flag of device.
* *
* @return the error code, RT_EOK on initialization successfully. * @return the error code, RT_EOK on initialization successfully.
*/ */
@ -72,9 +74,9 @@ rt_err_t rt_device_register(rt_device_t dev,
RTM_EXPORT(rt_device_register); RTM_EXPORT(rt_device_register);
/** /**
* 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 the pointer of device driver structure.
* *
* @return the error code, RT_EOK on successfully. * @return the error code, RT_EOK on successfully.
*/ */
@ -91,9 +93,9 @@ rt_err_t rt_device_unregister(rt_device_t dev)
RTM_EXPORT(rt_device_unregister); RTM_EXPORT(rt_device_unregister);
/** /**
* 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 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.
*/ */
@ -105,10 +107,11 @@ RTM_EXPORT(rt_device_find);
#ifdef RT_USING_HEAP #ifdef RT_USING_HEAP
/** /**
* 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 the kind type of this device object.
* @param attach_size, the size of user data. *
* @param attach_size 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.
*/ */
@ -134,9 +137,9 @@ rt_device_t rt_device_create(int type, int attach_size)
RTM_EXPORT(rt_device_create); RTM_EXPORT(rt_device_create);
/** /**
* This function destroy the specific device object. * @brief This function destroy the specific device object.
* *
* @param dev, the specific device object. * @param dev the specific device object.
*/ */
void rt_device_destroy(rt_device_t dev) void rt_device_destroy(rt_device_t dev)
{ {
@ -153,11 +156,11 @@ RTM_EXPORT(rt_device_destroy);
#endif /* RT_USING_HEAP */ #endif /* RT_USING_HEAP */
/** /**
* 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 the pointer of device driver structure.
* *
* @return the result * @return the result, RT_EOK on successfully.
*/ */
rt_err_t rt_device_init(rt_device_t dev) rt_err_t rt_device_init(rt_device_t dev)
{ {
@ -187,12 +190,13 @@ rt_err_t rt_device_init(rt_device_t dev)
} }
/** /**
* This function will open a device * @brief This function will open a device.
* *
* @param dev the pointer of device driver structure * @param dev the pointer of device driver structure.
* @param oflag the flags for device open
* *
* @return the result * @param oflag the flags for device open.
*
* @return the result, RT_EOK on successfully.
*/ */
rt_err_t rt_device_open(rt_device_t dev, rt_uint16_t oflag) rt_err_t rt_device_open(rt_device_t dev, rt_uint16_t oflag)
{ {
@ -253,11 +257,11 @@ rt_err_t rt_device_open(rt_device_t dev, rt_uint16_t oflag)
RTM_EXPORT(rt_device_open); RTM_EXPORT(rt_device_open);
/** /**
* This function will close a device * @brief This function will close a device.
* *
* @param dev the pointer of device driver structure * @param dev the pointer of device driver structure.
* *
* @return the result * @return the result, RT_EOK on successfully.
*/ */
rt_err_t rt_device_close(rt_device_t dev) rt_err_t rt_device_close(rt_device_t dev)
{ {
@ -289,12 +293,15 @@ rt_err_t rt_device_close(rt_device_t dev)
RTM_EXPORT(rt_device_close); RTM_EXPORT(rt_device_close);
/** /**
* 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 the pointer of device driver structure.
* @param pos the position of reading *
* @param buffer the data buffer to save read data * @param pos the position of reading.
* @param size the size of buffer *
* @param buffer the data buffer to save read data.
*
* @param size the size of buffer.
* *
* @return the actually read size on successful, otherwise negative returned. * @return the actually read size on successful, otherwise negative returned.
* *
@ -328,12 +335,15 @@ rt_size_t rt_device_read(rt_device_t dev,
RTM_EXPORT(rt_device_read); RTM_EXPORT(rt_device_read);
/** /**
* 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 the pointer of device driver structure.
* @param pos the position of written *
* @param buffer the data buffer to be written to device * @param pos the position of written.
* @param size the size of buffer *
* @param buffer the data buffer to be written to device.
*
* @param size the size of buffer.
* *
* @return the actually written size on successful, otherwise negative returned. * @return the actually written size on successful, otherwise negative returned.
* *
@ -367,13 +377,15 @@ rt_size_t rt_device_write(rt_device_t dev,
RTM_EXPORT(rt_device_write); RTM_EXPORT(rt_device_write);
/** /**
* 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 the pointer of device driver structure.
* @param cmd the command sent to device
* @param arg the argument of command
* *
* @return the result * @param cmd the command sent to device.
*
* @param arg the argument of command.
*
* @return the result, -RT_ENOSYS for failed.
*/ */
rt_err_t rt_device_control(rt_device_t dev, int cmd, void *arg) rt_err_t rt_device_control(rt_device_t dev, int cmd, void *arg)
{ {
@ -391,13 +403,14 @@ rt_err_t rt_device_control(rt_device_t dev, int cmd, void *arg)
RTM_EXPORT(rt_device_control); RTM_EXPORT(rt_device_control);
/** /**
* 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 the pointer of device driver structure.
* @param rx_ind the indication callback function
* *
* @return RT_EOK * @param rx_ind the indication callback function.
*
* @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,
@ -413,13 +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);
/** /**
* This function will set the indication callback function when device has * @brief This function will set the indication callback function when device has
* written data to physical hardware. * written data to physical hardware.
* *
* @param dev the pointer of device driver structure * @param dev the pointer of device driver structure.
* @param tx_done the indication callback function
* *
* @return RT_EOK * @param tx_done the indication callback function.
*
* @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,

44
src/idle.c
View File

@ -68,14 +68,13 @@ static struct rt_semaphore system_sem;
static void (*idle_hook_list[RT_IDLE_HOOK_LIST_SIZE])(void); static void (*idle_hook_list[RT_IDLE_HOOK_LIST_SIZE])(void);
/** /**
* @ingroup Hook * @brief This function sets a hook function to idle thread loop. When the system performs
* This function sets a hook function to idle thread loop. When the system performs * idle loop, this hook function should be invoked.
* idle loop, this hook function should be invoked.
* *
* @param hook the specified hook function * @param hook the specified hook function.
* *
* @return RT_EOK: set OK * @return RT_EOK: set OK.
* -RT_EFULL: hook list is full * -RT_EFULL: hook list is full.
* *
* @note the hook function must be simple and never be blocked or suspend. * @note the hook function must be simple and never be blocked or suspend.
*/ */
@ -104,12 +103,12 @@ rt_err_t rt_thread_idle_sethook(void (*hook)(void))
} }
/** /**
* delete the idle hook on hook list * @brief delete the idle hook on hook list.
* *
* @param hook the specified hook function * @param hook the specified hook function.
* *
* @return RT_EOK: delete OK * @return RT_EOK: delete OK.
* -RT_ENOSYS: hook was not found * -RT_ENOSYS: hook was not found.
*/ */
rt_err_t rt_thread_idle_delhook(void (*hook)(void)) rt_err_t rt_thread_idle_delhook(void (*hook)(void))
{ {
@ -153,8 +152,10 @@ rt_inline int _idle_has_defunct_thread(void)
} }
#endif /* RT_USING_MODULE */ #endif /* RT_USING_MODULE */
/* enqueue a thread to defunct queue /**
* it must be called between rt_hw_interrupt_disable and rt_hw_interrupt_enable * @brief Enqueue a thread to defunct queue.
*
* @note It must be called between rt_hw_interrupt_disable and rt_hw_interrupt_enable
*/ */
void rt_thread_defunct_enqueue(rt_thread_t thread) void rt_thread_defunct_enqueue(rt_thread_t thread)
{ {
@ -164,8 +165,10 @@ void rt_thread_defunct_enqueue(rt_thread_t thread)
#endif #endif
} }
/* dequeue a thread from defunct queue /**
* it must be called between rt_hw_interrupt_disable and rt_hw_interrupt_enable * @brief Dequeue a thread from defunct queue.
*
* @note It must be called between rt_hw_interrupt_disable and rt_hw_interrupt_enable.
*/ */
rt_thread_t rt_thread_defunct_dequeue(void) rt_thread_t rt_thread_defunct_dequeue(void)
{ {
@ -183,9 +186,7 @@ rt_thread_t rt_thread_defunct_dequeue(void)
} }
/** /**
* @ingroup Thread * @brief This function will perform system background job when system idle.
*
* This function will perform system background job when system idle.
*/ */
static void rt_defunct_execute(void) static void rt_defunct_execute(void)
{ {
@ -316,9 +317,7 @@ static void rt_thread_system_entry(void *parameter)
#endif #endif
/** /**
* @ingroup SystemInit * @brief This function will initialize idle thread, then start it.
*
* This function will initialize idle thread, then start it.
* *
* @note this function must be invoked when system init. * @note this function must be invoked when system init.
*/ */
@ -365,10 +364,7 @@ void rt_thread_idle_init(void)
} }
/** /**
* @ingroup Thread * @brief This function will get the handler of the idle thread.
*
* This function will get the handler of the idle thread.
*
*/ */
rt_thread_t rt_thread_idle_gethandler(void) rt_thread_t rt_thread_idle_gethandler(void)
{ {

55
src/mem.c
View File

@ -66,10 +66,10 @@ static void (*rt_free_hook)(void *ptr);
/**@{*/ /**@{*/
/** /**
* 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 heap memory. * block is allocated from heap memory.
* *
* @param hook the hook function * @param hook the hook function.
*/ */
void rt_malloc_sethook(void (*hook)(void *ptr, rt_size_t size)) void rt_malloc_sethook(void (*hook)(void *ptr, rt_size_t size))
{ {
@ -77,8 +77,8 @@ void rt_malloc_sethook(void (*hook)(void *ptr, rt_size_t size))
} }
/** /**
* 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 heap memory. * block is released to heap memory.
* *
* @param hook the hook function * @param hook the hook function
*/ */
@ -194,11 +194,10 @@ static void plug_holes(struct heap_mem *mem)
} }
/** /**
* @ingroup SystemInit * @brief This function will initialize system heap memory.
*
* This function will initialize system heap memory.
* *
* @param begin_addr the beginning address of system heap memory. * @param begin_addr the beginning address of system heap memory.
*
* @param end_addr the end address of system heap memory. * @param end_addr the end address of system heap memory.
*/ */
void rt_system_heap_init(void *begin_addr, void *end_addr) void rt_system_heap_init(void *begin_addr, void *end_addr)
@ -263,7 +262,7 @@ void rt_system_heap_init(void *begin_addr, void *end_addr)
/**@{*/ /**@{*/
/** /**
* Allocate a block of memory with a minimum of 'size' bytes. * @brief Allocate a block of memory with a minimum of 'size' bytes.
* *
* @param size is the minimum size of the requested block in bytes. * @param size is the minimum size of the requested block in bytes.
* *
@ -411,12 +410,13 @@ void *rt_malloc(rt_size_t size)
RTM_EXPORT(rt_malloc); RTM_EXPORT(rt_malloc);
/** /**
* This function will change the previously allocated memory block. * @brief This function will change the previously allocated memory block.
* *
* @param rmem pointer to memory allocated by rt_malloc * @param rmem pointer to memory allocated by rt_malloc.
* @param newsize the required new size
* *
* @return the changed memory block address * @param newsize the required new size.
*
* @return the changed memory block address.
*/ */
void *rt_realloc(void *rmem, rt_size_t newsize) void *rt_realloc(void *rmem, rt_size_t newsize)
{ {
@ -517,16 +517,17 @@ void *rt_realloc(void *rmem, rt_size_t newsize)
RTM_EXPORT(rt_realloc); RTM_EXPORT(rt_realloc);
/** /**
* This function will contiguously allocate enough space for count objects * @brief This function will contiguously allocate enough space for count objects
* that are size bytes of memory each and returns a pointer to the allocated * that are size bytes of memory each and returns a pointer to the allocated
* memory. * memory.
* *
* 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 number of objects to allocate.
* @param size size of the objects to allocate
* *
* @return pointer to allocated memory / NULL pointer if there is an error * @param size size of the objects to allocate.
*
* @return pointer to allocated memory / NULL pointer if there is an error.
*/ */
void *rt_calloc(rt_size_t count, rt_size_t size) void *rt_calloc(rt_size_t count, rt_size_t size)
{ {
@ -544,8 +545,8 @@ void *rt_calloc(rt_size_t count, rt_size_t size)
RTM_EXPORT(rt_calloc); RTM_EXPORT(rt_calloc);
/** /**
* 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
*/ */
@ -616,6 +617,16 @@ void rt_free(void *rmem)
RTM_EXPORT(rt_free); RTM_EXPORT(rt_free);
#ifdef RT_MEM_STATS #ifdef RT_MEM_STATS
/**
* @brief This function will caculate the total memory, the used memory, and
* the max used memory.
*
* @param total is a pointer to get the total size of the memory.
*
* @param used is a pointer to get the size of memory used.
*
* @param max_used is a pointer to get the maximum memory used.
*/
void rt_memory_info(rt_uint32_t *total, void rt_memory_info(rt_uint32_t *total,
rt_uint32_t *used, rt_uint32_t *used,
rt_uint32_t *max_used) rt_uint32_t *max_used)

41
src/mempool.c
View File

@ -32,8 +32,8 @@ static void (*rt_mp_free_hook)(struct rt_mempool *mp, void *block);
/**@{*/ /**@{*/
/** /**
* 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 memory pool.
* *
* @param hook the hook function * @param hook the hook function
*/ */
@ -43,8 +43,8 @@ void rt_mp_alloc_sethook(void (*hook)(struct rt_mempool *mp, void *block))
} }
/** /**
* 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 memory pool.
* *
* @param hook the hook function * @param hook the hook function
*/ */
@ -63,13 +63,17 @@ void rt_mp_free_sethook(void (*hook)(struct rt_mempool *mp, void *block))
/**@{*/ /**@{*/
/** /**
* 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 the memory pool object
*
* @param name the name of memory pool * @param name the name of memory pool
*
* @param start the star address of memory pool * @param start the star address of memory pool
*
* @param size the total size of memory pool * @param size the total size of memory pool
*
* @param block_size the size for each block * @param block_size the size for each block
* *
* @return RT_EOK * @return RT_EOK
@ -125,9 +129,9 @@ rt_err_t rt_mp_init(struct rt_mempool *mp,
RTM_EXPORT(rt_mp_init); RTM_EXPORT(rt_mp_init);
/** /**
* 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 the memory pool object.
* *
* @return RT_EOK * @return RT_EOK
*/ */
@ -172,11 +176,13 @@ RTM_EXPORT(rt_mp_detach);
#ifdef RT_USING_HEAP #ifdef RT_USING_HEAP
/** /**
* 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 the name of memory pool
*
* @param block_count the count of blocks in memory pool * @param block_count the count of blocks in memory pool
*
* @param block_size the size for each block * @param block_size the size for each block
* *
* @return the created mempool object * @return the created mempool object
@ -241,9 +247,9 @@ rt_mp_t rt_mp_create(const char *name,
RTM_EXPORT(rt_mp_create); RTM_EXPORT(rt_mp_create);
/** /**
* 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 the memory pool object.
* *
* @return RT_EOK * @return RT_EOK
*/ */
@ -293,12 +299,13 @@ RTM_EXPORT(rt_mp_delete);
#endif /* RT_USING_HEAP */ #endif /* RT_USING_HEAP */
/** /**
* 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 the memory pool object.
* @param time the waiting time
* *
* @return the allocated memory block or RT_NULL on allocated failed * @param time the waiting time.
*
* @return the allocated memory block or RT_NULL on allocated failed.
*/ */
void *rt_mp_alloc(rt_mp_t mp, rt_int32_t time) void *rt_mp_alloc(rt_mp_t mp, rt_int32_t time)
{ {
@ -392,7 +399,7 @@ void *rt_mp_alloc(rt_mp_t mp, rt_int32_t time)
RTM_EXPORT(rt_mp_alloc); RTM_EXPORT(rt_mp_alloc);
/** /**
* 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
*/ */

94
src/object.c
View File

@ -120,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 * @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 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))
{ {
@ -131,8 +131,8 @@ void rt_object_attach_sethook(void (*hook)(struct rt_object *object))
} }
/** /**
* 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 the hook function
*/ */
@ -142,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 * @brief This function will set a hook function, which will be invoked when object
* is taken from kernel object system. * is taken from kernel object system.
* *
* The object is taken means: * The object is taken means:
* semaphore - semaphore is taken by thread * semaphore - semaphore is taken by thread
* mutex - mutex is taken by thread * mutex - mutex is taken by thread
* event - event is received by thread * event - event is received by thread
* 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 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))
{ {
@ -160,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 * @brief This function will set a hook function, which will be invoked when object
* have been taken from kernel object system. * have been taken from kernel object system.
* *
* The object have been taken means: * The object have been taken means:
* semaphore - semaphore have been taken by thread * semaphore - semaphore have been taken by thread
* mutex - mutex have been taken by thread * mutex - mutex have been taken by thread
* event - event have been received by thread * event - event have been received by thread
* mailbox - mail have been received by thread * mailbox - mail have been received by thread
* message queue - message have been received by thread * message queue - message have been received by thread
* timer - timer is started * 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)) void rt_object_take_sethook(void (*hook)(struct rt_object *object))
{ {
@ -179,8 +179,8 @@ void rt_object_take_sethook(void (*hook)(struct rt_object *object))
} }
/** /**
* 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 the hook function
*/ */
@ -199,7 +199,7 @@ 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 the type of object, which can be
* RT_Object_Class_Thread/Semaphore/Mutex... etc * RT_Object_Class_Thread/Semaphore/Mutex... etc
@ -219,10 +219,11 @@ rt_object_get_information(enum rt_object_class_type type)
RTM_EXPORT(rt_object_get_information); 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 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
*/ */
int rt_object_get_length(enum rt_object_class_type type) int rt_object_get_length(enum rt_object_class_type type)
@ -248,12 +249,14 @@ int rt_object_get_length(enum rt_object_class_type type)
RTM_EXPORT(rt_object_get_length); RTM_EXPORT(rt_object_get_length);
/** /**
* 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 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 the pointers will be saved to
*
* @param maxlen the maximum number of pointers can be saved * @param maxlen the maximum number of pointers can be saved
* *
* @return the copied number of object pointers * @return the copied number of object pointers
@ -290,11 +293,13 @@ int rt_object_get_pointers(enum rt_object_class_type type, rt_object_t *pointers
RTM_EXPORT(rt_object_get_pointers); RTM_EXPORT(rt_object_get_pointers);
/** /**
* 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 the specified object to be initialized.
*
* @param type the object type. * @param type the object type.
*
* @param name the object name. In system, the object's name must be unique. * @param name 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,
@ -361,8 +366,8 @@ void rt_object_init(struct rt_object *object,
} }
/** /**
* This function will detach a static object from object system, * @brief This function will detach a static object from object system,
* and the memory of static object is not freed. * and the memory of static object is not freed.
* *
* @param object the specified object to be detached. * @param object the specified object to be detached.
*/ */
@ -390,9 +395,10 @@ void rt_object_detach(rt_object_t object)
#ifdef RT_USING_HEAP #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 type the type of object
*
* @param name the object name. In system, the object's name must be unique. * @param name the object name. In system, the object's name must be unique.
* *
* @return object * @return object
@ -459,7 +465,7 @@ 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 the specified object to be deleted.
*/ */
@ -491,9 +497,10 @@ void rt_object_delete(rt_object_t object)
#endif /* RT_USING_HEAP */ #endif /* RT_USING_HEAP */
/** /**
* This function will judge the object is system object or not. * @brief 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. * @note Normally, the system object is a static object and the type
* of object set to RT_Object_Class_Static.
* *
* @param object the specified object to be judged. * @param object the specified object to be judged.
* *
@ -511,8 +518,8 @@ rt_bool_t rt_object_is_systemobject(rt_object_t object)
} }
/** /**
* 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 the specified object to be get type.
* *
@ -527,10 +534,11 @@ rt_uint8_t rt_object_get_type(rt_object_t object)
} }
/** /**
* 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 the specified name of object.
*
* @param type the type of object * @param type 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

59
src/scheduler.c
View File

@ -58,19 +58,23 @@ static void (*rt_scheduler_switch_hook)(struct rt_thread *tid);
/**@{*/ /**@{*/
/** /**
* 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 the hook function.
*/ */
void void rt_scheduler_sethook(void (*hook)(struct rt_thread *from, struct rt_thread *to))
rt_scheduler_sethook(void (*hook)(struct rt_thread *from, struct rt_thread *to))
{ {
rt_scheduler_hook = hook; rt_scheduler_hook = hook;
} }
void /**
rt_scheduler_switch_sethook(void (*hook)(struct rt_thread *tid)) * @brief This function will set a hook function, which will be invoked when context
* switch happens.
*
* @param hook the hook function.
*/
void rt_scheduler_switch_sethook(void (*hook)(struct rt_thread *tid))
{ {
rt_scheduler_switch_hook = hook; rt_scheduler_switch_hook = hook;
} }
@ -181,8 +185,7 @@ static struct rt_thread* _scheduler_get_highest_priority_thread(rt_ubase_t *high
#endif /* RT_USING_SMP */ #endif /* RT_USING_SMP */
/** /**
* @ingroup SystemInit * @brief This function will initialize the system scheduler.
* This function will initialize the system scheduler
*/ */
void rt_system_scheduler_init(void) void rt_system_scheduler_init(void)
{ {
@ -271,12 +274,13 @@ void rt_system_scheduler_start(void)
#ifdef RT_USING_SMP #ifdef RT_USING_SMP
/** /**
* 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 the number of IPI interrupt for system scheduling.
* @param param, use RT_NULL
* *
* NOTE: this function should be invoke or register as ISR in BSP. * @param param use RT_NULL.
*
* @note this function should be invoke or register as ISR in BSP.
*/ */
void rt_scheduler_ipi_handler(int vector, void *param) void rt_scheduler_ipi_handler(int vector, void *param)
{ {
@ -284,9 +288,9 @@ void rt_scheduler_ipi_handler(int vector, void *param)
} }
/** /**
* This function will perform one scheduling. It will select one thread * @brief This function will perform one scheduling. It will select one thread
* with the highest priority level in global ready queue or local ready queue, * with the highest priority level in global ready queue or local ready queue,
* then switch to it. * then switch to it.
*/ */
void rt_schedule(void) void rt_schedule(void)
{ {
@ -407,8 +411,8 @@ __exit:
} }
#else #else
/** /**
* This function will perform one schedule. It will select one thread * @brief This function will perform one schedule. It will select one thread
* with the highest priority level, and switch to it immediately. * with the highest priority level, and switch to it immediately.
*/ */
void rt_schedule(void) void rt_schedule(void)
{ {
@ -536,9 +540,9 @@ __exit:
#endif /* RT_USING_SMP */ #endif /* RT_USING_SMP */
/** /**
* This function checks if a scheduling is needed after IRQ context. If yes, * @brief This function checks if a scheduling is needed after IRQ context. 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.
*/ */
#ifdef RT_USING_SMP #ifdef RT_USING_SMP
void rt_scheduler_do_irq_switch(void *context) void rt_scheduler_do_irq_switch(void *context)
@ -631,11 +635,12 @@ void rt_scheduler_do_irq_switch(void *context)
} }
#endif /* RT_USING_SMP */ #endif /* RT_USING_SMP */
/* /**
* This function will insert a thread to system ready queue. The state of * @brief This function will insert a thread to system ready queue. The state of
* thread will be set as READY and remove from suspend queue. * thread will be set as READY and remove from suspend queue.
* *
* @param thread the thread to be inserted * @param thread 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.
*/ */
#ifdef RT_USING_SMP #ifdef RT_USING_SMP
@ -835,7 +840,7 @@ void rt_schedule_remove_thread(struct rt_thread *thread)
#endif /* RT_USING_SMP */ #endif /* RT_USING_SMP */
/** /**
* This function will lock the thread scheduler. * @brief This function will lock the thread scheduler.
*/ */
#ifdef RT_USING_SMP #ifdef RT_USING_SMP
void rt_enter_critical(void) void rt_enter_critical(void)
@ -897,7 +902,7 @@ void rt_enter_critical(void)
RTM_EXPORT(rt_enter_critical); RTM_EXPORT(rt_enter_critical);
/** /**
* This function will unlock the thread scheduler. * @brief This function will unlock the thread scheduler.
*/ */
#ifdef RT_USING_SMP #ifdef RT_USING_SMP
void rt_exit_critical(void) void rt_exit_critical(void)
@ -971,7 +976,7 @@ void rt_exit_critical(void)
RTM_EXPORT(rt_exit_critical); RTM_EXPORT(rt_exit_critical);
/** /**
* Get the scheduler lock level * @brief Get the scheduler lock level.
* *
* @return the level of the scheduler lock. 0 means unlocked. * @return the level of the scheduler lock. 0 means unlocked.
*/ */

82
src/slab.c
View File

@ -74,10 +74,10 @@ static void (*rt_free_hook)(void *ptr);
/**@{*/ /**@{*/
/** /**
* 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 heap memory. * block is allocated from heap memory.
* *
* @param hook the hook function * @param hook the hook function.
*/ */
void rt_malloc_sethook(void (*hook)(void *ptr, rt_size_t size)) void rt_malloc_sethook(void (*hook)(void *ptr, rt_size_t size))
{ {
@ -86,8 +86,8 @@ void rt_malloc_sethook(void (*hook)(void *ptr, rt_size_t size))
RTM_EXPORT(rt_malloc_sethook); RTM_EXPORT(rt_malloc_sethook);
/** /**
* 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 heap memory. * block is released to heap memory.
* *
* @param hook the hook function * @param hook the hook function
*/ */
@ -233,6 +233,11 @@ struct rt_page_head
static struct rt_page_head *rt_page_list; static struct rt_page_head *rt_page_list;
static struct rt_semaphore heap_sem; static struct rt_semaphore heap_sem;
/**
* @brief Alloc memory size by page.
*
* @param npages the number of pages.
*/
void *rt_page_alloc(rt_size_t npages) void *rt_page_alloc(rt_size_t npages)
{ {
struct rt_page_head *b, *n; struct rt_page_head *b, *n;
@ -269,6 +274,13 @@ void *rt_page_alloc(rt_size_t npages)
return b; return b;
} }
/**
* @brief Free memory by page.
*
* @param addr the head address of first page.
*
* @param npages the number of pages.
*/
void rt_page_free(void *addr, rt_size_t npages) void rt_page_free(void *addr, rt_size_t npages)
{ {
struct rt_page_head *b, *n; struct rt_page_head *b, *n;
@ -334,12 +346,11 @@ static void rt_page_init(void *addr, rt_size_t npages)
} }
/** /**
* @ingroup SystemInit * @brief This function will init system heap.
* *
* This function will init system heap * @param begin_addr the beginning address of system page.
* *
* @param begin_addr the beginning address of system page * @param end_addr the end address of system page.
* @param end_addr the end address of system page
*/ */
void rt_system_heap_init(void *begin_addr, void *end_addr) void rt_system_heap_init(void *begin_addr, void *end_addr)
{ {
@ -465,15 +476,15 @@ rt_inline int zoneindex(rt_size_t *bytes)
/**@{*/ /**@{*/
/** /**
* This function will allocate a block from system heap memory. * @brief This function will allocate a block from system heap memory.
* - If the nbytes is less than zero,
* or
* - If there is no nbytes sized memory valid in system,
* the RT_NULL is returned.
* *
* @param size the size of memory to be allocated * @note the RT_NULL is returned if
* - the nbytes is less than zero.
* - there is no nbytes sized memory valid in system.
* *
* @return the allocated memory * @param size the size of memory to be allocated.
*
* @return the allocated memory.
*/ */
void *rt_malloc(rt_size_t size) void *rt_malloc(rt_size_t size)
{ {
@ -668,12 +679,13 @@ __exit:
RTM_EXPORT(rt_malloc); RTM_EXPORT(rt_malloc);
/** /**
* 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 the previously allocated memory block.
* @param size the new size of memory block
* *
* @return the allocated memory * @param size the new size of memory block.
*
* @return the allocated memory.
*/ */
void *rt_realloc(void *ptr, rt_size_t size) void *rt_realloc(void *ptr, rt_size_t size)
{ {
@ -736,16 +748,17 @@ void *rt_realloc(void *ptr, rt_size_t size)
RTM_EXPORT(rt_realloc); RTM_EXPORT(rt_realloc);
/** /**
* This function will contiguously allocate enough space for count objects * @brief This function will contiguously allocate enough space for count objects
* that are size bytes of memory each and returns a pointer to the allocated * that are size bytes of memory each and returns a pointer to the allocated
* memory. * memory.
* *
* 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 number of objects to allocate.
* @param size size of the objects to allocate
* *
* @return pointer to allocated memory / NULL pointer if there is an error * @param size size of the objects to allocate.
*
* @return pointer to allocated memory / NULL pointer if there is an error.
*/ */
void *rt_calloc(rt_size_t count, rt_size_t size) void *rt_calloc(rt_size_t count, rt_size_t size)
{ {
@ -763,8 +776,9 @@ void *rt_calloc(rt_size_t count, rt_size_t size)
RTM_EXPORT(rt_calloc); RTM_EXPORT(rt_calloc);
/** /**
* This function will release the previous allocated memory block by rt_malloc. * @brief This function will release the previous allocated memory block by rt_malloc.
* 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 the address of memory which will be released
*/ */
@ -905,6 +919,16 @@ void rt_free(void *ptr)
RTM_EXPORT(rt_free); RTM_EXPORT(rt_free);
#ifdef RT_MEM_STATS #ifdef RT_MEM_STATS
/**
* @brief This function will caculate the total memory, the used memory, and
* the max used memory.
*
* @param total is a pointer to get the total size of the memory.
*
* @param used is a pointer to get the size of memory used.
*
* @param max_used is a pointer to get the maximum memory used.
*/
void rt_memory_info(rt_uint32_t *total, void rt_memory_info(rt_uint32_t *total,
rt_uint32_t *used, rt_uint32_t *used,
rt_uint32_t *max_used) rt_uint32_t *max_used)