1------------------------------------------------------------------------------
2--                                                                          --
3--                         GNAT COMPILER COMPONENTS                         --
4--                                                                          --
5--               S Y S T E M . S E C O N D A R Y _ S T A C K                --
6--                                                                          --
7--                                 S p e c                                  --
8--                                                                          --
9--          Copyright (C) 1992-2013, Free Software Foundation, Inc.         --
10--                                                                          --
11-- GNAT 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-- GNAT was originally developed  by the GNAT team at  New York University. --
28-- Extensive contributions were provided by Ada Core Technologies Inc.      --
29--                                                                          --
30------------------------------------------------------------------------------
31
32pragma Compiler_Unit_Warning;
33
34with System.Storage_Elements;
35
36package System.Secondary_Stack is
37
38   package SSE renames System.Storage_Elements;
39
40   Default_Secondary_Stack_Size : Natural := 10 * 1024;
41   --  Default size of a secondary stack. May be modified by binder -D switch
42   --  which causes the binder to generate an appropriate assignment in the
43   --  binder generated file.
44
45   procedure SS_Init
46     (Stk  : in out Address;
47      Size : Natural := Default_Secondary_Stack_Size);
48   --  Initialize the secondary stack with a main stack of the given Size.
49   --
50   --  If System.Parameters.Sec_Stack_Percentage equals Dynamic, Stk is really
51   --  an OUT parameter that will be allocated on the heap. Then all further
52   --  allocations which do not overflow the main stack will not generate
53   --  dynamic (de)allocation calls. If the main Stack overflows, a new
54   --  chuck of at least the same size will be allocated and linked to the
55   --  previous chunk.
56   --
57   --  Otherwise (Sec_Stack_Percentage between 0 and 100), Stk is an IN
58   --  parameter that is already pointing to a Stack_Id. The secondary stack
59   --  in this case is fixed, and any attempt to allocate more than the initial
60   --  size will result in a Storage_Error being raised.
61   --
62   --  Note: the reason that Stk is passed is that SS_Init is called before
63   --  the proper interface is established to obtain the address of the
64   --  stack using System.Soft_Links.Get_Sec_Stack_Addr.
65
66   procedure SS_Allocate
67     (Addr         : out Address;
68      Storage_Size : SSE.Storage_Count);
69   --  Allocate enough space for a 'Storage_Size' bytes object with Maximum
70   --  alignment. The address of the allocated space is returned in Addr.
71
72   procedure SS_Free (Stk : in out Address);
73   --  Release the memory allocated for the Secondary Stack. That is
74   --  to say, all the allocated chunks. Upon return, Stk will be set
75   --  to System.Null_Address.
76
77   type Mark_Id is private;
78   --  Type used to mark the stack for mark/release processing
79
80   function SS_Mark return Mark_Id;
81   --  Return the Mark corresponding to the current state of the stack
82
83   procedure SS_Release (M : Mark_Id);
84   --  Restore the state of the stack corresponding to the mark M. If an
85   --  additional chunk have been allocated, it will never be freed during a
86   --  ??? missing comment here
87
88   function SS_Get_Max return Long_Long_Integer;
89   --  Return maximum used space in storage units for the current secondary
90   --  stack. For a dynamically allocated secondary stack, the returned
91   --  result is always -1. For a statically allocated secondary stack,
92   --  the returned value shows the largest amount of space allocated so
93   --  far during execution of the program to the current secondary stack,
94   --  i.e. the secondary stack for the current task.
95
96   generic
97      with procedure Put_Line (S : String);
98   procedure SS_Info;
99   --  Debugging procedure used to print out secondary Stack allocation
100   --  information. This procedure is generic in order to avoid a direct
101   --  dependance on a particular IO package.
102
103private
104   SS_Pool : Integer;
105   --  Unused entity that is just present to ease the sharing of the pool
106   --  mechanism for specific allocation/deallocation in the compiler
107
108   type SS_Ptr is new SSE.Integer_Address;
109   --  Stack pointer value for secondary stack
110
111   type Mark_Id is record
112      Sstk : System.Address;
113      Sptr : SS_Ptr;
114   end record;
115   --  A mark value contains the address of the secondary stack structure,
116   --  as returned by System.Soft_Links.Get_Sec_Stack_Addr, and a stack
117   --  pointer value corresponding to the point of the mark call.
118
119end System.Secondary_Stack;
120