Subversion Repositories openrisc

------------------------------------------------------------------------------

--                                                                          --

--                GNU ADA RUN-TIME LIBRARY (GNARL) COMPONENTS               --

--                                                                          --

--                   S Y S T E M - S T A C K _ U S A G E                    --

--                                                                          --

--                                 S p e c                                  --

--                                                                          --

--         Copyright (C) 2004-2011, 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 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.                                     --

--                                                                          --

-- 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.     --

--                                                                          --

------------------------------------------------------------------------------

with System;

with System.Storage_Elements;

with System.Address_To_Access_Conversions;

with Interfaces;

package System.Stack_Usage is

   pragma Preelaborate;

   package SSE renames System.Storage_Elements;

   subtype Stack_Address is SSE.Integer_Address;

   --  Address on the stack

   function To_Stack_Address

     (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.

      Stack_Size : Natural;

      --  Size of the stack

   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.

   --  Usage:

   --  A typical use of the package is something like:

   --  A : Stack_Analyzer;

   --  task T is

   --     pragma Storage_Size (A_Storage_Size);

   --  end T;

   --  [...]

   --     Bottom_Of_Stack : aliased Integer;

   --     --  Bottom_Of_Stack'Address will be used as an approximation of

   --     --  the bottom of stack. A good practise is to avoid allocating

   --     --  other local variables on this stack, as it would degrade

   --     --  the quality of this approximation.

   --  begin

   --     Initialize_Analyzer (A,

   --                          "Task t",

   --                          A_Storage_Size,

   --                          0,

   --                          A_Storage_Size - A_Guard,

   --                          To_Stack_Address (Bottom_Of_Stack'Address));

   --     Fill_Stack (A);

   --     Some_User_Code;

   --     Compute_Result (A);

   --     Report_Result (A);

   --  end T;

   --  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:

   --  Bottom offset:

   --     Description: The procedure used to fill the stack with a given

   --       pattern will itself have a stack frame. The value of the stack

   --       pointer in this procedure is, therefore, different from the value

   --       before the call to the instrumentation procedure.

   --     Strategy: The user of this package should measure the bottom of stack

   --       before the call to Fill_Stack and pass it in parameter. The impact

   --       is very minor unless the stack used is very small, but in this case

   --       you aren't very interested by the figure.

   --  Instrumentation threshold at writing:

   --     Description: The procedure used to fill the stack with a given

   --       pattern will itself have a stack frame.  Therefore, it will

   --       fill the stack after this stack frame. This part of the stack will

   --       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

   --       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

   --       computed, the pattern zone has been left untouched, we conclude

   --       that the stack usage is inferior to this minimum stack usage.

   --  Instrumentation threshold at reading:

   --    Description: The procedure used to read the stack at the end of the

   --      execution clobbers the stack by allocating its stack frame. If this

   --      stack frame is bigger than the total stack used by the user code at

   --      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 negligible.

   --   Pattern zone overflow:

   --     Description: The stack grows outer than the topmost bound of the

   --       pattern zone. In that case, the topmost region modified in the

   --       pattern is not the maximum value of the stack pointer during the

   --       execution.

   --     Strategy: At the end of the execution, the difference between the

   --       topmost memory region modified in the pattern zone and the

   --       topmost bound of the pattern zone can be understood as the

   --       biggest allocation that the method could have detect, provided

   --       that there is no "Untouched allocated zone" error and no "Pattern

   --       usage in user code" error. If no object in the user code is likely

   --       to have this size, this is not likely to happen.

   --   Pattern usage in user code:

   --     Description: The pattern can be found in the object of the user code.

   --       Therefore, the address space where this object has been allocated

   --       will appear as untouched.

   --     Strategy: Choose a pattern that is uncommon. 16#0000_0000# is the

   --       worst choice; 16#DEAD_BEEF# can be a good one. A good choice is an

   --       address which is not a multiple of 2, and which is not in the

   --       target address space. You can also change the pattern to see if it

   --       changes the measure. Note that this error *very* rarely influence

   --       the measure of the total stack usage: to have some influence, the

   --       pattern has to be used in the object that has been allocated on the

   --       topmost address of the used stack.

   --   Stack 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.

   --   Augmentation of the user stack frames:

   --     Description: The use of instrumentation object or procedure may

   --       augment the stack frame of the caller.

   --     Strategy: Do *not* inline the instrumentation procedures. Do *not*

   --       allocate the Stack_Analyzer object on the stack.

   --   Untouched allocated zone:

   --     Description: The user code may allocate objects that it will never

   --       touch. In that case, the pattern will not be changed.

   --     Strategy: There are no way to detect this error. Fortunately, this

   --       error is really rare, and it is most probably a bug in the user

   --       code, e.g. some uninitialized variable. It is (most of the time)

   --       harmless: it influences the measure only if the untouched allocated

   --       zone happens to be located at the topmost value of the stack

   --       pointer for the whole execution.

   procedure Initialize (Buffer_Size : Natural);

   pragma Export (C, Initialize, "__gnat_stack_usage_initialize");

   --  Initializes the size of the buffer that stores the results. Only the

   --  first Buffer_Size results are stored. Any results that do not fit in

   --  this buffer will be displayed on the fly.

   procedure Fill_Stack (Analyzer : in out Stack_Analyzer);

   --  Fill an area of the stack with the pattern Analyzer.Pattern. The size

   --  of this area is Analyzer.Size. After the call to this procedure,

   --  the memory will look like that:

   --

   --                                                             Stack growing

   --  ---------------------------------------------------------------------->

   --  |<--------------------->|<----------------------------------->|

   --  |  Stack frames to      | Memory filled with Analyzer.Pattern |

   --  |  Fill_Stack           |                                     |

   --  ^                       |                                     ^

   --  Analyzer.Stack_Base     |                      Analyzer.Pattern_Limit

   --                          ^

   --                    Analyzer.Pattern_Limit +/- Analyzer.Pattern_Size

   --

   procedure Initialize_Analyzer

     (Analyzer         : in out Stack_Analyzer;

      Task_Name        : String;

      Stack_Size       : Natural;

      Stack_Base       : Stack_Address;

      Pattern_Size     : Natural;

      Pattern          : Interfaces.Unsigned_32 := 16#DEAD_BEEF#);

   --  Should be called before any use of a Stack_Analyzer, to initialize it.

   --  Max_Pattern_Size is the size of the pattern zone, might be smaller than

   --  the full stack size 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 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:

   --  "instrumentation threshold at reading". See above. After the call

   --  to this procedure, the memory will look like:

   --

   --                                                             Stack growing

   --  ----------------------------------------------------------------------->

   --  |<---------------------->|<-------------->|<--------->|<--------->|

   --  |  Stack frames          | Array of       | used      |  Memory   |

   --  |  to Compute_Result     | Analyzer.Probe | during    |   filled  |

   --  |                        | elements       |  the      |    with   |

   --  |                        |                | execution |  pattern  |

   --  |                                                     |           |

   --  |<---------------------------------------------------->           |

   --                  Stack used                                        ^

   --                                                           Pattern_Limit

   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_Result in order to use as less stack as possible

   --  within a task.

   procedure Output_Results;

   --  Print the results computed so far on the standard output. Should be

   --  called when all tasks are dead.

   pragma Export (C, Output_Results, "__gnat_stack_usage_output_results");

private

   package Unsigned_32_Addr is

     new System.Address_To_Access_Conversions (Interfaces.Unsigned_32);

   subtype Pattern_Type is Interfaces.Unsigned_32;

   Bytes_Per_Pattern : constant := Pattern_Type'Object_Size / Storage_Unit;

   type Stack_Analyzer is record

      Task_Name : String (1 .. Task_Name_Length);

      --  Name of the task

      Stack_Base : Stack_Address;

      --  Address of the base of the stack, as given by the caller of

      --  Initialize_Analyzer.

      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

      Pattern_Limit : Stack_Address;

      --  Bound of the pattern area farthest to the base

      Topmost_Touched_Mark : Stack_Address;

      --  Topmost address of the pattern area whose value it is pointing

      --  at has been modified during execution. If the systematic error are

      --  compensated, it is the topmost value of the stack pointer during

      --  the execution.

      Pattern_Overlay_Address : System.Address;

      --  Address of the stack abstraction object we overlay over a

      --  task's real stack, typically a pattern-initialized array.

      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.

   end record;

   Environment_Task_Analyzer : Stack_Analyzer;

   Compute_Environment_Task  : Boolean;

   type Result_Array_Ptr is access all Result_Array_Type;

   Result_Array : Result_Array_Ptr;

   pragma Export (C, Result_Array, "__gnat_stack_usage_results");

   --  Exported in order to have an easy accessible symbol in when debugging

   Next_Id : Positive := 1;

   --  Id of the next stack analyzer

   function Stack_Size

     (SP_Low  : Stack_Address;

      SP_High : Stack_Address) return Natural;

   pragma Inline (Stack_Size);

   --  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.

end System.Stack_Usage;