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-2009, 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 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. --
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. --
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/>. --
27 -- GNARL was developed by the GNARL team at Florida State University. --
28 -- Extensive contributions were provided by Ada Core Technologies, Inc. --
30 ------------------------------------------------------------------------------
33 with System.Storage_Elements;
34 with System.Address_To_Access_Conversions;
37 package System.Stack_Usage is
40 package SSE renames System.Storage_Elements;
42 subtype Stack_Address is SSE.Integer_Address;
43 -- Address on the stack
45 function To_Stack_Address
46 (Value : System.Address) return Stack_Address
47 renames System.Storage_Elements.To_Integer;
49 Task_Name_Length : constant := 32;
50 -- The maximum length of task name displayed.
51 -- ??? Consider merging this variable with Max_Task_Image_Length.
53 type Task_Result is record
54 Task_Name : String (1 .. Task_Name_Length);
57 -- Amount of the stack used; the value is calculated on the basis of
58 -- the mechanism used by GNAT to allocate it, and it is NOT a precise
62 -- Possible variation in the amount of used stack. The real stack usage
63 -- may vary in the range Value +/- Variation
68 type Result_Array_Type is array (Positive range <>) of Task_Result;
70 type Stack_Analyzer is private;
71 -- Type of the stack analyzer tool. It is used to fill a portion of the
72 -- stack with Pattern, and to compute the stack used after some execution.
76 -- A typical use of the package is something like:
78 -- A : Stack_Analyzer;
81 -- pragma Storage_Size (A_Storage_Size);
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.
93 -- Initialize_Analyzer (A,
95 -- A_Storage_Size - A_Guard,
97 -- To_Stack_Address (Bottom_Of_Stack'Address));
100 -- Compute_Result (A);
101 -- Report_Result (A);
106 -- We are instrumenting the code to measure the stack used by the user
107 -- code. This method has a number of systematic errors, but several methods
108 -- can be used to evaluate or reduce those errors. Here are those errors
109 -- and the strategy that we use to deal with them:
113 -- Description: The procedure used to fill the stack with a given
114 -- pattern will itself have a stack frame. The value of the stack
115 -- pointer in this procedure is, therefore, different from the value
116 -- before the call to the instrumentation procedure.
118 -- Strategy: The user of this package should measure the bottom of stack
119 -- before the call to Fill_Stack and pass it in parameter.
121 -- Instrumentation threshold at writing:
123 -- Description: The procedure used to fill the stack with a given
124 -- pattern will itself have a stack frame. Therefore, it will
125 -- fill the stack after this stack frame. This part of the stack will
126 -- appear as used in the final measure.
128 -- Strategy: As the user passes the value of the bottom of stack to
129 -- the instrumentation to deal with the bottom offset error, and as
130 -- the instrumentation procedure knows where the pattern filling start
131 -- on the stack, the difference between the two values is the minimum
132 -- stack usage that the method can measure. If, when the results are
133 -- computed, the pattern zone has been left untouched, we conclude
134 -- that the stack usage is inferior to this minimum stack usage.
136 -- Instrumentation threshold at reading:
138 -- Description: The procedure used to read the stack at the end of the
139 -- execution clobbers the stack by allocating its stack frame. If this
140 -- stack frame is bigger than the total stack used by the user code at
141 -- this point, it will increase the measured stack size.
143 -- Strategy: We could augment this stack frame and see if it changes the
144 -- measure. However, this error should be negligible.
146 -- Pattern zone overflow:
148 -- Description: The stack grows outer than the topmost bound of the
149 -- pattern zone. In that case, the topmost region modified in the
150 -- pattern is not the maximum value of the stack pointer during the
153 -- Strategy: At the end of the execution, the difference between the
154 -- topmost memory region modified in the pattern zone and the
155 -- topmost bound of the pattern zone can be understood as the
156 -- biggest allocation that the method could have detect, provided
157 -- that there is no "Untouched allocated zone" error and no "Pattern
158 -- usage in user code" error. If no object in the user code is likely
159 -- to have this size, this is not likely to happen.
161 -- Pattern usage in user code:
163 -- Description: The pattern can be found in the object of the user code.
164 -- Therefore, the address space where this object has been allocated
165 -- will appear as untouched.
167 -- Strategy: Choose a pattern that is uncommon. 16#0000_0000# is the
168 -- worst choice; 16#DEAD_BEEF# can be a good one. A good choice is an
169 -- address which is not a multiple of 2, and which is not in the
170 -- target address space. You can also change the pattern to see if it
171 -- changes the measure. Note that this error *very* rarely influence
172 -- the measure of the total stack usage: to have some influence, the
173 -- pattern has to be used in the object that has been allocated on the
174 -- topmost address of the used stack.
178 -- Description: The pattern zone does not fit on the stack. This may
179 -- lead to an erroneous execution.
181 -- Strategy: Specify a storage size that is bigger than the size of the
182 -- pattern. 2 times bigger should be enough.
184 -- Augmentation of the user stack frames:
186 -- Description: The use of instrumentation object or procedure may
187 -- augment the stack frame of the caller.
189 -- Strategy: Do *not* inline the instrumentation procedures. Do *not*
190 -- allocate the Stack_Analyzer object on the stack.
192 -- Untouched allocated zone:
194 -- Description: The user code may allocate objects that it will never
195 -- touch. In that case, the pattern will not be changed.
197 -- Strategy: There are no way to detect this error. Fortunately, this
198 -- error is really rare, and it is most probably a bug in the user
199 -- code, e.g. some uninitialized variable. It is (most of the time)
200 -- harmless: it influences the measure only if the untouched allocated
201 -- zone happens to be located at the topmost value of the stack
202 -- pointer for the whole execution.
204 procedure Initialize (Buffer_Size : Natural);
205 pragma Export (C, Initialize, "__gnat_stack_usage_initialize");
206 -- Initializes the size of the buffer that stores the results. Only the
207 -- first Buffer_Size results are stored. Any results that do not fit in
208 -- this buffer will be displayed on the fly.
210 procedure Fill_Stack (Analyzer : in out Stack_Analyzer);
211 -- Fill an area of the stack with the pattern Analyzer.Pattern. The size
212 -- of this area is Analyzer.Size. After the call to this procedure,
213 -- the memory will look like that:
216 -- ----------------------------------------------------------------------->
217 -- |<---------------------->|<----------------------------------->|
218 -- | Stack frame | Memory filled with Analyzer.Pattern |
219 -- | of Fill_Stack | |
220 -- | (deallocated at | |
221 -- | the end of the call) | |
223 -- Analyzer.Bottom_Of_Stack ^ |
224 -- Analyzer.Bottom_Pattern_Mark ^
225 -- Analyzer.Top_Pattern_Mark
227 procedure Initialize_Analyzer
228 (Analyzer : in out Stack_Analyzer;
230 My_Stack_Size : Natural;
231 Max_Pattern_Size : Natural;
232 Bottom : Stack_Address;
233 Pattern : Interfaces.Unsigned_32 := 16#DEAD_BEEF#);
234 -- Should be called before any use of a Stack_Analyzer, to initialize it.
235 -- Max_Pattern_Size is the size of the pattern zone, might be smaller than
236 -- the full stack size in order to take into account e.g. the secondary
237 -- stack and a guard against overflow. The actual size taken will be
238 -- readjusted with data already used at the time the stack is actually
241 Is_Enabled : Boolean := False;
242 -- When this flag is true, then stack analysis is enabled
244 procedure Compute_Result (Analyzer : in out Stack_Analyzer);
245 -- Read the pattern zone and deduce the stack usage. It should be called
246 -- from the same frame as Fill_Stack. If Analyzer.Probe is not null, an
247 -- array of Unsigned_32 with Analyzer.Probe elements is allocated on
248 -- Compute_Result's stack frame. Probe can be used to detect the error:
249 -- "instrumentation threshold at reading". See above. After the call
250 -- to this procedure, the memory will look like:
253 -- ----------------------------------------------------------------------->
254 -- |<---------------------->|<-------------->|<--------->|<--------->|
255 -- | Stack frame | Array of | used | Memory |
256 -- | of Compute_Result | Analyzer.Probe | during | filled |
257 -- | (deallocated at | elements | the | with |
258 -- | the end of the call) | | execution | pattern |
260 -- | Bottom_Pattern_Mark | | |
262 -- |<----------------------------------------------------> |
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
272 procedure Output_Results;
273 -- Print the results computed so far on the standard output. Should be
274 -- called when all tasks are dead.
276 pragma Export (C, Output_Results, "__gnat_stack_usage_output_results");
280 package Unsigned_32_Addr is
281 new System.Address_To_Access_Conversions (Interfaces.Unsigned_32);
283 subtype Pattern_Type is Interfaces.Unsigned_32;
284 Bytes_Per_Pattern : constant := Pattern_Type'Object_Size / Storage_Unit;
286 type Stack_Analyzer is record
287 Task_Name : String (1 .. Task_Name_Length);
290 Stack_Size : Natural;
291 -- Entire size of the analyzed stack
293 Pattern_Size : Natural;
294 -- Size of the pattern zone
296 Pattern : Pattern_Type;
297 -- Pattern used to recognize untouched memory
299 Bottom_Pattern_Mark : Stack_Address;
300 -- Bound of the pattern area on the stack closest to the bottom
302 Top_Pattern_Mark : Stack_Address;
303 -- Topmost bound of the pattern area on the stack
305 Topmost_Touched_Mark : Stack_Address;
306 -- Topmost address of the pattern area whose value it is pointing
307 -- at has been modified during execution. If the systematic error are
308 -- compensated, it is the topmost value of the stack pointer during
311 Bottom_Of_Stack : Stack_Address;
312 -- Address of the bottom of the stack, as given by the caller of
313 -- Initialize_Analyzer.
315 Stack_Overlay_Address : System.Address;
316 -- Address of the stack abstraction object we overlay over a
317 -- task's real stack, typically a pattern-initialized array.
319 Result_Id : Positive;
320 -- Id of the result. If less than value given to gnatbind -u corresponds
321 -- to the location in the result array of result for the current task.
324 Environment_Task_Analyzer : Stack_Analyzer;
326 Compute_Environment_Task : Boolean;
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 delimited 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;