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 
128 #ifdef MODULE_CORE_THREAD_FLAGS
129 #include "thread_flags.h"
130 #endif
131 
132 #ifdef __cplusplus
133 extern "C" {
134 #endif
135 
136 #if defined(DEVELHELP) && !defined(CONFIG_THREAD_NAMES)
137 
143 #define CONFIG_THREAD_NAMES
144 #endif
145 
149 typedef void *(*thread_task_func_t)(void *arg);
150 
154 struct _thread {
155  char *sp;
157  uint8_t priority;
161 #if defined(MODULE_CORE_THREAD_FLAGS) || defined(DOXYGEN)
163 #endif
164 
167 #if defined(MODULE_CORE_MSG) || defined(MODULE_CORE_THREAD_FLAGS) \
168  || defined(MODULE_CORE_MBOX) || defined(DOXYGEN)
169  void *wait_data;
171 #endif
172 #if defined(MODULE_CORE_MSG) || defined(DOXYGEN)
180 #endif
181 #if defined(DEVELHELP) || defined(SCHED_TEST_STACK) \
182  || defined(MODULE_MPU_STACK_GUARD) || defined(DOXYGEN)
183  char *stack_start;
184 #endif
185 #if defined(CONFIG_THREAD_NAMES) || defined(DOXYGEN)
186  const char *name;
187 #endif
188 #if defined(DEVELHELP) || defined(DOXYGEN)
190 #endif
191 /* enable TLS only when Picolibc is compiled with TLS enabled */
192 #ifdef PICOLIBC_TLS
193  void *tls;
194 #endif
195 #ifdef HAVE_THREAD_ARCH_T
196  thread_arch_t arch;
197 #endif
198 };
199 
207 #ifndef THREAD_STACKSIZE_DEFAULT
208 #error THREAD_STACKSIZE_DEFAULT must be defined per CPU
209 #endif
210 #ifdef DOXYGEN
211 #define THREAD_STACKSIZE_DEFAULT
212 #endif
213 
221 #ifndef THREAD_STACKSIZE_IDLE
222 #error THREAD_STACKSIZE_IDLE must be defined per CPU
223 #endif
224 #ifdef DOXYGEN
225 #define THREAD_STACKSIZE_IDLE
226 #endif
227 
235 #ifndef THREAD_EXTRA_STACKSIZE_PRINTF
236 #error THREAD_EXTRA_STACKSIZE_PRINTF must be defined per CPU
237 #endif
238 #ifdef DOXYGEN
239 #define THREAD_EXTRA_STACKSIZE_PRINTF
240 #endif
241 
246 #ifndef THREAD_STACKSIZE_MAIN
247 #define THREAD_STACKSIZE_MAIN (THREAD_STACKSIZE_DEFAULT + \
248  THREAD_EXTRA_STACKSIZE_PRINTF)
249 #endif
250 
254 #ifndef THREAD_STACKSIZE_LARGE
255 #define THREAD_STACKSIZE_LARGE (THREAD_STACKSIZE_MEDIUM * 2)
256 #endif
257 
261 #ifndef THREAD_STACKSIZE_MEDIUM
262 #define THREAD_STACKSIZE_MEDIUM THREAD_STACKSIZE_DEFAULT
263 #endif
264 
268 #ifndef THREAD_STACKSIZE_SMALL
269 #define THREAD_STACKSIZE_SMALL (THREAD_STACKSIZE_MEDIUM / 2)
270 #endif
271 
275 #ifndef THREAD_STACKSIZE_TINY
276 #define THREAD_STACKSIZE_TINY (THREAD_STACKSIZE_MEDIUM / 4)
277 #endif
278 
282 #ifndef THREAD_STACKSIZE_MINIMUM
283 #define THREAD_STACKSIZE_MINIMUM (sizeof(thread_t))
284 #endif
285 
290 #define THREAD_PRIORITY_MIN (SCHED_PRIO_LEVELS - 1)
291 
296 #define THREAD_PRIORITY_IDLE (THREAD_PRIORITY_MIN)
297 
302 #ifndef THREAD_PRIORITY_MAIN
303 #define THREAD_PRIORITY_MAIN (THREAD_PRIORITY_MIN - \
304  (SCHED_PRIO_LEVELS / 2))
305 #endif
306 
314 #define THREAD_CREATE_SLEEPING (1)
315 
319 #define THREAD_AUTO_FREE (2)
320 
327 #define THREAD_CREATE_WOUT_YIELD (4)
328 
333 #define THREAD_CREATE_STACKTEST (8)
334 
360 kernel_pid_t thread_create(char *stack,
361  int stacksize,
362  uint8_t priority,
363  int flags,
364  thread_task_func_t task_func,
365  void *arg,
366  const char *name);
367 
375 {
376  return (thread_t *)sched_threads[pid];
377 }
378 
387 {
388  if (pid_is_valid(pid)) {
389  return thread_get_unchecked(pid);
390  }
391  return NULL;
392 }
393 
403 
407 void thread_sleep(void);
408 
420 void thread_yield(void);
421 
434 void thread_yield_higher(void);
435 
445 void thread_zombify(void);
446 
456 
465 int thread_wakeup(kernel_pid_t pid);
466 
472 static inline kernel_pid_t thread_getpid(void)
473 {
474  extern volatile kernel_pid_t sched_active_pid;
475 
476  return sched_active_pid;
477 }
478 
486 static inline thread_t *thread_get_active(void)
487 {
488  extern volatile thread_t *sched_active_thread;
489 
490  return (thread_t *)sched_active_thread;
491 }
492 
503 char *thread_stack_init(thread_task_func_t task_func, void *arg,
504  void *stack_start, int stack_size);
505 
519 void thread_add_to_list(list_node_t *list, thread_t *thread);
520 
531 const char *thread_getname(kernel_pid_t pid);
532 
533 #ifdef DEVELHELP
534 
543 uintptr_t thread_measure_stack_free(const char *stack);
544 #endif /* DEVELHELP */
545 
549 int thread_isr_stack_usage(void);
550 
554 void *thread_isr_stack_pointer(void);
555 
559 void *thread_isr_stack_start(void);
560 
564 void thread_stack_print(void);
565 
569 void thread_print_stack(void);
570 
581 static inline int thread_has_msg_queue(const volatile struct _thread *thread)
582 {
583 #if defined(MODULE_CORE_MSG) || defined(DOXYGEN)
584  return (thread->msg_array != NULL);
585 #else
586  (void)thread;
587  return 0;
588 #endif
589 }
590 
591 #ifdef __cplusplus
592 }
593 #endif
594 
596 #endif /* THREAD_H */
clist_node_t rq_entry
run queue entry
Definition: thread.h:165
list_node_t msg_waiters
threads waiting for their message to be delivered to this thread (i.e.
Definition: thread.h:173
static int thread_has_msg_queue(const volatile struct _thread *thread)
Checks if a thread has an initialized message queue.
Definition: thread.h:581
uintptr_t thread_measure_stack_free(const char *stack)
Measures the stack usage of a stack.
circular integer buffer structure
Definition: cib.h:34
kernel_pid_t pid
thread's process id
Definition: thread.h:159
int thread_kill_zombie(kernel_pid_t pid)
Terminates zombie thread.
thread_status_t status
thread's status
Definition: thread.h:156
static int pid_is_valid(kernel_pid_t pid)
Determine if the given pid is valid.
Definition: kernel_types.h:92
int thread_isr_stack_usage(void)
Get the number of bytes used on the ISR stack.
void thread_add_to_list(list_node_t *list, thread_t *thread)
Add thread to list, sorted by priority (internal)
msg_t * msg_array
memory holding messages sent to this thread's message queue
Definition: thread.h:178
void thread_stack_print(void)
Print the current stack to stdout.
thread_t holds thread's context data.
Definition: thread.h:154
int16_t kernel_pid_t
Unique process identifier.
Definition: kernel_types.h:83
static thread_t * thread_get_unchecked(kernel_pid_t pid)
Retrieve a thread control block by PID.
Definition: thread.h:374
uint16_t thread_flags_t
Type definition of thread_flags_t.
Definition: thread_flags.h:107
static thread_t * thread_get_active(void)
Returns a pointer to the Thread Control Block of the currently running thread.
Definition: thread.h:486
void thread_zombify(void)
Puts the current thread into zombie state.
volatile thread_t * sched_threads[KERNEL_PID_LAST+1]
Thread table.
Scheduler API definition.
Messaging API for inter process communication.
Thread Flags API.
void * thread_isr_stack_start(void)
Get the start of the ISR stack.
thread_flags_t flags
currently set flags
Definition: thread.h:162
Describes a message object which can be sent between threads.
Definition: msg.h:184
char * sp
thread's stack pointer
Definition: thread.h:155
void thread_print_stack(void)
Prints human readable, ps-like thread information for debugging purposes.
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.
void * thread_isr_stack_pointer(void)
Get the current ISR stack pointer.
const char * name
thread's name
Definition: thread.h:186
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_sleep(void)
Puts the current thread into sleep mode.
void *(* thread_task_func_t)(void *arg)
Prototype for a thread entry function.
Definition: thread.h:149
uint8_t priority
thread's priority
Definition: thread.h:157
List node structure.
Definition: list.h:40
void * wait_data
used by msg, mbox and thread flags
Definition: thread.h:169
void thread_yield(void)
Lets current thread yield.
int thread_wakeup(kernel_pid_t pid)
Wakes up a sleeping thread.
Circular integer buffer interface.
thread_status_t thread_getstatus(kernel_pid_t pid)
Returns the status of a process.
Circular linked list.
void thread_yield_higher(void)
Lets current thread yield in favor of a higher prioritized thread.
cib_t msg_queue
index of this [thread's message queue] (thread_t::msg_array), if any
Definition: thread.h:176
static thread_t * thread_get(kernel_pid_t pid)
Retrieve a thread control block by PID.
Definition: thread.h:386
int stack_size
thread's stack size
Definition: thread.h:189
char * stack_start
thread's stack start address
Definition: thread.h:183
static kernel_pid_t thread_getpid(void)
Returns the process ID of the currently running thread.
Definition: thread.h:472
const char * thread_getname(kernel_pid_t pid)
Returns the name of a process.
thread_status_t
Definition: sched.h:104