gcc/ada/libgnat/s-stausa.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                GNU ADA RUN-TIME LIBRARY (GNARL) COMPONENTS               --
   4 --                                                                          --
   5 --                   S Y S T E M - S T A C K _ U S A G E                    --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --         Copyright (C) 2004-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 with System.Storage_Elements;
  33 with System.Address_To_Access_Conversions;
  34 with Interfaces;
  35
  36 package System.Stack_Usage is
  37    pragma Preelaborate;
  38
  39    package SSE renames System.Storage_Elements;
  40
  41    subtype Stack_Address is SSE.Integer_Address;
  42    --  Address on the stack
  43
  44    function To_Stack_Address
  45      (Value : System.Address) return Stack_Address
  46       renames System.Storage_Elements.To_Integer;
  47
  48    Task_Name_Length : constant := 32;
  49    --  The maximum length of task name displayed.
  50    --  ??? Consider merging this variable with Max_Task_Image_Length.
  51
  52    type Task_Result is record
  53       Task_Name : String (1 .. Task_Name_Length);
  54
  55       Value : Natural;
  56       --  Amount of stack used. The value is calculated on the basis of the
  57       --  mechanism used by GNAT to allocate it, and it is NOT a precise value.
  58
  59       Stack_Size : Natural;
  60       --  Size of the stack
  61    end record;
  62
  63    type Result_Array_Type is array (Positive range <>) of Task_Result;
  64
  65    type Stack_Analyzer is private;
  66    --  Type of the stack analyzer tool. It is used to fill a portion of the
  67    --  stack with Pattern, and to compute the stack used after some execution.
  68
  69    --  Note that Fill_Stack writes data past the current top of the stack
  70    --  (i.e. at addresses less than the stack pointer register, assuming the
  71    --  stack grows downward). Therefore, this package is incompatible with
  72    --  tools like Valgrind and DrMemory.
  73
  74    --  Usage:
  75
  76    --  A typical use of the package is something like:
  77
  78    --  A : Stack_Analyzer;
  79
  80    --  task T is
  81    --     pragma Storage_Size (A_Storage_Size);
  82    --  end T;
  83
  84    --  [...]
  85
  86    --     Bottom_Of_Stack : aliased Integer;
  87    --     --  Bottom_Of_Stack'Address will be used as an approximation of
  88    --     --  the bottom of stack. A good practise is to avoid allocating
  89    --     --  other local variables on this stack, as it would degrade
  90    --     --  the quality of this approximation.
  91
  92    --  begin
  93    --     Initialize_Analyzer (A,
  94    --                          "Task t",
  95    --                          A_Storage_Size,
  96    --                          0,
  97    --                          A_Storage_Size - A_Guard,
  98    --                          To_Stack_Address (Bottom_Of_Stack'Address));
  99    --     Fill_Stack (A);
 100    --     Some_User_Code;
 101    --     Compute_Result (A);
 102    --     Report_Result (A);
 103    --  end T;
 104
 105    --  Errors:
 106    --
 107    --  We are instrumenting the code to measure the stack used by the user
 108    --  code. This method has a number of systematic errors, but several methods
 109    --  can be used to evaluate or reduce those errors. Here are those errors
 110    --  and the strategy that we use to deal with them:
 111
 112    --  Bottom offset:
 113
 114    --     Description: The procedure used to fill the stack with a given
 115    --       pattern will itself have a stack frame. The value of the stack
 116    --       pointer in this procedure is, therefore, different from the value
 117    --       before the call to the instrumentation procedure.
 118
 119    --     Strategy: The user of this package should measure the bottom of stack
 120    --       before the call to Fill_Stack and pass it in parameter. The impact
 121    --       is very minor unless the stack used is very small, but in this case
 122    --       you aren't very interested by the figure.
 123
 124    --  Instrumentation threshold at writing:
 125
 126    --     Description: The procedure used to fill the stack with a given
 127    --       pattern will itself have a stack frame.  Therefore, it will
 128    --       fill the stack after this stack frame. This part of the stack will
 129    --       appear as used in the final measure.
 130
 131    --     Strategy: As the user passes the value of the bottom of stack to
 132    --       the instrumentation to deal with the bottom offset error, and as
 133    --       the instrumentation procedure knows where the pattern filling start
 134    --       on the stack, the difference between the two values is the minimum
 135    --       stack usage that the method can measure. If, when the results are
 136    --       computed, the pattern zone has been left untouched, we conclude
 137    --       that the stack usage is inferior to this minimum stack usage.
 138
 139    --  Instrumentation threshold at reading:
 140
 141    --    Description: The procedure used to read the stack at the end of the
 142    --      execution clobbers the stack by allocating its stack frame. If this
 143    --      stack frame is bigger than the total stack used by the user code at
 144    --      this point, it will increase the measured stack size.
 145
 146    --    Strategy: We could augment this stack frame and see if it changes the
 147    --      measure. However, this error should be negligible.
 148
 149    --   Pattern zone overflow:
 150
 151    --     Description: The stack grows outer than the topmost bound of the
 152    --       pattern zone. In that case, the topmost region modified in the
 153    --       pattern is not the maximum value of the stack pointer during the
 154    --       execution.
 155
 156    --     Strategy: At the end of the execution, the difference between the
 157    --       topmost memory region modified in the pattern zone and the
 158    --       topmost bound of the pattern zone can be understood as the
 159    --       biggest allocation that the method could have detect, provided
 160    --       that there is no "Untouched allocated zone" error and no "Pattern
 161    --       usage in user code" error. If no object in the user code is likely
 162    --       to have this size, this is not likely to happen.
 163
 164    --   Pattern usage in user code:
 165
 166    --     Description: The pattern can be found in the object of the user code.
 167    --       Therefore, the address space where this object has been allocated
 168    --       will appear as untouched.
 169
 170    --     Strategy: Choose a pattern that is uncommon. 16#0000_0000# is the
 171    --       worst choice; 16#DEAD_BEEF# can be a good one. A good choice is an
 172    --       address which is not a multiple of 2, and which is not in the
 173    --       target address space. You can also change the pattern to see if it
 174    --       changes the measure. Note that this error *very* rarely influence
 175    --       the measure of the total stack usage: to have some influence, the
 176    --       pattern has to be used in the object that has been allocated on the
 177    --       topmost address of the used stack.
 178
 179    --   Stack overflow:
 180
 181    --     Description: The pattern zone does not fit on the stack. This may
 182    --       lead to an erroneous execution.
 183
 184    --     Strategy: Specify a storage size that is bigger than the size of the
 185    --       pattern. 2 times bigger should be enough.
 186
 187    --   Augmentation of the user stack frames:
 188
 189    --     Description: The use of instrumentation object or procedure may
 190    --       augment the stack frame of the caller.
 191
 192    --     Strategy: Do *not* inline the instrumentation procedures. Do *not*
 193    --       allocate the Stack_Analyzer object on the stack.
 194
 195    --   Untouched allocated zone:
 196
 197    --     Description: The user code may allocate objects that it will never
 198    --       touch. In that case, the pattern will not be changed.
 199
 200    --     Strategy: There are no way to detect this error. Fortunately, this
 201    --       error is really rare, and it is most probably a bug in the user
 202    --       code, e.g. some uninitialized variable. It is (most of the time)
 203    --       harmless: it influences the measure only if the untouched allocated
 204    --       zone happens to be located at the topmost value of the stack
 205    --       pointer for the whole execution.
 206
 207    procedure Initialize (Buffer_Size : Natural);
 208    pragma Export (C, Initialize, "__gnat_stack_usage_initialize");
 209    --  Initializes the size of the buffer that stores the results. Only the
 210    --  first Buffer_Size results are stored. Any results that do not fit in
 211    --  this buffer will be displayed on the fly.
 212
 213    procedure Fill_Stack (Analyzer : in out Stack_Analyzer);
 214    --  Fill an area of the stack with the pattern Analyzer.Pattern. The size
 215    --  of this area is Analyzer.Size. After the call to this procedure,
 216    --  the memory will look like that:
 217    --
 218    --                                                             Stack growing
 219    --  ---------------------------------------------------------------------->
 220    --  |<--------------------->|<----------------------------------->|
 221    --  |  Stack frames to      | Memory filled with Analyzer.Pattern |
 222    --  |  Fill_Stack           |                                     |
 223    --  ^                       |                                     ^
 224    --  Analyzer.Stack_Base     |                      Analyzer.Pattern_Limit
 225    --                          ^
 226    --                    Analyzer.Pattern_Limit +/- Analyzer.Pattern_Size
 227    --
 228
 229    procedure Initialize_Analyzer
 230      (Analyzer         : in out Stack_Analyzer;
 231       Task_Name        : String;
 232       Stack_Size       : Natural;
 233       Stack_Base       : Stack_Address;
 234       Pattern_Size     : Natural;
 235       Pattern          : Interfaces.Unsigned_32 := 16#DEAD_BEEF#);
 236    --  Should be called before any use of a Stack_Analyzer, to initialize it.
 237    --  Max_Pattern_Size is the size of the pattern zone, might be smaller than
 238    --  the full stack size Stack_Size in order to take into account e.g. the
 239    --  secondary stack and a guard against overflow. The actual size taken
 240    --  will be readjusted with data already used at the time the stack is
 241    --  actually filled.
 242
 243    Is_Enabled : Boolean := False;
 244    --  When this flag is true, then stack analysis is enabled
 245
 246    procedure Compute_Result (Analyzer : in out Stack_Analyzer);
 247    --  Read the pattern zone and deduce the stack usage. It should be called
 248    --  from the same frame as Fill_Stack. If Analyzer.Probe is not null, an
 249    --  array of Unsigned_32 with Analyzer.Probe elements is allocated on
 250    --  Compute_Result's stack frame. Probe can be used to detect  the error:
 251    --  "instrumentation threshold at reading". See above. After the call
 252    --  to this procedure, the memory will look like:
 253    --
 254    --                                                             Stack growing
 255    --  ----------------------------------------------------------------------->
 256    --  |<---------------------->|<-------------->|<--------->|<--------->|
 257    --  |  Stack frames          | Array of       | used      |  Memory   |
 258    --  |  to Compute_Result     | Analyzer.Probe | during    |   filled  |
 259    --  |                        | elements       |  the      |    with   |
 260    --  |                        |                | execution |  pattern  |
 261    --  |                                                     |           |
 262    --  |<---------------------------------------------------->           |
 263    --                  Stack used                                        ^
 264    --                                                           Pattern_Limit
 265
 266    procedure Report_Result (Analyzer : Stack_Analyzer);
 267    --  Store the results of the computation in memory, at the address
 268    --  corresponding to the symbol __gnat_stack_usage_results. This is not
 269    --  done inside Compute_Result in order to use as less stack as possible
 270    --  within a task.
 271
 272    procedure Output_Results;
 273    --  Print the results computed so far on the standard output. Should be
 274    --  called when all tasks are dead.
 275
 276    pragma Export (C, Output_Results, "__gnat_stack_usage_output_results");
 277
 278 private
 279
 280    package Unsigned_32_Addr is
 281      new System.Address_To_Access_Conversions (Interfaces.Unsigned_32);
 282
 283    subtype Pattern_Type is Interfaces.Unsigned_32;
 284    Bytes_Per_Pattern : constant := Pattern_Type'Object_Size / Storage_Unit;
 285
 286    type Stack_Analyzer is record
 287       Task_Name : String (1 .. Task_Name_Length);
 288       --  Name of the task
 289
 290       Stack_Base : Stack_Address;
 291       --  Address of the base of the stack, as given by the caller of
 292       --  Initialize_Analyzer.
 293
 294       Stack_Size : Natural;
 295       --  Entire size of the analyzed stack
 296
 297       Pattern_Size : Natural;
 298       --  Size of the pattern zone
 299
 300       Pattern : Pattern_Type;
 301       --  Pattern used to recognize untouched memory
 302
 303       Pattern_Limit : Stack_Address;
 304       --  Bound of the pattern area farthest to the base
 305
 306       Topmost_Touched_Mark : Stack_Address;
 307       --  Topmost address of the pattern area whose value it is pointing
 308       --  at has been modified during execution. If the systematic error are
 309       --  compensated, it is the topmost value of the stack pointer during
 310       --  the execution.
 311
 312       Pattern_Overlay_Address : System.Address;
 313       --  Address of the stack abstraction object we overlay over a
 314       --  task's real stack, typically a pattern-initialized array.
 315
 316       Result_Id : Positive;
 317       --  Id of the result. If less than value given to gnatbind -u corresponds
 318       --  to the location in the result array of result for the current task.
 319    end record;
 320
 321    Environment_Task_Analyzer : Stack_Analyzer;
 322
 323    Compute_Environment_Task  : Boolean;
 324
 325    type Result_Array_Ptr is access all Result_Array_Type;
 326
 327    Result_Array : Result_Array_Ptr;
 328    pragma Export (C, Result_Array, "__gnat_stack_usage_results");
 329    --  Exported in order to have an easy accessible symbol in when debugging
 330
 331    Next_Id : Positive := 1;
 332    --  Id of the next stack analyzer
 333
 334    function Stack_Size
 335      (SP_Low  : Stack_Address;
 336       SP_High : Stack_Address) return Natural;
 337    pragma Inline (Stack_Size);
 338    --  Return the size of a portion of stack delimited by SP_High and SP_Low
 339    --  (), i.e. the difference between SP_High and SP_Low. The storage element
 340    --  pointed by SP_Low is not included in the size. Inlined to reduce the
 341    --  size of the stack used by the instrumentation code.
 342
 343 end System.Stack_Usage;