Subversion Repositories openrisc_me

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

--                                                                          --

--                         GNAT COMPILER COMPONENTS                         --

--                                                                          --

--                       G N A T . D E B U G _ P O O L S                    --

--                                                                          --

--                                 S p e c                                  --

--                                                                          --

--          Copyright (C) 1992-2009, Free Software Foundation, Inc.         --

--                                                                          --

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

--                                                                          --

-- GNAT was originally developed  by the GNAT team at  New York University. --

-- Extensive contributions were provided by Ada Core Technologies Inc.      --

--                                                                          --

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

--  This packages provides a special implementation of the Ada95 storage pools

--  The goal of this debug pool is to detect incorrect uses of memory

--  (multiple deallocations, access to invalid memory,...). Errors are reported

--  in one of two ways: either by immediately raising an exception, or by

--  printing a message on standard output or standard error.

--  You need to instrument your code to use this package: for each access type

--  you want to monitor, you need to add a clause similar to:

--      type Integer_Access is access Integer;

--      for Integer_Access'Storage_Pool use Pool;

--  where Pool is a tagged object declared with

--

--      Pool : GNAT.Debug_Pools.Debug_Pool;

--  This package was designed to be as efficient as possible, but still has an

--  impact on the performance of your code, which depends on the number of

--  allocations, deallocations and, somewhat less, dereferences that your

--  application performs.

--  For each faulty memory use, this debug pool will print several lines

--  of information, including things like the location where the memory

--  was initially allocated, the location where it was freed etc.

--  Physical allocations and deallocations are done through the usual system

--  calls. However, in order to provide proper checks, the debug pool will not

--  release the memory immediately. It keeps released memory around (the amount

--  kept around is configurable) so that it can distinguish between memory that

--  has not been allocated and memory that has been allocated but freed. This

--  also means that this memory cannot be reallocated, preventing what would

--  otherwise be a false indication that freed memory is now allocated.

--  In addition, this package presents several subprograms that help analyze

--  the behavior of your program, by reporting memory leaks, the total amount

--  of memory that was allocated. The pool is also designed to work correctly

--  in conjunction with gnatmem.

--  Finally, a subprogram Print_Pool is provided for use from the debugger

--  Limitations

--  ===========

--  Current limitation of this debug pool: if you use this debug pool for a

--  general access type ("access all"), the pool might report invalid

--  dereferences if the access object is pointing to another object on the

--  stack which was not allocated through a call to "new".

--  This debug pool will respect all alignments specified in your code, but

--  it does that by aligning all objects using Standard'Maximum_Alignment.

--  This allows faster checks, and limits the performance impact of using

--  this pool.

with System;                  use System;

with System.Storage_Elements; use System.Storage_Elements;

with System.Checked_Pools;

package GNAT.Debug_Pools is

   type Debug_Pool is new System.Checked_Pools.Checked_Pool with private;

   --  The new debug pool

   subtype SSC is System.Storage_Elements.Storage_Count;

   Default_Max_Freed         : constant SSC     := 50_000_000;

   Default_Stack_Trace_Depth : constant Natural := 20;

   Default_Reset_Content     : constant Boolean := False;

   Default_Raise_Exceptions  : constant Boolean := True;

   Default_Advanced_Scanning : constant Boolean := False;

   Default_Min_Freed         : constant SSC     := 0;

   Default_Errors_To_Stdout  : constant Boolean := True;

   Default_Low_Level_Traces  : constant Boolean := False;

   --  The above values are constants used for the parameters to Configure

   --  if not overridden in the call. See description of Configure for full

   --  details on these parameters. If these defaults are not satisfactory,

   --  then you need to call Configure to change the default values.

   procedure Configure

     (Pool                           : in out Debug_Pool;

      Stack_Trace_Depth              : Natural := Default_Stack_Trace_Depth;

      Maximum_Logically_Freed_Memory : SSC     := Default_Max_Freed;

      Minimum_To_Free                : SSC     := Default_Min_Freed;

      Reset_Content_On_Free          : Boolean := Default_Reset_Content;

      Raise_Exceptions               : Boolean := Default_Raise_Exceptions;

      Advanced_Scanning              : Boolean := Default_Advanced_Scanning;

      Errors_To_Stdout               : Boolean := Default_Errors_To_Stdout;

      Low_Level_Traces               : Boolean := Default_Low_Level_Traces);

   --  Subprogram used to configure the debug pool.

   --

   --    Stack_Trace_Depth. This parameter controls the maximum depth of stack

   --    traces that are output to indicate locations of actions for error

   --    conditions such as bad allocations. If set to zero, the debug pool

   --    will not try to compute backtraces. This is more efficient but gives

   --    less information on problem locations

   --

   --    Maximum_Logically_Freed_Memory: maximum amount of memory (bytes)

   --    that should be kept before starting to physically deallocate some.

   --    This value should be non-zero, since having memory that is logically

   --    but not physically freed helps to detect invalid memory accesses.

   --

   --    Minimum_To_Free is the minimum amount of memory that should be freed

   --    every time the pool starts physically releasing memory. The algorithm

   --    to compute which block should be physically released needs some

   --    expensive initialization (see Advanced_Scanning below), and this

   --    parameter can be used to limit the performance impact by ensuring

   --    that a reasonable amount of memory is freed each time. Even in the

   --    advanced scanning mode, marked blocks may be released to match this

   --    Minimum_To_Free parameter.

   --

   --    Reset_Content_On_Free: If true, then the contents of the freed memory

   --    is reset to the pattern 16#DEADBEEF#, following an old IBM convention.

   --    This helps in detecting invalid memory references from the debugger.

   --

   --    Raise_Exceptions: If true, the exceptions below will be raised every

   --    time an error is detected. If you set this to False, then the action

   --    is to generate output on standard error or standard output, depending

   --    on Errors_To_Stdout, noting the errors, but to

   --    keep running if possible (of course if storage is badly damaged, this

   --    attempt may fail. This helps to detect more than one error in a run.

   --

   --    Advanced_Scanning: If true, the pool will check the contents of all

   --    allocated blocks before physically releasing memory. Any possible

   --    reference to a logically free block will prevent its deallocation.

   --    Note that this algorithm is approximate, and it is recommended

   --    that you set Minimum_To_Free to a non-zero value to save time.

   --

   --    Errors_To_Stdout: Errors messages will be displayed on stdout if

   --    this parameter is True, or to stderr otherwise.

   --

   --    Low_Level_Traces: Traces all allocation and deallocations on the

   --    stream specified by Errors_To_Stdout. This can be used for

   --    post-processing by your own application, or to debug the

   --    debug_pool itself. The output indicates the size of the allocated

   --    block both as requested by the application and as physically

   --    allocated to fit the additional information needed by the debug

   --    pool.

   --

   --  All instantiations of this pool use the same internal tables. However,

   --  they do not store the same amount of information for the tracebacks,

   --  and they have different counters for maximum logically freed memory.

   Accessing_Not_Allocated_Storage : exception;

   --  Exception raised if Raise_Exception is True, and an attempt is made

   --  to access storage that was never allocated.

   Accessing_Deallocated_Storage : exception;

   --  Exception raised if Raise_Exception is True, and an attempt is made

   --  to access storage that was allocated but has been deallocated.

   Freeing_Not_Allocated_Storage : exception;

   --  Exception raised if Raise_Exception is True, and an attempt is made

   --  to free storage that had not been previously allocated.

   Freeing_Deallocated_Storage : exception;

   --  Exception raised if Raise_Exception is True, and an attempt is made

   --  to free storage that had already been freed.

   --  Note on the above exceptions. The distinction between not allocated

   --  and deallocated storage is not guaranteed to be accurate in the case

   --  where storage is allocated, and then physically freed. Larger values

   --  of the parameter Maximum_Logically_Freed_Memory will help to guarantee

   --  that this distinction is made more accurately.

   generic

      with procedure Put_Line (S : String) is <>;

      with procedure Put      (S : String) is <>;

   procedure Print_Info

     (Pool          : Debug_Pool;

      Cumulate      : Boolean := False;

      Display_Slots : Boolean := False;

      Display_Leaks : Boolean := False);

   --  Print out information about the High Water Mark, the current and

   --  total number of bytes allocated and the total number of bytes

   --  deallocated.

   --

   --  If Display_Slots is true, this subprogram prints a list of all the

   --  locations in the application that have done at least one allocation or

   --  deallocation. The result might be used to detect places in the program

   --  where lots of allocations are taking place. This output is not in any

   --  defined order.

   --

   --  If Cumulate if True, then each stack trace will display the number of

   --  allocations that were done either directly, or by the subprograms called

   --  at that location (e.g: if there were two physical allocations at a->b->c

   --  and a->b->d, then a->b would be reported as performing two allocations).

   --

   --  If Display_Leaks is true, then each block that has not been deallocated

   --  (often called a "memory leak") will be listed, along with the traceback

   --  showing where it was allocated. Not that no grouping of the blocks is

   --  done, you should use the Dump_Gnatmem procedure below in conjunction

   --  with the gnatmem utility.

   procedure Print_Info_Stdout

     (Pool          : Debug_Pool;

      Cumulate      : Boolean := False;

      Display_Slots : Boolean := False;

      Display_Leaks : Boolean := False);

   --  Standard instantiation of Print_Info to print on standard_output. More

   --  convenient to use where this is the intended location, and in particular

   --  easier to use from the debugger.

   procedure Dump_Gnatmem (Pool : Debug_Pool; File_Name : String);

   --  Create an external file on the disk, which can be processed by gnatmem

   --  to display the location of memory leaks.

   --

   --  This provides a nicer output that Print_Info above, and groups similar

   --  stack traces together. This also provides an easy way to save the memory

   --  status of your program for post-mortem analysis.

   --

   --  To use this file, use the following command line:

   --     gnatmem 5 -i <File_Name> <Executable_Name>

   --  If you want all the stack traces to be displayed with 5 levels.

   procedure Print_Pool (A : System.Address);

   pragma Export (C, Print_Pool, "print_pool");

   --  This subprogram is meant to be used from a debugger. Given an address in

   --  memory, it will print on standard output the known information about

   --  this address (provided, of course, the matching pointer is handled by

   --  the Debug_Pool).

   --

   --  The information includes the stacktrace for the allocation or

   --  deallocation of that memory chunk, its current status (allocated or

   --  logically freed), etc.

private

   --  The following are the standard primitive subprograms for a pool

   procedure Allocate

     (Pool                     : in out Debug_Pool;

      Storage_Address          : out Address;

      Size_In_Storage_Elements : Storage_Count;

      Alignment                : Storage_Count);

   --  Allocate a new chunk of memory, and set it up so that the debug pool

   --  can check accesses to its data, and report incorrect access later on.

   --  The parameters have the same semantics as defined in the ARM95.

   procedure Deallocate

     (Pool                     : in out Debug_Pool;

      Storage_Address          : Address;

      Size_In_Storage_Elements : Storage_Count;

      Alignment                : Storage_Count);

   --  Mark a block of memory as invalid. It might not be physically removed

   --  immediately, depending on the setup of the debug pool, so that checks

   --  are still possible. The parameters have the same semantics as defined

   --  in the RM.

   function Storage_Size (Pool : Debug_Pool) return SSC;

   --  Return the maximal size of data that can be allocated through Pool.

   --  Since Pool uses the malloc() system call, all the memory is accessible

   --  through the pool

   procedure Dereference

     (Pool                     : in out Debug_Pool;

      Storage_Address          : System.Address;

      Size_In_Storage_Elements : Storage_Count;

      Alignment                : Storage_Count);

   --  Check whether a dereference statement is valid, i.e. whether the pointer

   --  was allocated through Pool. As documented above, errors will be

   --  reported either by a special error message or an exception, depending

   --  on the setup of the storage pool.

   --  The parameters have the same semantics as defined in the ARM95.

   type Byte_Count is mod System.Max_Binary_Modulus;

   --  Type used for maintaining byte counts, needs to be large enough

   --  to accommodate counts allowing for repeated use of the same memory.

   type Debug_Pool is new System.Checked_Pools.Checked_Pool with record

      Stack_Trace_Depth              : Natural := Default_Stack_Trace_Depth;

      Maximum_Logically_Freed_Memory : SSC     := Default_Max_Freed;

      Reset_Content_On_Free          : Boolean := Default_Reset_Content;

      Raise_Exceptions               : Boolean := Default_Raise_Exceptions;

      Minimum_To_Free                : SSC     := Default_Min_Freed;

      Advanced_Scanning              : Boolean := Default_Advanced_Scanning;

      Errors_To_Stdout               : Boolean := Default_Errors_To_Stdout;

      Low_Level_Traces               : Boolean := Default_Low_Level_Traces;

      Allocated : Byte_Count := 0;

      --  Total number of bytes allocated in this pool

      Logically_Deallocated : Byte_Count := 0;

      --  Total number of bytes logically deallocated in this pool. This is the

      --  memory that the application has released, but that the pool has not

      --  yet physically released through a call to free(), to detect later

      --  accessed to deallocated memory.

      Physically_Deallocated : Byte_Count := 0;

      --  Total number of bytes that were free()-ed

      Marked_Blocks_Deallocated : Boolean := False;

      --  Set to true if some mark blocks had to be deallocated in the advanced

      --  scanning scheme. Since this is potentially dangerous, this is

      --  reported to the user, who might want to rerun his program with a

      --  lower Minimum_To_Free value.

      High_Water : Byte_Count := 0;

      --  Maximum of Allocated - Logically_Deallocated - Physically_Deallocated

      First_Free_Block : System.Address := System.Null_Address;

      Last_Free_Block  : System.Address := System.Null_Address;

      --  Pointers to the first and last logically freed blocks

      First_Used_Block : System.Address := System.Null_Address;

      --  Pointer to the list of currently allocated blocks. This list is

      --  used to list the memory leaks in the application on exit, as well as

      --  for the advanced freeing algorithms that needs to traverse all these

      --  blocks to find possible references to the block being physically

      --  freed.

   end record;

end GNAT.Debug_Pools;