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