gcc/ada/s-tasdeb.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                 GNU ADA 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 --                             $Revision$
  10 --                                                                          --
  11 --          Copyright (C) 1997-2001, Free Software Foundation, Inc.         --
  12 --                                                                          --
  13 -- GNARL is free software; you can  redistribute it  and/or modify it under --
  14 -- terms of the  GNU General Public License as published  by the Free Soft- --
  15 -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
  16 -- sion. GNARL is distributed in the hope that it will be useful, but WITH- --
  17 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  18 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  19 -- for  more details.  You should have  received  a copy of the GNU General --
  20 -- Public License  distributed with GNARL; see file COPYING.  If not, write --
  21 -- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
  22 -- MA 02111-1307, USA.                                                      --
  23 --                                                                          --
  24 -- As a special exception,  if other files  instantiate  generics from this --
  25 -- unit, or you link  this unit with other files  to produce an executable, --
  26 -- this  unit  does not  by itself cause  the resulting  executable  to  be --
  27 -- covered  by the  GNU  General  Public  License.  This exception does not --
  28 -- however invalidate  any other reasons why  the executable file  might be --
  29 -- covered by the  GNU Public License.                                      --
  30 --                                                                          --
  31 -- GNARL was developed by the GNARL team at Florida State University. It is --
  32 -- now maintained by Ada Core Technologies Inc. in cooperation with Florida --
  33 -- State University (http://www.gnat.com).                                  --
  34 --                                                                          --
  35 ------------------------------------------------------------------------------
  36
  37 --  This package encapsulates all direct interfaces to task debugging services
  38 --  that are needed by gdb with gnat mode (1.17 and higher)
  39
  40 with Interfaces.C;
  41 with System.Tasking;
  42 with System.OS_Interface;
  43
  44 package System.Tasking.Debug is
  45
  46    subtype int is Interfaces.C.int;
  47    subtype unsigned_long is Interfaces.C.unsigned_long;
  48
  49    package ST renames System.Tasking;
  50
  51    Known_Tasks : array (0 .. 999) of Task_ID;
  52    --  Global array of tasks read by gdb, and updated by
  53    --  Create_Task and Finalize_TCB
  54
  55    procedure Task_Creation_Hook (Thread : OS_Interface.Thread_Id);
  56    --  This procedure is used to notify VxGdb of task's creation.
  57    --  It must be called by the task's creator.
  58
  59    procedure Task_Termination_Hook;
  60    --  This procedure is used to notify VxGdb of task's termination.
  61
  62    function Self return Task_ID;
  63    --  return system ID of current task
  64
  65    procedure List_Tasks;
  66    --  Print a list of all the known Ada tasks with abbreviated state
  67    --  information, one-per-line, to the standard output file
  68
  69    procedure Print_Current_Task;
  70    procedure Print_Task_Info_Header;
  71    procedure Print_Task_Info (T : Task_ID);
  72    --  Write TASK_ID of current task, in hexadecimal, as one line, to
  73    --  the standard output file
  74    --
  75    --  Beware that Print_Current_Task may print garbage during an early
  76    --  stage of activation. There is a small window where a task is just
  77    --  initializing itself and has not yet recorded its own task Id.
  78    --
  79    --  Beware that Print_Current_Task will either not work at all or print
  80    --  garbage if it has interrupted a thread of control that does not
  81    --  correspond to any Ada task. For example, this is could happen if
  82    --  the debugger interrupts a signal handler that is using an alternate
  83    --  stack, or interrupts the dispatcher in the underlying thread
  84    --  implementation.
  85
  86    procedure Set_User_State (Value : Integer);
  87
  88    procedure Print_Accept_Info (T : Task_ID);
  89
  90    procedure Trace
  91      (Self_ID  : Task_ID;
  92       Msg      : String;
  93       Other_ID : Task_ID;
  94       Flag     : Character);
  95
  96    procedure Trace
  97      (Self_ID : Task_ID;
  98       Msg     : String;
  99       Flag    : Character);
 100
 101    procedure Trace
 102      (Msg  : String;
 103       Flag : Character);
 104
 105    procedure Trace
 106      (Msg      : String;
 107       Other_ID : Task_ID;
 108       Flag     : Character);
 109
 110    procedure Set_Trace
 111      (Flag  : Character;
 112       Value : Boolean := True);
 113
 114    function Image (T : Task_ID) return String;
 115
 116    procedure Suspend_All_Tasks (Thread_Self : OS_Interface.Thread_Id);
 117    --  Suspend all the tasks except the one whose associated thread is
 118    --  Thread_Self by traversing All_Tasks_Lists and calling
 119    --  System.Task_Primitives.Operations.Suspend_Task
 120    --  Such functionality is needed by gdb on some targets (e.g VxWorks)
 121    --  Warning: for efficiency purposes, there is no locking.
 122
 123    procedure Resume_All_Tasks (Thread_Self : OS_Interface.Thread_Id);
 124    --  Resume all the tasks except the one whose associated thread is
 125    --  Thread_Self by traversing All_Tasks_Lists and calling
 126    --  System.Task_Primitives.Operations.Continue_Task
 127    --  Such functionality is needed by gdb on some targets (e.g VxWorks)
 128    --  Warning: for efficiency purposes, there is no locking.
 129
 130 end System.Tasking.Debug;
 131
 132 -----------------------------
 133 -- Use of These Functions  --
 134 -----------------------------
 135
 136 --  Calling complicated functions from the debugger is generally pretty
 137 --  risky, especially in a multithreaded program.
 138
 139 --  The debugger may interrupt something that is not an Ada task,
 140 --  within the thread implementation, and which is not async-safe.
 141
 142 --  For example, under Solaris, it can interrupt code in "_dynamiclwps",
 143 --  which seems to serve as dispatcher when all the user threads are
 144 --  suspended. By experience, we have found that one cannot safely
 145 --  do certain things, apparently including calls to thread primitives
 146 --  from the debugger if the debugger has interrupted at one of these
 147 --  unsafe points. In general, if you interrupt a running program
 148 --  asynchronously (e.g. via control-C), it will not be safe to
 149 --  call the subprograms in this package.
 150
 151 -----------------
 152 -- Future work --
 153 -----------------
 154
 155 --  It would be nice to be able to tell whether execution has been
 156 --  interrupted in an Ada task. A heuristic way of checking this would
 157 --  be if we added to the Ada TCB a component that always contains a
 158 --  constant value that is unlikely to occur accidentally in code or
 159 --  data. We could then check this in the debugger-callable subprograms,
 160 --  and simply return an error code if it looks unsafe to proceed.
 161
 162 --  ???
 163 --  Recently we have added such a marker as a local variable of the
 164 --  task-wrapper routine. This allows Self to generate a fake ATCB for
 165 --  non-Ada threads of control. Given this capability, it is probably
 166 --  time to revisit the issue above.
 167
 168 --  DEADLOCK
 169
 170 --  We follow a simple rule here to avoid deadlock:
 171
 172 --  We do not use any locks in functions called by gdb, and we do not
 173 --  traverse linked lists.
 174 --
 175 --  The use of an array (Known_Tasks) has many advantages:
 176
 177 --   - Easy and fast to examine;
 178 --   - No risk of dangling references (to the next element) when traversing
 179 --     the array.