1 ------------------------------------------------------------------------------
3 -- GNU ADA RUN-TIME LIBRARY (GNARL) COMPONENTS --
5 -- S Y S T E M - S T A C K _ U S A G E --
9 -- Copyright (C) 2004-2007, Free Software Foundation, Inc. --
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 2, 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. See the GNU General Public License --
17 -- for more details. You should have received a copy of the GNU General --
18 -- Public License distributed with GNARL; see file COPYING. If not, write --
19 -- to the Free Software Foundation, 51 Franklin Street, Fifth Floor, --
20 -- Boston, MA 02110-1301, USA. --
22 -- As a special exception, if other files instantiate generics from this --
23 -- unit, or you link this unit with other files to produce an executable, --
24 -- this unit does not by itself cause the resulting executable to be --
25 -- covered by the GNU General Public License. This exception does not --
26 -- however invalidate any other reasons why the executable file might be --
27 -- covered by the GNU Public License. --
29 -- GNARL was developed by the GNARL team at Florida State University. --
30 -- Extensive contributions were provided by Ada Core Technologies, Inc. --
32 ------------------------------------------------------------------------------
35 with System
.Storage_Elements
;
36 with System
.Address_To_Access_Conversions
;
39 package System
.Stack_Usage
is
42 package SSE
renames System
.Storage_Elements
;
44 Byte_Size
: constant := 8;
45 Unsigned_32_Size
: constant := 4 * Byte_Size
;
47 -- The alignment clause seems dubious, what about architectures where
48 -- the maximum alignment is less than 4???
49 -- Anyway, why not use Interfaces.Unsigned_32???
51 subtype Stack_Address
is SSE
.Integer_Address
;
52 -- Address on the stack
54 function To_Stack_Address
55 (Value
: System
.Address
) return Stack_Address
56 renames System
.Storage_Elements
.To_Integer
;
58 type Stack_Analyzer
is private;
59 -- Type of the stack analyzer tool. It is used to fill a portion of
60 -- the stack with Pattern, and to compute the stack used after some
65 -- A typical use of the package is something like:
67 -- A : Stack_Analyzer;
70 -- pragma Storage_Size (A_Storage_Size);
75 -- Bottom_Of_Stack : aliased Integer;
76 -- -- Bottom_Of_Stack'Address will be used as an approximation of
77 -- -- the bottom of stack. A good practise is to avoid allocating
78 -- -- other local variables on this stack, as it would degrade
79 -- -- the quality of this approximation.
82 -- Initialize_Analyzer (A,
84 -- A_Storage_Size - A_Guard,
86 -- To_Stack_Address (Bottom_Of_Stack'Address));
89 -- Compute_Result (A);
95 -- We are instrumenting the code to measure the stack used by the user
96 -- code. This method has a number of systematic errors, but several
97 -- methods can be used to evaluate or reduce those errors. Here are
98 -- those errors and the strategy that we use to deal with them:
102 -- Description: The procedure used to fill the stack with a given
103 -- pattern will itself have a stack frame. The value of the stack
104 -- pointer in this procedure is, therefore, different from the value
105 -- before the call to the instrumentation procedure.
107 -- Strategy: The user of this package should measure the bottom of stack
108 -- before the call to Fill_Stack and pass it in parameter.
110 -- Instrumentation threshold at writing:
112 -- Description: The procedure used to fill the stack with a given
113 -- pattern will itself have a stack frame. Therefore, it will
114 -- fill the stack after this stack frame. This part of the stack will
115 -- appear as used in the final measure.
117 -- Strategy: As the user passes the value of the bottom of stack to
118 -- the instrumentation to deal with the bottom offset error, and as as
119 -- the instrumentation procedure knows where the pattern filling start
120 -- on the stack, the difference between the two values is the minimum
121 -- stack usage that the method can measure. If, when the results are
122 -- computed, the pattern zone has been left untouched, we conclude
123 -- that the stack usage is inferior to this minimum stack usage.
125 -- Instrumentation threshold at reading:
127 -- Description: The procedure used to read the stack at the end of the
128 -- execution clobbers the stack by allocating its stack frame. If this
129 -- stack frame is bigger than the total stack used by the user code at
130 -- this point, it will increase the measured stack size.
132 -- Strategy: We could augment this stack frame and see if it changes the
133 -- measure. However, this error should be negligeable.
135 -- Pattern zone overflow:
137 -- Description: The stack grows outer than the topmost bound of the
138 -- pattern zone. In that case, the topmost region modified in the
139 -- pattern is not the maximum value of the stack pointer during the
142 -- Strategy: At the end of the execution, the difference between the
143 -- topmost memory region modified in the pattern zone and the
144 -- topmost bound of the pattern zone can be understood as the
145 -- biggest allocation that the method could have detect, provided
146 -- that there is no "Untouched allocated zone" error and no "Pattern
147 -- usage in user code" error. If no object in the user code is likely
148 -- to have this size, this is not likely to happen.
150 -- Pattern usage in user code:
152 -- Description: The pattern can be found in the object of the user code.
153 -- Therefore, the address space where this object has been allocated
154 -- will appear as untouched.
156 -- Strategy: Choose a pattern that is uncommon. 16#0000_0000# is the
157 -- worst choice; 16#DEAD_BEEF# can be a good one. A good choice is an
158 -- address which is not a multiple of 2, and which is not in the
159 -- target address space. You can also change the pattern to see if it
160 -- changes the measure. Note that this error *very* rarely influence
161 -- the measure of the total stack usage: to have some influence, the
162 -- pattern has to be used in the object that has been allocated on the
163 -- topmost address of the used stack.
167 -- Description: The pattern zone does not fit on the stack. This may
168 -- lead to an erroneous execution.
170 -- Strategy: Specify a storage size that is bigger than the size of the
171 -- pattern. 2 times bigger should be enough.
173 -- Augmentation of the user stack frames:
175 -- Description: The use of instrumentation object or procedure may
176 -- augment the stack frame of the caller.
178 -- Strategy: Do *not* inline the instrumentation procedures. Do *not*
179 -- allocate the Stack_Analyzer object on the stack.
181 -- Untouched allocated zone:
183 -- Description: The user code may allocate objects that it will never
184 -- touch. In that case, the pattern will not be changed.
186 -- Strategy: There are no way to detect this error. Fortunately, this
187 -- error is really rare, and it is most probably a bug in the user
188 -- code, e.g. some uninitialized variable. It is (most of the time)
189 -- harmless: it influences the measure only if the untouched allocated
190 -- zone happens to be located at the topmost value of the stack
191 -- pointer for the whole execution.
193 procedure Initialize
(Buffer_Size
: Natural);
194 pragma Export
(C
, Initialize
, "__gnat_stack_usage_initialize");
195 -- Initializes the size of the buffer that stores the results. Only the
196 -- first Buffer_Size results are stored. Any results that do not fit in
197 -- this buffer will be displayed on the fly.
199 procedure Fill_Stack
(Analyzer
: in out Stack_Analyzer
);
200 -- Fill an area of the stack with the pattern Analyzer.Pattern. The size
201 -- of this area is Analyzer.Size. After the call to this procedure,
202 -- the memory will look like that:
205 -- ----------------------------------------------------------------------->
206 -- |<---------------------->|<----------------------------------->|
207 -- | Stack frame | Memory filled with Analyzer.Pattern |
208 -- | of Fill_Stack | |
209 -- | (deallocated at | |
210 -- | the end of the call) | |
212 -- Analyzer.Bottom_Of_Stack ^ |
213 -- Analyzer.Bottom_Pattern_Mark ^
214 -- Analyzer.Top_Pattern_Mark
216 procedure Initialize_Analyzer
217 (Analyzer
: in out Stack_Analyzer
;
220 Overflow_Guard
: Natural;
221 Bottom
: Stack_Address
;
222 Pattern
: Interfaces
.Unsigned_32
:= 16#DEAD_BEEF#
);
223 -- Should be called before any use of a Stack_Analyzer, to initialize it.
224 -- Size is the size of the pattern zone. Bottom should be a close
225 -- approximation of the caller base frame address.
227 Is_Enabled
: Boolean := False;
228 -- When this flag is true, then stack analysis is enabled
230 procedure Compute_Result
(Analyzer
: in out Stack_Analyzer
);
231 -- Read the patern zone and deduce the stack usage. It should be called
232 -- from the same frame as Fill_Stack. If Analyzer.Probe is not null, an
233 -- array of Unsigned_32 with Analyzer.Probe elements is allocated on
234 -- Compute_Result's stack frame. Probe can be used to detect the error:
235 -- "instrumentation threshold at reading". See above. After the call
236 -- to this procedure, the memory will look like:
239 -- ----------------------------------------------------------------------->
240 -- |<---------------------->|<-------------->|<--------->|<--------->|
241 -- | Stack frame | Array of | used | Memory |
242 -- | of Compute_Result | Analyzer.Probe | during | filled |
243 -- | (deallocated at | elements | the | with |
244 -- | the end of the call) | | execution | pattern |
246 -- | Bottom_Pattern_Mark | | |
248 -- |<----------------------------------------------------> |
252 procedure Report_Result
(Analyzer
: Stack_Analyzer
);
253 -- Store the results of the computation in memory, at the address
254 -- corresponding to the symbol __gnat_stack_usage_results. This is not
255 -- done inside Compute_Resuls in order to use as less stack as possible
258 procedure Output_Results
;
259 -- Print the results computed so far on the standard output. Should be
260 -- called when all tasks are dead.
262 pragma Export
(C
, Output_Results
, "__gnat_stack_usage_output_results");
266 Task_Name_Length
: constant := 32;
267 -- The maximum length of task name displayed.
268 -- ??? Consider merging this variable with Max_Task_Image_Length.
270 package Unsigned_32_Addr
is
271 new System
.Address_To_Access_Conversions
(Interfaces
.Unsigned_32
);
273 type Stack_Analyzer
is record
274 Task_Name
: String (1 .. Task_Name_Length
);
278 -- Size of the pattern zone
280 Pattern
: Interfaces
.Unsigned_32
;
281 -- Pattern used to recognize untouched memory
283 Bottom_Pattern_Mark
: Stack_Address
;
284 -- Bound of the pattern area on the stack clostest to the bottom
286 Top_Pattern_Mark
: Stack_Address
;
287 -- Topmost bound of the pattern area on the stack
289 Topmost_Touched_Mark
: Stack_Address
;
290 -- Topmost address of the pattern area whose value it is pointing
291 -- at has been modified during execution. If the systematic error are
292 -- compensated, it is the topmost value of the stack pointer during
295 Bottom_Of_Stack
: Stack_Address
;
296 -- Address of the bottom of the stack, as given by the caller of
297 -- Initialize_Analyzer.
299 Array_Address
: System
.Address
;
300 -- Address of the array of Unsigned_32 that represents the pattern zone
302 First_Is_Topmost
: Boolean;
303 -- Set to true if the first element of the array of Unsigned_32 that
304 -- represents the pattern zone is at the topmost address of the
305 -- pattern zone; false if it is the bottommost address.
307 Result_Id
: Positive;
308 -- Id of the result. If less than value given to gnatbind -u corresponds
309 -- to the location in the result array of result for the current task.
311 Overflow_Guard
: Natural;
312 -- The amount of bytes that won't be analyzed in order to prevent
313 -- writing out of the stack
316 Environment_Task_Analyzer
: Stack_Analyzer
;
318 Compute_Environment_Task
: Boolean;
320 type Task_Result
is record
321 Task_Name
: String (1 .. Task_Name_Length
);
324 Overflow_Guard
: Natural;
327 type Result_Array_Type
is array (Positive range <>) of Task_Result
;
328 type Result_Array_Ptr
is access all Result_Array_Type
;
330 Result_Array
: Result_Array_Ptr
;
331 pragma Export
(C
, Result_Array
, "__gnat_stack_usage_results");
332 -- Exported in order to have an easy accessible symbol in when debugging
334 Next_Id
: Positive := 1;
335 -- Id of the next stack analyzer
338 (SP_Low
: Stack_Address
;
339 SP_High
: Stack_Address
) return Natural;
340 pragma Inline
(Stack_Size
);
341 -- Return the size of a portion of stack delimeted by SP_High and SP_Low
342 -- (), i.e. the difference between SP_High and SP_Low. The storage element
343 -- pointed by SP_Low is not included in the size. Inlined to reduce the
344 -- size of the stack used by the instrumentation code.
346 end System
.Stack_Usage
;