OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-dev/] [or1k-gcc/] [gcc/] [ada/] [s-stausa.ads] - Blame information for rev 706

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 706 jeremybenn
------------------------------------------------------------------------------
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
 
32
with System;
33
with System.Storage_Elements;
34
with System.Address_To_Access_Conversions;
35
with Interfaces;
36
 
37
package 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
 
274
private
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
 
339
end System.Stack_Usage;

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.