1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME COMPONENTS --
9 -- Copyright (C) 1999-2004 Free Software Foundation, Inc. --
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 2, 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. See the GNU General Public License --
17 -- for more details. You should have received a copy of the GNU General --
18 -- Public License distributed with GNAT; see file COPYING. If not, write --
19 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
20 -- MA 02111-1307, USA. --
22 -- GNAT was originally developed by the GNAT team at New York University. --
23 -- Extensive contributions were provided by Ada Core Technologies Inc. --
25 ------------------------------------------------------------------------------
27 -- This package obtains parameters from the target runtime version of
28 -- System, to indicate parameters relevant to the target environment.
30 -- Conceptually, these parameters could be obtained using rtsfind, but
31 -- we do not do this for four reasons:
33 -- 1. Compiling System for every compilation wastes time
35 -- 2. This compilation impedes debugging by adding extra compile steps
37 -- 3. There are recursion problems coming from compiling System itself
38 -- or any of its children.
40 -- 4. The binder also needs the parameters, and we do not want to have
41 -- to drag a lot of front end stuff into the binder.
43 -- For all these reasons, we read in the source of System, and then scan
44 -- it at the text level to extract the parameter values.
46 -- Note however, that later on, when the ali file is written, we make sure
47 -- that the System file is at least parsed, so that the checksum is properly
48 -- computed and set in the ali file. This partially negates points 1 and 2
49 -- above although just parsing is quick and does not impact debugging much.
51 -- The parameters acquired by this routine from system.ads fall into three
54 -- 1. Configuration pragmas, that must appear at the start of the file.
55 -- Any such pragmas automatically apply to any unit compiled in the
56 -- presence of this system file. Only a limited set of such pragmas
57 -- may appear as documented in the corresponding section below,
59 -- 2. Target parameters. These are boolean constants that are defined
60 -- in the private part of the package giving fixed information
61 -- about the target architecture, and the capabilities of the
62 -- code generator and run-time library.
64 -- 3. Identification information. This is an optional string constant
65 -- that gives the name of the run-time library configuration. This
66 -- line may be ommitted for a version of system.ads to be used with
67 -- the full Ada 95 run time.
69 with Rident; use Rident;
70 with Types; use Types;
74 ---------------------------
75 -- Configuration Pragmas --
76 ---------------------------
78 -- The following switches get set if the corresponding configuration
79 -- pragma is scanned from the source of system.ads. No other pragmas
80 -- are permitted to appear at the start of the system.ads source file.
82 -- If a pragma Discard_Names appears, then Opt.Global_Discard_Names is
83 -- set to True to indicate that all units must be compiled in this mode.
85 -- If a pragma Locking_Policy appears, then Opt.Locking_Policy is set
86 -- to the first character of the policy name, and Opt.Locking_Policy_Sloc
87 -- is set to System_Location.
89 -- If a pragma Normalize_Scalars appears, then Opt.Normalize_Scalars
90 -- is set True, as well as Opt.Init_Or_Norm_Scalars.
92 -- If a pragma Queuing_Policy appears, then Opt.Queuing_Policy is set
93 -- to the first character of the policy name, and Opt.Queuing_Policy_Sloc
94 -- is set to System_Location.
96 -- If a pragma Task_Dispatching_Policy appears, then the flag
97 -- Opt.Task_Dispatching_Policy is set to the first character of the
98 -- policy name, and Opt.Task_Dispatching_Policy_Sloc is set to
101 -- If a pragma Polling (On) appears, then the flag Opt.Polling_Required
104 -- if a pragma Suppress_Exception_Locations appears, then the flag
105 -- Opt.Exception_Locations_Suppressed is set to True.
107 -- The only other pragma allowed is a pragma Restrictions that specifies
108 -- a restriction that will be imposed on all units in the partition. Note
109 -- that in this context, only one restriction can be specified in a single
110 -- pragma, and the pragma must appear on its own on a single source line.
112 Restrictions_On_Target : Restrictions_Info;
113 -- Records restrictions specified by system.ads. Only the Set and Value
114 -- members are modified. The Violated and Count fields are never modified.
120 -- This parameter should be regarded as read only by all clients of
121 -- of package. The only way they get modified is by calling the
122 -- Get_Target_Parameters routine which reads the values from a provided
123 -- text buffer containing the source of the system package.
125 -- The corresponding string constant is placed immediately at the start
126 -- of the private part of system.ads if is present, e.g. in the form:
128 -- Run_Time_Name : constant String := "Zero Footprint Run Time";
130 -- the corresponding messages will look something like
132 -- xxx not supported (Zero Footprint Run Time)
134 Run_Time_Name_On_Target : Name_Id := No_Name;
135 -- Set to appropriate names table entry Id value if a Run_Time_Name
136 -- string constant is defined in system.ads. This name is used only
137 -- for the configurable run-time case, and is used to parametrize
138 -- messages that complain about non-supported run-time features.
139 -- The name should contain only letters A-Z, digits 1-9, spaces,
142 -----------------------
143 -- Target Parameters --
144 -----------------------
146 -- The following parameters correspond to the variables defined in the
147 -- private part of System (without the terminating _On_Target). Note
148 -- that it is required that all parameters defined here be specified
149 -- in the target specific version of system.ads (there are no defaults).
151 -- All these parameters should be regarded as read only by all clients
152 -- of the package. The only way they get modified is by calling the
153 -- Get_Target_Parameters routine which reads the values from a provided
154 -- text buffer containing the source of the system package.
156 ----------------------------
157 -- Special Target Control --
158 ----------------------------
160 -- The great majority of GNAT ports are based on GCC. The switches in
161 -- This section indicate the use of some non-standard target back end.
163 AAMP_On_Target : Boolean;
164 -- Set to True if target is AAMP.
166 -------------------------------
167 -- Backend Arithmetic Checks --
168 -------------------------------
170 -- Divide and overflow checks are either done in the front end or
171 -- back end. The front end will generate checks when required unless
172 -- the corresponding parameter here is set to indicate that the back
173 -- end will generate the required checks (or that the checks are
174 -- automatically performed by the hardware in an appropriate form).
176 Backend_Divide_Checks_On_Target : Boolean;
177 -- Set True if the back end generates divide checks, or if the hardware
178 -- checks automatically. Set False if the front end must generate the
179 -- required tests using explicit expanded code.
181 Backend_Overflow_Checks_On_Target : Boolean;
182 -- Set True if the back end generates arithmetic overflow checks, or if
183 -- the hardware checks automatically. Set False if the front end must
184 -- generate the required tests using explicit expanded code.
186 -----------------------------------
187 -- Control of Exception Handling --
188 -----------------------------------
190 -- GNAT implements three methods of implementing exceptions:
192 -- Front-End Longjmp/Setjmp Exceptions
194 -- This approach uses longjmp/setjmp to handle exceptions. It
195 -- uses less storage, and can often propagate exceptions faster,
196 -- at the expense of (sometimes considerable) overhead in setting
197 -- up an exception handler. This approach is available on all
198 -- targets, and is the default where it is the only approach.
200 -- The generation of the setjmp and longjmp calls is handled by
201 -- the front end of the compiler (this includes gigi in the case
202 -- of the standard GCC back end). It does not use any back end
203 -- suport (such as the GCC3 exception handling mechanism). When
204 -- this approach is used, the compiler generates special exception
205 -- handlers for handling cleanups when an exception is raised.
207 -- Front-End Zero Cost Exceptions
209 -- This approach uses separate exception tables. These use extra
210 -- storage, and exception propagation can be quite slow, but there
211 -- is no overhead in setting up an exception handler (it is to this
212 -- latter operation that the phrase zero-cost refers). This approach
213 -- is only available on some targets, and is the default where it is
216 -- The generation of the exception tables is handled by the front
217 -- end of the compiler. It does not use any back end support (such
218 -- as the GCC3 exception handling mechanism). When this approach
219 -- is used, the compiler generates special exception handlers for
220 -- handling cleanups when an exception is raised.
222 -- Back-End Zero Cost Exceptions
224 -- With this approach, the back end handles the generation and
225 -- handling of exceptions. For example, the GCC3 exception handling
226 -- mechanisms are used in this mode. The front end simply generates
227 -- code for explicit exception handlers, and AT END cleanup handlers
228 -- are simply passed unchanged to the backend for generating cleanups
229 -- both in the exceptional and non-exceptional cases.
231 -- As the name implies, this approach generally uses a zero-cost
232 -- mechanism with tables, but the tables are generated by the back
233 -- end. However, since the back-end is entirely responsible for the
234 -- handling of exceptions, another mechanism might be used. In the
235 -- case of GCC3 for instance, it might be the case that the compiler
236 -- is configured for setjmp/longjmp handling, then everything will
237 -- work correctly. However, it is definitely preferred that the
238 -- back end provide zero cost exception handling.
240 -- Controlling the selection of methods
242 -- The Front-End Longjmp/Setjmp approach is always available in
243 -- all implementations. If it is not the default method, then it
244 -- may be explicitly specified by the use of -gnatL. Note however
245 -- that there is a requirement that all Ada units in a partition
246 -- be compiled with this overriding option if it is not the default.
248 -- On some, but not all, implementations of GNAT, one of the two
249 -- ZCX approaches (but not both) is implemented. If this is the
250 -- case, and ZCX is not the default mechanism, then ZCX handling
251 -- (front-end or back-end according to the implementation) may be
252 -- specified by use of the -gnatZ switch. Again, this switch must
253 -- be used to compile all Ada units in a partition. The use of
254 -- the -gnatZ switch will cause termination with a fatal error.
256 -- Finally the debug option -gnatdX can be used to force the
257 -- compiler to operate in front-end ZCX exception mode and force
258 -- the front end to generate exception tables. This is only useful
259 -- for debugging purposes for implementations which do not provide
260 -- the possibility of front-end ZCX mode. The resulting object file
261 -- is unusable, but this debug switch may still be useful (e.g. in
262 -- conjunction with -gnatG) for front-end debugging purposes.
264 -- Control of Available Methods and Defaults
266 -- The following switches specify which of the two ZCX methods
267 -- (if any) is available in an implementation, and which method
268 -- is the default method.
270 ZCX_By_Default_On_Target : Boolean;
271 -- Indicates if zero cost exceptions are active by default. If this
272 -- variable is False, then the only possible exception method is the
273 -- front-end setjmp/longjmp approach, and this is the default. If
274 -- this variable is True, then one of the following two flags must
275 -- be True, and represents the method to be used by default.
277 GCC_ZCX_Support_On_Target : Boolean;
278 -- Indicates that when ZCX is active, the mechanism to be used is the
279 -- back-end ZCX exception approach. If this variable is set to True,
280 -- then Front_End_ZCX_Support_On_Target must be False.
282 Front_End_ZCX_Support_On_Target : Boolean;
283 -- Indicates that when ZCX is active, the mechanism to be used is the
284 -- front-end ZCX exception approach. If this variable is set to True,
285 -- then GCC_ZCX_Support_On_Target must be False.
287 --------------------------------
288 -- Configurable Run-Time Mode --
289 --------------------------------
291 -- In configurable run-time mode, the system run-time may not support
292 -- the full Ada language. The effect of setting this switch is to let
293 -- the compiler know that it is not surprising (i.e. the system is not
294 -- misconfigured) if run-time library units or entities within units are
295 -- not present in the run-time.
297 Configurable_Run_Time_On_Target : Boolean;
298 -- Indicates that the system.ads file is for a configurable run-time
300 -- This has some specific effects as follows
302 -- The binder generates the gnat_argc/argv/envp variables in the
303 -- binder file instead of being imported from the run-time library.
304 -- If Command_Line_Args_On_Target is set to False, then the
305 -- generation of these variables is suppressed completely.
307 -- The binder generates the gnat_exit_status variable in the binder
308 -- file instead of being imported from the run-time library. If
309 -- Exit_Status_Supported_On_Target is set to False, then the
310 -- generation of this variable is suppressed entirely.
312 -- The routine __gnat_break_start is defined within the binder file
313 -- instead of being imported from the run-time library.
315 -- The variable __gnat_exit_status is generated within the binder file
316 -- instead of being imported from the run-time library.
318 Suppress_Standard_Library_On_Target : Boolean;
319 -- If this flag is True, then the standard library is not included by
320 -- default in the executable (see unit System.Standard_Library in file
321 -- s-stalib.ads for details of what this includes). This is for example
322 -- set True for the zero foot print case, where these files should not
323 -- be included by default.
325 -- This flag has some other related effects:
327 -- The generation of global variables in the bind file is suppressed,
328 -- with the exception of the priority of the environment task, which
329 -- is needed by the Ravenscar run-time.
331 -- The generation of exception tables is suppressed for front end
332 -- ZCX exception handling (since we assume no exception handling).
334 -- The calls to __gnat_initialize and __gnat_finalize are omitted
336 -- All finalization and initialization (controlled types) is omitted
338 -- The routine __gnat_handler_installed is not imported
340 ---------------------
341 -- Duration Format --
342 ---------------------
344 -- By default, type Duration is a 64-bit fixed-point type with a delta
345 -- and small of 10**(-9) (i.e. it is a count in nanoseconds. This flag
346 -- allows that standard format to be modified.
348 Duration_32_Bits_On_Target : Boolean;
349 -- If True, then Duration is represented in 32 bits and the delta and
350 -- small values are set to 20.0*(10**(-3)) (i.e. it is a count in units
351 -- of 20 milliseconds.
353 ------------------------------------
354 -- Back-End Code Generation Flags --
355 ------------------------------------
357 -- These flags indicate possible limitations in what the code generator
358 -- can handle. They will all be True for a full run-time, but one or more
359 -- of these may be false for a configurable run-time, and if a feature is
360 -- used at the source level, and the corresponding flag is false, then an
361 -- error message will be issued saying the feature is not supported.
363 Support_64_Bit_Divides_On_Target : Boolean;
364 -- If True, the back end supports 64-bit divide operations. If False, then
365 -- the source program may not contain 64-bit divide operations. This is
366 -- specifically useful in the zero foot-print case, where the issue is
367 -- whether there is a hardware divide instruction for 64-bits so that
368 -- no run-time support is required. It should always be set True if the
369 -- necessary run-time support is present.
371 Support_Aggregates_On_Target : Boolean;
372 -- In the general case, the use of aggregates may generate calls
373 -- to run-time routines in the C library, including memset, memcpy,
374 -- memmove, and bcopy. This flag is set to True if these routines
375 -- are available. If any of these routines is not available, then
376 -- this flag is False, and the use of aggregates is not permitted.
378 Support_Composite_Assign_On_Target : Boolean;
379 -- The assignment of composite objects other than small records and
380 -- arrays whose size is 64-bits or less and is set by an explicit
381 -- size clause may generate calls to memcpy, memmove, and bcopy.
382 -- If versions of all these routines are available, then this flag
383 -- is set to True. If any of these routines is not available, then
384 -- the flag is set False, and composite assignments are not allowed.
386 Support_Composite_Compare_On_Target : Boolean;
387 -- If this flag is True, then the back end supports bit-wise comparison
388 -- of composite objects for equality, either generating inline code or
389 -- calling appropriate (and available) run-time routines. If this flag
390 -- is False, then the back end does not provide this support, and the
391 -- front end uses component by component comparison for composites.
393 Support_Long_Shifts_On_Target : Boolean;
394 -- If True, the back end supports 64-bit shift operations. If False, then
395 -- the source program may not contain explicit 64-bit shifts. In addition,
396 -- the code generated for packed arrays will avoid the use of long shifts.
398 -------------------------------
399 -- Control of Stack Checking --
400 -------------------------------
402 -- GNAT provides two methods of implementing exceptions:
404 -- GCC Probing Mechanism
406 -- This approach uses the standard GCC mechanism for
407 -- stack checking. The method assumes that accessing
408 -- storage immediately beyond the end of the stack
409 -- will result in a trap that is converted to a storage
410 -- error by the runtime system. This mechanism has
411 -- minimal overhead, but requires complex hardware,
412 -- operating system and run-time support. Probing is
413 -- the default method where it is available. The stack
414 -- size for the environment task depends on the operating
415 -- system and cannot be set in a system-independent way.
417 -- GNAT Stack-limit Checking
419 -- This method relies on comparing the stack pointer
420 -- with per-task stack limits. If the check fails, an
421 -- exception is explicitly raised. The advantage is
422 -- that the method requires no extra system dependent
423 -- runtime support and can be used on systems without
424 -- memory protection as well, but at the cost of more
425 -- overhead for doing the check. This method is the
426 -- default on systems that lack complete support for
429 Stack_Check_Probes_On_Target : Boolean;
430 -- Indicates if stack check probes are used, as opposed to the standard
431 -- target independent comparison method.
433 Stack_Check_Default_On_Target : Boolean;
434 -- Indicates if stack checking is on by default
436 ----------------------------
437 -- Command Line Arguments --
438 ----------------------------
440 -- For most ports of GNAT, command line arguments are supported. The
441 -- following flag is set to False for targets that do not support
442 -- command line arguments (VxWorks and AAMP). Note that support of
443 -- command line arguments is not required on such targets (RM A.15(13)).
445 Command_Line_Args_On_Target : Boolean;
446 -- Set False if no command line arguments on target. Note that if this
447 -- is False in with Configurable_Run_Time_On_Target set to True, then
448 -- this causes suppression of generation of the argv/argc variables
449 -- used to record command line arguments.
451 -- Similarly, most ports support the use of an exit status, but AAMP
452 -- is an exception (as allowed by RM A.15(18-20))
454 Exit_Status_Supported_On_Target : Boolean;
455 -- Set False if returning of an exit status is not supported on target.
456 -- Note that if this False in with Configurable_Run_Time_On_Target
457 -- set to True, then this causes suppression of the gnat_exit_status
458 -- variable used to recod the exit status.
460 -----------------------
461 -- Main Program Name --
462 -----------------------
464 -- When the binder generates the main program to be used to create the
465 -- executable, the main program name is main by default (to match the
466 -- usual Unix practice). If this parameter is set to True, then the
467 -- name is instead by default taken from the actual Ada main program
468 -- name (just the name of the child if the main program is a child unit).
469 -- In either case, this value can be overridden using -M name.
471 Use_Ada_Main_Program_Name_On_Target : Boolean;
472 -- Set True to use the Ada main program name as the main name
474 ----------------------------------------------
475 -- Boolean-Valued Floating-Point Attributes --
476 ----------------------------------------------
478 -- The constants below give the values for representation oriented
479 -- floating-point attributes that are the same for all float types
480 -- on the target. These are all boolean values.
482 -- A value is only True if the target reliably supports the corresponding
483 -- feature. Reliably here means that support is guaranteed for all
484 -- possible settings of the relevant compiler switches (like -mieee),
485 -- since we cannot control the user setting of those switches.
487 -- The attributes cannot dependent on the current setting of compiler
488 -- switches, since the values must be static and consistent throughout
489 -- the partition. We probably should add such consistency checks in future,
490 -- but for now we don't do this.
492 Denorm_On_Target : Boolean;
493 -- Set to False on targets that do not reliably support denormals.
494 -- Reliably here means for all settings of the relevant -m flag, so
495 -- for example, this is False on the Alpha where denormals are not
496 -- supported unless -mieee is used.
498 Machine_Rounds_On_Target : Boolean;
499 -- Set to False for targets where S'Machine_Rounds is False
501 Machine_Overflows_On_Target : Boolean;
502 -- Set to True for targets where S'Machine_Overflows is True
504 Signed_Zeros_On_Target : Boolean;
505 -- Set to False on targets that do not reliably support signed zeros.
507 OpenVMS_On_Target : Boolean;
508 -- Set to True if target is OpenVMS.
510 -------------------------------------------
511 -- Boolean-Valued Fixed-Point Attributes --
512 -------------------------------------------
514 Fractional_Fixed_Ops_On_Target : Boolean;
515 -- Set to True for targets that support fixed-by-fixed multiplication
516 -- and division for fixed-point types with a small value equal to
517 -- 2 ** (-(T'Object_Size - 1)) and whose values have an absolute
518 -- value less than 1.0.
520 --------------------------------------------------------------
521 -- Handling of Unconstrained Values Returned from Functions --
522 --------------------------------------------------------------
524 -- Functions that return variable length objects, notably unconstrained
525 -- arrays are a special case, because there is no simple obvious way of
526 -- implementing this feature. Furthermore, this capability is not present
527 -- in C++ or C, so typically the system ABI does not handle this case.
529 -- GNAT uses two different approaches
531 -- The Secondary Stack
533 -- The secondary stack is a special storage pool that is used for
534 -- this purpose. The called function places the result on the
535 -- secondary stack, and the caller uses or copies the value from
536 -- the secondary stack, and pops the secondary stack after the
537 -- value is consumed. The secondary stack is outside the system
538 -- ABI, and the important point is that although generally it is
539 -- handled in a stack like manner corresponding to the subprogram
540 -- call structure, a return from a function does NOT pop the stack.
542 -- DSP (Depressed Stack Pointer)
544 -- Some targets permit the implementation of a function call/return
545 -- protocol in which the function does not pop the main stack pointer
546 -- on return, but rather returns with the stack pointer depressed.
547 -- This is not generally permitted by any ABI, but for at least some
548 -- targets, the implementation of alloca provides a model for this
549 -- approach. If return-with-DSP is implemented, then functions that
550 -- return variable length objects do it by returning with the stack
551 -- pointer depressed, and the returned object is a pointer to the
552 -- area within the stack frame of the called procedure that contains
553 -- the returned value. The caller must then pop the main stack when
554 -- this value is consumed.
556 Functions_Return_By_DSP_On_Target : Boolean;
557 -- Set to True if target permits functions to return with using the
558 -- DSP (depressed stack pointer) approach.
564 -- Normally when using the GCC backend, Gigi and GCC perform much of the
565 -- data layout using the standard layout capabilities of GCC. If the
566 -- parameter Backend_Layout is set to False, then the front end must
567 -- perform all data layout. For further details see the package Layout.
569 Frontend_Layout_On_Target : Boolean;
570 -- Set True if front end does layout
576 -- These subprograms are used to initialize the target parameter values
577 -- from the system.ads file. Note that this is only done once, so if more
578 -- than one call is made to either routine, the second and subsequent
579 -- calls are ignored.
581 procedure Get_Target_Parameters
582 (System_Text : Source_Buffer_Ptr;
583 Source_First : Source_Ptr;
584 Source_Last : Source_Ptr);
585 -- Called at the start of execution to obtain target parameters from
586 -- the source of package System. The parameters provide the source
587 -- text to be scanned (in System_Text (Source_First .. Source_Last)).
589 procedure Get_Target_Parameters;
590 -- This version reads in system.ads using Osint. The idea is that the
591 -- caller uses the first version if they have to read system.ads anyway
592 -- (e.g. the compiler) and uses this simpler interface if system.ads is
593 -- not otherwise needed.