1 /* 2 * Copyright (c) 2016, Wind River Systems, Inc. 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef ZEPHYR_INCLUDE_KERNEL_THREAD_H_ 8 #define ZEPHYR_INCLUDE_KERNEL_THREAD_H_ 9 10 #ifdef CONFIG_DEMAND_PAGING_THREAD_STATS 11 #include <zephyr/kernel/mm/demand_paging.h> 12 #endif 13 14 #include <zephyr/kernel/stats.h> 15 #include <zephyr/sys/arch_interface.h> 16 17 /** 18 * @typedef k_thread_entry_t 19 * @brief Thread entry point function type. 20 * 21 * A thread's entry point function is invoked when the thread starts executing. 22 * Up to 3 argument values can be passed to the function. 23 * 24 * The thread terminates execution permanently if the entry point function 25 * returns. The thread is responsible for releasing any shared resources 26 * it may own (such as mutexes and dynamically allocated memory), prior to 27 * returning. 28 * 29 * @param p1 First argument. 30 * @param p2 Second argument. 31 * @param p3 Third argument. 32 */ 33 34 #ifdef CONFIG_THREAD_MONITOR 35 struct __thread_entry { 36 k_thread_entry_t pEntry; 37 void *parameter1; 38 void *parameter2; 39 void *parameter3; 40 }; 41 #endif 42 43 struct k_thread; 44 45 /* 46 * This _pipe_desc structure is used by the pipes kernel module when 47 * CONFIG_PIPES has been selected. 48 */ 49 50 struct _pipe_desc { 51 sys_dnode_t node; 52 unsigned char *buffer; /* Position in src/dest buffer */ 53 size_t bytes_to_xfer; /* # bytes left to transfer */ 54 struct k_thread *thread; /* Back pointer to pended thread */ 55 }; 56 57 /* can be used for creating 'dummy' threads, e.g. for pending on objects */ 58 struct _thread_base { 59 60 /* this thread's entry in a ready/wait queue */ 61 union { 62 sys_dnode_t qnode_dlist; 63 struct rbnode qnode_rb; 64 }; 65 66 /* wait queue on which the thread is pended (needed only for 67 * trees, not dumb lists) 68 */ 69 _wait_q_t *pended_on; 70 71 /* user facing 'thread options'; values defined in include/kernel.h */ 72 uint8_t user_options; 73 74 /* thread state */ 75 uint8_t thread_state; 76 77 /* 78 * scheduler lock count and thread priority 79 * 80 * These two fields control the preemptibility of a thread. 81 * 82 * When the scheduler is locked, sched_locked is decremented, which 83 * means that the scheduler is locked for values from 0xff to 0x01. A 84 * thread is coop if its prio is negative, thus 0x80 to 0xff when 85 * looked at the value as unsigned. 86 * 87 * By putting them end-to-end, this means that a thread is 88 * non-preemptible if the bundled value is greater than or equal to 89 * 0x0080. 90 */ 91 union { 92 struct { 93 #ifdef CONFIG_BIG_ENDIAN 94 uint8_t sched_locked; 95 int8_t prio; 96 #else /* Little Endian */ 97 int8_t prio; 98 uint8_t sched_locked; 99 #endif 100 }; 101 uint16_t preempt; 102 }; 103 104 #ifdef CONFIG_SCHED_DEADLINE 105 int prio_deadline; 106 #endif 107 108 uint32_t order_key; 109 110 #ifdef CONFIG_SMP 111 /* True for the per-CPU idle threads */ 112 uint8_t is_idle; 113 114 /* CPU index on which thread was last run */ 115 uint8_t cpu; 116 117 /* Recursive count of irq_lock() calls */ 118 uint8_t global_lock_count; 119 120 #endif 121 122 #ifdef CONFIG_SCHED_CPU_MASK 123 /* "May run on" bits for each CPU */ 124 #if CONFIG_MP_MAX_NUM_CPUS <= 8 125 uint8_t cpu_mask; 126 #else 127 uint16_t cpu_mask; 128 #endif 129 #endif /* CONFIG_SCHED_CPU_MASK */ 130 131 /* data returned by APIs */ 132 void *swap_data; 133 134 #ifdef CONFIG_SYS_CLOCK_EXISTS 135 /* this thread's entry in a timeout queue */ 136 struct _timeout timeout; 137 #endif 138 139 #ifdef CONFIG_TIMESLICE_PER_THREAD 140 int32_t slice_ticks; 141 k_thread_timeslice_fn_t slice_expired; 142 void *slice_data; 143 #endif 144 145 #ifdef CONFIG_SCHED_THREAD_USAGE 146 struct k_cycle_stats usage; /* Track thread usage statistics */ 147 #endif 148 }; 149 150 typedef struct _thread_base _thread_base_t; 151 152 #if defined(CONFIG_THREAD_STACK_INFO) 153 /* Contains the stack information of a thread */ 154 struct _thread_stack_info { 155 /* Stack start - Represents the start address of the thread-writable 156 * stack area. 157 */ 158 uintptr_t start; 159 160 /* Thread writable stack buffer size. Represents the size of the actual 161 * buffer, starting from the 'start' member, that should be writable by 162 * the thread. This comprises of the thread stack area, any area reserved 163 * for local thread data storage, as well as any area left-out due to 164 * random adjustments applied to the initial thread stack pointer during 165 * thread initialization. 166 */ 167 size_t size; 168 169 /* Adjustment value to the size member, removing any storage 170 * used for TLS or random stack base offsets. (start + size - delta) 171 * is the initial stack pointer for a thread. May be 0. 172 */ 173 size_t delta; 174 }; 175 176 typedef struct _thread_stack_info _thread_stack_info_t; 177 #endif /* CONFIG_THREAD_STACK_INFO */ 178 179 #if defined(CONFIG_USERSPACE) 180 struct _mem_domain_info { 181 /** memory domain queue node */ 182 sys_dnode_t mem_domain_q_node; 183 /** memory domain of the thread */ 184 struct k_mem_domain *mem_domain; 185 }; 186 187 #endif /* CONFIG_USERSPACE */ 188 189 #ifdef CONFIG_THREAD_USERSPACE_LOCAL_DATA 190 struct _thread_userspace_local_data { 191 #if defined(CONFIG_ERRNO) && !defined(CONFIG_ERRNO_IN_TLS) && !defined(CONFIG_LIBC_ERRNO) 192 int errno_var; 193 #endif 194 }; 195 #endif 196 197 typedef struct k_thread_runtime_stats { 198 #ifdef CONFIG_SCHED_THREAD_USAGE 199 uint64_t execution_cycles; 200 uint64_t total_cycles; /* total # of non-idle cycles */ 201 /* 202 * In the context of thread statistics, [execution_cycles] is the same 203 * as the total # of non-idle cycles. In the context of CPU statistics, 204 * it refers to the sum of non-idle + idle cycles. 205 */ 206 #endif 207 208 #ifdef CONFIG_SCHED_THREAD_USAGE_ANALYSIS 209 /* 210 * For threads, the following fields refer to the time spent executing 211 * as bounded by when the thread was scheduled in and scheduled out. 212 * For CPUs, the same fields refer to the time spent executing 213 * non-idle threads as bounded by the idle thread(s). 214 */ 215 216 uint64_t current_cycles; /* current # of non-idle cycles */ 217 uint64_t peak_cycles; /* peak # of non-idle cycles */ 218 uint64_t average_cycles; /* average # of non-idle cycles */ 219 #endif 220 221 #ifdef CONFIG_SCHED_THREAD_USAGE_ALL 222 /* 223 * This field is always zero for individual threads. It only comes 224 * into play when gathering statistics for the CPU. In that case it 225 * represents the total number of cycles spent idling. 226 */ 227 228 uint64_t idle_cycles; 229 #endif 230 231 #if defined(__cplusplus) && !defined(CONFIG_SCHED_THREAD_USAGE) && \ 232 !defined(CONFIG_SCHED_THREAD_USAGE_ANALYSIS) && !defined(CONFIG_SCHED_THREAD_USAGE_ALL) 233 /* If none of the above Kconfig values are defined, this struct will have a size 0 in C 234 * which is not allowed in C++ (it'll have a size 1). To prevent this, we add a 1 byte dummy 235 * variable when the struct would otherwise be empty. 236 */ 237 uint8_t dummy; 238 #endif 239 } k_thread_runtime_stats_t; 240 241 struct z_poller { 242 bool is_polling; 243 uint8_t mode; 244 }; 245 246 /** 247 * @ingroup thread_apis 248 * Thread Structure 249 */ 250 struct k_thread { 251 252 struct _thread_base base; 253 254 /** defined by the architecture, but all archs need these */ 255 struct _callee_saved callee_saved; 256 257 /** static thread init data */ 258 void *init_data; 259 260 /** threads waiting in k_thread_join() */ 261 _wait_q_t join_queue; 262 263 #if defined(CONFIG_POLL) 264 struct z_poller poller; 265 #endif 266 267 #if defined(CONFIG_EVENTS) 268 struct k_thread *next_event_link; 269 270 uint32_t events; 271 uint32_t event_options; 272 273 /** true if timeout should not wake the thread */ 274 bool no_wake_on_timeout; 275 #endif 276 277 #if defined(CONFIG_THREAD_MONITOR) 278 /** thread entry and parameters description */ 279 struct __thread_entry entry; 280 281 /** next item in list of all threads */ 282 struct k_thread *next_thread; 283 #endif 284 285 #if defined(CONFIG_THREAD_NAME) 286 /** Thread name */ 287 char name[CONFIG_THREAD_MAX_NAME_LEN]; 288 #endif 289 290 #ifdef CONFIG_THREAD_CUSTOM_DATA 291 /** crude thread-local storage */ 292 void *custom_data; 293 #endif 294 295 #ifdef CONFIG_THREAD_USERSPACE_LOCAL_DATA 296 struct _thread_userspace_local_data *userspace_local_data; 297 #endif 298 299 #if defined(CONFIG_ERRNO) && !defined(CONFIG_ERRNO_IN_TLS) && !defined(CONFIG_LIBC_ERRNO) 300 #ifndef CONFIG_USERSPACE 301 /** per-thread errno variable */ 302 int errno_var; 303 #endif 304 #endif 305 306 #if defined(CONFIG_THREAD_STACK_INFO) 307 /** Stack Info */ 308 struct _thread_stack_info stack_info; 309 #endif /* CONFIG_THREAD_STACK_INFO */ 310 311 #if defined(CONFIG_USERSPACE) 312 /** memory domain info of the thread */ 313 struct _mem_domain_info mem_domain_info; 314 /** Base address of thread stack */ 315 k_thread_stack_t *stack_obj; 316 /** current syscall frame pointer */ 317 void *syscall_frame; 318 #endif /* CONFIG_USERSPACE */ 319 320 321 #if defined(CONFIG_USE_SWITCH) 322 /* When using __switch() a few previously arch-specific items 323 * become part of the core OS 324 */ 325 326 /** z_swap() return value */ 327 int swap_retval; 328 329 /** Context handle returned via arch_switch() */ 330 void *switch_handle; 331 #endif 332 /** resource pool */ 333 struct k_heap *resource_pool; 334 335 #if defined(CONFIG_THREAD_LOCAL_STORAGE) 336 /* Pointer to arch-specific TLS area */ 337 uintptr_t tls; 338 #endif /* CONFIG_THREAD_LOCAL_STORAGE */ 339 340 #ifdef CONFIG_DEMAND_PAGING_THREAD_STATS 341 /** Paging statistics */ 342 struct k_mem_paging_stats_t paging_stats; 343 #endif 344 345 #ifdef CONFIG_PIPES 346 /** Pipe descriptor used with blocking k_pipe operations */ 347 struct _pipe_desc pipe_desc; 348 #endif 349 350 #ifdef CONFIG_OBJ_CORE_THREAD 351 struct k_obj_core obj_core; 352 #endif 353 354 #ifdef CONFIG_SMP 355 /** threads waiting in k_thread_suspend() */ 356 _wait_q_t halt_queue; 357 #endif 358 359 /** arch-specifics: must always be at the end */ 360 struct _thread_arch arch; 361 }; 362 363 typedef struct k_thread _thread_t; 364 typedef struct k_thread *k_tid_t; 365 366 #endif 367
