-- --
-- S p e c --
-- --
--- Copyright (C) 2004-2007, Free Software Foundation, Inc. --
+-- Copyright (C) 2004-2009, Free Software Foundation, Inc. --
-- --
-- GNARL is free software; you can redistribute it and/or modify it under --
-- terms of the GNU General Public License as published by the Free Soft- --
--- ware Foundation; either version 2, or (at your option) any later ver- --
--- sion. GNARL is distributed in the hope that it will be useful, but WITH- --
+-- ware Foundation; either version 3, or (at your option) any later ver- --
+-- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
-- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
--- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
--- for more details. You should have received a copy of the GNU General --
--- Public License distributed with GNARL; see file COPYING. If not, write --
--- to the Free Software Foundation, 51 Franklin Street, Fifth Floor, --
--- Boston, MA 02110-1301, USA. --
+-- or FITNESS FOR A PARTICULAR PURPOSE. --
-- --
--- As a special exception, if other files instantiate generics from this --
--- unit, or you link this unit with other files to produce an executable, --
--- this unit does not by itself cause the resulting executable to be --
--- covered by the GNU General Public License. This exception does not --
--- however invalidate any other reasons why the executable file might be --
--- covered by the GNU Public License. --
+-- As a special exception under Section 7 of GPL version 3, you are granted --
+-- additional permissions described in the GCC Runtime Library Exception, --
+-- version 3.1, as published by the Free Software Foundation. --
+-- --
+-- You should have received a copy of the GNU General Public License and --
+-- a copy of the GCC Runtime Library Exception along with this program; --
+-- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
+-- <http://www.gnu.org/licenses/>. --
-- --
-- GNARL was developed by the GNARL team at Florida State University. --
-- Extensive contributions were provided by Ada Core Technologies, Inc. --
package SSE renames System.Storage_Elements;
- -- The alignment clause seems dubious, what about architectures where
- -- the maximum alignment is less than 4???
- -- Anyway, why not use Interfaces.Unsigned_32???
-
subtype Stack_Address is SSE.Integer_Address;
-- Address on the stack
(Value : System.Address) return Stack_Address
renames System.Storage_Elements.To_Integer;
+ Task_Name_Length : constant := 32;
+ -- The maximum length of task name displayed.
+ -- ??? Consider merging this variable with Max_Task_Image_Length.
+
+ type Task_Result is record
+ Task_Name : String (1 .. Task_Name_Length);
+
+ Value : Natural;
+ -- Amount of stack used. The value is calculated on the basis of the
+ -- mechanism used by GNAT to allocate it, and it is NOT a precise value.
+
+ Variation : Natural;
+ -- Possible variation in the amount of used stack. The real stack usage
+ -- may vary in the range Value +/- Variation
+
+ Max_Size : Natural;
+ end record;
+
+ type Result_Array_Type is array (Positive range <>) of Task_Result;
+
type Stack_Analyzer is private;
- -- Type of the stack analyzer tool. It is used to fill a portion of
- -- the stack with Pattern, and to compute the stack used after some
- -- execution.
+ -- Type of the stack analyzer tool. It is used to fill a portion of the
+ -- stack with Pattern, and to compute the stack used after some execution.
-- Usage:
-- Errors:
--
-- We are instrumenting the code to measure the stack used by the user
- -- code. This method has a number of systematic errors, but several
- -- methods can be used to evaluate or reduce those errors. Here are
- -- those errors and the strategy that we use to deal with them:
+ -- code. This method has a number of systematic errors, but several methods
+ -- can be used to evaluate or reduce those errors. Here are those errors
+ -- and the strategy that we use to deal with them:
-- Bottom offset:
-- appear as used in the final measure.
-- Strategy: As the user passes the value of the bottom of stack to
- -- the instrumentation to deal with the bottom offset error, and as as
+ -- the instrumentation to deal with the bottom offset error, and as
-- the instrumentation procedure knows where the pattern filling start
-- on the stack, the difference between the two values is the minimum
-- stack usage that the method can measure. If, when the results are
-- this point, it will increase the measured stack size.
-- Strategy: We could augment this stack frame and see if it changes the
- -- measure. However, this error should be negligeable.
+ -- measure. However, this error should be negligible.
-- Pattern zone overflow:
-- Description: The pattern zone does not fit on the stack. This may
-- lead to an erroneous execution.
- -- Strategy: Specify a storage size that is bigger than the size of the
- -- pattern. 2 times bigger should be enough.
+ -- Strategy: Specify a storage size that is bigger than the size of the
+ -- pattern. 2 times bigger should be enough.
-- Augmentation of the user stack frames:
-- Analyzer.Top_Pattern_Mark
procedure Initialize_Analyzer
- (Analyzer : in out Stack_Analyzer;
- Task_Name : String;
- Size : Natural;
- Overflow_Guard : Natural;
- Bottom : Stack_Address;
- Pattern : Interfaces.Unsigned_32 := 16#DEAD_BEEF#);
+ (Analyzer : in out Stack_Analyzer;
+ Task_Name : String;
+ My_Stack_Size : Natural;
+ Max_Pattern_Size : Natural;
+ Bottom : Stack_Address;
+ Pattern : Interfaces.Unsigned_32 := 16#DEAD_BEEF#);
-- Should be called before any use of a Stack_Analyzer, to initialize it.
- -- Size is the size of the pattern zone. Bottom should be a close
- -- approximation of the caller base frame address.
+ -- Max_Pattern_Size is the size of the pattern zone, might be smaller than
+ -- the full stack size in order to take into account e.g. the secondary
+ -- stack and a guard against overflow. The actual size taken will be
+ -- readjusted with data already used at the time the stack is actually
+ -- filled.
Is_Enabled : Boolean := False;
-- When this flag is true, then stack analysis is enabled
procedure Compute_Result (Analyzer : in out Stack_Analyzer);
- -- Read the patern zone and deduce the stack usage. It should be called
+ -- Read the pattern zone and deduce the stack usage. It should be called
-- from the same frame as Fill_Stack. If Analyzer.Probe is not null, an
-- array of Unsigned_32 with Analyzer.Probe elements is allocated on
-- Compute_Result's stack frame. Probe can be used to detect the error:
procedure Report_Result (Analyzer : Stack_Analyzer);
-- Store the results of the computation in memory, at the address
-- corresponding to the symbol __gnat_stack_usage_results. This is not
- -- done inside Compute_Resuls in order to use as less stack as possible
+ -- done inside Compute_Result in order to use as less stack as possible
-- within a task.
procedure Output_Results;
private
- Task_Name_Length : constant := 32;
- -- The maximum length of task name displayed.
- -- ??? Consider merging this variable with Max_Task_Image_Length.
-
package Unsigned_32_Addr is
new System.Address_To_Access_Conversions (Interfaces.Unsigned_32);
Task_Name : String (1 .. Task_Name_Length);
-- Name of the task
- Size : Natural;
+ Stack_Size : Natural;
+ -- Entire size of the analyzed stack
+
+ Pattern_Size : Natural;
-- Size of the pattern zone
Pattern : Pattern_Type;
-- Pattern used to recognize untouched memory
Bottom_Pattern_Mark : Stack_Address;
- -- Bound of the pattern area on the stack clostest to the bottom
+ -- Bound of the pattern area on the stack closest to the bottom
Top_Pattern_Mark : Stack_Address;
-- Topmost bound of the pattern area on the stack
Result_Id : Positive;
-- Id of the result. If less than value given to gnatbind -u corresponds
-- to the location in the result array of result for the current task.
-
- Overflow_Guard : Natural;
- -- The amount of bytes that won't be analyzed in order to prevent
- -- writing out of the stack
end record;
Environment_Task_Analyzer : Stack_Analyzer;
Compute_Environment_Task : Boolean;
- type Task_Result is record
- Task_Name : String (1 .. Task_Name_Length);
- Measure : Natural;
- Max_Size : Natural;
- Overflow_Guard : Natural;
- end record;
-
- type Result_Array_Type is array (Positive range <>) of Task_Result;
type Result_Array_Ptr is access all Result_Array_Type;
Result_Array : Result_Array_Ptr;
(SP_Low : Stack_Address;
SP_High : Stack_Address) return Natural;
pragma Inline (Stack_Size);
- -- Return the size of a portion of stack delimeted by SP_High and SP_Low
+ -- Return the size of a portion of stack delimited by SP_High and SP_Low
-- (), i.e. the difference between SP_High and SP_Low. The storage element
-- pointed by SP_Low is not included in the size. Inlined to reduce the
-- size of the stack used by the instrumentation code.