thread.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2014 Freie Universit├Ąt Berlin
3  *
4  * This file is subject to the terms and conditions of the GNU Lesser
5  * General Public License v2.1. See the file LICENSE in the top level
6  * directory for more details.
7  */
8 
119 #ifndef THREAD_H
120 #define THREAD_H
121 
122 #include "clist.h"
123 #include "cib.h"
124 #include "msg.h"
125 #include "cpu_conf.h"
126 #include "sched.h"
127 #include "thread_config.h"
128 
129 #ifdef MODULE_CORE_THREAD_FLAGS
130 #include "thread_flags.h"
131 #endif
132 
133 #include "thread_arch.h"
134 
135 #ifdef __cplusplus
136 extern "C" {
137 #endif
138 
145 #ifdef THREAD_API_INLINED
146 #define THREAD_MAYBE_INLINE static inline __attribute__((always_inline))
147 #else
148 #define THREAD_MAYBE_INLINE
149 #endif /* THREAD_API_INLINED */
150 
151 #if defined(DEVELHELP) && !defined(CONFIG_THREAD_NAMES)
158 #define CONFIG_THREAD_NAMES
159 #endif
160 
164 typedef void *(*thread_task_func_t)(void *arg);
165 
169 struct _thread {
170  char *sp;
172  uint8_t priority;
176 #if defined(MODULE_CORE_THREAD_FLAGS) || defined(DOXYGEN)
178 #endif
179 
182 #if defined(MODULE_CORE_MSG) || defined(MODULE_CORE_THREAD_FLAGS) \
183  || defined(MODULE_CORE_MBOX) || defined(DOXYGEN)
184  void *wait_data;
186 #endif
187 #if defined(MODULE_CORE_MSG) || defined(DOXYGEN)
195 #endif
196 #if defined(DEVELHELP) || IS_ACTIVE(SCHED_TEST_STACK) \
197  || defined(MODULE_MPU_STACK_GUARD) || defined(DOXYGEN)
198  char *stack_start;
199 #endif
200 #if defined(CONFIG_THREAD_NAMES) || defined(DOXYGEN)
201  const char *name;
202 #endif
203 #if defined(DEVELHELP) || defined(DOXYGEN)
205 #endif
206 /* enable TLS only when Picolibc is compiled with TLS enabled */
207 #ifdef PICOLIBC_TLS
208  void *tls;
209 #endif
210 #ifdef HAVE_THREAD_ARCH_T
211  thread_arch_t arch;
212 #endif
213 };
214 
222 #define THREAD_CREATE_SLEEPING (1)
223 
227 #define THREAD_AUTO_FREE (2)
228 
235 #define THREAD_CREATE_WOUT_YIELD (4)
236 
241 #define THREAD_CREATE_STACKTEST (8)
269  int stacksize,
270  uint8_t priority,
271  int flags,
272  thread_task_func_t task_func,
273  void *arg,
274  const char *name);
275 
283 {
284  return (thread_t *)sched_threads[pid];
285 }
286 
294 static inline thread_t *thread_get(kernel_pid_t pid)
295 {
296  if (pid_is_valid(pid)) {
297  return thread_get_unchecked(pid);
298  }
299  return NULL;
300 }
301 
311 
315 void thread_sleep(void);
316 
328 void thread_yield(void);
329 
343 
353 void thread_zombify(void);
354 
364 
374 
380 static inline kernel_pid_t thread_getpid(void)
381 {
382  extern volatile kernel_pid_t sched_active_pid;
383 
384  return sched_active_pid;
385 }
386 
394 static inline thread_t *thread_get_active(void)
395 {
396  extern volatile thread_t *sched_active_thread;
397 
398  return (thread_t *)sched_active_thread;
399 }
400 
411 char *thread_stack_init(thread_task_func_t task_func, void *arg,
412  void *stack_start, int stack_size);
413 
428 
439 const char *thread_getname(kernel_pid_t pid);
440 
441 #ifdef DEVELHELP
451 uintptr_t thread_measure_stack_free(const char *stack);
452 #endif /* DEVELHELP */
453 
458 
463 
468 
473 
478 
489 static inline int thread_has_msg_queue(const volatile struct _thread *thread)
490 {
491 #if defined(MODULE_CORE_MSG) || defined(DOXYGEN)
492  return (thread->msg_array != NULL);
493 #else
494  (void)thread;
495  return 0;
496 #endif
497 }
498 
505 static inline thread_status_t thread_get_status(const thread_t *thread)
506 {
507  return thread->status;
508 }
509 
516 static inline uint8_t thread_get_priority(const thread_t *thread)
517 {
518  return thread->priority;
519 }
520 
527 static inline bool thread_is_active(const thread_t *thread)
528 {
529  return thread->status >= STATUS_ON_RUNQUEUE;
530 }
531 
539 
546 static inline void *thread_get_stackstart(const thread_t *thread)
547 {
548 #if defined(DEVELHELP) || IS_ACTIVE(SCHED_TEST_STACK) \
549  || defined(MODULE_MPU_STACK_GUARD)
550  return thread->stack_start;
551 #else
552  (void)thread;
553  return NULL;
554 #endif
555 }
556 
565 static inline void *thread_get_sp(const thread_t *thread)
566 {
567  return thread->sp;
568 }
569 
576 static inline size_t thread_get_stacksize(const thread_t *thread)
577 {
578 #if defined(DEVELHELP)
579  return thread->stack_size;
580 #else
581  (void)thread;
582  return 0;
583 #endif
584 }
585 
594 static inline kernel_pid_t thread_getpid_of(const thread_t *thread)
595 {
596  return thread->pid;
597 }
598 
605 static inline const char *thread_get_name(const thread_t *thread)
606 {
607 #if defined(CONFIG_THREAD_NAMES)
608  return thread->name;
609 #else
610  (void)thread;
611  return NULL;
612 #endif
613 }
614 
615 #ifdef __cplusplus
616 }
617 #endif
618 
620 #endif /* THREAD_H */
Circular integer buffer interface.
Circular linked list.
static int pid_is_valid(kernel_pid_t pid)
Determine if the given pid is valid.
Definition: sched.h:143
int16_t kernel_pid_t
Unique process identifier.
Definition: sched.h:134
volatile thread_t * sched_threads[KERNEL_PID_LAST+1]
Thread table.
thread_status_t
Definition: sched.h:158
#define STATUS_ON_RUNQUEUE
to check if on run queue: st >= STATUS_ON_RUNQUEUE
Definition: sched.h:180
uint16_t thread_flags_t
Type definition of thread_flags_t.
Definition: thread_flags.h:106
void thread_stack_print(void)
Print the current stack to stdout.
thread_status_t thread_getstatus(kernel_pid_t pid)
Returns the status of a process.
static uint8_t thread_get_priority(const thread_t *thread)
Get a thread's priority.
Definition: thread.h:516
static thread_t * thread_get(kernel_pid_t pid)
Retrieve a thread control block by PID.
Definition: thread.h:294
static size_t thread_get_stacksize(const thread_t *thread)
Get size of a thread's stack.
Definition: thread.h:576
uintptr_t thread_measure_stack_free(const char *stack)
Measures the stack usage of a stack.
char * thread_stack_init(thread_task_func_t task_func, void *arg, void *stack_start, int stack_size)
Gets called upon thread creation to set CPU registers.
const char * thread_state_to_string(thread_status_t state)
Convert a thread state code to a human readable string.
static thread_t * thread_get_unchecked(kernel_pid_t pid)
Retrieve a thread control block by PID.
Definition: thread.h:282
static thread_t * thread_get_active(void)
Returns a pointer to the Thread Control Block of the currently running thread.
Definition: thread.h:394
void thread_add_to_list(list_node_t *list, thread_t *thread)
Add thread to list, sorted by priority (internal)
static const char * thread_get_name(const thread_t *thread)
Get name of thread.
Definition: thread.h:605
void thread_zombify(void)
Puts the current thread into zombie state.
void * thread_isr_stack_pointer(void)
Get the current ISR stack pointer.
static int thread_has_msg_queue(const volatile struct _thread *thread)
Checks if a thread has an initialized message queue.
Definition: thread.h:489
kernel_pid_t thread_create(char *stack, int stacksize, uint8_t priority, int flags, thread_task_func_t task_func, void *arg, const char *name)
Creates a new thread.
void * thread_isr_stack_start(void)
Get the start of the ISR stack.
THREAD_MAYBE_INLINE void thread_yield_higher(void)
Lets current thread yield in favor of a higher prioritized thread.
int thread_kill_zombie(kernel_pid_t pid)
Terminates zombie thread.
void thread_sleep(void)
Puts the current thread into sleep mode.
const char * thread_getname(kernel_pid_t pid)
Returns the name of a process.
void thread_yield(void)
Lets current thread yield.
int thread_wakeup(kernel_pid_t pid)
Wakes up a sleeping thread.
static void * thread_get_sp(const thread_t *thread)
Get stored Stack Pointer of thread.
Definition: thread.h:565
void *(* thread_task_func_t)(void *arg)
Prototype for a thread entry function.
Definition: thread.h:164
static kernel_pid_t thread_getpid(void)
Returns the process ID of the currently running thread.
Definition: thread.h:380
static bool thread_is_active(const thread_t *thread)
Returns if a thread is active (currently running or waiting to be scheduled)
Definition: thread.h:527
int thread_isr_stack_usage(void)
Get the number of bytes used on the ISR stack.
static thread_status_t thread_get_status(const thread_t *thread)
Get a thread's status.
Definition: thread.h:505
static void * thread_get_stackstart(const thread_t *thread)
Get start address (lowest) of a thread's stack.
Definition: thread.h:546
void thread_print_stack(void)
Prints human readable, ps-like thread information for debugging purposes.
#define THREAD_MAYBE_INLINE
Macro definition to inline some of the platform specific implementations.
Definition: thread.h:148
static kernel_pid_t thread_getpid_of(const thread_t *thread)
Get PID of thread.
Definition: thread.h:594
Scheduler API definition.
thread_t holds thread's context data.
Definition: thread.h:169
char * sp
thread's stack pointer
Definition: thread.h:170
char * stack_start
thread's stack start address
Definition: thread.h:198
cib_t msg_queue
index of this [thread's message queue] (thread_t::msg_array), if any
Definition: thread.h:191
thread_flags_t flags
currently set flags
Definition: thread.h:177
list_node_t msg_waiters
threads waiting for their message to be delivered to this thread (i.e.
Definition: thread.h:188
thread_status_t status
thread's status
Definition: thread.h:171
msg_t * msg_array
memory holding messages sent to this thread's message queue
Definition: thread.h:193
uint8_t priority
thread's priority
Definition: thread.h:172
int stack_size
thread's stack size
Definition: thread.h:204
const char * name
thread's name
Definition: thread.h:201
clist_node_t rq_entry
run queue entry
Definition: thread.h:180
void * wait_data
used by msg, mbox and thread flags
Definition: thread.h:184
kernel_pid_t pid
thread's process id
Definition: thread.h:174
circular integer buffer structure
Definition: cib.h:34
List node structure.
Definition: list.h:40
Describes a message object which can be sent between threads.
Definition: msg.h:185
Definitions for parsing and composition of DNS messages.
Thread configuration defines.
Thread Flags API.