thread.h¶
Threading API.
-
STATUS_NOT_FOUND
¶ Describes an illegal thread status.
1
(-1)
-
STATUS_STOPPED
¶ has terminated
1
0
-
STATUS_SLEEPING
¶ sleeping
1
1
-
STATUS_MUTEX_BLOCKED
¶ waiting for a locked mutex
1
2
-
STATUS_RECEIVE_BLOCKED
¶ waiting for a message
1
3
-
STATUS_SEND_BLOCKED
¶ waiting for message to be delivered
1
4
-
STATUS_REPLY_BLOCKED
¶ waiting for a message response
1
5
-
STATUS_FLAG_BLOCKED_ANY
¶ waiting for any flag from flag_mask
1
6
-
STATUS_FLAG_BLOCKED_ALL
¶ waiting for all flags in flag_mask
1
7
-
STATUS_MBOX_BLOCKED
¶ waiting for get/put on mbox
1
8
-
STATUS_ON_RUNQUEUE
¶ to check if on run queue:
st >= STATUS_ON_RUNQUEUE
1
STATUS_RUNNING
-
STATUS_RUNNING
¶ currently running
1
9
-
STATUS_PENDING
¶ waiting to be scheduled to run
1
10
-
THREAD_CREATE_SLEEPING
¶ Set the new thread to sleeping.
1
(1)
It must be woken up manually.
-
THREAD_AUTO_FREE
¶ Currently not implemented.
1
(2)
-
THREAD_CREATE_WOUT_YIELD
¶ Do not automatically call
thread.h::thread_yield()
after creation: the newly created thread might not run immediately.1
(4)
Purely for optimization. Any other context switch (i.e. an interrupt) can still start the thread at any time!
-
THREAD_CREATE_STACKTEST
¶ Write markers into the thread’s stack to measure stack usage (for debugging and profiling purposes)
1
(8)
-
THREAD_STACKSIZE_DEFAULT
¶ A reasonable default stack size that will suffice most smaller tasks.
Note
This value must be defined by the CPU specific implementation, please take a look at
cpu/$CPU/include/cpu_conf
.h
-
THREAD_STACKSIZE_IDLE
¶ Size of the idle task’s stack in bytes.
Note
This value must be defined by the CPU specific implementation, please take a look at
cpu/$CPU/include/cpu_conf
.h
-
THREAD_EXTRA_STACKSIZE_PRINTF
¶ Size of the task’s printf stack in bytes.
Note
This value must be defined by the CPU specific implementation, please take a look at
cpu/$CPU/include/cpu_conf
.h
-
THREAD_STACKSIZE_MAIN
¶ Size of the main task’s stack in bytes.
1
(THREAD_STACKSIZE_DEFAULT + THREAD_EXTRA_STACKSIZE_PRINTF)
-
THREAD_STACKSIZE_LARGE
¶ Large stack size.
1
(THREAD_STACKSIZE_MEDIUM * 2)
-
THREAD_STACKSIZE_MEDIUM
¶ Medium stack size.
1
THREAD_STACKSIZE_DEFAULT
-
THREAD_STACKSIZE_SMALL
¶ Small stack size.
1
(THREAD_STACKSIZE_MEDIUM / 2)
-
THREAD_STACKSIZE_TINY
¶ Tiny stack size.
1
(THREAD_STACKSIZE_MEDIUM / 4)
-
THREAD_STACKSIZE_MINIMUM
¶ Minimum stack size.
1
(sizeof(thread_t))
-
THREAD_PRIORITY_MIN
¶ Least priority a thread can have.
1
(SCHED_PRIO_LEVELS-1)
-
THREAD_PRIORITY_IDLE
¶ Priority of the idle thread.
1
(THREAD_PRIORITY_MIN)
-
THREAD_PRIORITY_MAIN
¶ Priority of the main thread.
1
(THREAD_PRIORITY_MIN - (SCHED_PRIO_LEVELS/2))
-
void *(*
thread_task_func_t
()¶ Prototype for a thread entry function.
-
kernel_types.h::kernel_pid_t
thread_create
(char * stack, int stacksize, char priority, int flags,thread.h::thread_task_func_t
task_func, void * arg, const char * name)¶ Creates a new thread.
For an in-depth discussion of thread priorities, behavior and and flags, see Threading.
Note
Avoid assigning the same priority to two or more threads.
Note
Creating threads from within an ISR is currently supported, however it is considered to be a bad programming practice and we strongly discourage you from doing so.
Parameters
stack: start address of the preallocated stack memory stacksize: the size of the thread’s stack in bytes priority: priority of the new thread, lower mean higher priority flags: optional flags for the creation of the new thread task_func: pointer to the code that is executed in the new thread arg: the argument to the function name: a human readable descriptor for the thread Return values
- PID of newly created task on success
- -EINVAL, if
priority
is greater than or equal tosched.h::SCHED_PRIO_LEVELS
- -EOVERFLOW, if there are too many threads running already
-
sched.h::thread_t
*thread_get
(kernel_types.h::kernel_pid_t
pid)¶ Retreive a thread control block by PID.
This is a bound-checked variant of accessing
sched_threads[pid]
directly. If you know that the PID is valid, then don’t use this function.Parameters
pid: Thread to retreive. Return values
NULL
if the PID is invalid or there is no such thread.
-
int
thread_getstatus
(kernel_types.h::kernel_pid_t
pid)¶ Returns the status of a process.
Parameters
pid: the PID of the thread to get the status from Return values
- status of the thread
STATUS_NOT_FOUND
if pid is unknown
-
void
thread_sleep
(void)¶ Puts the current thread into sleep mode.
Has to be woken up externally.
-
void
thread_yield
(void)¶ Lets current thread yield.
The current thread will resume operation immediately, if there is no other ready thread with the same or a higher priority.
Differently from
thread.h::thread_yield_higher()
the current thread will be put to the end of the thread’s in its priority class.See also
-
void
thread_yield_higher
(void)¶ Lets current thread yield in favor of a higher prioritized thread.
The current thread will resume operation immediately, if there is no other ready thread with a higher priority.
Differently from
thread.h::thread_yield()
the current thread will be scheduled next in its own priority class, i.e. it stays the first thread in its priority class.See also
-
int
thread_wakeup
(kernel_types.h::kernel_pid_t
pid)¶ Wakes up a sleeping thread.
Parameters
pid: the PID of the thread to be woken up Return values
1
on successSTATUS_NOT_FOUND
if pid is unknown or not sleeping
-
kernel_types.h::kernel_pid_t
thread_getpid
(void)¶ Returns the process ID of the currently running thread.
Return values
- obviously you are not a golfer.
-
char *
thread_stack_init
(thread.h::thread_task_func_t
task_func, void * arg, void * stack_start, int stack_size)¶ Gets called upon thread creation to set CPU registers.
Parameters
task_func: First function to call within the thread arg: Argument to supply to task_func stack_start: Start address of the stack stack_size: Stack size Return values
- stack pointer
-
void
thread_add_to_list
(list.h::list_node_t
* list,sched.h::thread_t
* thread)¶ Add thread to list, sorted by priority (internal)
This will add
thread
tolist
sorted by the thread priority. It reuses the thread’s rq_entry field. Used internally by msg and mutex implementations.Note
Only use for threads not on any runqueue and with interrupts disabled.
Parameters
list: ptr to list root node thread: thread to add
-
const char *
thread_getname
(kernel_types.h::kernel_pid_t
pid)¶ Returns the name of a process.
Note
when compiling without DEVELHELP, this always returns NULL!
Parameters
pid: the PID of the thread to get the name from Return values
- the threads name
NULL
if pid is unknown
-
uintptr_t
thread_measure_stack_free
(char * stack)¶ Measures the stack usage of a stack.
Only works if the thread was created with the flag THREAD_CREATE_STACKTEST.
Parameters
stack: the stack you want to measure. try sched_active_thread->stack_start
Return values
- the amount of unused space of the thread’s stack
-
int
thread_isr_stack_usage
(void)¶ Get the number of bytes used on the ISR stack.
-
void *
thread_isr_stack_pointer
(void)¶ Get the current ISR stack pointer.
-
void *
thread_isr_stack_start
(void)¶ Get the start of the ISR stack.
-
void
thread_stack_print
(void)¶ Print the current stack to stdout.
-
void
thread_print_stack
(void)¶ Prints human readable, ps-like thread information for debugging purposes.
-
struct
_thread
¶ thread_t
holds thread’s context data.-
char *
sp
¶ thread’s stack pointer
-
uint8_t
status
¶ thread’s status
-
uint8_t
priority
¶ thread’s priority
-
kernel_types.h::kernel_pid_t
pid
¶ thread’s process id
-
thread_flags.h::thread_flags_t
flags
¶ currently set flags
-
clist.h::clist_node_t
rq_entry
¶ run queue entry
-
void *
wait_data
¶ used by msg, mbox and thread flags
-
list.h::list_node_t
msg_waiters
¶ threads waiting for their message to be delivered to this thread (i.e.
all blocked sends)
-
cib_t
msg_queue
¶ index of this [thread’s message queue] (
thread.h::_thread::msg_array
), if any
-
char *
stack_start
¶ thread’s stack start address
-
const char *
name
¶ thread’s name
-
int
stack_size
¶ thread’s stack size
-
char *