File : s-taskin-raven.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT RUN-TIME LIBRARY (GNARL) COMPONENTS --
4 -- --
5 -- S Y S T E M . T A S K I N G --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 1992-2016, Free Software Foundation, Inc. --
10 -- --
11 -- GNARL is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 3, or (at your option) any later ver- --
14 -- sion. GNARL is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. --
17 -- --
18 -- --
19 -- --
20 -- --
21 -- --
22 -- You should have received a copy of the GNU General Public License and --
23 -- a copy of the GCC Runtime Library Exception along with this program; --
24 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
25 -- <http://www.gnu.org/licenses/>. --
26 -- --
27 -- GNARL was developed by the GNARL team at Florida State University. --
28 -- Extensive contributions were provided by Ada Core Technologies, Inc. --
29 -- --
30 ------------------------------------------------------------------------------
31
32 -- This is the Ravenscar/HI-E version of this package
33
34 -- Note: the compiler generates direct calls to this interface, via Rtsfind.
35 -- Any changes to this interface may require corresponding compiler changes.
36
37 pragma Restrictions (No_Elaboration_Code);
38
39 with Ada.Unchecked_Conversion;
40
41 with System.Storage_Elements;
42 with System.Parameters;
43 with System.Task_Info;
44 with System.Task_Primitives;
45 with System.Multiprocessors;
46
47 package System.Tasking is
48 pragma Preelaborate;
49
50 ---------------------------------
51 -- Task_Id related definitions --
52 ---------------------------------
53
54 type Ada_Task_Control_Block;
55
56 type Task_Id is access all Ada_Task_Control_Block;
57 function To_Task_Id is
58 new Ada.Unchecked_Conversion
59 (System.Task_Primitives.Task_Address, Task_Id);
60
61 function To_Address is
62 new Ada.Unchecked_Conversion
63 (Task_Id, System.Task_Primitives.Task_Address);
64
65 Null_Task : constant Task_Id := null;
66
67 type Task_List is array (Positive range <>) of Task_Id;
68 pragma Suppress_Initialization (Task_List);
69
70 function Self return Task_Id;
71 -- This is the compiler interface version of this function. Do not call
72 -- from the run-time system.
73
74 -----------------------
75 -- Enumeration types --
76 -----------------------
77
78 type Task_States is
79 (Unactivated,
80 -- Task was created but has not been activated. It cannot be executing
81
82 -- For all states from here down, the task has been activated. In
83 -- addition, for all states from here down, except for Terminated,
84 -- the task may be executing.
85
86 Runnable,
87 -- Task is not blocked for any reason known to Ada. (It may be waiting
88 -- for a mutex, though.) It is conceptually "executing" in normal mode.
89
90 Terminated,
91 -- The task is terminated, in the sense of ARM 9.3 (5)
92
93 Activator_Sleep,
94 -- Task is waiting for created tasks to complete activation
95
96 Acceptor_Sleep,
97 -- Task is waiting on an accept or selective wait statement
98
99 Entry_Caller_Sleep,
100 -- Task is waiting on an entry call
101
102 Async_Select_Sleep,
103 -- Task is waiting to start the abortable part of an asynchronous select
104 -- statement.
105
106 Delay_Sleep,
107 -- Task is waiting on a delay statement
108
109 Master_Completion_Sleep,
110 -- Master completion has two phases. In Phase 1 the task is sleeping
111 -- in Complete_Master having completed a master within itself, and is
112 -- waiting for the tasks dependent on that master to become terminated
113 -- or waiting on a terminate Phase.
114
115 Master_Phase_2_Sleep,
116 -- In Phase 2 the task is sleeping in Complete_Master waiting for tasks
117 -- on terminate alternatives to finish terminating.
118
119 Interrupt_Server_Idle_Sleep,
120 Interrupt_Server_Blocked_Interrupt_Sleep,
121 Timer_Server_Sleep,
122 AST_Server_Sleep,
123 -- Special uses of sleep, for server tasks within the run-time system
124
125 Asynchronous_Hold,
126 -- The task has been held by Asynchronous_Task_Control.Hold_Task
127
128 Interrupt_Server_Blocked_On_Event_Flag
129 -- The task has been blocked on a system call waiting for the
130 -- completion event.
131 );
132
133 -- The following status indicators are never used in a Ravenscar run time.
134 -- They Are defined for debugging purposes: The same code in GDB to get
135 -- the Current status of a task in a full run-time environment and in a
136 -- Ravenscar environment.
137
138 pragma Unreferenced (Activator_Sleep);
139 pragma Unreferenced (Acceptor_Sleep);
140 pragma Unreferenced (Async_Select_Sleep);
141 pragma Unreferenced (Master_Completion_Sleep);
142 pragma Unreferenced (Master_Phase_2_Sleep);
143 pragma Unreferenced (Interrupt_Server_Idle_Sleep);
144 pragma Unreferenced (Interrupt_Server_Blocked_Interrupt_Sleep);
145 pragma Unreferenced (Timer_Server_Sleep);
146 pragma Unreferenced (AST_Server_Sleep);
147 pragma Unreferenced (Asynchronous_Hold);
148 pragma Unreferenced (Interrupt_Server_Blocked_On_Event_Flag);
149
150 -------------------------------
151 -- Entry related definitions --
152 -------------------------------
153
154 -- These need comments ???
155
156 Null_Entry : constant := 0;
157
158 Max_Entry : constant := Integer'Last;
159
160 Interrupt_Entry : constant := -2;
161
162 Cancelled_Entry : constant := -1;
163
164 type Entry_Index is range Interrupt_Entry .. Max_Entry;
165
166 Null_Task_Entry : constant := Null_Entry;
167
168 Max_Task_Entry : constant := Max_Entry;
169
170 type Task_Entry_Index is new Entry_Index
171 range Null_Task_Entry .. Max_Task_Entry;
172
173 type Entry_Call_Record;
174
175 type Entry_Call_Link is access all Entry_Call_Record;
176
177 ----------------------------------
178 -- Entry_Call_Record definition --
179 ----------------------------------
180
181 type Entry_Call_Record is record
182 Self : Task_Id;
183 -- ID of the caller
184
185 Uninterpreted_Data : System.Address;
186 -- Data passed by the compiler
187
188 Next : Entry_Call_Link;
189 -- Entry_Call List
190 end record;
191 pragma Suppress_Initialization (Entry_Call_Record);
192
193 -------------------------------------------
194 -- Task termination procedure definition --
195 -------------------------------------------
196
197 -- We need to redefine this type (already defined in Ada.Task_Termination)
198 -- here to avoid circular dependencies.
199
200 type Termination_Handler is access protected procedure (T : Task_Id);
201 -- Represent a protected procedure to be executed when a task terminates
202
203 Fall_Back_Handler : Termination_Handler;
204 -- This is the fall-back handler that applies to all the tasks in the
205 -- partition (this is only for Ravenscar-compliant systems).
206
207 ------------------------------------
208 -- Other Task-Related Definitions --
209 ------------------------------------
210
211 Idle_Priority : constant Integer := Any_Priority'First - 1;
212 -- A priority lower than any user priority. Used by the idle task
213
214 subtype Extended_Priority is
215 Integer range Idle_Priority .. Any_Priority'Last;
216 -- Priority range that also includes the idle priority
217
218 type Activation_Chain is limited private;
219
220 type Activation_Chain_Access is access all Activation_Chain;
221
222 type Task_Procedure_Access is access procedure (Arg : System.Address);
223
224 type Access_Boolean is access all Boolean;
225
226 ----------------------------------------------
227 -- Ada_Task_Control_Block (ATCB) definition --
228 ----------------------------------------------
229
230 -- Notes on protection (synchronization) of TRTS data structures
231
232 -- Any field of the TCB can be written by the activator of a task when the
233 -- task is created, since no other task can access the new task's state
234 -- until creation is complete.
235
236 -- The protection for each field is described in a comment starting with
237 -- "Protection:".
238
239 -- When a lock is used to protect an ATCB field, this lock is simply named
240
241 -- Some protection is described in terms of tasks related to the ATCB being
242 -- protected. These are:
243
244 -- Self: The task which is controlled by this ATCB.
245 -- Activator: The task that created Self and initiated its activation.
246 -- Created: A task created and activated by Self.
247
248 type Stack_Info is record
249 Start_Address : System.Address := System.Null_Address;
250 Size : System.Storage_Elements.Storage_Offset;
251 end record;
252 pragma Suppress_Initialization (Stack_Info);
253
254 type TSD is record
255 Pri_Stack_Info : aliased Stack_Info;
256 -- Stack address and size of the task
257
258 Sec_Stack_Addr : Address;
259 -- Address of currently allocated secondary stack
260 end record;
261 pragma Suppress_Initialization (TSD);
262
263 type Common_ATCB is record
264 State : Task_States;
265 pragma Atomic (State);
266 -- Encodes some basic information about the state of a task, including
267 -- whether it has been activated, whether it is sleeping, and whether
268 -- it is terminated.
269 --
270 -- Protection: Only accessed by Self
271
272 Base_CPU : System.Multiprocessors.CPU_Range;
273 -- Protection: Only written during initialization, accessed by anyone
274
275 Base_Priority : Extended_Priority;
276 -- Base priority
277 --
278 -- Protection: Only written by Self, accessed by anyone
279
280 Protected_Action_Nesting : Natural;
281 pragma Atomic (Protected_Action_Nesting);
282 -- The dynamic level of protected action nesting for this task. This
283 -- field is needed for checking whether potentially blocking operations
284 -- are invoked from protected actions. pragma Atomic is used because it
285 -- can be read/written from protected interrupt handlers.
286
287 LL : aliased Task_Primitives.Private_Data;
288 -- Control block used by underlying low-level tasking service (GNULLI)
289 --
290 -- Protection: This is used only by the GNULLI implementation, which
291 -- takes care of all of its synchronization.
292
293 Task_Arg : System.Address;
294 -- The argument to task procedure. Currently unused, this will provide
295 -- a handle for discriminant information.
296 --
297 -- Protection: Part of the synchronization between Self and Activator.
298 -- Activator writes it, once, before Self starts executing. Thereafter,
299 -- Self only reads it.
300
301 Task_Entry_Point : Task_Procedure_Access;
302 -- Information needed to call the procedure containing the code for
303 -- the body of this task.
304 --
305 -- Protection: Part of the synchronization between Self and Activator.
306 -- Activator writes it, once, before Self starts executing. Self reads
307 -- it, once, as part of its execution.
308
309 Compiler_Data : TSD;
310 -- Task-specific data needed by compiler to store per-task stuctures
311 --
312 -- Protection: Only accessed by Self
313
314 Activation_Link : Task_Id;
315 -- Used to link this task to a list of tasks to be activated
316 --
317 -- Protection: Only used by Activator. Once the task is activated, this
318 -- can also be reused by System.Tasking.Debug for the list of known
319 -- tasks.
320
321 Task_Info : System.Task_Info.Task_Info_Type;
322 -- System-specific attributes of the task as specified by the
323 -- Task_Info pragma.
324 end record;
325 pragma Suppress_Initialization (Common_ATCB);
326
327 type Ada_Task_Control_Block (Entry_Num : Task_Entry_Index) is record
328 -- The discriminant Entry_Num is not needed, but we keep it here for
329 -- compatibility reasons with the rest of the run times, so that the
330 -- expander does not need to know which run time is being used.
331
332 Common : Common_ATCB;
333
334 Entry_Call : aliased Entry_Call_Record;
335 -- Protection: This field is used on entry call queues associated with
336 -- protected objects, and is protected by the protected object lock.
337 end record;
338 pragma Suppress_Initialization (Ada_Task_Control_Block);
339 -- Why this pragma? comment needed???
340
341 --------------------------------
342 -- Master Related Definitions --
343 --------------------------------
344
345 subtype Master_Level is Integer;
346 subtype Master_ID is Master_Level;
347
348 Library_Task_Level : constant Master_Level := 3;
349
350 ----------------------------------
351 -- Secondary Stack Manipulation --
352 ----------------------------------
353
354 function Get_Sec_Stack return Address;
355 pragma Export (C, Get_Sec_Stack, "__gnat_get_secondary_stack");
356 -- Return the address of the task specific secondary stack, as expected by
357 -- System.Secondary_Stack.
358
359 procedure Set_Sec_Stack (Stk : Address);
360 -- Set the task specific secondary stack, as expected by
361 -- System.Secondary_Stack.
362
363 ----------------------------------------
364 -- Task size, priority, affinity info --
365 ----------------------------------------
366
367 function Storage_Size (T : Task_Id) return System.Parameters.Size_Type;
368 -- Retrieve from the TCB of the task the allocated size of its stack,
369 -- either the system default or the size specified by a pragma. This
370 -- is in general a non-static value that can depend on discriminants
371 -- of the task.
372
373 Unspecified_Priority : constant := -1;
374 -- No specified priority. This value is also hard-coded in gnatbind.
375
376 Unspecified_CPU : constant := -1;
377 -- No affinity specified
378
379 --------------------
380 -- Initialization --
381 --------------------
382
383 procedure Initialize;
384 -- This procedure constitutes the first part of the initialization of the
385 -- GNARL. This includes creating data structures to make the initial thread
386 -- into the environment task. The last part of the initialization is done
387 -- in System.Tasking.Initialization or System.Tasking.Restricted.Stages.
388 -- All the initializations used to be in Tasking.Initialization, but this
389 -- is no longer possible with the run time simplification (including
390 -- optimized PO and the restricted run time) since one cannot rely on
391 -- System.Tasking.Initialization being present, as was done before.
392
393 procedure Initialize_ATCB
394 (Task_Entry_Point : Task_Procedure_Access;
395 Task_Arg : System.Address;
396 Base_Priority : Extended_Priority;
397 Base_CPU : System.Multiprocessors.CPU_Range;
398 Task_Info : System.Task_Info.Task_Info_Type;
399 Stack_Address : System.Address;
400 Stack_Size : System.Parameters.Size_Type;
401 T : Task_Id;
402 Success : out Boolean);
403 -- Initialize fields of a TCB and link into global TCB structures
404 -- Call this only with abort deferred and holding All_Tasks_L.
405
406 private
407
408 type Activation_Chain is limited record
409 T_ID : Task_Id;
410 end record;
411
412 end System.Tasking;