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 
139 typedef void *(*thread_task_func_t)(void *arg);
140 
144 struct _thread {
145  char *sp;
147  uint8_t priority;
151 #if defined(MODULE_CORE_THREAD_FLAGS) || defined(DOXYGEN)
153 #endif
154 
157 #if defined(MODULE_CORE_MSG) || defined(MODULE_CORE_THREAD_FLAGS) \
158  || defined(MODULE_CORE_MBOX) || defined(DOXYGEN)
159  void *wait_data;
161 #endif
162 #if defined(MODULE_CORE_MSG) || defined(DOXYGEN)
170 #endif
171 #if defined(DEVELHELP) || defined(SCHED_TEST_STACK) \
172  || defined(MODULE_MPU_STACK_GUARD) || defined(DOXYGEN)
173  char *stack_start;
174 #endif
175 #if defined(DEVELHELP) || defined(DOXYGEN)
176  const char *name;
178 #endif
179 #ifdef HAVE_THREAD_ARCH_T
180  thread_arch_t arch;
181 #endif
182 };
183 
191 #ifndef THREAD_STACKSIZE_DEFAULT
192 #error THREAD_STACKSIZE_DEFAULT must be defined per CPU
193 #endif
194 #ifdef DOXYGEN
195 #define THREAD_STACKSIZE_DEFAULT
196 #endif
197 
205 #ifndef THREAD_STACKSIZE_IDLE
206 #error THREAD_STACKSIZE_IDLE must be defined per CPU
207 #endif
208 #ifdef DOXYGEN
209 #define THREAD_STACKSIZE_IDLE
210 #endif
211 
219 #ifndef THREAD_EXTRA_STACKSIZE_PRINTF
220 #error THREAD_EXTRA_STACKSIZE_PRINTF must be defined per CPU
221 #endif
222 #ifdef DOXYGEN
223 #define THREAD_EXTRA_STACKSIZE_PRINTF
224 #endif
225 
230 #ifndef THREAD_STACKSIZE_MAIN
231 #define THREAD_STACKSIZE_MAIN (THREAD_STACKSIZE_DEFAULT + THREAD_EXTRA_STACKSIZE_PRINTF)
232 #endif
233 
237 #ifndef THREAD_STACKSIZE_LARGE
238 #define THREAD_STACKSIZE_LARGE (THREAD_STACKSIZE_MEDIUM * 2)
239 #endif
240 
244 #ifndef THREAD_STACKSIZE_MEDIUM
245 #define THREAD_STACKSIZE_MEDIUM THREAD_STACKSIZE_DEFAULT
246 #endif
247 
251 #ifndef THREAD_STACKSIZE_SMALL
252 #define THREAD_STACKSIZE_SMALL (THREAD_STACKSIZE_MEDIUM / 2)
253 #endif
254 
258 #ifndef THREAD_STACKSIZE_TINY
259 #define THREAD_STACKSIZE_TINY (THREAD_STACKSIZE_MEDIUM / 4)
260 #endif
261 
265 #ifndef THREAD_STACKSIZE_MINIMUM
266 #define THREAD_STACKSIZE_MINIMUM (sizeof(thread_t))
267 #endif
268 
273 #define THREAD_PRIORITY_MIN (SCHED_PRIO_LEVELS-1)
274 
279 #define THREAD_PRIORITY_IDLE (THREAD_PRIORITY_MIN)
280 
285 #ifndef THREAD_PRIORITY_MAIN
286 #define THREAD_PRIORITY_MAIN (THREAD_PRIORITY_MIN - (SCHED_PRIO_LEVELS/2))
287 #endif
288 
296 #define THREAD_CREATE_SLEEPING (1)
297 
301 #define THREAD_AUTO_FREE (2)
302 
309 #define THREAD_CREATE_WOUT_YIELD (4)
310 
315 #define THREAD_CREATE_STACKTEST (8)
316 
342 kernel_pid_t thread_create(char *stack,
343  int stacksize,
344  uint8_t priority,
345  int flags,
346  thread_task_func_t task_func,
347  void *arg,
348  const char *name);
349 
358 
368 
372 void thread_sleep(void);
373 
385 void thread_yield(void);
386 
399 void thread_yield_higher(void);
400 
410 
416 static inline kernel_pid_t thread_getpid(void)
417 {
418  extern volatile kernel_pid_t sched_active_pid;
419  return sched_active_pid;
420 }
421 
432 char *thread_stack_init(thread_task_func_t task_func, void *arg, void *stack_start, int stack_size);
433 
447 void thread_add_to_list(list_node_t *list, thread_t *thread);
448 
459 const char *thread_getname(kernel_pid_t pid);
460 
461 #ifdef DEVELHELP
462 
471 uintptr_t thread_measure_stack_free(char *stack);
472 #endif /* DEVELHELP */
473 
477 int thread_isr_stack_usage(void);
478 
482 void *thread_isr_stack_pointer(void);
483 
487 void *thread_isr_stack_start(void);
488 
492 void thread_stack_print(void);
493 
497 void thread_print_stack(void);
498 
509 static inline int thread_has_msg_queue(const volatile struct _thread *thread)
510 {
511 #if defined(MODULE_CORE_MSG) || defined(DOXYGEN)
512  return (thread->msg_array != NULL);
513 #else
514  (void)thread;
515  return 0;
516 #endif
517 }
518 
519 #ifdef __cplusplus
520 }
521 #endif
522 
524 #endif /* THREAD_H */
clist_node_t rq_entry
run queue entry
Definition: thread.h:155
volatile kernel_pid_t sched_active_pid
Process ID of active thread.
list_node_t msg_waiters
threads waiting for their message to be delivered to this thread (i.e.
Definition: thread.h:163
static int thread_has_msg_queue(const volatile struct _thread *thread)
Checks if a thread has an initialized message queue.
Definition: thread.h:509
circular integer buffer structure
Definition: cib.h:34
kernel_pid_t pid
thread's process id
Definition: thread.h:149
thread_status_t status
thread's status
Definition: thread.h:146
uintptr_t thread_measure_stack_free(char *stack)
Measures the stack usage of a stack.
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)
volatile thread_t * thread_get(kernel_pid_t pid)
Retreive a thread control block by PID.
msg_t * msg_array
memory holding messages sent to this thread's message queue
Definition: thread.h:168
void thread_stack_print(void)
Print the current stack to stdout.
thread_t holds thread's context data.
Definition: thread.h:144
int16_t kernel_pid_t
Unique process identifier.
Definition: kernel_types.h:83
uint16_t thread_flags_t
Type definition of thread_flags_t.
Definition: thread_flags.h:111
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:152
Describes a message object which can be sent between threads.
Definition: msg.h:184
char * sp
thread's stack pointer
Definition: thread.h:145
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:176
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:139
uint8_t priority
thread's priority
Definition: thread.h:147
List node structure.
Definition: list.h:40
void * wait_data
used by msg, mbox and thread flags
Definition: thread.h:159
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:166
int stack_size
thread's stack size
Definition: thread.h:177
char * stack_start
thread's stack start address
Definition: thread.h:173
static kernel_pid_t thread_getpid(void)
Returns the process ID of the currently running thread.
Definition: thread.h:416
const char * thread_getname(kernel_pid_t pid)
Returns the name of a process.
thread_status_t
Definition: sched.h:103