thread.h

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2014 Freie Universität Berlin
 * SPDX-License-Identifier: LGPL-2.1-only
 */
 
#pragma once

 
#include <stdbool.h>
 
#include "cib.h"
#include "clist.h"
#include "compiler_hints.h"
#include "msg.h"
#include "sched.h"
#include "thread_config.h"
 
#ifdef MODULE_CORE_THREAD_FLAGS
#include "thread_flags.h"
#endif
 
#include "thread_arch.h" /* IWYU pragma: export */
 
#ifdef __cplusplus
extern "C" {
#endif

#ifdef THREAD_API_INLINED
#define THREAD_MAYBE_INLINE static inline __attribute__((always_inline))
#else
#define THREAD_MAYBE_INLINE
#endif /* THREAD_API_INLINED */
 
#if defined(DEVELHELP) && !defined(CONFIG_THREAD_NAMES)
#define CONFIG_THREAD_NAMES
#endif

typedef void *(*thread_task_func_t)(void *arg);

struct _thread {
    char *sp;                       
    thread_status_t status;         
    uint8_t priority;               
 
    kernel_pid_t pid;               
 
#if defined(MODULE_CORE_THREAD_FLAGS) || defined(DOXYGEN)
    thread_flags_t flags;           
#endif
 
    clist_node_t rq_entry;          
 
#if defined(MODULE_CORE_MSG) || defined(MODULE_CORE_THREAD_FLAGS) \
    || defined(MODULE_CORE_MBOX) || defined(DOXYGEN)
    void *wait_data;                
#endif
#if defined(MODULE_CORE_MSG) || defined(DOXYGEN)
    list_node_t msg_waiters;        
    cib_t msg_queue;                
    msg_t *msg_array;               
#endif
#if defined(DEVELHELP) || IS_ACTIVE(SCHED_TEST_STACK) \
    || defined(MODULE_MPU_STACK_GUARD) || defined(DOXYGEN)
    char *stack_start;              
#endif
#if defined(CONFIG_THREAD_NAMES) || defined(DOXYGEN)
    const char *name;               
#endif
#if defined(DEVELHELP) || defined(DOXYGEN)
    int stack_size;                 
#endif
/* enable TLS only when Picolibc is compiled with TLS enabled */
#ifdef PICOLIBC_TLS
    void *tls;                      
#endif
};

#define THREAD_CREATE_SLEEPING          (1)

#define THREAD_AUTO_FREE                (2)

#define THREAD_CREATE_WOUT_YIELD        (4)

#define THREAD_CREATE_NO_STACKTEST      (8)

#define THREAD_CREATE_STACKTEST         (0)

ACCESS(write_only, 1, 2)
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);

static inline thread_t *thread_get_unchecked(kernel_pid_t pid)
{
    return (thread_t *)sched_threads[pid];
}

static inline thread_t *thread_get(kernel_pid_t pid)
{
    if (pid_is_valid(pid)) {
        return thread_get_unchecked(pid);
    }
    return NULL;
}

thread_status_t thread_getstatus(kernel_pid_t pid);

void thread_sleep(void);

#if defined(MODULE_CORE_THREAD) || DOXYGEN
void thread_yield(void);
#else
static inline void thread_yield(void)
{
    /* NO-OP */
}
#endif

THREAD_MAYBE_INLINE void thread_yield_higher(void);

void thread_zombify(void);

int thread_kill_zombie(kernel_pid_t pid);

int thread_wakeup(kernel_pid_t pid);

static inline kernel_pid_t thread_getpid(void)
{
    extern volatile kernel_pid_t sched_active_pid;
 
    return sched_active_pid;
}

static inline thread_t *thread_get_active(void)
{
    extern volatile thread_t *sched_active_thread;
 
    return (thread_t *)sched_active_thread;
}

ACCESS(write_only, 3, 4)
char *thread_stack_init(thread_task_func_t task_func, void *arg,
                        void *stack_start, int stack_size);

void thread_add_to_list(list_node_t *list, thread_t *thread);

#if defined(MODULE_CORE_THREAD) || DOXYGEN
const char *thread_getname(kernel_pid_t pid);
#else
static inline const char *thread_getname(kernel_pid_t pid)
{
    (void)pid;
    return "(none)";
}
#endif

ACCESS(read_only, 1, 2)
uintptr_t measure_stack_free_internal(const char *stack, size_t size);

int thread_isr_stack_usage(void);

void *thread_isr_stack_pointer(void);

void *thread_isr_stack_start(void);

void thread_stack_print(void);

void thread_print_stack(void);

static inline bool thread_has_msg_queue(const thread_t *thread)
{
    assume(thread != NULL);
#if defined(MODULE_CORE_MSG) || defined(DOXYGEN)
    return (thread->msg_array != NULL);
#else
    (void)thread;
    return 0;
#endif
}

static inline thread_status_t thread_get_status(const thread_t *thread)
{
    return thread->status;
}

static inline uint8_t thread_get_priority(const thread_t *thread)
{
    return thread->priority;
}

static inline bool thread_is_active(const thread_t *thread)
{
    return thread->status >= STATUS_ON_RUNQUEUE;
}

const char *thread_state_to_string(thread_status_t state);

static inline void *thread_get_stackstart(const thread_t *thread)
{
#if defined(DEVELHELP) || IS_ACTIVE(SCHED_TEST_STACK) \
    || defined(MODULE_MPU_STACK_GUARD)
    return thread->stack_start;
#else
    (void)thread;
    return NULL;
#endif
}

static inline void *thread_get_sp(const thread_t *thread)
{
    return thread->sp;
}

static inline size_t thread_get_stacksize(const thread_t *thread)
{
#if defined(DEVELHELP)
    return thread->stack_size;
#else
    (void)thread;
    return 0;
#endif
}

static inline kernel_pid_t thread_getpid_of(const thread_t *thread)
{
    return thread->pid;
}

static inline const char *thread_get_name(const thread_t *thread)
{
#if defined(CONFIG_THREAD_NAMES)
    return thread->name;
#else
    (void)thread;
    return NULL;
#endif
}

static inline uintptr_t thread_measure_stack_free(const thread_t *thread)
{
    /* explicitly casting void pointers is bad code style, but needed for C++
     * compatibility */
    return measure_stack_free_internal((const char *)thread_get_stackstart(thread),
                                       thread_get_stacksize(thread));
}
 
#ifdef __cplusplus
}
#endif