gcc/ada/libgnarl/s-tasdeb.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 . D E B U G                 --
   6 --                                                                          --
   7 --                                  S p e c                                 --
   8 --                                                                          --
   9 --          Copyright (C) 1997-2024, 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.  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 -- As a special exception under Section 7 of GPL version 3, you are granted --
  19 -- additional permissions described in the GCC Runtime Library Exception,   --
  20 -- version 3.1, as published by the Free Software Foundation.               --
  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 package encapsulates all direct interfaces to task debugging services
  33 --  that are needed by gdb with gnat mode.
  34
  35 with System.OS_Interface;
  36
  37 package System.Tasking.Debug is
  38    pragma Preelaborate;
  39
  40    ------------------------------------------
  41    -- Application-level debugging routines --
  42    ------------------------------------------
  43
  44    procedure List_Tasks;
  45    --  Print a list of all the known Ada tasks with abbreviated state
  46    --  information, one-per-line, to the standard error file.
  47
  48    procedure Print_Current_Task;
  49    --  Write information about current task, in hexadecimal, as one line, to
  50    --  the standard error file.
  51
  52    procedure Print_Task_Info (T : Task_Id);
  53    --  Similar to Print_Current_Task, for a given task
  54
  55    procedure Set_User_State (Value : Long_Integer);
  56    --  Set user state value in the current task. This state will be displayed
  57    --  when calling List_Tasks or Print_Current_Task. It is useful for setting
  58    --  task specific state.
  59
  60    function Get_User_State return Long_Integer;
  61    --  Return the user state for the current task
  62
  63    -------------------------
  64    -- General GDB support --
  65    -------------------------
  66
  67    Known_Tasks : array (0 .. 999) of Task_Id := [others => null]
  68      with Atomic_Components;
  69    --  Global array of tasks read by gdb, and updated by Create_Task and
  70    --  Finalize_TCB. Ensure access to its components is atomic to allow
  71    --  lock-free concurrent access.
  72
  73    Debug_Event_Activating           : constant := 1;
  74    Debug_Event_Run                  : constant := 2;
  75    Debug_Event_Suspended            : constant := 3;
  76    Debug_Event_Preempted            : constant := 4;
  77    Debug_Event_Terminated           : constant := 5;
  78    Debug_Event_Abort_Terminated     : constant := 6;
  79    Debug_Event_Exception_Terminated : constant := 7;
  80    Debug_Event_Rendezvous_Exception : constant := 8;
  81    Debug_Event_Handled              : constant := 9;
  82    Debug_Event_Dependents_Exception : constant := 10;
  83    Debug_Event_Handled_Others       : constant := 11;
  84
  85    subtype Event_Kind_Type is Positive range 1 .. 11;
  86    --  Event kinds currently defined for debugging, used globally
  87    --  below and on a per task basis.
  88
  89    procedure Signal_Debug_Event
  90      (Event_Kind : Event_Kind_Type;
  91       Task_Value : Task_Id);
  92
  93    ----------------------------------
  94    -- VxWorks specific GDB support --
  95    ----------------------------------
  96
  97    --  Although the following routines are implemented in a target independent
  98    --  manner, only VxWorks currently uses them.
  99
 100    procedure Task_Creation_Hook (Thread : OS_Interface.Thread_Id);
 101    --  This procedure is used to notify GDB of task's creation. It must be
 102    --  called by the task's creator.
 103
 104    procedure Task_Termination_Hook;
 105    --  This procedure is used to notify GDB of task's termination
 106
 107    procedure Suspend_All_Tasks (Thread_Self : OS_Interface.Thread_Id);
 108    --  Suspend all the tasks except the one whose associated thread is
 109    --  Thread_Self by traversing All_Tasks_List and calling
 110    --  System.Task_Primitives.Operations.Suspend_Task.
 111
 112    procedure Resume_All_Tasks (Thread_Self : OS_Interface.Thread_Id);
 113    --  Resume all the tasks except the one whose associated thread is
 114    --  Thread_Self by traversing All_Tasks_List and calling
 115    --  System.Task_Primitives.Operations.Continue_Task.
 116
 117    procedure Stop_All_Tasks_Handler;
 118    --  Stop all the tasks by traversing All_Tasks_List and calling
 119    --  System.Task_Primitives.Operations.Stop_All_Task. This function
 120    --  can be used in an interrupt handler.
 121
 122    procedure Stop_All_Tasks;
 123    --  Stop all the tasks by traversing All_Tasks_List and calling
 124    --  System.Task_Primitives.Operations.Stop_Task.
 125
 126    procedure Continue_All_Tasks;
 127    --  Continue all the tasks by traversing All_Tasks_List and calling
 128    --  System.Task_Primitives.Operations.Continue_Task.
 129
 130    -------------------------------
 131    -- Run-time tracing routines --
 132    -------------------------------
 133
 134    procedure Trace
 135      (Self_Id  : Task_Id;
 136       Msg      : String;
 137       Flag     : Character;
 138       Other_Id : Task_Id := null);
 139    --  If traces for Flag are enabled, display on Standard_Error a given
 140    --  message for the current task. Other_Id is an optional second task id
 141    --  to display.
 142
 143    procedure Set_Trace
 144      (Flag  : Character;
 145       Value : Boolean := True);
 146    --  Enable or disable tracing for Flag. By default, flags in the range
 147    --  'A' .. 'Z' are disabled, others are enabled.
 148
 149    ---------------------------------
 150    -- Hooks for Valgrind/Helgrind --
 151    ---------------------------------
 152
 153    procedure Master_Hook
 154      (Dependent    : Task_Id;
 155       Parent       : Task_Id;
 156       Master_Level : Integer);
 157    --  Indicate to Valgrind/Helgrind that the master of Dependent is
 158    --  Parent + Master_Level.
 159
 160    procedure Master_Completed_Hook
 161      (Self_ID      : Task_Id;
 162       Master_Level : Integer);
 163    --  Indicate to Valgrind/Helgrind that Self_ID has completed the master
 164    --  Master_Level.
 165
 166 end System.Tasking.Debug;