RTEMS 6.1-rc2
Loading...
Searching...
No Matches
thread.h
Go to the documentation of this file.
1/* SPDX-License-Identifier: BSD-2-Clause */
2
13/*
14 * COPYRIGHT (c) 1989-2014.
15 * On-Line Applications Research Corporation (OAR).
16 *
17 * Copyright (C) 2014, 2016 embedded brains GmbH & Co. KG
18 *
19 * Redistribution and use in source and binary forms, with or without
20 * modification, are permitted provided that the following conditions
21 * are met:
22 * 1. Redistributions of source code must retain the above copyright
23 * notice, this list of conditions and the following disclaimer.
24 * 2. Redistributions in binary form must reproduce the above copyright
25 * notice, this list of conditions and the following disclaimer in the
26 * documentation and/or other materials provided with the distribution.
27 *
28 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
29 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
30 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
31 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
32 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
33 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
34 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
35 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
36 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
37 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
38 * POSSIBILITY OF SUCH DAMAGE.
39 */
40
41#ifndef _RTEMS_SCORE_THREAD_H
42#define _RTEMS_SCORE_THREAD_H
43
44#include <rtems/score/atomic.h>
45#include <rtems/score/context.h>
46#if defined(RTEMS_MULTIPROCESSING)
47#include <rtems/score/mppkt.h>
48#endif
50#include <rtems/score/isrlock.h>
54#include <rtems/score/stack.h>
55#include <rtems/score/states.h>
56#include <rtems/score/threadq.h>
59
60#if defined(RTEMS_SMP)
62#endif
63
64struct rtems_user_env_t;
65
66struct _pthread_cleanup_context;
67
68struct Per_CPU_Control;
69
71
73
74#ifdef __cplusplus
75extern "C" {
76#endif
77
98#if defined(RTEMS_DEBUG)
99#define RTEMS_SCORE_THREAD_ENABLE_RESOURCE_COUNT
100#endif
101
112
116typedef struct {
117 void *( *entry )( uintptr_t argument );
119
123typedef struct {
124 void ( *entry )( Thread_Entry_numeric_type argument );
127
132typedef struct {
133 void *( *entry )( void *argument );
134 void *argument;
136
140typedef struct {
148 void ( *adaptor )( Thread_Control *executing );
149
154 union {
156 Thread_Entry_numeric Numeric;
157 Thread_Entry_pointer Pointer;
158 } Kinds;
160
165typedef struct {
170 void ( *at_tick )( Thread_Control * );
171
176 void ( *at_context_switch )( Thread_Control * );
177
182 void ( *initialize )( Thread_Control * );
184
188typedef struct {
195
201 uint32_t available;
203
208typedef struct {
211 /*-------------- initial execution modes ----------------- */
216
222
224 uint32_t isr_level;
230 void ( *stack_free )( void * );
233 #if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE )
236 #endif
238 void *tls_area;
240
241#if defined(RTEMS_SMP)
245typedef enum {
251 THREAD_SCHEDULER_BLOCKED,
252
260 THREAD_SCHEDULER_SCHEDULED,
261
267 THREAD_SCHEDULER_READY
268} Thread_Scheduler_state;
269#endif
270
274typedef struct {
275#if defined(RTEMS_SMP)
279 ISR_lock_Control Lock;
280
284 Thread_Scheduler_state state;
285
289 const struct _Scheduler_Control *home_scheduler;
290
294 const struct _Scheduler_Control *pinned_scheduler;
295
299 struct Per_CPU_Control *cpu;
300
310 Chain_Control Wait_nodes;
311
325 Chain_Control Scheduler_nodes;
326
337 struct Per_CPU_Control *ask_for_help_cpu;
338
347 Chain_Node Help_node;
348
354 size_t helping_nodes;
355
361 Scheduler_Node *requests;
362
383 int pin_level;
384
388 Processor_mask Affinity;
389#endif
390
398
409typedef union {
410 void *mutable_object;
411 const void *immutable_object;
413
428typedef unsigned int Thread_Wait_flags;
429
436typedef struct {
437#if defined(RTEMS_MULTIPROCESSING)
438 /*
439 * @brief This field is the identifier of the remote object this thread is
440 * waiting upon.
441 */
442 Objects_Id remote_id;
443#endif
445 uint32_t count;
452 uint32_t option;
458 uint32_t return_code;
459
464#if defined(RTEMS_SMP)
465 Atomic_Uint flags;
466#else
468#endif
469
470#if defined(RTEMS_SMP)
488 struct {
492 ISR_lock_Control Default;
493
498 Chain_Control Pending_requests;
499
509 Thread_queue_Gate Tranquilizer;
510 } Lock;
511
516 Thread_queue_Link Link;
517#endif
518
528
537
538 Thread_queue_Heads *spare_heads;
540
544typedef struct {
545 ISR_LOCK_MEMBER( Lock )
546 Watchdog_Header *header;
547 Watchdog_Control Watchdog;
549
557typedef struct {
560
565
568
573
574#if defined(RTEMS_SCORE_THREAD_ENABLE_RESOURCE_COUNT)
576 uint32_t resource_count;
577#endif
578
583
588#if defined(RTEMS_MULTIPROCESSING)
590 MP_packet_Prefix *receive_packet;
591 /****************** end of common block ********************/
592
596 Thread_queue_MP_callout thread_queue_callout;
597
601 RBTree_Node Active;
602
607 Scheduler_Node Scheduler_node;
608
616 Thread_queue_Heads Thread_queue_heads[ RTEMS_ZERO_LENGTH_ARRAY ];
617#endif
619
627typedef enum {
633
635#define THREAD_API_FIRST THREAD_API_RTEMS
636
638#define THREAD_API_LAST THREAD_API_POSIX
639
640typedef struct Thread_Action Thread_Action;
641
661typedef void ( *Thread_Action_handler )(
662 Thread_Control *the_thread,
663 Thread_Action *action,
664 ISR_lock_Context *lock_context
665);
666
682 Chain_Node Node;
683 Thread_Action_handler handler;
684};
685
689typedef struct {
693 RBTree_Control Key_value_pairs;
694
695#if defined(RTEMS_SMP)
699 ISR_lock_Control Lock;
700#endif
702
708typedef struct {
709 Chain_Control Chain;
711
722typedef unsigned int Thread_Life_state;
723
731#define THREAD_LIFE_PROTECTED 0x1U
732
739#define THREAD_LIFE_RESTARTING 0x2U
740
747#define THREAD_LIFE_TERMINATING 0x4U
748
756#define THREAD_LIFE_CHANGE_DEFERRED 0x8U
757
765#define THREAD_LIFE_DETACHED 0x10U
766
770typedef struct {
776
781
786
797
798typedef struct {
799 uint32_t flags;
800 void * control;
802
815
832
835
840
841#if defined(RTEMS_SCORE_THREAD_ENABLE_RESOURCE_COUNT)
843 uint32_t resource_count;
844#endif
845
850
855#if defined(RTEMS_MULTIPROCESSING)
857 MP_packet_Prefix *receive_packet;
858#endif
859 /*================= end of common block =================*/
860
869
870#if defined(RTEMS_SMP) && defined(RTEMS_PROFILING)
879 SMP_lock_Stats Potpourri_stats;
880#endif
881
884#if defined(RTEMS_MULTIPROCESSING)
886 bool is_global;
887#endif
891 bool is_fp;
892
898
904
910
917
922
923 Thread_Action_control Post_switch_actions;
924
925#if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE )
930#endif
931
932#ifndef _REENT_THREAD_LOCAL
934 struct _reent *libc_reent;
935#endif
936
939
944
951
953
958
962 struct _pthread_cleanup_context *last_cleanup_context;
963
968
975};
976
977typedef void (*rtems_per_thread_routine)( Thread_Control * );
978
985 rtems_per_thread_routine routine
987
991typedef struct {
998
1005
1020
1028extern const size_t _Thread_Control_add_on_count;
1029
1035extern const size_t _Thread_Initial_thread_count;
1036
1044#define THREAD_DEFAULT_MAXIMUM_NAME_SIZE 16
1045
1052extern const size_t _Thread_Maximum_name_size;
1053
1062extern const size_t _Thread_Maximum_TLS_size;
1063
1071
1078#if defined(RTEMS_SMP)
1080#else
1082#endif
1083
1089#if defined(RTEMS_SMP)
1090extern const size_t _Thread_queue_Heads_size;
1091#else
1092#define _Thread_queue_Heads_size sizeof(Thread_queue_Heads)
1093#endif
1094
1098typedef struct {
1103
1107 union {
1114
1121 } Thread_queue_heads;
1123
1128
1129#define THREAD_INFORMATION_DEFINE_ZERO( name, api, cls ) \
1130Thread_Information name##_Information = { \
1131 { \
1132 _Objects_Build_id( api, cls, 1, 0 ), \
1133 NULL, \
1134 _Objects_Allocate_none, \
1135 NULL, \
1136 0, \
1137 0, \
1138 0, \
1139 0, \
1140 CHAIN_INITIALIZER_EMPTY( name##_Information.Objects.Inactive ), \
1141 NULL, \
1142 NULL, \
1143 NULL \
1144 OBJECTS_INFORMATION_MP( name##_Information.Objects, NULL ), \
1145 }, { \
1146 NULL \
1147 } \
1148}
1149
1157
1158#define THREAD_INFORMATION_DEFINE( name, api, cls, max ) \
1159static Objects_Control * \
1160name##_Local_table[ _Objects_Maximum_per_allocation( max ) ]; \
1161static RTEMS_SECTION( ".noinit.rtems.content.objects." #name ) \
1162Thread_Configured_control \
1163name##_Objects[ _Objects_Maximum_per_allocation( max ) ]; \
1164static RTEMS_SECTION( ".noinit.rtems.content.objects." #name ) \
1165Thread_queue_Configured_heads \
1166name##_Heads[ _Objects_Maximum_per_allocation( max ) ]; \
1167Thread_Information name##_Information = { \
1168 { \
1169 _Objects_Build_id( api, cls, 1, _Objects_Maximum_per_allocation( max ) ), \
1170 name##_Local_table, \
1171 _Objects_Is_unlimited( max ) ? \
1172 _Thread_Allocate_unlimited : _Objects_Allocate_static, \
1173 _Objects_Is_unlimited( max ) ? \
1174 _Objects_Free_unlimited : _Objects_Free_static, \
1175 0, \
1176 _Objects_Is_unlimited( max ) ? _Objects_Maximum_per_allocation( max ) : 0, \
1177 sizeof( Thread_Configured_control ), \
1178 OBJECTS_NO_STRING_NAME, \
1179 CHAIN_INITIALIZER_EMPTY( name##_Information.Objects.Inactive ), \
1180 NULL, \
1181 NULL, \
1182 &name##_Objects[ 0 ].Control.Object \
1183 OBJECTS_INFORMATION_MP( name##_Information.Objects, NULL ) \
1184 }, { \
1185 &name##_Heads[ 0 ] \
1186 } \
1187}
1188
1189#if defined(RTEMS_MULTIPROCESSING)
1196typedef struct Thread_Configured_proxy_control Thread_Configured_proxy_control;
1197
1203extern Thread_Configured_proxy_control * const _Thread_MP_Proxies;
1204#endif
1205
1208#ifdef __cplusplus
1209}
1210#endif
1211
1212#endif
1213/* end of include file */
This header file provides the interfaces of the Context Handler.
This header file provides interfaces of the Stack Handler which are used by the implementation and th...
This header file provides interfaces of the Watchdog Handler which are used by the implementation and...
This header file provides interfaces of the Freechain Handler which are used by the implementation an...
#define RTEMS_DEPRECATED
Instructs the compiler in a declaration to issue a warning whenever a variable, function,...
Definition: basedefs.h:334
#define RTEMS_ZERO_LENGTH_ARRAY
This constant represents the element count of a zero-length array.
Definition: basedefs.h:1032
uintptr_t CPU_Uint32ptr
Definition: cpu.h:557
#define ISR_LOCK_MEMBER(_designator)
Defines an ISR lock member.
Definition: isrlock.h:105
uint32_t Objects_Id
Definition: object.h:101
uint64_t Priority_Control
The thread priority control.
Definition: priority.h:91
uint32_t States_Control
Definition: states.h:65
const size_t _Thread_Initial_thread_count
Count of configured threads.
Thread_Information _Thread_Information
The internal thread objects information.
const size_t _Thread_Maximum_TLS_size
If this constant is greater than zero, then it defines the maximum thread-local storage size,...
#define _Thread_queue_Heads_size
Size of the thread queue heads of a particular application.
Definition: thread.h:1092
void rtems_iterate_over_all_threads(rtems_per_thread_routine routine) RTEMS_DEPRECATED
Deprecated, use rtems_task_iterate() instead.
Definition: iterateoverthreads.c:57
const Thread_Control_add_on _Thread_Control_add_ons[]
Thread control add-ons.
unsigned int Thread_Life_state
This type represents the thread life state.
Definition: thread.h:722
const size_t _Thread_Control_add_on_count
Thread control add-on count.
unsigned int Thread_Wait_flags
This type is able to contain several flags used to control the wait class and state of a thread.
Definition: thread.h:428
void(* Thread_Action_handler)(Thread_Control *the_thread, Thread_Action *action, ISR_lock_Context *lock_context)
This type defines the prototype of thread action handlers.
Definition: thread.h:661
CPU_Uint32ptr Thread_Entry_numeric_type
Type of the numeric argument of a thread entry function with at least one numeric argument.
Definition: thread.h:111
Objects_Control * _Thread_Allocate_unlimited(Objects_Information *information)
Return an inactive thread object or NULL.
Definition: threadallocateunlimited.c:70
Thread_queue_Heads Thread_queue_Configured_heads
The configured thread queue heads.
Definition: thread.h:1081
struct Thread_Configured_control Thread_Configured_control
The configured thread control block.
Definition: thread.h:1070
const size_t _Thread_Maximum_name_size
Maximum size of a thread name in characters (including the terminating '\0' character).
#define THREAD_API_LAST
Definition: thread.h:638
Thread_APIs
Definition: thread.h:627
@ THREAD_API_POSIX
Definition: thread.h:631
@ THREAD_API_RTEMS
Definition: thread.h:629
int64_t Timestamp_Control
Definition: timestamp.h:76
This header file provides the interfaces of the Atomic Operations.
This header file provides the interfaces of the ISR Locks.
This header file provides the interfaces of the Multiprocessing (MP) Packet Handler.
This header file provides data structures used by the implementation and the Application Configuratio...
This header file provides the interfaces of the Processor Mask.
This header file provides interfaces of the Priority Handler which are used by the implementation and...
This header file provides interfaces of the Scheduler Handler related to scheduler nodes which are us...
This header file provides interfaces of the Thread States which are used by the implementation and th...
This structure represents a chain node.
Definition: chain.h:78
SPARC basic context.
Definition: cpu.h:213
Thread register context.
Definition: cpu.h:169
The freechain control.
Definition: freechain.h:64
Local ISR lock context for acquire and release pairs.
Definition: isrlock.h:81
ISR lock control.
Definition: isrlock.h:72
Definition: mppkt.h:102
Definition: objectdata.h:61
The information structure used to manage each API class of objects.
Definition: objectdata.h:198
Per CPU Core Structure.
Definition: percpu.h:384
The priority node to build up a priority aggregation.
Definition: priority.h:112
Red-black tree node.
Definition: rbtree.h:73
Scheduler node for per-thread data.
Definition: schedulernode.h:94
Definition: stack.h:71
Control block to manage thread actions.
Definition: thread.h:708
Thread action.
Definition: thread.h:681
This structure is used to control the CPU budget of a thread.
Definition: thread.h:188
uint32_t available
This member contains the count of the time quantum that this thread is allowed to consume until an ac...
Definition: thread.h:201
const Thread_CPU_budget_operations * operations
If this member is not NULL, then it references the CPU budget operations used to manage the CPU budge...
Definition: thread.h:194
This structure contains operations which manage the CPU budget of a thread.
Definition: thread.h:165
Definition: thread.h:798
Thread control add-on.
Definition: thread.h:991
size_t source_offset
Offset relative to the thread control block begin to an application configuration dependent memory ar...
Definition: thread.h:1003
size_t destination_offset
Offset of the pointer field in Thread_Control referencing an application configuration dependent memo...
Definition: thread.h:997
Data for idle thread entry.
Definition: thread.h:116
Thread entry information.
Definition: thread.h:140
Data for thread entry with one numeric argument and no return value.
Definition: thread.h:123
Data for thread entry with one pointer argument and a pointer return value.
Definition: thread.h:132
The thread object information.
Definition: thread.h:1098
Freechain_Control Free
The free thread queue heads.
Definition: thread.h:1120
Objects_Information Objects
The object information.
Definition: thread.h:1102
Thread_queue_Configured_heads * initial
Contains the initial set of thread queue heads.
Definition: thread.h:1113
Per-thread information for POSIX Keys.
Definition: thread.h:689
RBTree_Control Key_value_pairs
Key value pairs registered for this thread.
Definition: thread.h:693
Thread life control.
Definition: thread.h:770
uint32_t pending_life_change_requests
The count of pending life change requests.
Definition: thread.h:785
Thread_Action Action
Thread life action used to react upon thread restart and delete requests.
Definition: thread.h:775
Thread_Life_state state
The current thread life state.
Definition: thread.h:780
void * exit_value
The thread exit value.
Definition: thread.h:795
Definition: thread.h:557
States_Control current_state
Definition: thread.h:567
Objects_Control Object
Definition: thread.h:559
Priority_Node Real_priority
The base priority of this thread in its home scheduler instance.
Definition: thread.h:572
Thread_Timer_information Timer
Definition: thread.h:587
Thread_Wait_information Wait
Definition: thread.h:585
Thread_Scheduler_control Scheduler
Scheduler related control.
Definition: thread.h:582
Thread_queue_Control Join_queue
Definition: thread.h:564
Thread scheduler control.
Definition: thread.h:274
Scheduler_Node * nodes
The scheduler nodes of this thread.
Definition: thread.h:396
Definition: thread.h:208
Stack_Control Initial_stack
Definition: thread.h:232
bool is_preemptible
Definition: thread.h:215
Thread_Entry_information Entry
Definition: thread.h:210
void * tls_area
Definition: thread.h:238
const Thread_CPU_budget_operations * cpu_budget_operations
This member may provide the CPU budget operations activated when a thread is initialized before it is...
Definition: thread.h:221
uint32_t isr_level
Definition: thread.h:224
Priority_Control initial_priority
Definition: thread.h:226
Context_Control_fp * fp_context
Definition: thread.h:235
Information required to manage a thread timer.
Definition: thread.h:544
Information required to manage a thread while it is blocked.
Definition: thread.h:436
Thread_queue_Queue * queue
The current thread queue.
Definition: thread.h:527
uint32_t count
Definition: thread.h:445
uint32_t option
Definition: thread.h:452
Thread_Wait_flags flags
This field contains several flags used to control the wait class and state of a thread in case fine-g...
Definition: thread.h:467
Thread_Wait_information_Object_argument_type return_argument_second
Definition: thread.h:450
const Thread_queue_Operations * operations
The current thread queue operations.
Definition: thread.h:536
uint32_t return_code
Definition: thread.h:458
void * return_argument
Definition: thread.h:447
Definition: threadq.h:609
The thread queue operations are used to manage the threads of a thread queue.
Definition: threadq.h:554
Definition: threadq.h:427
Chain iterator for dynamic user extensions.
Definition: userextimpl.h:66
The control block used to manage each watchdog timer.
Definition: watchdog.h:109
The watchdog header to manage scheduled watchdogs.
Definition: watchdog.h:90
Scheduler control.
Definition: scheduler.h:335
Definition: thread.h:812
Context_Control Registers
This member contains the context of this thread.
Definition: thread.h:868
Objects_Control Object
Definition: thread.h:814
struct User_extensions_Iterator * last_user_extensions_iterator
LIFO list of user extensions iterators.
Definition: thread.h:967
Timestamp_Control cpu_time_used
This member contains the amount of CPU time consumed by this thread since it was created.
Definition: thread.h:909
Thread_Wait_information Wait
Definition: thread.h:852
Context_Control_fp * fp_context
Definition: thread.h:929
Priority_Node Real_priority
The base priority of this thread in its home scheduler instance.
Definition: thread.h:839
Thread_Keys_information Keys
The POSIX Keys information.
Definition: thread.h:943
States_Control current_state
Definition: thread.h:834
bool is_fp
Definition: thread.h:891
Thread_Scheduler_control Scheduler
Scheduler related control.
Definition: thread.h:849
Thread_queue_Control Join_queue
Thread queue for thread join operations and multi-purpose lock.
Definition: thread.h:831
void * API_Extensions[THREAD_API_LAST+1]
Definition: thread.h:938
Thread_Timer_information Timer
Definition: thread.h:854
Thread_Life_control Life
Thread life-cycle control.
Definition: thread.h:950
Thread_CPU_budget_control CPU_budget
This member contains the CPU budget control used to manage the CPU budget of the thread.
Definition: thread.h:903
bool was_created_with_inherited_scheduler
True, if the thread was created with an inherited scheduler (PTHREAD_INHERIT_SCHED),...
Definition: thread.h:897
struct _pthread_cleanup_context * last_cleanup_context
LIFO list of POSIX cleanup contexts.
Definition: thread.h:962
bool is_preemptible
Definition: thread.h:889
Thread_Start_information Start
Definition: thread.h:921
Timestamp_Control cpu_time_used_at_last_reset
This member contains the amount of CPU time consumed by this thread at the time of the last reset of ...
Definition: thread.h:916
void * extensions[RTEMS_ZERO_LENGTH_ARRAY]
Variable length array of user extension pointers.
Definition: thread.h:974
bool is_idle
Definition: thread.h:883
struct rtems_user_env_t * user_environment
Pointer to an optional thread-specific POSIX user environment.
Definition: thread.h:957
struct _reent * libc_reent
Definition: thread.h:934
Thread queue heads.
Definition: threadq.h:385
Definition: intercom.c:87
Definition: mmu-config.c:53
User environment.
Definition: userenv.h:80
This header file provides interfaces of the Thread Queue Handler which are used by the implementation...
This header file provides interfaces of the Timestamp Handler which are used by the implementation an...
This union represents a chain control block.
Definition: chain.h:96
Union type to hold a pointer to an immutable or a mutable object.
Definition: thread.h:409