RTEMS 6.1-rc7
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)
102#define RTEMS_SCORE_THREAD_ENABLE_RESOURCE_COUNT
103#endif
104
105#if defined(RTEMS_POSIX_API)
112#define RTEMS_SCORE_THREAD_REAL_PRIORITY_MAY_BE_INACTIVE
113#endif
114
115#if defined(RTEMS_POSIX_API) && defined(RTEMS_SMP)
122#define RTEMS_SCORE_THREAD_HAS_SCHEDULER_CHANGE_INHIBITORS
123#endif
124
135
139typedef struct {
140 void *( *entry )( uintptr_t argument );
142
146typedef struct {
147 void ( *entry )( Thread_Entry_numeric_type argument );
150
155typedef struct {
156 void *( *entry )( void *argument );
157 void *argument;
159
163typedef struct {
171 void ( *adaptor )( Thread_Control *executing );
172
177 union {
179 Thread_Entry_numeric Numeric;
180 Thread_Entry_pointer Pointer;
181 } Kinds;
183
188typedef struct {
193 void ( *at_tick )( Thread_Control * );
194
199 void ( *at_context_switch )( Thread_Control * );
200
205 void ( *initialize )( Thread_Control * );
207
211typedef struct {
218
224 uint32_t available;
226
231typedef struct {
234 /*-------------- initial execution modes ----------------- */
239
245
247 uint32_t isr_level;
253 void ( *stack_free )( void * );
256 #if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE )
259 #endif
261 void *tls_area;
263
264#if defined(RTEMS_SMP)
268typedef enum {
274 THREAD_SCHEDULER_BLOCKED,
275
283 THREAD_SCHEDULER_SCHEDULED,
284
290 THREAD_SCHEDULER_READY
291} Thread_Scheduler_state;
292#endif
293
297typedef struct {
298#if defined(RTEMS_SMP)
302 ISR_lock_Control Lock;
303
307 Thread_Scheduler_state state;
308
312 const struct _Scheduler_Control *home_scheduler;
313
317 const struct _Scheduler_Control *pinned_scheduler;
318
322 struct Per_CPU_Control *cpu;
323
333 Chain_Control Wait_nodes;
334
348 Chain_Control Scheduler_nodes;
349
360 struct Per_CPU_Control *ask_for_help_cpu;
361
370 Chain_Node Help_node;
371
377 size_t helping_nodes;
378
384 Scheduler_Node *requests;
385
406 int pin_level;
407
411 Processor_mask Affinity;
412#endif
413
421
432typedef union {
433 void *mutable_object;
434 const void *immutable_object;
436
451typedef unsigned int Thread_Wait_flags;
452
459typedef struct {
460#if defined(RTEMS_MULTIPROCESSING)
461 /*
462 * @brief This field is the identifier of the remote object this thread is
463 * waiting upon.
464 */
465 Objects_Id remote_id;
466#endif
468 uint32_t count;
475 uint32_t option;
481 uint32_t return_code;
482
487#if defined(RTEMS_SMP)
488 Atomic_Uint flags;
489#else
491#endif
492
493#if defined(RTEMS_SMP)
511 struct {
515 ISR_lock_Control Default;
516
521 Chain_Control Pending_requests;
522
532 Thread_queue_Gate Tranquilizer;
533 } Lock;
534
539 Thread_queue_Link Link;
540#endif
541
551
560
561 Thread_queue_Heads *spare_heads;
563
567typedef struct {
568#if ISR_LOCK_NEEDS_OBJECT
569 ISR_lock_Control Lock;
570#endif
571 Watchdog_Header *header;
572 Watchdog_Control Watchdog;
574
582typedef struct {
585
590
593
598
599#if defined(RTEMS_SCORE_THREAD_ENABLE_RESOURCE_COUNT)
601 uint32_t resource_count;
602#endif
603
608
613#if defined(RTEMS_MULTIPROCESSING)
615 MP_packet_Prefix *receive_packet;
616 /****************** end of common block ********************/
617
621 Thread_queue_MP_callout thread_queue_callout;
622
626 RBTree_Node Active;
627
632 Scheduler_Node Scheduler_node;
633
641 Thread_queue_Heads Thread_queue_heads[ RTEMS_ZERO_LENGTH_ARRAY ];
642#endif
644
652typedef enum {
658
660#define THREAD_API_FIRST THREAD_API_RTEMS
661
663#define THREAD_API_LAST THREAD_API_POSIX
664
665typedef struct Thread_Action Thread_Action;
666
686typedef void ( *Thread_Action_handler )(
687 Thread_Control *the_thread,
688 Thread_Action *action,
689 ISR_lock_Context *lock_context
690);
691
707 Chain_Node Node;
708 Thread_Action_handler handler;
709};
710
714typedef struct {
718 RBTree_Control Key_value_pairs;
719
720#if defined(RTEMS_SMP)
724 ISR_lock_Control Lock;
725#endif
727
733typedef struct {
734 Chain_Control Chain;
736
747typedef unsigned int Thread_Life_state;
748
756#define THREAD_LIFE_PROTECTED 0x1U
757
764#define THREAD_LIFE_RESTARTING 0x2U
765
772#define THREAD_LIFE_TERMINATING 0x4U
773
781#define THREAD_LIFE_CHANGE_DEFERRED 0x8U
782
790#define THREAD_LIFE_DETACHED 0x10U
791
795typedef struct {
801
806
811
822
823typedef struct {
824 uint32_t flags;
825 void * control;
827
840
857
860
865
866#if defined(RTEMS_SCORE_THREAD_ENABLE_RESOURCE_COUNT)
868 uint32_t resource_count;
869#endif
870
875
880#if defined(RTEMS_MULTIPROCESSING)
882 MP_packet_Prefix *receive_packet;
883#endif
884 /*================= end of common block =================*/
885
894
895#if defined(RTEMS_SMP) && defined(RTEMS_PROFILING)
904 SMP_lock_Stats Potpourri_stats;
905#endif
906
909#if defined(RTEMS_MULTIPROCESSING)
911 bool is_global;
912#endif
916 bool is_fp;
917
923
924#if defined(RTEMS_SCORE_THREAD_HAS_SCHEDULER_CHANGE_INHIBITORS)
931 bool is_scheduler_change_inhibited;
932#endif
933
939
945
952
957
958 Thread_Action_control Post_switch_actions;
959
960#if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE )
965#endif
966
967#ifndef _REENT_THREAD_LOCAL
969 struct _reent *libc_reent;
970#endif
971
974
979
986
988
993
997 struct _pthread_cleanup_context *last_cleanup_context;
998
1003
1010};
1011
1012typedef void (*rtems_per_thread_routine)( Thread_Control * );
1013
1020 rtems_per_thread_routine routine
1022
1026typedef struct {
1033
1040
1055
1063extern const size_t _Thread_Control_add_on_count;
1064
1070extern const size_t _Thread_Initial_thread_count;
1071
1079#define THREAD_DEFAULT_MAXIMUM_NAME_SIZE 16
1080
1087extern const size_t _Thread_Maximum_name_size;
1088
1097extern const size_t _Thread_Maximum_TLS_size;
1098
1106
1113#if defined(RTEMS_SMP)
1115#else
1117#endif
1118
1124#if defined(RTEMS_SMP)
1125extern const size_t _Thread_queue_Heads_size;
1126#else
1127#define _Thread_queue_Heads_size sizeof(Thread_queue_Heads)
1128#endif
1129
1133typedef struct {
1138
1142 union {
1149
1156 } Thread_queue_heads;
1158
1163
1164#define THREAD_INFORMATION_DEFINE_ZERO( name, api, cls ) \
1165Thread_Information name##_Information = { \
1166 { \
1167 _Objects_Build_id( api, cls, 1, 0 ), \
1168 NULL, \
1169 _Objects_Allocate_none, \
1170 NULL, \
1171 0, \
1172 0, \
1173 0, \
1174 0, \
1175 CHAIN_INITIALIZER_EMPTY( name##_Information.Objects.Inactive ), \
1176 NULL, \
1177 NULL, \
1178 NULL \
1179 OBJECTS_INFORMATION_MP( name##_Information.Objects, NULL ), \
1180 }, { \
1181 NULL \
1182 } \
1183}
1184
1192
1193#define THREAD_INFORMATION_DEFINE( name, api, cls, max ) \
1194static Objects_Control * \
1195name##_Local_table[ _Objects_Maximum_per_allocation( max ) ]; \
1196static RTEMS_SECTION( ".noinit.rtems.content.objects." #name ) \
1197Thread_Configured_control \
1198name##_Objects[ _Objects_Maximum_per_allocation( max ) ]; \
1199static RTEMS_SECTION( ".noinit.rtems.content.objects." #name ) \
1200Thread_queue_Configured_heads \
1201name##_Heads[ _Objects_Maximum_per_allocation( max ) ]; \
1202Thread_Information name##_Information = { \
1203 { \
1204 _Objects_Build_id( api, cls, 1, _Objects_Maximum_per_allocation( max ) ), \
1205 name##_Local_table, \
1206 _Objects_Is_unlimited( max ) ? \
1207 _Thread_Allocate_unlimited : _Objects_Allocate_static, \
1208 _Objects_Is_unlimited( max ) ? \
1209 _Objects_Free_unlimited : _Objects_Free_static, \
1210 0, \
1211 _Objects_Is_unlimited( max ) ? _Objects_Maximum_per_allocation( max ) : 0, \
1212 sizeof( Thread_Configured_control ), \
1213 OBJECTS_NO_STRING_NAME, \
1214 CHAIN_INITIALIZER_EMPTY( name##_Information.Objects.Inactive ), \
1215 NULL, \
1216 NULL, \
1217 &name##_Objects[ 0 ].Control.Object \
1218 OBJECTS_INFORMATION_MP( name##_Information.Objects, NULL ) \
1219 }, { \
1220 &name##_Heads[ 0 ] \
1221 } \
1222}
1223
1224#if defined(RTEMS_MULTIPROCESSING)
1231typedef struct Thread_Configured_proxy_control Thread_Configured_proxy_control;
1232
1238extern Thread_Configured_proxy_control * const _Thread_MP_Proxies;
1239#endif
1240
1243#ifdef __cplusplus
1244}
1245#endif
1246
1247#endif
1248/* 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
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:1127
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:747
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:451
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:686
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:134
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:1116
struct Thread_Configured_control Thread_Configured_control
The configured thread control block.
Definition: thread.h:1105
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:663
Thread_APIs
Definition: thread.h:652
@ THREAD_API_POSIX
Definition: thread.h:656
@ THREAD_API_RTEMS
Definition: thread.h:654
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:173
The freechain control.
Definition: freechain.h:64
Local ISR lock context for acquire and release pairs.
Definition: isrlock.h:94
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:733
Thread action.
Definition: thread.h:706
This structure is used to control the CPU budget of a thread.
Definition: thread.h:211
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:224
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:217
This structure contains operations which manage the CPU budget of a thread.
Definition: thread.h:188
Definition: thread.h:823
Thread control add-on.
Definition: thread.h:1026
size_t source_offset
Offset relative to the thread control block begin to an application configuration dependent memory ar...
Definition: thread.h:1038
size_t destination_offset
Offset of the pointer field in Thread_Control referencing an application configuration dependent memo...
Definition: thread.h:1032
Data for idle thread entry.
Definition: thread.h:139
Thread entry information.
Definition: thread.h:163
Data for thread entry with one numeric argument and no return value.
Definition: thread.h:146
Data for thread entry with one pointer argument and a pointer return value.
Definition: thread.h:155
The thread object information.
Definition: thread.h:1133
Freechain_Control Free
The free thread queue heads.
Definition: thread.h:1155
Objects_Information Objects
The object information.
Definition: thread.h:1137
Thread_queue_Configured_heads * initial
Contains the initial set of thread queue heads.
Definition: thread.h:1148
Per-thread information for POSIX Keys.
Definition: thread.h:714
RBTree_Control Key_value_pairs
Key value pairs registered for this thread.
Definition: thread.h:718
Thread life control.
Definition: thread.h:795
uint32_t pending_life_change_requests
The count of pending life change requests.
Definition: thread.h:810
Thread_Action Action
Thread life action used to react upon thread restart and delete requests.
Definition: thread.h:800
Thread_Life_state state
The current thread life state.
Definition: thread.h:805
void * exit_value
The thread exit value.
Definition: thread.h:820
Definition: thread.h:582
States_Control current_state
Definition: thread.h:592
Objects_Control Object
Definition: thread.h:584
Priority_Node Real_priority
The base priority of this thread in its home scheduler instance.
Definition: thread.h:597
Thread_Timer_information Timer
Definition: thread.h:612
Thread_Wait_information Wait
Definition: thread.h:610
Thread_Scheduler_control Scheduler
Scheduler related control.
Definition: thread.h:607
Thread_queue_Control Join_queue
Definition: thread.h:589
Thread scheduler control.
Definition: thread.h:297
Scheduler_Node * nodes
The scheduler nodes of this thread.
Definition: thread.h:419
Definition: thread.h:231
Stack_Control Initial_stack
Definition: thread.h:255
bool is_preemptible
Definition: thread.h:238
Thread_Entry_information Entry
Definition: thread.h:233
void * tls_area
Definition: thread.h:261
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:244
uint32_t isr_level
Definition: thread.h:247
Priority_Control initial_priority
Definition: thread.h:249
Context_Control_fp * fp_context
Definition: thread.h:258
Information required to manage a thread timer.
Definition: thread.h:567
Information required to manage a thread while it is blocked.
Definition: thread.h:459
Thread_queue_Queue * queue
The current thread queue.
Definition: thread.h:550
uint32_t count
Definition: thread.h:468
uint32_t option
Definition: thread.h:475
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:490
Thread_Wait_information_Object_argument_type return_argument_second
Definition: thread.h:473
const Thread_queue_Operations * operations
The current thread queue operations.
Definition: thread.h:559
uint32_t return_code
Definition: thread.h:481
void * return_argument
Definition: thread.h:470
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:337
Definition: thread.h:837
Context_Control Registers
This member contains the context of this thread.
Definition: thread.h:893
Objects_Control Object
Definition: thread.h:839
struct User_extensions_Iterator * last_user_extensions_iterator
LIFO list of user extensions iterators.
Definition: thread.h:1002
Timestamp_Control cpu_time_used
This member contains the amount of CPU time consumed by this thread since it was created.
Definition: thread.h:944
Thread_Wait_information Wait
Definition: thread.h:877
Context_Control_fp * fp_context
Definition: thread.h:964
Priority_Node Real_priority
The base priority of this thread in its home scheduler instance.
Definition: thread.h:864
Thread_Keys_information Keys
The POSIX Keys information.
Definition: thread.h:978
States_Control current_state
Definition: thread.h:859
bool is_fp
Definition: thread.h:916
Thread_Scheduler_control Scheduler
Scheduler related control.
Definition: thread.h:874
Thread_queue_Control Join_queue
Thread queue for thread join operations and multi-purpose lock.
Definition: thread.h:856
void * API_Extensions[THREAD_API_LAST+1]
Definition: thread.h:973
Thread_Timer_information Timer
Definition: thread.h:879
Thread_Life_control Life
Thread life-cycle control.
Definition: thread.h:985
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:938
bool was_created_with_inherited_scheduler
True, if the thread was created with an inherited scheduler (PTHREAD_INHERIT_SCHED),...
Definition: thread.h:922
struct _pthread_cleanup_context * last_cleanup_context
LIFO list of POSIX cleanup contexts.
Definition: thread.h:997
bool is_preemptible
Definition: thread.h:914
Thread_Start_information Start
Definition: thread.h:956
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:951
void * extensions[RTEMS_ZERO_LENGTH_ARRAY]
Variable length array of user extension pointers.
Definition: thread.h:1009
bool is_idle
Definition: thread.h:908
struct rtems_user_env_t * user_environment
Pointer to an optional thread-specific POSIX user environment.
Definition: thread.h:992
struct _reent * libc_reent
Definition: thread.h:969
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:432