diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/clock.c | 32 | ||||
| -rw-r--r-- | src/components.c | 20 | ||||
| -rw-r--r-- | src/cpu.c | 52 | ||||
| -rw-r--r-- | src/device.c | 106 | ||||
| -rw-r--r-- | src/idle.c | 44 | ||||
| -rw-r--r-- | src/kservice.c | 226 | ||||
| -rw-r--r-- | src/mem.c | 59 | ||||
| -rw-r--r-- | src/memheap.c | 141 | ||||
| -rw-r--r-- | src/mempool.c | 60 | ||||
| -rw-r--r-- | src/object.c | 130 | ||||
| -rw-r--r-- | src/scheduler.c | 76 | ||||
| -rw-r--r-- | src/signal.c | 60 | ||||
| -rw-r--r-- | src/slab.c | 84 | ||||
| -rw-r--r-- | src/thread.c | 203 |
14 files changed, 850 insertions, 443 deletions
diff --git a/src/clock.c b/src/clock.c index 77516b3775..fb7ee447d2 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. + * @brief This function will return the passed millisecond from boot. + * + * @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. * - * @return passed millisecond from boot + * @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 e156b783e4..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"); /** - * 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) { @@ -102,7 +104,7 @@ void rt_components_board_init(void) } /** - * RT-Thread Components Initialization + * @brief RT-Thread Components Initialization. */ void rt_components_init(void) { @@ -169,7 +171,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 +199,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 +226,10 @@ void rt_application_init(void) rt_thread_startup(tid); } +/** + * @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) { rt_hw_interrupt_disable(); @@ -65,12 +65,25 @@ 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. + */ 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 +91,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 +103,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 +126,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 +143,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 +192,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) { diff --git a/src/device.c b/src/device.c index a9c244d306..6e22c2b692 100644 --- a/src/device.c +++ b/src/device.c @@ -39,11 +39,13 @@ #endif /* RT_USING_DEVICE_OPS */ /** - * 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 name the device driver's name - * @param flags the capabilities flag of device + * @param dev is the pointer of device driver structure. + * + * @param name is the device driver's name. + * + * @param flags is the capabilities flag of device. * * @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); /** - * 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. */ @@ -91,9 +93,9 @@ rt_err_t rt_device_unregister(rt_device_t dev) 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 is the device driver's name. * * @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 /** - * 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 attach_size, the size of user data. + * @param type is the type of the device object. + * + * @param attach_size is the size of user data. * * @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); /** - * 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) { @@ -153,11 +156,11 @@ RTM_EXPORT(rt_device_destroy); #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 is 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) { @@ -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 is the pointer of device driver structure. * - * @param dev the pointer of device driver structure - * @param oflag the flags for device open + * @param oflag is the flags for device open. * - * @return the result + * @return the result, RT_EOK on successfully. */ 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); /** - * 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 + * @return the result, RT_EOK on successfully. */ 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); /** - * This function will read some data from a device. + * @brief This function will read some data from a device. + * + * @param dev is the pointer of device driver structure. + * + * @param pos is the position when reading. + * + * @param buffer is a data buffer to save the read data. * - * @param dev the pointer of device driver structure - * @param pos the position of reading - * @param buffer the data buffer to save 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. * @@ -328,12 +335,15 @@ rt_size_t rt_device_read(rt_device_t dev, 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 pos the position of written - * @param buffer the data buffer to be written to device - * @param size the size of buffer + * @param dev is the pointer of device driver structure. + * + * @param pos is the position when writing. + * + * @param buffer is the data buffer to be written to device. + * + * @param size is the size of buffer. * * @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); /** - * 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 is 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 + * @param cmd is the command sent to device. * - * @return the result + * @param arg is 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) { @@ -391,11 +403,12 @@ rt_err_t rt_device_control(rt_device_t dev, int cmd, void *arg) RTM_EXPORT(rt_device_control); /** - * This function will set the reception indication callback function. This callback function - * is invoked when this device receives data. + * @brief This function will set the reception indication callback function. This callback function + * is invoked when this device receives data. + * + * @param dev is the pointer of device driver structure. * - * @param dev the pointer of device driver structure - * @param rx_ind the indication callback function + * @param rx_ind is the indication callback function. * * @return RT_EOK */ @@ -413,11 +426,12 @@ rt_device_set_rx_indicate(rt_device_t dev, RTM_EXPORT(rt_device_set_rx_indicate); /** - * This function will set the indication callback function when device has - * written data to physical hardware. + * @brief This function will set a callback function. The callback function + * will be called when device has written data to physical hardware. + * + * @param dev is the pointer of device driver structure. * - * @param dev the pointer of device driver structure - * @param tx_done the indication callback function + * @param tx_done is the indication callback function. * * @return RT_EOK */ diff --git a/src/idle.c b/src/idle.c index ec625cb4a1..61f6a5b383 100644 --- a/src/idle.c +++ b/src/idle.c @@ -68,14 +68,13 @@ static struct rt_semaphore system_sem; static void (*idle_hook_list[RT_IDLE_HOOK_LIST_SIZE])(void); /** - * @ingroup Hook - * This function sets a hook function to idle thread loop. When the system performs - * idle loop, this hook function should be invoked. + * @brief This function sets a hook function to idle thread loop. When the system performs + * 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 - * -RT_EFULL: hook list is full + * @return RT_EOK: set OK. + * -RT_EFULL: hook list is full. * * @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 - * -RT_ENOSYS: hook was not found + * @return RT_EOK: delete OK. + * -RT_ENOSYS: hook was not found. */ 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 */ -/* 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) { @@ -164,8 +165,10 @@ void rt_thread_defunct_enqueue(rt_thread_t thread) #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) { @@ -183,9 +186,7 @@ rt_thread_t rt_thread_defunct_dequeue(void) } /** - * @ingroup Thread - * - * This function will perform system background job when system idle. + * @brief This function will perform system background job when system idle. */ static void rt_defunct_execute(void) { @@ -316,9 +317,7 @@ static void rt_thread_system_entry(void *parameter) #endif /** - * @ingroup SystemInit - * - * This function will initialize idle thread, then start it. + * @brief This function will initialize idle thread, then start it. * * @note this function must be invoked when system init. */ @@ -365,10 +364,7 @@ void rt_thread_idle_init(void) } /** - * @ingroup Thread - * - * This function will get the handler of the idle thread. - * + * @brief This function will get the handler of the idle thread. */ rt_thread_t rt_thread_idle_gethandler(void) { diff --git a/src/kservice.c b/src/kservice.c index 91872492fb..25d34dfc47 100644 --- a/src/kservice.c +++ b/src/kservice.c @@ -43,8 +43,8 @@ static volatile int __rt_errno; static rt_device_t _console_device = RT_NULL; #endif -/* - * This function will get errno +/** + * This function gets the global errno for the current thread. * * @return errno */ @@ -66,10 +66,10 @@ rt_err_t rt_get_errno(void) } RTM_EXPORT(rt_get_errno); -/* - * This function will set errno +/** + * This function sets the global errno for the current thread. * - * @param error the errno shall be set + * @param error is the errno shall be set. */ void rt_set_errno(rt_err_t error) { @@ -96,9 +96,9 @@ void rt_set_errno(rt_err_t error) RTM_EXPORT(rt_set_errno); /** - * This function returns errno. + * This function returns the address of the current thread errno. * - * @return the errno in the system + * @return The errno address. */ int *_rt_errno(void) { @@ -116,13 +116,16 @@ int *_rt_errno(void) RTM_EXPORT(_rt_errno); /** - * This function will set the content of memory to specified value + * This function will set the content of memory to specified value. + * + * @param s is the address of source memory, point to the memory block to be filled. + * + * @param c is the value to be set. The value is passed in int form, but the function + * uses the unsigned character form of the value when filling the memory block. * - * @param s the address of source memory - * @param c the value shall be set in content - * @param count the copied length + * @param count number of bytes to be set. * - * @return the address of source memory + * @return The address of source memory. */ RT_WEAK void *rt_memset(void *s, int c, rt_ubase_t count) { @@ -200,14 +203,15 @@ RTM_EXPORT(rt_memset); #ifndef RT_USING_ASM_MEMCPY /** - * This function will copy memory content from source address to destination - * address. + * This function will copy memory content from source address to destination address. * - * @param dst the address of destination memory - * @param src the address of source memory - * @param count the copied length + * @param dst is the address of destination memory, points to the copied content. * - * @return the address of destination memory + * @param src is the address of source memory, pointing to the data source to be copied. + * + * @param count is the copied length. + * + * @return The address of destination memory */ void *rt_memcpy(void *dst, const void *src, rt_ubase_t count) { @@ -287,13 +291,16 @@ RTM_EXPORT(rt_memcpy); /** * This function will move memory content from source address to destination - * address. + * address. If the destination memory does not overlap with the source memory, + * the function is the same as memcpy(). + * + * @param dst is the address of destination memory, points to the copied content. * - * @param dest the address of destination memory - * @param src the address of source memory - * @param n the copied length + * @param src is the address of source memory, point to the data source to be copied. * - * @return the address of destination memory + * @param count is the copied length. + * + * @return The address of destination memory. */ void *rt_memmove(void *dest, const void *src, rt_ubase_t n) { @@ -318,13 +325,18 @@ void *rt_memmove(void *dest, const void *src, rt_ubase_t n) RTM_EXPORT(rt_memmove); /** - * This function will compare two areas of memory + * This function will compare two areas of memory. + * + * @param cs is a block of memory. + * + * @param ct is another block of memory. * - * @param cs one area of memory - * @param ct another area of memory - * @param count the size of the area + * @param count is the size of the area. * - * @return the result + * @return Compare the results: + * If the result < 0, cs is smaller than ct. + * If the result > 0, cs is greater than ct. + * If the result = 0, cs is equal to ct. */ RT_WEAK rt_int32_t rt_memcmp(const void *cs, const void *ct, rt_ubase_t count) { @@ -340,12 +352,14 @@ RT_WEAK rt_int32_t rt_memcmp(const void *cs, const void *ct, rt_ubase_t count) RTM_EXPORT(rt_memcmp); /** - * This function will return the first occurrence of a string. + * This function will return the first occurrence of a string, without the + * terminator '\0'. * - * @param s1 the source string - * @param s2 the find string + * @param s1 is the source string. * - * @return the first occurrence of a s2 in s1, or RT_NULL if no found. + * @param s2 is the find string. + * + * @return The first occurrence of a s2 in s1, or RT_NULL if no found. */ char *rt_strstr(const char *s1, const char *s2) { @@ -370,10 +384,14 @@ RTM_EXPORT(rt_strstr); /** * This function will compare two strings while ignoring differences in case * - * @param a the string to be compared - * @param b the string to be compared + * @param a is the string to be compared. + * + * @param b is the string to be compared. * - * @return the result + * @return Compare the results: + * If the result < 0, a is smaller than a. + * If the result > 0, a is greater than a. + * If the result = 0, a is equal to a. */ rt_int32_t rt_strcasecmp(const char *a, const char *b) { @@ -397,11 +415,13 @@ RTM_EXPORT(rt_strcasecmp); /** * This function will copy string no more than n bytes. * - * @param dst the string to copy - * @param src the string to be copied - * @param n the maximum copied length + * @param dst points to the address used to store the copied content. + * + * @param src is the string to be copied. * - * @return the result + * @param n is the maximum copied length. + * + * @return The address where the copied content is stored. */ char *rt_strncpy(char *dst, const char *src, rt_ubase_t n) { @@ -427,13 +447,18 @@ char *rt_strncpy(char *dst, const char *src, rt_ubase_t n) RTM_EXPORT(rt_strncpy); /** - * This function will compare two strings with specified maximum length + * This function will compare two strings with specified maximum length. + * + * @param cs is the string to be compared. + * + * @param ct is the string to be compared. * - * @param cs the string to be compared - * @param ct the string to be compared - * @param count the maximum compare length + * @param count is the maximum compare length. * - * @return the result + * @return Compare the results: + * If the result < 0, cs is smaller than ct. + * If the result > 0, cs is greater than ct. + * If the result = 0, cs is equal to ct. */ rt_int32_t rt_strncmp(const char *cs, const char *ct, rt_ubase_t count) { @@ -451,12 +476,16 @@ rt_int32_t rt_strncmp(const char *cs, const char *ct, rt_ubase_t count) RTM_EXPORT(rt_strncmp); /** - * This function will compare two strings without specified length + * This function will compare two strings without specified length. * - * @param cs the string to be compared - * @param ct the string to be compared + * @param cs is the string to be compared. * - * @return the result + * @param ct is the string to be compared. + * + * @return Compare the results: + * If the result < 0, cs is smaller than ct. + * If the result > 0, cs is greater than ct. + * If the result = 0, cs is equal to ct. */ rt_int32_t rt_strcmp(const char *cs, const char *ct) { @@ -477,9 +506,11 @@ RTM_EXPORT(rt_strcmp); * first maxlen characters in the string pointed to by s and never * beyond s+maxlen. * - * @param s the string - * @param maxlen the max size - * @return the length of string + * @param s is the string. + * + * @param maxlen is the max size. + * + * @return The length of string. */ rt_size_t rt_strnlen(const char *s, rt_ubase_t maxlen) { @@ -496,9 +527,9 @@ RTM_EXPORT(rt_strnlen); * This function will return the length of a string, which terminate will * null character. * - * @param s the string + * @param s is the string * - * @return the length of string + * @return The length of string. */ rt_size_t rt_strlen(const char *s) { @@ -517,9 +548,9 @@ RTM_EXPORT(rt_strlen); /** * This function will duplicate a string. * - * @param s the string to be duplicated + * @param s is the string to be duplicated. * - * @return the duplicated string pointer + * @return The string address of the copy. */ char *rt_strdup(const char *s) { @@ -556,6 +587,13 @@ RTM_EXPORT(rt_show_version); #define _ISDIGIT(c) ((unsigned)((c) - '0') < 10) #ifdef RT_PRINTF_LONGLONG +/** + * This function will duplicate a string. + * + * @param s the string to be duplicated + * + * @return the duplicated string pointer + */ rt_inline int divide(long long *n, int base) { int res; @@ -784,6 +822,19 @@ static char *print_number(char *buf, return buf; } +/** + * This function will fill a formatted string to buffer. + * + * @param buf is the buffer to save formatted string. + * + * @param size is the size of buffer. + * + * @param fmt is the format parameters. + * + * @param args is a list of variable parameters. + * + * @return The number of characters actually written to buffer. + */ rt_int32_t rt_vsnprintf(char *buf, rt_size_t size, const char *fmt, @@ -1051,11 +1102,15 @@ rt_int32_t rt_vsnprintf(char *buf, RTM_EXPORT(rt_vsnprintf); /** - * This function will fill a formatted string to buffer + * This function will fill a formatted string to buffer. * - * @param buf the buffer to save formatted string - * @param size the size of buffer - * @param fmt the format + * @param buf is the buffer to save formatted string. + * + * @param size is the size of buffer. + * + * @param fmt is the format parameters. + * + * @return The number of characters actually written to buffer. */ rt_int32_t rt_snprintf(char *buf, rt_size_t size, const char *fmt, ...) { @@ -1071,11 +1126,15 @@ rt_int32_t rt_snprintf(char *buf, rt_size_t size, const char *fmt, ...) RTM_EXPORT(rt_snprintf); /** - * This function will fill a formatted string to buffer + * This function will fill a formatted string to buffer. + * + * @param buf is the buffer to save formatted string. + * + * @param format is the format parameters. * - * @param buf the buffer to save formatted string - * @param arg_ptr the arg_ptr - * @param format the format + * @param arg_ptr is a list of variable parameters. + * + * @return The number of characters actually written to buffer. */ rt_int32_t rt_vsprintf(char *buf, const char *format, va_list arg_ptr) { @@ -1086,8 +1145,11 @@ RTM_EXPORT(rt_vsprintf); /** * This function will fill a formatted string to buffer * - * @param buf the buffer to save formatted string - * @param format the format + * @param buf the buffer to save formatted string. + * + * @param format is the format parameters. + * + * @return The number of characters actually written to buffer. */ rt_int32_t rt_sprintf(char *buf, const char *format, ...) { @@ -1108,7 +1170,7 @@ RTM_EXPORT(rt_sprintf); /** * This function returns the device using in console. * - * @return the device using in console or RT_NULL + * @return Returns the console device pointer or RT_NULL. */ rt_device_t rt_console_get_device(void) { @@ -1121,7 +1183,7 @@ RTM_EXPORT(rt_console_get_device); * After set a device to console, all output of rt_kprintf will be * redirected to this new device. * - * @param name the name of new console device + * @param name is the name of new console device. * * @return the old console device handler on successful, or RT_NULL on failure. */ @@ -1165,7 +1227,7 @@ RTM_EXPORT(rt_hw_console_output); /** * This function will put string to the console. * - * @param str the string output to the console. + * @param str is the string output to the console. */ void rt_kputs(const char *str) { @@ -1186,9 +1248,9 @@ void rt_kputs(const char *str) } /** - * This function will print a formatted string on system console + * This function will print a formatted string on system console. * - * @param fmt the format + * @param fmt is the format parameters. */ RT_WEAK void rt_kprintf(const char *fmt, ...) { @@ -1227,10 +1289,12 @@ RTM_EXPORT(rt_kprintf); * This function allocates a memory block, which address is aligned to the * specified alignment size. * - * @param size the allocated memory block size - * @param align the alignment size + * @param size is the allocated memory block size. * - * @return the allocated memory block on successful, otherwise returns RT_NULL + * @param align is the alignment size. + * + * @return The memory block address was returned successfully, otherwise it was + * returned empty RT_NULL. */ RT_WEAK void *rt_malloc_align(rt_size_t size, rt_size_t align) { @@ -1276,7 +1340,7 @@ RTM_EXPORT(rt_malloc_align); * This function release the memory block, which is allocated by * rt_malloc_align function and address is aligned. * - * @param ptr the memory block pointer + * @param ptr is the memory block pointer. */ RT_WEAK void rt_free_align(void *ptr) { @@ -1316,8 +1380,8 @@ const rt_uint8_t __lowest_bit_bitmap[] = * Bits are numbered starting at 1 (the least significant bit). A return value of * zero from any of these functions means that the argument was zero. * - * @return return the index of the first bit set. If value is 0, then this function - * shall return 0. + * @return Return the index of the first bit set. If value is 0, then this function + * shall return 0. */ int __rt_ffs(int value) { @@ -1344,7 +1408,7 @@ void (*rt_assert_hook)(const char *ex, const char *func, rt_size_t line); /** * This function will set a hook function to RT_ASSERT(EX). It will run when the expression is false. * - * @param hook the hook function + * @param hook is the hook function. */ void rt_assert_set_hook(void (*hook)(const char *ex, const char *func, rt_size_t line)) { @@ -1354,9 +1418,11 @@ void rt_assert_set_hook(void (*hook)(const char *ex, const char *func, rt_size_t /** * The RT_ASSERT function. * - * @param ex the assertion condition string - * @param func the function name when assertion. - * @param line the file line number when assertion. + * @param ex is the assertion condition string. + * + * @param func is the function name when assertion. + * + * @param line is the file line number when assertion. */ void rt_assert_handler(const char *ex_string, const char *func, rt_size_t line) { @@ -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 - * block is allocated from heap memory. + * @brief This function will set a hook function, which will be invoked when a 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)) { @@ -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 - * block is released to heap memory. + * @brief This function will set a hook function, which will be invoked when a memory + * block is released to heap memory. * * @param hook the hook function */ @@ -194,11 +194,10 @@ static void plug_holes(struct heap_mem *mem) } /** - * @ingroup SystemInit - * - * This function will initialize system heap memory. + * @brief This function will initialize system heap memory. * * @param begin_addr the beginning 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) @@ -263,11 +262,11 @@ 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. * - * @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) { @@ -411,12 +410,13 @@ void *rt_malloc(rt_size_t size) RTM_EXPORT(rt_malloc); /** - * 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 newsize the required new size + * @param rmem is the pointer to memory allocated by rt_malloc. * - * @return the changed memory block address + * @param newsize is the required new size. + * + * @return the changed memory block address. */ 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); /** - * This function will contiguously allocate enough space for count objects - * that are size bytes of memory each and returns a pointer to the allocated - * memory. + * @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 + * memory. + * + * @note The allocated memory is filled with bytes of value zero. * - * The allocated memory is filled with bytes of value zero. + * @param count is the number of objects to allocate. * - * @param count 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. */ void *rt_calloc(rt_size_t count, rt_size_t size) { @@ -544,10 +545,10 @@ void *rt_calloc(rt_size_t count, rt_size_t size) RTM_EXPORT(rt_calloc); /** - * This function will release the previously allocated memory block by - * rt_malloc. The released memory block is taken back to system heap. + * @brief This function will release the previously allocated memory block by + * 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) { @@ -616,6 +617,16 @@ void rt_free(void *rmem) RTM_EXPORT(rt_free); #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, rt_uint32_t *used, rt_uint32_t *max_used) diff --git a/src/memheap.c b/src/memheap.c index e09f5c4bce..8422b1d802 100644 --- a/src/memheap.c +++ b/src/memheap.c @@ -39,6 +39,13 @@ #define MEMITEM(ptr) (struct rt_memheap_item*)((rt_uint8_t*)ptr - RT_MEMHEAP_SIZE) #ifdef RT_USING_MEMTRACE +/** + * @brief This function will set a new name for memheap. + * + * @param item is a pointer point to a memheap object. + * + * @param name is the new name to be set. + */ rt_inline void rt_memheap_setname(struct rt_memheap_item *item, const char *name) { int index; @@ -64,6 +71,13 @@ rt_inline void rt_memheap_setname(struct rt_memheap_item *item, const char *name } } +/** + * @brief This function will set a new name for memheap. + * + * @param ptr is a pointer point to a memheap object. + * + * @param name is the new name to be set. + */ void rt_mem_set_tag(void *ptr, const char *name) { struct rt_memheap_item *item; @@ -76,16 +90,28 @@ void rt_mem_set_tag(void *ptr, const char *name) } #endif /* RT_USING_MEMTRACE */ -/* - * The initialized memory pool will be: - * +-----------------------------------+--------------------------+ - * | whole freed memory block | Used Memory Block Tailer | - * +-----------------------------------+--------------------------+ +/** + * @brief This function initializes a piece of memory called memheap. + * + * @note The initialized memory pool will be: + * +-----------------------------------+--------------------------+ + * | whole freed memory block | Used Memory Block Tailer | + * +-----------------------------------+--------------------------+ + * + * block_list --> whole freed memory block + * + * The length of Used Memory Block Tailer is 0, + * which is prevents block merging across list + * + * @param memheap is a pointer of the memheap object. + * + * @param name is the name of the memheap. + * + * @param start_addr is the start address of the memheap. * - * block_list --> whole freed memory block + * @param size is the size of the memheap. * - * The length of Used Memory Block Tailer is 0, - * which is prevents block merging across list + * @return RT_EOK */ rt_err_t rt_memheap_init(struct rt_memheap *memheap, const char *name, @@ -165,6 +191,13 @@ rt_err_t rt_memheap_init(struct rt_memheap *memheap, } RTM_EXPORT(rt_memheap_init); +/** + * @brief This function will remove a memheap from the system. + * + * @param heap is a pointer of memheap object. + * + * @return RT_EOK + */ rt_err_t rt_memheap_detach(struct rt_memheap *heap) { RT_ASSERT(heap); @@ -179,6 +212,15 @@ rt_err_t rt_memheap_detach(struct rt_memheap *heap) } RTM_EXPORT(rt_memheap_detach); +/** + * @brief Allocate a block of memory with a minimum of 'size' bytes on memheap. + * + * @param heap is a pointer for memheap object. + * + * @param size is the minimum size of the requested block in bytes. + * + * @return the pointer to allocated memory or NULL if no free memory was found. + */ void *rt_memheap_alloc(struct rt_memheap *heap, rt_size_t size) { rt_err_t result; @@ -336,6 +378,18 @@ void *rt_memheap_alloc(struct rt_memheap *heap, rt_size_t size) } RTM_EXPORT(rt_memheap_alloc); +/** + * @brief This function will change the size of previously allocated memory block. + * + * @param heap is a pointer to the memheap object, which will reallocate + * memory from the block + * + * @param ptr is a pointer to start address of memory. + * + * @param newsize is the required new size. + * + * @return the changed memory block address. + */ void *rt_memheap_realloc(struct rt_memheap *heap, void *ptr, rt_size_t newsize) { rt_err_t result; @@ -556,6 +610,12 @@ void *rt_memheap_realloc(struct rt_memheap *heap, void *ptr, rt_size_t newsize) } RTM_EXPORT(rt_memheap_realloc); +/** + * @brief This function will release the allocated memory block by + * rt_malloc. The released memory block is taken back to system heap. + * + * @param ptr the address of memory which will be released. + */ void rt_memheap_free(void *ptr) { rt_err_t result; @@ -680,7 +740,13 @@ static void _memheap_dump_tag(struct rt_memheap_item *item) rt_kprintf("%.*s", 2 * sizeof(void *), name); } - +/** + * @brief This function will print the memheap infomation. + * + * @param heap is the pointer to the memheap to get information. + * + * @return 0 + */ int rt_memheap_dump(struct rt_memheap *heap) { struct rt_memheap_item *item, *end; @@ -757,6 +823,13 @@ MSH_CMD_EXPORT(memheaptrace, dump memory trace information); #ifdef RT_USING_MEMHEAP_AS_HEAP static struct rt_memheap _heap; +/** + * @brief This function initializes a heap for system. + * + * @param begin_addr is the start address of the memory. + * + * @param end_addr is the end address of the memory. + */ void rt_system_heap_init(void *begin_addr, void *end_addr) { RT_ASSERT((rt_uint32_t)end_addr > (rt_uint32_t)begin_addr); @@ -768,6 +841,11 @@ void rt_system_heap_init(void *begin_addr, void *end_addr) (rt_uint32_t)end_addr - (rt_uint32_t)begin_addr); } +/** + * @brief Allocate a block of memory with a minimum of 'size' bytes. + * + * @param size is the minimum size of the requested block in bytes. + */ void *rt_malloc(rt_size_t size) { void *ptr; @@ -804,7 +882,6 @@ void *rt_malloc(rt_size_t size) } } - #ifdef RT_USING_MEMTRACE if (ptr == RT_NULL) { @@ -826,12 +903,27 @@ void *rt_malloc(rt_size_t size) } RTM_EXPORT(rt_malloc); +/** + * @brief This function will release the previously allocated memory block by + * rt_malloc. The released memory block is taken back to system heap. + * + * @param rmem the address of memory which will be released. + */ void rt_free(void *rmem) { rt_memheap_free(rmem); } RTM_EXPORT(rt_free); +/** + * @brief This function will change the size of previously allocated memory block. + * + * @param rmem is the pointer to memory allocated by rt_malloc. + * + * @param newsize is the required new size. + * + * @return the changed memory block address. + */ void *rt_realloc(void *rmem, rt_size_t newsize) { void *new_ptr; @@ -892,6 +984,19 @@ void *rt_realloc(void *rmem, rt_size_t newsize) } RTM_EXPORT(rt_realloc); +/** + * @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 + * memory. + * + * @note The allocated memory is filled with bytes of value zero. + * + * @param count is the number of objects to allocate. + * + * @param size is the size of one object to allocate. + * + * @return pointer to allocated memory pointer. + */ void *rt_calloc(rt_size_t count, rt_size_t size) { void *ptr; @@ -922,6 +1027,16 @@ void *rt_calloc(rt_size_t count, rt_size_t size) } RTM_EXPORT(rt_calloc); +/** +* @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, rt_uint32_t *used, rt_uint32_t *max_used) @@ -940,12 +1055,16 @@ void rt_memory_info(rt_uint32_t *total, #ifdef RT_USING_MEMTRACE +/** + * @brief This function will print the used memheap infomation. + * + * @param memheap is a pointer of the memheap object. + */ void dump_used_memheap(struct rt_memheap *mh) { struct rt_memheap_item *header_ptr; rt_uint32_t block_size; - rt_kprintf("\nmemory heap address:\n"); rt_kprintf("heap_ptr: 0x%08x\n", mh->start_addr); rt_kprintf("free : 0x%08x\n", mh->available_size); diff --git a/src/mempool.c b/src/mempool.c index 5ac87d2bc8..09a4955eee 100644 --- a/src/mempool.c +++ b/src/mempool.c @@ -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 - * block is allocated from memory pool. + * @brief This function will set a hook function, which will be invoked when a memory + * block is allocated from the memory pool. * * @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 - * block is released to memory pool. + * @brief This function will set a hook function, which will be invoked when a memory + * block is released to the memory pool. * * @param hook the hook function */ @@ -63,14 +63,18 @@ 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 - * for static object. + * @brief This function will initialize a memory pool object, normally which is used + * for static object. * - * @param mp the memory pool object - * @param name the name of memory pool - * @param start the star address of memory pool - * @param size the total size of memory pool - * @param block_size the size for each block + * @param mp is the memory pool object. + * + * @param name is the name of the memory pool. + * + * @param start is the start address of the memory pool. + * + * @param size is the total size of the memory pool. + * + * @param block_size is the size for each block.. * * @return RT_EOK */ @@ -125,9 +129,9 @@ rt_err_t rt_mp_init(struct rt_mempool *mp, 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 is the memory pool object. * * @return RT_EOK */ @@ -172,12 +176,14 @@ RTM_EXPORT(rt_mp_detach); #ifdef RT_USING_HEAP /** - * This function will create a mempool object and allocate the memory pool from - * heap. + * @brief This function will create a mempool object and allocate the memory pool from + * heap. * - * @param name the name of memory pool - * @param block_count the count of blocks in memory pool - * @param block_size the size for each block + * @param name is the name of memory pool. + * + * @param block_count is the count of blocks in memory pool. + * + * @param block_size is the size for each block. * * @return the created mempool object */ @@ -241,9 +247,9 @@ rt_mp_t rt_mp_create(const char *name, 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 is the memory pool object. * * @return RT_EOK */ @@ -293,12 +299,14 @@ RTM_EXPORT(rt_mp_delete); #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 is the memory pool object. * - * @param mp 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. */ void *rt_mp_alloc(rt_mp_t mp, rt_int32_t time) { @@ -392,9 +400,9 @@ void *rt_mp_alloc(rt_mp_t mp, rt_int32_t time) 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. */ void rt_mp_free(void *block) { diff --git a/src/object.c b/src/object.c index 718b0aa5b2..66d5775bd7 100644 --- a/src/object.c +++ b/src/object.c @@ -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 - * 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)) { @@ -131,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)) { @@ -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 - * 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)) { @@ -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 - * 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)) { @@ -179,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)) { @@ -199,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 @@ -219,10 +219,11 @@ rt_object_get_information(enum rt_object_class_type type) 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) @@ -248,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) { @@ -290,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 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 type is the object type. + * + * @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, @@ -361,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. */ @@ -390,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 is 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 is the object name. In system, the object's name must be unique. * * @return object */ @@ -459,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) { @@ -491,11 +497,12 @@ void rt_object_delete(rt_object_t object) #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. */ @@ -511,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. */ @@ -527,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. diff --git a/src/scheduler.c b/src/scheduler.c index bb431e2efe..6ef02f3d3c 100644 --- a/src/scheduler.c +++ b/src/scheduler.c @@ -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 - * switch happens. + * @brief This function will set a hook function, which will be invoked when thread + * 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)) { 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 is the hook function. + */ +void rt_scheduler_switch_sethook(void (*hook)(struct rt_thread *tid)) { 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 */ /** - * @ingroup SystemInit - * This function will initialize the system scheduler + * @brief This function will initialize the system scheduler. */ void rt_system_scheduler_init(void) { @@ -232,9 +235,8 @@ void rt_system_scheduler_init(void) } /** - * @ingroup SystemInit - * This function will startup scheduler. It will select one thread - * with the highest priority level, then switch to it. + * @brief This function will startup the scheduler. It will select one thread + * with the highest priority level, then switch to it. */ void rt_system_scheduler_start(void) { @@ -271,12 +273,13 @@ void rt_system_scheduler_start(void) #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 param, use RT_NULL + * @param vector is the number of IPI interrupt for system scheduling. * - * NOTE: this function should be invoke or register as ISR in BSP. + * @param param is not used, and can be set to RT_NULL. + * + * @note this function should be invoke or register as ISR in BSP. */ void rt_scheduler_ipi_handler(int vector, void *param) { @@ -284,9 +287,9 @@ void rt_scheduler_ipi_handler(int vector, void *param) } /** - * This function will perform one scheduling. It will select one thread - * with the highest priority level in global ready queue or local ready queue, - * then switch to it. + * @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, + * then switch to it. */ void rt_schedule(void) { @@ -407,8 +410,8 @@ __exit: } #else /** - * This function will perform one schedule. It will select one thread - * with the highest priority level, and switch to it immediately. + * @brief This function will perform scheduling once. It will select one thread + * with the highest priority, and switch to it immediately. */ void rt_schedule(void) { @@ -536,9 +539,9 @@ __exit: #endif /* RT_USING_SMP */ /** - * 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 - * to it. + * @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 + * to it. */ #ifdef RT_USING_SMP void rt_scheduler_do_irq_switch(void *context) @@ -631,12 +634,13 @@ void rt_scheduler_do_irq_switch(void *context) } #endif /* RT_USING_SMP */ -/* - * This function will insert a thread to system ready queue. The state of - * thread will be set as READY and remove from suspend queue. +/** + * @brief This function will insert a thread to the system ready queue. The state of + * thread will be set as READY and the thread will be removed from suspend queue. + * + * @param thread is 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 void rt_schedule_insert_thread(struct rt_thread *thread) @@ -741,12 +745,12 @@ __exit: } #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. */ #ifdef RT_USING_SMP void rt_schedule_remove_thread(struct rt_thread *thread) @@ -835,7 +839,7 @@ void rt_schedule_remove_thread(struct rt_thread *thread) #endif /* RT_USING_SMP */ /** - * This function will lock the thread scheduler. + * @brief This function will lock the thread scheduler. */ #ifdef RT_USING_SMP void rt_enter_critical(void) @@ -897,7 +901,7 @@ void rt_enter_critical(void) RTM_EXPORT(rt_enter_critical); /** - * This function will unlock the thread scheduler. + * @brief This function will unlock the thread scheduler. */ #ifdef RT_USING_SMP void rt_exit_critical(void) @@ -971,7 +975,7 @@ void rt_exit_critical(void) 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. */ diff --git a/src/signal.c b/src/signal.c index c5ae2a709a..e630c0dd97 100644 --- a/src/signal.c +++ b/src/signal.c @@ -206,6 +206,20 @@ void *rt_signal_check(void* context) } #endif /* RT_USING_SMP */ +/** + * @brief This function will install a processing function to a specific + * signal and return the old processing function of this signal. + * + * @note This function needs to be used in conjunction with the + * rt_signal_unmask() function to make the signal effective. + * + * @see rt_signal_unmask() + * + * @param signo is a specific signal value (range: 0 ~ RT_SIG_MAX). + * + * @return Return the old processing function of this signal. ONLY When the + * return value is SIG_ERR, the operation is failed. + */ rt_sighandler_t rt_signal_install(int signo, rt_sighandler_t handler) { rt_base_t level; @@ -233,6 +247,17 @@ rt_sighandler_t rt_signal_install(int signo, rt_sighandler_t handler) return old; } +/** + * @brief This function will block the specified signal. + * + * @note This function will block the specified signal, even if the + * rt_thread_kill() function is called to send this signal to + * the current thread, it will no longer take effect. + * + * @see rt_thread_kill() + * + * @param signo is a specific signal value (range: 0 ~ RT_SIG_MAX). + */ void rt_signal_mask(int signo) { rt_base_t level; @@ -245,6 +270,17 @@ void rt_signal_mask(int signo) rt_hw_interrupt_enable(level); } +/** + * @brief This function will unblock the specified signal. + * + * @note This function will unblock the specified signal. After calling + * the rt_thread_kill() function to send this signal to the current + * thread, it will take effect. + * + * @see rt_thread_kill() + * + * @param signo is a specific signal value (range: 0 ~ RT_SIG_MAX). + */ void rt_signal_unmask(int signo) { rt_base_t level; @@ -266,6 +302,20 @@ void rt_signal_unmask(int signo) } } +/** + * @brief This function will wait for the arrival of the set signal. If it does not wait for this signal, the thread will be + * suspended until it waits for this signal or the waiting time exceeds the specified timeout: timeout. + * + * @param set is the set of signal values to be waited for. Use the function + * sigaddset() to add the signal. + * + * @param si is a pointer to the received signal info. If you don't care about this value, you can use RT_NULL to set. + * + * @param timeout is a timeout period (unit: an OS tick). + * + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that the signal wait failed. + */ int rt_signal_wait(const rt_sigset_t *set, rt_siginfo_t *si, rt_int32_t timeout) { int ret = RT_EOK; @@ -497,6 +547,16 @@ void rt_thread_free_sig(rt_thread_t tid) } } +/** + * @brief This function can be used to send any signal to any thread. + * + * @param tid is a pointer to the thread that receives the signal. + * + * @param sig is a specific signal value (range: 0 ~ RT_SIG_MAX). + * + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that the signal send failed. + */ int rt_thread_kill(rt_thread_t tid, int sig) { siginfo_t si; diff --git a/src/slab.c b/src/slab.c index ad1dc71811..8e0ce7bc83 100644 --- a/src/slab.c +++ b/src/slab.c @@ -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 - * block is allocated from heap memory. + * @brief This function will set a hook function, which will be invoked when a 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)) { @@ -86,8 +86,8 @@ void rt_malloc_sethook(void (*hook)(void *ptr, rt_size_t size)) RTM_EXPORT(rt_malloc_sethook); /** - * This function will set a hook function, which will be invoked when a memory - * block is released to heap memory. + * @brief This function will set a hook function, which will be invoked when a memory + * block is released to heap memory. * * @param hook the hook function */ @@ -233,6 +233,11 @@ struct rt_page_head static struct rt_page_head *rt_page_list; 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) { struct rt_page_head *b, *n; @@ -269,6 +274,13 @@ void *rt_page_alloc(rt_size_t npages) return b; } +/** + * @brief Free memory by page. + * + * @param addr is the head address of first page. + * + * @param npages is the number of pages. + */ void rt_page_free(void *addr, rt_size_t npages) { 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) { @@ -465,15 +476,15 @@ rt_inline int zoneindex(rt_size_t *bytes) /**@{*/ /** - * 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. + * @brief This function will allocate a block from system heap memory. + * + * @note the RT_NULL is returned if + * - the nbytes is less than zero. + * - 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. */ void *rt_malloc(rt_size_t size) { @@ -668,12 +679,13 @@ __exit: 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 is the previously allocated memory block. * - * @param ptr 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. */ 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); /** - * This function will contiguously allocate enough space for count objects - * that are size bytes of memory each and returns a pointer to the allocated - * memory. + * @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 + * 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 size size of the objects to allocate + * @param count is the number of objects to allocate. * - * @return pointer to allocated memory / NULL pointer if there is an error + * @param size is the 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) { @@ -763,10 +776,11 @@ void *rt_calloc(rt_size_t count, rt_size_t size) RTM_EXPORT(rt_calloc); /** - * This function will release the previous allocated memory block by rt_malloc. - * The released memory block is taken back to system heap. + * @brief This function will release the previous allocated memory block by rt_malloc. + * + * @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) { @@ -905,6 +919,16 @@ void rt_free(void *ptr) RTM_EXPORT(rt_free); #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, rt_uint32_t *used, rt_uint32_t *max_used) diff --git a/src/thread.c b/src/thread.c index 7e0c10bfef..0c7ae4beaa 100644 --- a/src/thread.c +++ b/src/thread.c @@ -38,12 +38,11 @@ static void (*rt_thread_resume_hook) (rt_thread_t thread); static void (*rt_thread_inited_hook) (rt_thread_t thread); /** - * @ingroup Hook - * This function sets a hook function when the system suspend a thread. + * @brief This function sets a hook function when the system suspend a thread. * - * @param hook the specified hook function + * @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. + * @param hook is the specified hook function. */ void rt_thread_suspend_sethook(void (*hook)(rt_thread_t thread)) { @@ -51,12 +50,11 @@ void rt_thread_suspend_sethook(void (*hook)(rt_thread_t thread)) } /** - * @ingroup Hook - * This function sets a hook function when the system resume a thread. + * @brief This function sets a hook function when the system resume a thread. * - * @param hook the specified hook function + * @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. + * @param hook is the specified hook function. */ void rt_thread_resume_sethook(void (*hook)(rt_thread_t thread)) { @@ -64,10 +62,9 @@ void rt_thread_resume_sethook(void (*hook)(rt_thread_t thread)) } /** - * @ingroup Hook - * This function sets a hook function when a thread is initialized. + * @brief This function sets a hook function when a thread is initialized. * - * @param hook the specified hook function + * @param hook is the specified hook function. */ void rt_thread_inited_sethook(void (*hook)(rt_thread_t thread)) { @@ -76,7 +73,6 @@ void rt_thread_inited_sethook(void (*hook)(rt_thread_t thread)) #endif /* RT_USING_HOOK */ -/* must be invoke witch rt_hw_interrupt_disable */ static void _thread_cleanup_execute(rt_thread_t thread) { register rt_base_t level; @@ -244,19 +240,27 @@ static rt_err_t _thread_init(struct rt_thread *thread, /**@{*/ /** - * This function will initialize a thread, normally it's used to initialize a - * static thread object. + * @brief This function will initialize a thread. It's used to initialize a + * static thread object. * - * @param thread the static thread object - * @param name the name of thread, which shall be unique - * @param entry the entry function of thread - * @param parameter the parameter of thread enter function - * @param stack_start the start address of thread stack - * @param stack_size the size of thread stack - * @param priority the priority of thread - * @param tick the time slice if there are same priority thread + * @param thread is the static thread object. * - * @return the operation status, RT_EOK on OK, -RT_ERROR on error + * @param name is the name of thread, which shall be unique. + * + * @param entry is the entry function of thread. + * + * @param parameter is the parameter of thread enter function. + * + * @param stack_start is the start address of thread stack. + * + * @param stack_size is the size of thread stack. + * + * @param priority is the priority of thread. + * + * @param tick is the time slice if there are same priority thread. + * + * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed. + * If the return value is any other values, it means this operation failed. */ rt_err_t rt_thread_init(struct rt_thread *thread, const char *name, @@ -286,9 +290,9 @@ rt_err_t rt_thread_init(struct rt_thread *thread, RTM_EXPORT(rt_thread_init); /** - * This function will return self thread object + * @brief This function will return self thread object. * - * @return the self thread object + * @return The self thread object. */ rt_thread_t rt_thread_self(void) { @@ -309,11 +313,12 @@ rt_thread_t rt_thread_self(void) RTM_EXPORT(rt_thread_self); /** - * This function will start a thread and put it to system ready queue + * @brief This function will start a thread and put it to system ready queue. * - * @param thread the thread to be started + * @param thread is the thread to be started. * - * @return the operation status, RT_EOK on OK, -RT_ERROR on error + * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed. + * If the return value is any other values, it means this operation failed. */ rt_err_t rt_thread_startup(rt_thread_t thread) { @@ -351,12 +356,13 @@ rt_err_t rt_thread_startup(rt_thread_t thread) RTM_EXPORT(rt_thread_startup); /** - * This function will detach a thread. The thread object will be removed from - * thread queue and detached/deleted from system object management. + * @brief This function will detach a thread. The thread object will be removed from + * thread queue and detached/deleted from the system object management. * - * @param thread the thread to be deleted + * @param thread is the thread to be deleted. * - * @return the operation status, RT_EOK on OK, -RT_ERROR on error + * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed. + * If the return value is any other values, it means this operation failed. */ rt_err_t rt_thread_detach(rt_thread_t thread) { @@ -404,17 +410,23 @@ RTM_EXPORT(rt_thread_detach); #ifdef RT_USING_HEAP /** - * This function will create a thread object and allocate thread object memory - * and stack. + * @brief This function will create a thread object and allocate thread object memory. + * and stack. + * + * @param name is the name of thread, which shall be unique. + * + * @param entry is the entry function of thread. + * + * @param parameter is the parameter of thread enter function. * - * @param name the name of thread, which shall be unique - * @param entry the entry function of thread - * @param parameter the parameter of thread enter function - * @param stack_size the size of thread stack - * @param priority the priority of thread - * @param tick the time slice if there are same priority thread + * @param stack_size is the size of thread stack. * - * @return the created thread object + * @param priority is the priority of thread. + * + * @param tick is the time slice if there are same priority thread. + * + * @return If the return value is a rt_thread structure pointer, the function is successfully executed. + * If the return value is RT_NULL, it means this operation failed. */ rt_thread_t rt_thread_create(const char *name, void (*entry)(void *parameter), @@ -454,12 +466,13 @@ rt_thread_t rt_thread_create(const char *name, RTM_EXPORT(rt_thread_create); /** - * This function will delete a thread. The thread object will be removed from - * thread queue and deleted from system object management in the idle thread. + * @brief This function will delete a thread. The thread object will be removed from + * thread queue and deleted from system object management in the idle thread. * - * @param thread the thread to be deleted + * @param thread is the thread to be deleted. * - * @return the operation status, RT_EOK on OK, -RT_ERROR on error + * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed. + * If the return value is any other values, it means this operation failed. */ rt_err_t rt_thread_delete(rt_thread_t thread) { @@ -502,11 +515,12 @@ RTM_EXPORT(rt_thread_delete); #endif /* RT_USING_HEAP */ /** - * This function will let current thread yield processor, and scheduler will - * choose a highest thread to run. After yield processor, the current thread - * is still in READY state. + * @brief This function will let current thread yield processor, and scheduler will + * choose the highest thread to run. After yield processor, the current thread + * is still in READY state. * - * @return RT_EOK + * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed. + * If the return value is any other values, it means this operation failed. */ rt_err_t rt_thread_yield(void) { @@ -525,11 +539,13 @@ rt_err_t rt_thread_yield(void) RTM_EXPORT(rt_thread_yield); /** - * This function will let current thread sleep for some ticks. + * @brief This function will let current thread sleep for some ticks. Change current thread state to suspend, + * when the thread timer reaches the tick value, scheduler will awaken this thread. * - * @param tick the sleep ticks + * @param tick is the sleep ticks. * - * @return RT_EOK + * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed. + * If the return value is any other values, it means this operation failed. */ rt_err_t rt_thread_sleep(rt_tick_t tick) { @@ -564,11 +580,12 @@ rt_err_t rt_thread_sleep(rt_tick_t tick) } /** - * This function will let current thread delay for some ticks. + * @brief This function will let current thread delay for some ticks. * - * @param tick the delay ticks + * @param tick is the delay ticks. * - * @return RT_EOK + * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed. + * If the return value is any other values, it means this operation failed. */ rt_err_t rt_thread_delay(rt_tick_t tick) { @@ -577,12 +594,14 @@ rt_err_t rt_thread_delay(rt_tick_t tick) RTM_EXPORT(rt_thread_delay); /** - * This function will let current thread delay until (*tick + inc_tick). + * @brief This function will let current thread delay until (*tick + inc_tick). + * + * @param tick is the tick of last wakeup. * - * @param tick the tick of last wakeup. - * @param inc_tick the increment tick + * @param inc_tick is the increment tick. * - * @return RT_EOK + * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed. + * If the return value is any other values, it means this operation failed. */ rt_err_t rt_thread_delay_until(rt_tick_t *tick, rt_tick_t inc_tick) { @@ -637,11 +656,12 @@ rt_err_t rt_thread_delay_until(rt_tick_t *tick, rt_tick_t inc_tick) RTM_EXPORT(rt_thread_delay_until); /** - * This function will let current thread delay for some milliseconds. + * @brief This function will let current thread delay for some milliseconds. * - * @param ms the delay ms time + * @param ms is the delay ms time. * - * @return RT_EOK + * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed. + * If the return value is any other values, it means this operation failed. */ rt_err_t rt_thread_mdelay(rt_int32_t ms) { @@ -654,17 +674,24 @@ rt_err_t rt_thread_mdelay(rt_int32_t ms) RTM_EXPORT(rt_thread_mdelay); /** - * This function will control thread behaviors according to control command. + * @brief This function will control thread behaviors according to control command. + * + * @param thread is the specified thread to be controlled. + * + * @param cmd is the control command, which includes. * - * @param thread the specified thread to be controlled - * @param cmd the control command, which includes - * RT_THREAD_CTRL_CHANGE_PRIORITY for changing priority level of thread; - * RT_THREAD_CTRL_STARTUP for starting a thread; - * RT_THREAD_CTRL_CLOSE for delete a thread; - * RT_THREAD_CTRL_BIND_CPU for bind the thread to a CPU. - * @param arg the argument of control command + * RT_THREAD_CTRL_CHANGE_PRIORITY for changing priority level of thread. * - * @return RT_EOK + * RT_THREAD_CTRL_STARTUP for starting a thread. + * + * RT_THREAD_CTRL_CLOSE for delete a thread. + * + * RT_THREAD_CTRL_BIND_CPU for bind the thread to a CPU. + * + * @param arg is the argument of control command. + * + * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed. + * If the return value is any other values, it means this operation failed. */ rt_err_t rt_thread_control(rt_thread_t thread, int cmd, void *arg) { @@ -770,14 +797,15 @@ rt_err_t rt_thread_control(rt_thread_t thread, int cmd, void *arg) RTM_EXPORT(rt_thread_control); /** - * This function will suspend the specified thread. + * @brief This function will suspend the specified thread and change it to suspend state. * - * @param thread the thread to be suspended + * @note If suspend self thread, after this function call, the + * rt_schedule() must be invoked. * - * @return the operation status, RT_EOK on OK, -RT_ERROR on error + * @param thread is the thread to be suspended. * - * @note if suspend self thread, after this function call, the - * rt_schedule() must be invoked. + * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed. + * If the return value is any other values, it means this operation failed. */ rt_err_t rt_thread_suspend(rt_thread_t thread) { @@ -822,11 +850,12 @@ rt_err_t rt_thread_suspend(rt_thread_t thread) RTM_EXPORT(rt_thread_suspend); /** - * This function will resume a thread and put it to system ready queue. + * @brief This function will resume a thread and put it to system ready queue. * - * @param thread the thread to be resumed + * @param thread is the thread to be resumed. * - * @return the operation status, RT_EOK on OK, -RT_ERROR on error + * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed. + * If the return value is any other values, it means this operation failed. */ rt_err_t rt_thread_resume(rt_thread_t thread) { @@ -866,10 +895,10 @@ rt_err_t rt_thread_resume(rt_thread_t thread) RTM_EXPORT(rt_thread_resume); /** - * This function is the timeout function for thread, normally which is invoked - * when thread is timeout to wait some resource. + * @brief This function is the timeout function for thread, normally which is invoked + * when thread is timeout to wait some resource. * - * @param parameter the parameter of thread timeout function + * @param parameter is the parameter of thread timeout function */ void rt_thread_timeout(void *parameter) { @@ -904,18 +933,20 @@ void rt_thread_timeout(void *parameter) RTM_EXPORT(rt_thread_timeout); /** - * This function will find the specified thread. + * @brief This function will find the specified thread. * - * @param name the name of thread finding + * @note Please don't invoke this function in interrupt status. * - * @return the found thread + * @param name is the name of thread finding. * - * @note please don't invoke this function in interrupt status. + * @return If the return value is a rt_thread structure pointer, the function is successfully executed. + * If the return value is RT_NULL, it means this operation failed. */ rt_thread_t rt_thread_find(char *name) { return (rt_thread_t)rt_object_find(name, RT_Object_Class_Thread); } + RTM_EXPORT(rt_thread_find); /**@}*/ |