thread.h

Go to the documentation of this file.

/*
 * Copyright (c) 2016, Wind River Systems, Inc.
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_KERNEL_THREAD_H_
#define ZEPHYR_INCLUDE_KERNEL_THREAD_H_
 
#ifdef CONFIG_DEMAND_PAGING_THREAD_STATS
#include <zephyr/kernel/mm/demand_paging.h>
#endif /* CONFIG_DEMAND_PAGING_THREAD_STATS */
 
#include <zephyr/kernel/stats.h>
#include <zephyr/arch/arch_interface.h>

 
#ifdef CONFIG_THREAD_MONITOR
struct __thread_entry {
        k_thread_entry_t pEntry;
        void *parameter1;
        void *parameter2;
        void *parameter3;
};
#endif /* CONFIG_THREAD_MONITOR */
 
struct k_thread;
 
/* can be used for creating 'dummy' threads, e.g. for pending on objects */
struct _thread_base {
 
        /* this thread's entry in a ready/wait queue */
        union {
                sys_dnode_t qnode_dlist;
                struct rbnode qnode_rb;
        };
 
        /* wait queue on which the thread is pended (needed only for
         * trees, not simple lists)
         */
        _wait_q_t *pended_on;
 
        /* user facing 'thread options'; values defined in include/zephyr/kernel.h */
        uint16_t user_options;
 
        /*
         * scheduler lock count and thread priority
         *
         * These two fields control the preemptibility of a thread.
         *
         * When the scheduler is locked, sched_locked is decremented, which
         * means that the scheduler is locked for values from 0xff to 0x01. A
         * thread is coop if its prio is negative, thus 0x80 to 0xff when
         * looked at the value as unsigned.
         *
         * By putting them end-to-end, this means that a thread is
         * non-preemptible if the bundled value is greater than or equal to
         * 0x0080.
         */
        union {
                struct {
#ifdef CONFIG_BIG_ENDIAN
                        uint8_t sched_locked;
                        int8_t prio;
#else /* Little Endian */
                        int8_t prio;
                        uint8_t sched_locked;
#endif /* CONFIG_BIG_ENDIAN */
                };
                uint16_t preempt;
        };
 
#ifdef CONFIG_SCHED_DEADLINE
        int prio_deadline;
#endif /* CONFIG_SCHED_DEADLINE */
 
#if defined(CONFIG_SCHED_SCALABLE) || defined(CONFIG_WAITQ_SCALABLE)
        uint32_t order_key;
#endif
 
        /* thread state */
        uint8_t thread_state;
 
#ifdef CONFIG_SMP
        /* True for the per-CPU idle threads */
        uint8_t is_idle;
 
        /* Identify CPU on which thread is (or was last) executing */
        uint8_t cpu;
 
        /* Recursive count of irq_lock() calls */
        uint8_t global_lock_count;
 
#endif /* CONFIG_SMP */
 
#ifdef CONFIG_SCHED_CPU_MASK
        /* "May run on" bits for each CPU */
        uint32_t cpu_mask;
#endif /* CONFIG_SCHED_CPU_MASK */
 
        /* data returned by APIs */
        void *swap_data;
 
#ifdef CONFIG_SYS_CLOCK_EXISTS
        /* this thread's entry in a timeout queue */
        struct _timeout timeout;
#endif /* CONFIG_SYS_CLOCK_EXISTS */
 
#ifdef CONFIG_TIMESLICE_PER_THREAD
        int32_t slice_ticks;
        k_thread_timeslice_fn_t slice_expired;
        void *slice_data;
#endif /* CONFIG_TIMESLICE_PER_THREAD */
 
#ifdef CONFIG_SCHED_THREAD_USAGE
        struct k_cycle_stats  usage;   /* Track thread usage statistics */
#endif /* CONFIG_SCHED_THREAD_USAGE */
};
 
typedef struct _thread_base _thread_base_t;
 
#if defined(CONFIG_THREAD_STACK_INFO)
 
#if defined(CONFIG_THREAD_RUNTIME_STACK_SAFETY)
struct _thread_stack_usage {
        size_t unused_threshold; /* Threshold below which to trigger hook */
};
#endif
 
/* Contains the stack information of a thread */
struct _thread_stack_info {
        /* Stack start - Represents the start address of the thread-writable
         * stack area.
         */
        uintptr_t start;
 
        /* Thread writable stack buffer size. Represents the size of the actual
         * buffer, starting from the 'start' member, that should be writable by
         * the thread. This comprises of the thread stack area, any area reserved
         * for local thread data storage, as well as any area left-out due to
         * random adjustments applied to the initial thread stack pointer during
         * thread initialization.
         */
        size_t size;
 
        /* Adjustment value to the size member, removing any storage
         * used for TLS or random stack base offsets. (start + size - delta)
         * is the initial stack pointer for a thread. May be 0.
         */
        size_t delta;
 
#if defined(CONFIG_THREAD_STACK_MEM_MAPPED)
        struct {
                k_thread_stack_t *addr;

                size_t sz;
        } mapped;
#endif /* CONFIG_THREAD_STACK_MEM_MAPPED */
 
#if defined(CONFIG_THREAD_RUNTIME_STACK_SAFETY)
        struct _thread_stack_usage usage;
#endif
};
 
typedef struct _thread_stack_info _thread_stack_info_t;
#endif /* CONFIG_THREAD_STACK_INFO */
 
#if defined(CONFIG_USERSPACE)
struct _mem_domain_info {
#ifdef CONFIG_MEM_DOMAIN_HAS_THREAD_LIST
        sys_dnode_t thread_mem_domain_node;
#endif /* CONFIG_MEM_DOMAIN_HAS_THREAD_LIST */
        struct k_mem_domain *mem_domain;
};
 
typedef struct _mem_domain_info _mem_domain_info_t;
#endif /* CONFIG_USERSPACE */
 
#ifdef CONFIG_THREAD_USERSPACE_LOCAL_DATA
struct _thread_userspace_local_data {
#if defined(CONFIG_ERRNO) && !defined(CONFIG_ERRNO_IN_TLS) && !defined(CONFIG_LIBC_ERRNO)
        int errno_var;
#endif /* CONFIG_ERRNO && !CONFIG_ERRNO_IN_TLS && !CONFIG_LIBC_ERRNO */
};
#endif /* CONFIG_THREAD_USERSPACE_LOCAL_DATA */
 
typedef struct k_thread_runtime_stats {
#ifdef CONFIG_SCHED_THREAD_USAGE
        /*
         * For CPU stats, execution_cycles is the sum of non-idle + idle cycles.
         * For thread stats, execution_cycles = total_cycles.
         */
        uint64_t execution_cycles;    /* total # of cycles (cpu: non-idle + idle) */
        uint64_t total_cycles;        /* total # of non-idle cycles */
#endif /* CONFIG_SCHED_THREAD_USAGE */
 
#ifdef CONFIG_SCHED_THREAD_USAGE_ANALYSIS
        /*
         * For threads, the following fields refer to the time spent executing
         * as bounded by when the thread was scheduled in and scheduled out.
         * For CPUs, the same fields refer to the time spent executing
         * non-idle threads as bounded by the idle thread(s).
         */
 
        uint64_t current_cycles;      /* current # of non-idle cycles */
        uint64_t peak_cycles;         /* peak # of non-idle cycles */
        uint64_t average_cycles;      /* average # of non-idle cycles */
#endif /* CONFIG_SCHED_THREAD_USAGE_ANALYSIS */
 
#ifdef CONFIG_SCHED_THREAD_USAGE_ALL
        /*
         * This field is always zero for individual threads. It only comes
         * into play when gathering statistics for the CPU. In that case it
         * represents the total number of cycles spent idling.
         */
 
        uint64_t idle_cycles;
#endif /* CONFIG_SCHED_THREAD_USAGE_ALL */
 
#if defined(__cplusplus) && !defined(CONFIG_SCHED_THREAD_USAGE) &&                                 \
        !defined(CONFIG_SCHED_THREAD_USAGE_ANALYSIS) && !defined(CONFIG_SCHED_THREAD_USAGE_ALL)
        /* An empty struct is not valid C, and compilers that accept it give
         * it size 0 while C++ gives 1. Keep a byte so both languages agree.
         */
        uint8_t dummy;
#endif
}  k_thread_runtime_stats_t;
 
struct z_poller {
        bool is_polling;
        uint8_t mode;
};

struct k_thread {
 
        struct _thread_base base;

        struct _callee_saved callee_saved;

        void *init_data;

        _wait_q_t join_queue;
 
#if defined(CONFIG_USERSPACE)
        void *futex_pointer;
#endif /* CONFIG_USERSPACE */
 
#if defined(CONFIG_POLL)
        struct z_poller poller;
#endif /* CONFIG_POLL */
 
#if defined(CONFIG_WAITQ_SCALABLE) && (defined(CONFIG_EVENTS) || defined(CONFIG_USERSPACE))
        struct k_thread *next_wake_link;
#endif /* CONFIG_WAITQ_SCALABLE && (CONFIG_EVENTS || CONFIG_USERSPACE) */
 
#if defined(CONFIG_EVENTS)
        uint32_t   events; /* dual purpose - wait on and then received */
        uint32_t   event_options;
#endif /* CONFIG_EVENTS */
 
#if defined(CONFIG_THREAD_MONITOR)
        struct __thread_entry entry;

        struct k_thread *next_thread;
#endif /* CONFIG_THREAD_MONITOR */
 
#if defined(CONFIG_THREAD_NAME)
        char name[CONFIG_THREAD_MAX_NAME_LEN];
#endif /* CONFIG_THREAD_NAME */
 
#ifdef CONFIG_THREAD_CUSTOM_DATA
        void *custom_data;
#endif /* CONFIG_THREAD_CUSTOM_DATA */
 
#ifdef CONFIG_THREAD_USERSPACE_LOCAL_DATA
        struct _thread_userspace_local_data *userspace_local_data;
#endif /* CONFIG_THREAD_USERSPACE_LOCAL_DATA */
 
#if defined(CONFIG_ERRNO) && !defined(CONFIG_ERRNO_IN_TLS) && !defined(CONFIG_LIBC_ERRNO)
#ifndef CONFIG_USERSPACE
        int errno_var;
#endif /* CONFIG_USERSPACE */
#endif /* CONFIG_ERRNO && !CONFIG_ERRNO_IN_TLS && !CONFIG_LIBC_ERRNO */
 
#if defined(CONFIG_THREAD_STACK_INFO)
        struct _thread_stack_info stack_info;
#endif /* CONFIG_THREAD_STACK_INFO */
 
#if defined(CONFIG_USERSPACE)
        struct _mem_domain_info mem_domain_info;

        k_thread_stack_t *stack_obj;

        void *syscall_frame;
#endif /* CONFIG_USERSPACE */
 
 
#if defined(CONFIG_USE_SWITCH)
        /* When using __switch() a few previously arch-specific items
         * become part of the core OS
         */

        int swap_retval;

        void *switch_handle;
#endif /* CONFIG_USE_SWITCH */
        struct k_heap *resource_pool;
 
#if defined(CONFIG_THREAD_LOCAL_STORAGE)
        /* Pointer to arch-specific TLS area */
        uintptr_t tls;
#endif /* CONFIG_THREAD_LOCAL_STORAGE */
 
#ifdef CONFIG_DEMAND_PAGING_THREAD_STATS
        struct k_mem_paging_stats_t paging_stats;
#endif /* CONFIG_DEMAND_PAGING_THREAD_STATS */
 
#ifdef CONFIG_OBJ_CORE_THREAD
        struct k_obj_core  obj_core;
#endif /* CONFIG_OBJ_CORE_THREAD */
 
#ifdef CONFIG_SMP
        _wait_q_t  halt_queue;
#endif /* CONFIG_SMP */
 
/*
 * True when the priority-inheritance fields below and in struct k_mutex
 * (kernel.h) are compiled in. Defined here rather than in kernel.h because
 * this header is included first.
 */
#define Z_MUTEX_PI_ENABLED (CONFIG_PRIORITY_CEILING < CONFIG_NUM_PREEMPT_PRIORITIES)
 
#if Z_MUTEX_PI_ENABLED
        sys_slist_t held_mutexes;

        struct k_mutex *mutex_pended_on;
        int8_t orig_prio;
#endif /* Z_MUTEX_PI_ENABLED */

        struct _thread_arch arch;
};
 
typedef struct k_thread _thread_t;
typedef struct k_thread *k_tid_t;
 
#endif /* ZEPHYR_INCLUDE_KERNEL_THREAD_H_ */