diff options
Diffstat (limited to 'src/thread.c')
| -rw-r--r-- | src/thread.c | 131 |
1 files changed, 87 insertions, 44 deletions
diff --git a/src/thread.c b/src/thread.c index a520a323b1..7c3a7e0c65 100644 --- a/src/thread.c +++ b/src/thread.c @@ -306,23 +306,39 @@ static rt_err_t _thread_init(struct rt_thread *thread, * @brief This function will initialize a thread. It's used to initialize a * static thread object. * - * @param thread is the static thread object. + * @param thread Thread handle. Thread handle is provided by the user and + * points to the corresponding thread control block memory address. * - * @param name is the name of thread, which shall be unique. + * @param name Name of the thread (shall be unique); the maximum length of the + * thread name is specified by the `RT_NAME_MAX` macro defined in + * `rtconfig.h`, and the extra part is automatically truncated. * - * @param entry is the entry function of thread. + * @param entry Entry function of thread. * - * @param parameter is the parameter of thread enter function. + * @param parameter Parameter of thread entry function. * - * @param stack_start is the start address of thread stack. + * @param stack_start Start address of thread stack. * - * @param stack_size is the size of thread stack. + * @param stack_size Size of thread stack in bytes. Stack space address + * alignment is required in most systems (for example, + * alignment to 4-byte addresses in the ARM architecture). * - * @param priority is the priority of thread. + * @param priority Priority of thread. The priority range is based on the + * system configuration (macro definition `RT_THREAD_PRIORITY_MAX` + * in `rtconfig.h`). If 256 levels of priority are supported, + * the range is from 0 to 255. The smaller the value, the + * higher the priority, and 0 is the highest priority. * - * @param tick is the time slice if there are same priority thread. + * @param tick Time slice if there are same priority thread. The unit of the + * time slice (tick) is the tick of the operating system. When + * there are threads with the same priority in the system, this + * parameter specifies the maximum length of time of a thread for + * one schedule. At the end of this time slice run, the scheduler + * automatically selects the next ready state of the same priority + * thread to run. * - * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed. + * @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, @@ -359,7 +375,8 @@ RTM_EXPORT(rt_thread_init); /** * @brief This function will return self thread object. * - * @return The self thread object. + * @return The self thread object. If returns `RT_NULL`, it means that the + * scheduler has not started yet. */ rt_thread_t rt_thread_self(void) { @@ -385,9 +402,10 @@ RTM_EXPORT(rt_thread_self); /** * @brief This function will start a thread and put it to system ready queue. * - * @param thread is the thread to be started. + * @param thread Handle of the thread to be started. * - * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed. + * @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) @@ -462,9 +480,11 @@ static rt_err_t _thread_detach(rt_thread_t thread); * @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 is the thread to be deleted. + * @param thread Handle of the thread to be deleted. The thread must be + * initialized by `rt_thread_init()`. * - * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed. + * @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) @@ -505,20 +525,32 @@ static rt_err_t _thread_detach(rt_thread_t thread) * @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 name The name of the thread (shall be unique.); the maximum length of + * the thread name is specified by macro `RT_NAME_MAX` in `rtconfig.h`, + * and the extra part is automatically truncated. * - * @param entry is the entry function of thread. + * @param entry Entry function of thread. * - * @param parameter is the parameter of thread enter function. + * @param parameter Parameter of thread entry function. * - * @param stack_size is the size of thread stack. + * @param stack_size Size of thread stack in bytes. * - * @param priority is the priority of thread. + * @param priority Priority of thread. The priority range is based on the + * system configuration (macro definition `RT_THREAD_PRIORITY_MAX` + * in rtconfig.h). If 256-level priority is supported, then + * the range is from 0 to 255. The smaller the value, the + * higher the priority, and 0 is the highest priority. * - * @param tick is the time slice if there are same priority thread. + * @param tick Time slice if there are same priority thread. The unit of the + * time slice (tick) is the tick of the operating system. When + * there are threads with the same priority in the system, this + * parameter specifies the maximum length of time of a thread for + * one schedule. At the end of this time slice run, the scheduler + * automatically selects the next ready state of the same priority + * thread to run. * - * @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. + * @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), @@ -564,9 +596,10 @@ RTM_EXPORT(rt_thread_create); * @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 is the thread to be deleted. + * @param thread Handle of the thread to be deleted. * - * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed. + * @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) @@ -668,9 +701,10 @@ static rt_err_t _thread_sleep(rt_tick_t tick) /** * @brief This function will let current thread delay for some ticks. * - * @param tick is the delay ticks. + * @param tick The delay ticks, in units of 1 OS Tick. * - * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed. + * @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) @@ -746,9 +780,10 @@ RTM_EXPORT(rt_thread_delay_until); /** * @brief This function will let current thread delay for some milliseconds. * - * @param ms is the delay ms time. + * @param ms The delay time in units of 1ms. * - * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed. + * @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) @@ -767,23 +802,21 @@ RTM_EXPORT(rt_thread_mdelay); /** * @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. - * - * RT_THREAD_CTRL_CHANGE_PRIORITY for changing priority level of thread. - * - * RT_THREAD_CTRL_STARTUP for starting a thread. + * @param thread Handle of the thread to be controlled. * - * RT_THREAD_CTRL_CLOSE for delete a thread. + * @param cmd Control command, which includes. + * - `RT_THREAD_CTRL_CHANGE_PRIORITY` for changing priority level of thread. + * - `RT_THREAD_CTRL_STARTUP` for starting a thread, equivalent to + * the `rt_thread_startup()` function call. + * - `RT_THREAD_CTRL_CLOSE` for closing a thread, equivalent to the + * `rt_thread_delete()` function call. + * - `RT_THREAD_CTRL_BIND_CPU` for bind the thread to a CPU. + * - `RT_THREAD_CTRL_RESET_PRIORITY` for reset priority level of thread. * - * RT_THREAD_CTRL_BIND_CPU for bind the thread to a CPU. + * @param arg Argument of control command. * - * RT_THREAD_CTRL_RESET_PRIORITY for reset priority level of thread. - * - * @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. + * @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) @@ -1006,6 +1039,15 @@ rt_err_t rt_thread_suspend_with_flag(rt_thread_t thread, int suspend_flag) } RTM_EXPORT(rt_thread_suspend_with_flag); +/** + * @brief This function will suspend the specified thread and change it to suspend state. + * + * @param thread Handle of the thread to be suspended. + * + * @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) { return rt_thread_suspend_with_flag(thread, RT_UNINTERRUPTIBLE); @@ -1015,9 +1057,10 @@ RTM_EXPORT(rt_thread_suspend); /** * @brief This function will resume a thread and put it to system ready queue. * - * @param thread is the thread to be resumed. + * @param thread Handle of the thread to be resumed. * - * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed. + * @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) |