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;