File : s-taskin-raven-cert.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-2013, Free Software Foundation, Inc. --
10 -- --
11 -- GNAT 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. GNAT 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/cert 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.Exceptions;
40 -- used for Exception_ID
41
42 with System.Soft_Links;
43 -- used for TSD
44
45 with System.Storage_Elements;
46 -- used for Storage_Offset
47
48 with System.Parameters;
49 -- used for Size_Type
50
51 with System.Task_Info;
52 -- used for Task_Info_Type
53
54 with System.Task_Primitives;
55 -- used for Private_Data
56 -- Lock (in System.Tasking.Protected_Objects)
57
58 with System.Multiprocessors;
59 -- used for CPU_Range type
60
61 with Unchecked_Conversion;
62
63 package System.Tasking is
64 pragma Preelaborate;
65
66 ---------------------------------
67 -- Task_Id related definitions --
68 ---------------------------------
69
70 type Ada_Task_Control_Block;
71
72 type Task_Id is access all Ada_Task_Control_Block;
73 function To_Task_Id is new Unchecked_Conversion (System.Address, Task_Id);
74 function To_Address is new Unchecked_Conversion (Task_Id, System.Address);
75
76 Null_Task : constant Task_Id := null;
77
78 type Task_List is array (Positive range <>) of Task_Id;
79 pragma Suppress_Initialization (Task_List);
80
81 function Self return Task_Id;
82 -- This is the compiler interface version of this function. Do not call
83 -- from the run-time system.
84
85 -----------------------
86 -- Enumeration types --
87 -----------------------
88
89 type Task_States is
90 (Unactivated,
91 -- Task has been created but has not been activated.
92 -- It cannot be executing.
93
94 -- Active states
95
96 -- For all states from here down, the task has been activated.
97 -- For all states from here down, except for Terminated, the task
98 -- may be executing.
99
100 -- For all states from here down, the task has been activated,
101 -- and may be executing.
102
103 Runnable,
104 -- Task is not blocked for any reason known to Ada.
105 -- (It may be waiting for a mutex, though.)
106 -- It is conceptually "executing" in normal mode.
107
108 Terminated,
109 -- The task is terminated, in the sense of ARM 9.3 (5)
110
111 Activator_Sleep,
112 -- Task is waiting for created tasks to complete activation
113
114 Acceptor_Sleep,
115 -- Task is waiting on an accept or selective wait statement
116
117 Entry_Caller_Sleep,
118 -- Task is waiting on an entry call
119
120 Async_Select_Sleep,
121 -- Task is waiting to start the abortable part of an
122 -- asynchronous select statement.
123
124 Delay_Sleep,
125 -- Task is waiting on a delay statement
126
127 Master_Completion_Sleep,
128 -- Master completion has two phases.
129 -- In Phase 1 the task is sleeping in Complete_Master
130 -- having completed a master within itself,
131 -- and is waiting for the tasks dependent on that master to become
132 -- terminated or waiting on a terminate Phase.
133
134 Master_Phase_2_Sleep,
135 -- In Phase 2 the task is sleeping in Complete_Master
136 -- waiting for tasks on terminate alternatives to finish
137 -- terminating.
138
139 -- The following are special uses of sleep, for server tasks
140 -- within the run-time system.
141
142 Interrupt_Server_Idle_Sleep,
143 Interrupt_Server_Blocked_Interrupt_Sleep,
144 Timer_Server_Sleep,
145 AST_Server_Sleep,
146
147 Asynchronous_Hold,
148 -- The task has been held by Asynchronous_Task_Control.Hold_Task
149
150 Interrupt_Server_Blocked_On_Event_Flag
151 -- The task has been blocked on a system call waiting for the
152 -- completion event.
153 );
154
155 -- The following status are never used in a Ravenscar run time. They are
156 -- defined for debugging purposes: The same code in GDB to get the current
157 -- status of a task in a full run-time environment and in a Ravenscar
158 -- environment.
159 pragma Unreferenced (Activator_Sleep);
160 pragma Unreferenced (Acceptor_Sleep);
161 pragma Unreferenced (Async_Select_Sleep);
162 pragma Unreferenced (Master_Completion_Sleep);
163 pragma Unreferenced (Master_Phase_2_Sleep);
164 pragma Unreferenced (Interrupt_Server_Idle_Sleep);
165 pragma Unreferenced (Interrupt_Server_Blocked_Interrupt_Sleep);
166 pragma Unreferenced (Timer_Server_Sleep);
167 pragma Unreferenced (AST_Server_Sleep);
168 pragma Unreferenced (Asynchronous_Hold);
169 pragma Unreferenced (Interrupt_Server_Blocked_On_Event_Flag);
170
171 type Call_Modes is (Simple_Call);
172
173 -------------------------------
174 -- Entry related definitions --
175 -------------------------------
176
177 Null_Entry : constant := 0;
178
179 Max_Entry : constant := Integer'Last;
180
181 Interrupt_Entry : constant := -2;
182
183 Cancelled_Entry : constant := -1;
184
185 type Entry_Index is range Interrupt_Entry .. Max_Entry;
186
187 Null_Task_Entry : constant := Null_Entry;
188
189 Max_Task_Entry : constant := Max_Entry;
190
191 type Task_Entry_Index is new Entry_Index
192 range Null_Task_Entry .. Max_Task_Entry;
193
194 type Entry_Call_Record;
195
196 type Entry_Call_Link is access all Entry_Call_Record;
197
198 ----------------------------------
199 -- Entry_Call_Record definition --
200 ----------------------------------
201
202 type Entry_Call_Record is record
203 Self : Task_Id;
204 -- ID of the caller
205
206 Uninterpreted_Data : System.Address;
207 -- Data passed by the compiler
208
209 Exception_To_Raise : Ada.Exceptions.Exception_Id;
210 -- The exception to raise once this call has been completed without
211 -- being aborted.
212 end record;
213 pragma Suppress_Initialization (Entry_Call_Record);
214
215 ------------------------------------
216 -- Other Task-Related Definitions --
217 ------------------------------------
218
219 type Activation_Chain is limited private;
220
221 type Activation_Chain_Access is access all Activation_Chain;
222
223 type Task_Procedure_Access is access procedure (Arg : System.Address);
224
225 type Access_Boolean is access all Boolean;
226
227 ----------------------------------------------
228 -- Ada_Task_Control_Block (ATCB) definition --
229 ----------------------------------------------
230
231 -- Notes on protection (synchronization) of TRTS data structures
232
233 -- Any field of the TCB can be written by the activator of a task when the
234 -- task is created, since no other task can access the new task's
235 -- state until creation is complete.
236
237 -- The protection for each field is described in a comment starting with
238 -- "Protection:".
239
240 -- When a lock is used to protect an ATCB field, this lock is simply named
241
242 -- Some protection is described in terms of tasks related to the
243 -- ATCB being protected. These are:
244
245 -- Self: The task which is controlled by this ATCB.
246 -- Activator: The task that created Self and initiated its activation.
247 -- Created: A task created and activated by Self.
248
249 type Common_ATCB is record
250 State : Task_States;
251 pragma Atomic (State);
252 -- Encodes some basic information about the state of a task, including
253 -- whether it has been activated, whether it is sleeping, and whether
254 -- it is terminated.
255 --
256 -- Protection: Only accessed by Self
257
258 Base_CPU : System.Multiprocessors.CPU_Range;
259 -- Protection: Only written during initialization, accessed by anyone
260
261 Base_Priority : System.Any_Priority;
262 -- Base priority.
263 --
264 -- Protection: Only written by Self, accessed by anyone
265
266 Current_Priority : System.Any_Priority;
267 -- Current priority. Used only by LynxOS-178.
268 --
269 -- Protection: Only written by Self, accessed by anyone
270
271 Protected_Action_Nesting : Natural;
272 pragma Atomic (Protected_Action_Nesting);
273 -- The dynamic level of protected action nesting for this task. This
274 -- field is needed for checking whether potentially blocking operations
275 -- are invoked from protected actions. pragma Atomic is used because it
276 -- can be read/written from protected interrupt handlers.
277
278 LL : aliased Task_Primitives.Private_Data;
279 -- Control block used by the underlying low-level tasking service
280 -- (GNULLI).
281 --
282 -- Protection: This is used only by the GNULLI implementation, which
283 -- takes care of all of its synchronization.
284
285 Wakeup_Signaled : Boolean := False;
286 -- Variable which reflects whether another thread has performed a
287 -- Wakeup operation on the thread. It may happen when a task is about
288 -- to suspend itself, but it is preempted just before by the task that
289 -- is going to awake it. Used in s-taprop-raven-cert-lynxos178.adb.
290 --
291 -- Protection: Common.LL.L.
292
293 Task_Arg : System.Address;
294 -- The argument to task procedure. Currently unused; this will provide a
295 -- 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 : System.Soft_Links.TSD;
310 -- Task-specific data needed by the compiler to store per-task
311 -- structures.
312 --
313 -- Protection: Only accessed by Self
314
315 Activation_Link : Task_Id;
316 -- Used to link this task to a list of tasks to be activated.
317 --
318 -- Protection: Only used by Activator
319
320 Task_Info : System.Task_Info.Task_Info_Type;
321 -- System-specific attributes of the task as specified by the Task_Info
322 -- pragma.
323 end record;
324 pragma Suppress_Initialization (Common_ATCB);
325
326 type Ada_Task_Control_Block (Entry_Num : Task_Entry_Index) is record
327 Common : Common_ATCB;
328 Entry_Call : aliased Entry_Call_Record;
329 -- Protection: This field is used on entry call queues associated with
330 -- protected objects, and is protected by the protected object lock.
331 end record;
332 pragma Suppress_Initialization (Ada_Task_Control_Block);
333 -- The discriminant Entry_Num is not needed, but we keep it here for
334 -- compatibility reasons with the rest of the run times, so that the
335 -- expander does not need to know which run time is being used.
336
337 --------------------------------
338 -- Master Related Definitions --
339 --------------------------------
340
341 subtype Master_Level is Integer;
342 subtype Master_ID is Master_Level;
343
344 Library_Task_Level : constant Master_Level := 3;
345
346 ----------------------------------------
347 -- Task size, priority, affinity info --
348 ----------------------------------------
349
350 function Storage_Size (T : Task_Id) return System.Parameters.Size_Type;
351 -- Retrieve from the TCB of the task the allocated size of its stack,
352 -- either the system default or the size specified by a pragma. This
353 -- is in general a non-static value that can depend on discriminants
354 -- of the task.
355
356 Unspecified_Priority : constant Integer := System.Priority'First - 1;
357
358 Unspecified_CPU : constant := -1;
359 -- No affinity specified
360
361 --------------------
362 -- Initialization --
363 --------------------
364
365 procedure Initialize;
366 -- This procedure constitutes the first part of the initialization of the
367 -- GNARL. This includes creating data structures to make the initial thread
368 -- into the environment task. The last part of the initialization is done
369 -- in System.Tasking.Initialization or System.Tasking.Restricted.Stages.
370 -- All the initializations used to be in Tasking.Initialization, but this
371 -- is no longer possible with the run time simplification (including
372 -- optimized PO and the restricted run time) since one cannot rely on
373 -- System.Tasking.Initialization being present, as was done before.
374
375 procedure Initialize_ATCB
376 (Task_Entry_Point : Task_Procedure_Access;
377 Task_Arg : System.Address;
378 Base_Priority : System.Any_Priority;
379 Base_CPU : System.Multiprocessors.CPU_Range;
380 Task_Info : System.Task_Info.Task_Info_Type;
381 Stack_Address : System.Address;
382 Stack_Size : System.Parameters.Size_Type;
383 T : Task_Id;
384 Success : out Boolean);
385 -- Initialize fields of a TCB and link into global TCB structures. Call
386 -- this only with abort deferred and holding All_Tasks_L.
387
388 private
389
390 type Activation_Chain is record
391 T_ID : Task_Id;
392 end record;
393 pragma Volatile (Activation_Chain);
394
395 end System.Tasking;