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 #if defined(MODULE_CORE_THREAD) || DOXYGEN
329 void thread_yield(void);
330 #else
331 static inline void thread_yield(void)
332 {
333  /* NO-OP */
334 }
335 #endif
336 
350 
360 void thread_zombify(void);
361 
371 
381 
387 static inline kernel_pid_t thread_getpid(void)
388 {
389  extern volatile kernel_pid_t sched_active_pid;
390 
391  return sched_active_pid;
392 }
393 
401 static inline thread_t *thread_get_active(void)
402 {
403  extern volatile thread_t *sched_active_thread;
404 
405  return (thread_t *)sched_active_thread;
406 }
407 
418 char *thread_stack_init(thread_task_func_t task_func, void *arg,
419  void *stack_start, int stack_size);
420 
435 
446 #if defined(MODULE_CORE_THREAD) || DOXYGEN
447 const char *thread_getname(kernel_pid_t pid);
448 #else
449 static inline const char *thread_getname(kernel_pid_t pid)
450 {
451  (void)pid;
452  return "(none)";
453 }
454 #endif
455 
465 uintptr_t thread_measure_stack_free(const char *stack);
466 
471 
476 
481 
486 
491 
502 static inline int thread_has_msg_queue(const volatile struct _thread *thread)
503 {
504 #if defined(MODULE_CORE_MSG) || defined(DOXYGEN)
505  return (thread->msg_array != NULL);
506 #else
507  (void)thread;
508  return 0;
509 #endif
510 }
511 
518 static inline thread_status_t thread_get_status(const thread_t *thread)
519 {
520  return thread->status;
521 }
522 
529 static inline uint8_t thread_get_priority(const thread_t *thread)
530 {
531  return thread->priority;
532 }
533 
540 static inline bool thread_is_active(const thread_t *thread)
541 {
542  return thread->status >= STATUS_ON_RUNQUEUE;
543 }
544 
552 
559 static inline void *thread_get_stackstart(const thread_t *thread)
560 {
561 #if defined(DEVELHELP) || IS_ACTIVE(SCHED_TEST_STACK) \
562  || defined(MODULE_MPU_STACK_GUARD)
563  return thread->stack_start;
564 #else
565  (void)thread;
566  return NULL;
567 #endif
568 }
569 
578 static inline void *thread_get_sp(const thread_t *thread)
579 {
580  return thread->sp;
581 }
582 
589 static inline size_t thread_get_stacksize(const thread_t *thread)
590 {
591 #if defined(DEVELHELP)
592  return thread->stack_size;
593 #else
594  (void)thread;
595  return 0;
596 #endif
597 }
598 
607 static inline kernel_pid_t thread_getpid_of(const thread_t *thread)
608 {
609  return thread->pid;
610 }
611 
618 static inline const char *thread_get_name(const thread_t *thread)
619 {
620 #if defined(CONFIG_THREAD_NAMES)
621  return thread->name;
622 #else
623  (void)thread;
624  return NULL;
625 #endif
626 }
627 
628 #ifdef __cplusplus
629 }
630 #endif
631 
633 #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:148
int16_t kernel_pid_t
Unique process identifier.
Definition: sched.h:139
volatile thread_t * sched_threads[KERNEL_PID_LAST+1]
Thread table.
thread_status_t
Definition: sched.h:163
#define STATUS_ON_RUNQUEUE
to check if on run queue: st >= STATUS_ON_RUNQUEUE
Definition: sched.h:185
uint16_t thread_flags_t
Type definition of thread_flags_t.
Definition: thread_flags.h:122
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:529
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:589
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:401
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:618
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:502
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:578
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:387
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:540
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:518
static void * thread_get_stackstart(const thread_t *thread)
Get start address (lowest) of a thread's stack.
Definition: thread.h:559
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:607
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:196
Definitions for parsing and composition of DNS messages.
Thread configuration defines.
Thread Flags API.