Collaboration diagram for Thread Management:

Data Structures
struct	rt_cpu_usage_stats

struct	rt_thread

Macros
#define	RT_THREAD_INIT 0x00

#define	RT_THREAD_CLOSE 0x01

#define	RT_THREAD_READY 0x02

#define	RT_THREAD_RUNNING 0x03

#define	RT_THREAD_SUSPEND_INTERRUPTIBLE (RT_THREAD_SUSPEND_MASK)

#define	RT_THREAD_SUSPEND_KILLABLE (RT_THREAD_SUSPEND_MASK \| RT_SIGNAL_COMMON_WAKEUP_MASK)

#define	RT_THREAD_SUSPEND_UNINTERRUPTIBLE (RT_THREAD_SUSPEND_MASK \| RT_SIGNAL_COMMON_WAKEUP_MASK \| RT_SIGNAL_KILL_WAKEUP_MASK)

#define	RT_THREAD_STAT_YIELD 0x08

#define	RT_THREAD_STAT_SIGNAL 0x10

#define	RT_THREAD_STAT_SIGNAL_WAIT 0x20

#define	RT_THREAD_STAT_SIGNAL_PENDING 0x40

#define	RT_THREAD_CTRL_STARTUP 0x00

#define	RT_THREAD_CTRL_CLOSE 0x01

#define	RT_THREAD_CTRL_CHANGE_PRIORITY 0x02

#define	RT_THREAD_CTRL_INFO 0x03

#define	RT_THREAD_CTRL_BIND_CPU 0x04

Typedefs
typedef void(*	rt_thread_inited_hookproto_t) (rt_thread_t thread)

Functions
rt_err_t	rt_thread_init (struct rt_thread thread, const char name, void(entry)(void parameter), void parameter, void stack_start, rt_uint32_t stack_size, rt_uint8_t priority, rt_uint32_t tick)

rt_thread_t	rt_thread_self (void)

rt_err_t	rt_thread_startup (rt_thread_t thread)

rt_err_t	rt_thread_close (rt_thread_t thread)

rt_err_t	rt_thread_detach (rt_thread_t thread)

rt_thread_t	rt_thread_create (const char name, void(entry)(void parameter), void parameter, rt_uint32_t stack_size, rt_uint8_t priority, rt_uint32_t tick)

rt_err_t	rt_thread_delete (rt_thread_t thread)

rt_err_t	rt_thread_yield (void)

rt_err_t	rt_thread_delay (rt_tick_t tick)

rt_err_t	rt_thread_delay_until (rt_tick_t *tick, rt_tick_t inc_tick)

rt_err_t	rt_thread_mdelay (rt_int32_t ms)

rt_err_t	rt_thread_control (rt_thread_t thread, int cmd, void *arg)

rt_err_t	rt_thread_suspend_to_list (rt_thread_t thread, rt_list_t *susp_list, int ipc_flags, int suspend_flag)

rt_err_t	rt_thread_suspend_with_flag (rt_thread_t thread, int suspend_flag)

rt_err_t	rt_thread_resume (rt_thread_t thread)

rt_thread_t	rt_thread_find (char *name)

rt_err_t	rt_thread_get_name (rt_thread_t thread, char *name, rt_uint8_t name_size)

void	rt_thread_idle_init (void)

rt_err_t	rt_thread_idle_delhook (void(*hook)(void))

rt_thread_t	rt_thread_idle_gethandler (void)

void	rt_system_scheduler_init (void)

void	rt_system_scheduler_start (void)

void	rt_schedule (void)

void	rt_scheduler_do_irq_switch (void *context)

rt_base_t	rt_enter_critical (void)

void	rt_exit_critical (void)

rt_uint16_t	rt_critical_level (void)

void	rt_scheduler_ipi_handler (int vector, void *param)

void	rt_schedule_insert_thread (struct rt_thread *thread)

void	rt_schedule_remove_thread (struct rt_thread *thread)

Detailed Description

the thread management

RT-Thread operating system supports multitask systems, which are based on thread scheduling.

The scheduling is a full preemptive priority-based scheduling algorithm.
8/32/256 priority levels are supported, in which 0 is the highest and 7/31/255 the lowest. The 7/31/255th priority is used for idle thread.
Threads running at same priority level are supported. The shared time-slice round-robin scheduling is used for this case.
The time of scheduler to choose the next highest ready thread is determinant.
There are four status in thread management
1. Initialization
2. Running/Ready
3. Blocked
4. Closed
The number of threads in the system is unlimited, only related with RAM.

Macro Definition Documentation

◆ RT_THREAD_INIT

#define RT_THREAD_INIT 0x00

Initialized status

◆ RT_THREAD_CLOSE

#define RT_THREAD_CLOSE 0x01

Closed status

◆ RT_THREAD_READY

#define RT_THREAD_READY 0x02

Ready status

◆ RT_THREAD_RUNNING

#define RT_THREAD_RUNNING 0x03

Running status

◆ RT_THREAD_SUSPEND_INTERRUPTIBLE

#define RT_THREAD_SUSPEND_INTERRUPTIBLE (RT_THREAD_SUSPEND_MASK)

Suspend interruptable 0x4

◆ RT_THREAD_SUSPEND_KILLABLE

#define RT_THREAD_SUSPEND_KILLABLE (RT_THREAD_SUSPEND_MASK | RT_SIGNAL_COMMON_WAKEUP_MASK)

Suspend with killable 0x6

◆ RT_THREAD_SUSPEND_UNINTERRUPTIBLE

#define RT_THREAD_SUSPEND_UNINTERRUPTIBLE (RT_THREAD_SUSPEND_MASK | RT_SIGNAL_COMMON_WAKEUP_MASK | RT_SIGNAL_KILL_WAKEUP_MASK)

Suspend with uninterruptable 0x7

◆ RT_THREAD_STAT_YIELD

#define RT_THREAD_STAT_YIELD 0x08

indicate whether remaining_tick has been reloaded since last schedule

◆ RT_THREAD_STAT_SIGNAL

#define RT_THREAD_STAT_SIGNAL 0x10

task hold signals

◆ RT_THREAD_STAT_SIGNAL_WAIT

#define RT_THREAD_STAT_SIGNAL_WAIT 0x20

task is waiting for signals

◆ RT_THREAD_STAT_SIGNAL_PENDING

#define RT_THREAD_STAT_SIGNAL_PENDING 0x40

signals is held and it has not been procressed

◆ RT_THREAD_CTRL_STARTUP

#define RT_THREAD_CTRL_STARTUP 0x00

thread control command definitions Startup thread.

◆ RT_THREAD_CTRL_CLOSE

#define RT_THREAD_CTRL_CLOSE 0x01

Close thread.

◆ RT_THREAD_CTRL_CHANGE_PRIORITY

#define RT_THREAD_CTRL_CHANGE_PRIORITY 0x02

Change thread priority.

◆ RT_THREAD_CTRL_INFO

#define RT_THREAD_CTRL_INFO 0x03

Get thread information.

◆ RT_THREAD_CTRL_BIND_CPU

#define RT_THREAD_CTRL_BIND_CPU 0x04

Set thread bind cpu.

Typedef Documentation

◆ rt_thread_inited_hookproto_t

typedef void(* rt_thread_inited_hookproto_t) (rt_thread_t thread)

Sets a hook function when a thread is initialized.

Parameters

thread is the target thread that initializing

Function Documentation

◆ rt_thread_init()

rt_err_t rt_thread_init	(	struct rt_thread *	thread,
		const char *	name,
		void()(void parameter)	entry,
		void *	parameter,
		void *	stack_start,
		rt_uint32_t	stack_size,
		rt_uint8_t	priority,
		rt_uint32_t	tick
	)

This function will initialize a thread. It's used to initialize a static thread object.

Parameters

thread	is the static thread object.
name	is the name of thread, which shall be unique.
entry	is the entry function of thread.
parameter	is the parameter of thread enter function.
stack_start	is the start address of thread stack.
stack_size	is the size of thread stack.
priority	is the priority of thread.
tick	is the time slice if there are same priority thread.

Returns: 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_thread_self()

rt_thread_t rt_thread_self ( void )

This function will return self thread object.

Returns: The self thread object.

◆ rt_thread_startup()

rt_err_t rt_thread_startup ( rt_thread_t thread )

This function will start a thread and put it to system ready queue.

Parameters

thread is the thread to be started.

Returns: 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_thread_close()

rt_err_t rt_thread_close ( rt_thread_t thread )

This function will close a thread. The thread object will be removed from thread queue and detached/deleted from the system object management. It's different from rt_thread_delete or rt_thread_detach that this will not enqueue the closing thread to cleanup queue.

Parameters

thread is the thread to be closed.

Returns: 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_thread_detach()

rt_err_t rt_thread_detach ( rt_thread_t thread )

This function will detach a thread. The thread object will be removed from thread queue and detached/deleted from the system object management.

Parameters

thread is the thread to be deleted.

Returns: 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_thread_create()

rt_thread_t rt_thread_create	(	const char *	name,
		void()(void parameter)	entry,
		void *	parameter,
		rt_uint32_t	stack_size,
		rt_uint8_t	priority,
		rt_uint32_t	tick
	)

This function will create a thread object and allocate thread object memory. and stack.

Parameters

name	is the name of thread, which shall be unique.
entry	is the entry function of thread.
parameter	is the parameter of thread enter function.
stack_size	is the size of thread stack.
priority	is the priority of thread.
tick	is the time slice if there are same priority thread.

Returns: 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_delete()

rt_err_t rt_thread_delete ( rt_thread_t thread )

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.

Parameters

thread is the thread to be deleted.

Returns: 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_thread_yield()

rt_err_t rt_thread_yield ( void )

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.

Returns: 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_thread_delay()

rt_err_t rt_thread_delay ( rt_tick_t tick )

This function will let current thread delay for some ticks.

Parameters

tick	is the delay ticks.

Returns: 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_thread_delay_until()

rt_err_t rt_thread_delay_until	(	rt_tick_t *	tick,
		rt_tick_t	inc_tick
	)

This function will let current thread delay until (*tick + inc_tick).

Parameters

tick	is the tick of last wakeup.
inc_tick	is the increment tick.

Returns: 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_thread_mdelay()

rt_err_t rt_thread_mdelay ( rt_int32_t ms )

This function will let current thread delay for some milliseconds.

Parameters

ms	is the delay ms time.

Returns: 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_thread_control()

rt_err_t rt_thread_control	(	rt_thread_t	thread,
		int	cmd,
		void *	arg
	)

This function will control thread behaviors according to control command.

Parameters

thread is the specified thread to be controlled.

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.

         RT_THREAD_CTRL_CLOSE for delete a thread.

         RT_THREAD_CTRL_BIND_CPU for bind the thread to a CPU.

arg is the argument of control command.

Returns: 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_thread_suspend_to_list()

rt_err_t rt_thread_suspend_to_list	(	rt_thread_t	thread,
		rt_list_t *	susp_list,
		int	ipc_flags,
		int	suspend_flag
	)

This function will suspend the specified thread and change it to suspend state.

Note: This function ONLY can suspend current thread itself. rt_thread_suspend(rt_thread_self());

Do not use the rt_thread_suspend to suspend other threads. You have no way of knowing what code a thread is executing when you suspend it. If you suspend a thread while sharing a resouce with other threads and occupying this resouce, starvation can occur very easily.

Parameters

thread	the thread to be suspended.
susp_list	the list thread enqueued to. RT_NULL if no list.
ipc_flags	is a flag for the thread object to be suspended. It determines how the thread is suspended. The flag can be ONE of the following values: RT_IPC_FLAG_PRIO The pending threads will queue in order of priority. RT_IPC_FLAG_FIFO The pending threads will queue in the first-in-first-out method (also known as first-come-first-served (FCFS) scheduling strategy). NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about the first-in-first-out principle, and you clearly understand that all threads involved in this semaphore will become non-real-time threads.
suspend_flag	status flag of the thread to be suspended.

Returns: 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.

enqueue thread on the push list before leaving critical region of scheduler, so we won't miss notification of async events.

◆ rt_thread_suspend_with_flag()

rt_err_t rt_thread_suspend_with_flag	(	rt_thread_t	thread,
		int	suspend_flag
	)

This function will suspend the specified thread and change it to suspend state.

Note: This function ONLY can suspend current thread itself. rt_thread_suspend(rt_thread_self());

Do not use the rt_thread_suspend to suspend other threads. You have no way of knowing what code a thread is executing when you suspend it. If you suspend a thread while sharing a resouce with other threads and occupying this resouce, starvation can occur very easily.

Parameters

thread	the thread to be suspended.
suspend_flag	status flag of the thread to be suspended.

Returns: 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_thread_resume()

rt_err_t rt_thread_resume ( rt_thread_t thread )

This function will resume a thread and put it to system ready queue.

Parameters

thread is the thread to be resumed.

Returns: 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_ESCHEDLOCKED indicates that the current thread is in a critical section, rather than 'thread' can't be resumed. Therefore, we can ignore this error.

◆ rt_thread_find()

rt_thread_t rt_thread_find ( char * name )

This function will find the specified thread.

Note: Please don't invoke this function in interrupt status.

Parameters

name	is the name of thread finding.

Returns: 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_get_name()

rt_err_t rt_thread_get_name	(	rt_thread_t	thread,
		char *	name,
		rt_uint8_t	name_size
	)

This function will return the name of the specified thread.

Note: Please don't invoke this function in interrupt status

Parameters

thread	the thread to retrieve thread name
name	buffer to store the thread name string
name_size	maximum size of the buffer to store the thread name

Returns: If the return value is RT_EOK, the function is successfully executed If the return value is -RT_EINVAL, it means this operation failed

◆ rt_thread_idle_init()

void rt_thread_idle_init ( void )

This function will initialize idle thread, then start it.

Note: this function must be invoked when system init.

◆ rt_thread_idle_delhook()

rt_err_t rt_thread_idle_delhook ( void(*)(void) hook )

delete the idle hook on hook list.

Parameters

hook	the specified hook function.

Returns: RT_EOK: delete OK. -RT_ENOSYS: hook was not found.

◆ rt_thread_idle_gethandler()

rt_thread_t rt_thread_idle_gethandler ( void )

This function will get the handler of the idle thread.

◆ rt_system_scheduler_init()

void rt_system_scheduler_init ( void )

This function will initialize the system scheduler.

◆ rt_system_scheduler_start()

void rt_system_scheduler_start ( void )

This function will startup the scheduler. It will select one thread with the highest priority level, then switch to it.

legacy rt_cpus_lock. some bsp codes still use it as for it's critical region. Since scheduler is never touching this, here we just release it on the entry.

for the accessing of the scheduler context. Noted that we don't have current_thread at this point

◆ rt_schedule()

void rt_schedule ( void )

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.

Note: this function is implemented in both scheduler_up.c and scheduler_mp.c.

◆ rt_scheduler_do_irq_switch()

void rt_scheduler_do_irq_switch ( void * context )

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.

Parameters

context is the context to be switched to.

Note: this function is only implemented in scheduler_mp.c.

◆ rt_enter_critical()

void rt_enter_critical ( void )

This function will lock the thread scheduler.

Note: this function is implemented in both scheduler_up.c and scheduler_mp.c.

◆ rt_exit_critical()

void rt_exit_critical ( void )

This function will unlock the thread scheduler.

Note: this function is implemented in both scheduler_up.c and scheduler_mp.c.

◆ rt_critical_level()

rt_uint16_t rt_critical_level ( void )

Get the scheduler lock level.

Returns: the level of the scheduler lock. 0 means unlocked.

Note: this function is implemented in both scheduler_up.c and scheduler_mp.c.

◆ rt_scheduler_ipi_handler()

void rt_scheduler_ipi_handler	(	int	vector,
		void *	param
	)

This function will handle IPI interrupt and do a scheduling in system.

Parameters

vector	is the number of IPI interrupt for system scheduling.
param	is not used, and can be set to RT_NULL.

Note: this function should be invoke or register as ISR in BSP.; this function is only implemented in scheduler_mp.c.

◆ rt_schedule_insert_thread()

void rt_schedule_insert_thread ( struct rt_thread * thread )

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.

Parameters

thread is the thread to be inserted.

Note: Please do not invoke this function in user application.; this function is implemented in both scheduler_up.c and scheduler_mp.c.

◆ rt_schedule_remove_thread()

void rt_schedule_remove_thread ( struct rt_thread * thread )

This function will remove a thread from system ready queue.

Parameters

thread is the thread to be removed.

Note: Please do not invoke this function in user application.; this function is implemented in both scheduler_up.c and scheduler_mp.c.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ RT_THREAD_INIT

◆ RT_THREAD_CLOSE

◆ RT_THREAD_READY

◆ RT_THREAD_RUNNING

◆ RT_THREAD_SUSPEND_INTERRUPTIBLE

◆ RT_THREAD_SUSPEND_KILLABLE

◆ RT_THREAD_SUSPEND_UNINTERRUPTIBLE

◆ RT_THREAD_STAT_YIELD

◆ RT_THREAD_STAT_SIGNAL

◆ RT_THREAD_STAT_SIGNAL_WAIT

◆ RT_THREAD_STAT_SIGNAL_PENDING

◆ RT_THREAD_CTRL_STARTUP

◆ RT_THREAD_CTRL_CLOSE

◆ RT_THREAD_CTRL_CHANGE_PRIORITY

◆ RT_THREAD_CTRL_INFO

◆ RT_THREAD_CTRL_BIND_CPU

Typedef Documentation

◆ rt_thread_inited_hookproto_t

Function Documentation

◆ rt_thread_init()

◆ rt_thread_self()

◆ rt_thread_startup()

◆ rt_thread_close()

◆ rt_thread_detach()

◆ rt_thread_create()

◆ rt_thread_delete()

◆ rt_thread_yield()

◆ rt_thread_delay()

◆ rt_thread_delay_until()

◆ rt_thread_mdelay()

◆ rt_thread_control()

◆ rt_thread_suspend_to_list()

◆ rt_thread_suspend_with_flag()

◆ rt_thread_resume()

◆ rt_thread_find()

◆ rt_thread_get_name()

◆ rt_thread_idle_init()

◆ rt_thread_idle_delhook()

◆ rt_thread_idle_gethandler()

◆ rt_system_scheduler_init()

◆ rt_system_scheduler_start()

◆ rt_schedule()

◆ rt_scheduler_do_irq_switch()

◆ rt_enter_critical()

◆ rt_exit_critical()

◆ rt_critical_level()

◆ rt_scheduler_ipi_handler()

◆ rt_schedule_insert_thread()

◆ rt_schedule_remove_thread()