From 298e0c6bf77b2e218bd5f8a386ecfdd4e7c9ab52 Mon Sep 17 00:00:00 2001 From: Yannick Moy Date: Tue, 21 Aug 2018 14:47:25 +0000 Subject: [PATCH] [Ada] Document entries of the target parametrization file 2018-08-21 Yannick Moy gcc/ada/ * doc/gnat_ugn/building_executable_programs_with_gnat.rst: Document entries of the target parametrization file. * gnat_ugn.texi: Regenerate. From-SVN: r263725 --- gcc/ada/ChangeLog | 6 ++++ ...building_executable_programs_with_gnat.rst | 33 ++++++++++++++++++- gcc/ada/gnat_ugn.texi | 30 +++++++++++++++-- 3 files changed, 66 insertions(+), 3 deletions(-) diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog index 312d891fad6..0c558c0cb06 100644 --- a/gcc/ada/ChangeLog +++ b/gcc/ada/ChangeLog @@ -1,3 +1,9 @@ +2018-08-21 Yannick Moy + + * doc/gnat_ugn/building_executable_programs_with_gnat.rst: + Document entries of the target parametrization file. + * gnat_ugn.texi: Regenerate. + 2018-08-21 Ed Schonberg * sem_attr.adb: Set scope of elaboration flag for 'Access. diff --git a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst index e79f630731c..1455087b1eb 100644 --- a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst +++ b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst @@ -1692,13 +1692,44 @@ Alphabetical List of All Switches Maximum_Alignment : Pos; -- Maximum permitted alignment Max_Unaligned_Field : Pos; -- Maximum size for unaligned bit field Pointer_Size : Pos; -- System.Address'Size - Short_Enums : Nat; -- Short foreign convention enums? + Short_Enums : Nat; -- Foreign enums use short size? Short_Size : Pos; -- Standard.Short_Integer'Size Strict_Alignment : Nat; -- Strict alignment? System_Allocator_Alignment : Nat; -- Alignment for malloc calls Wchar_T_Size : Pos; -- Interfaces.C.wchar_t'Size Words_BE : Nat; -- Words stored big-endian? + ``Bits_Per_Unit`` is the number of bits in a storage unit, the equivalent of + GCC macro ``BITS_PER_UNIT`` documented as follows: `Define this macro to be + the number of bits in an addressable storage unit (byte); normally 8.` + + ``Bits_Per_Word`` is the number of bits in a machine word, the equivalent of + GCC macro ``BITS_PER_WORD`` documented as follows: `Number of bits in a word; + normally 32.` + + ``Double_Scalar_Alignment`` is the alignment for a scalar whose size is two + machine words. It should be the same as the alignment for C ``long_long`` on + most targets. + + ``Maximum_Alignment`` is the maximum alignment that the compiler might choose + by default for a type or object, which is also the maximum alignment that can + be specified in GNAT. It is computed for GCC backends as ``BIGGEST_ALIGNMENT + / BITS_PER_UNIT`` where GCC macro ``BIGGEST_ALIGNMENT`` is documented as + follows: `Biggest alignment that any data type can require on this machine, + in bits.` + + ``Max_Unaligned_Field`` is the maximum size for unaligned bit field, which is + 64 for the majority of GCC targets (but can be different on some targets like + AAMP). + + ``Strict_Alignment`` is the equivalent of GCC macro ``STRICT_ALIGNMENT`` + documented as follows: `Define this macro to be the value 1 if instructions + will fail to work if given data not on the nominal alignment. If instructions + will merely go slower in that case, define this macro as 0.` + + ``System_Allocator_Alignment`` is the guaranteed alignment of data returned + by calls to ``malloc``. + The format of the input file is as follows. First come the values of the variables defined above, with one line per value: diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi index dfff37d3d65..aeaa1461c05 100644 --- a/gcc/ada/gnat_ugn.texi +++ b/gcc/ada/gnat_ugn.texi @@ -21,7 +21,7 @@ @copying @quotation -GNAT User's Guide for Native Platforms , Aug 17, 2018 +GNAT User's Guide for Native Platforms , Aug 20, 2018 AdaCore @@ -9429,7 +9429,7 @@ Long_Size : Pos; -- Standard.Long_Integer'Size Maximum_Alignment : Pos; -- Maximum permitted alignment Max_Unaligned_Field : Pos; -- Maximum size for unaligned bit field Pointer_Size : Pos; -- System.Address'Size -Short_Enums : Nat; -- Short foreign convention enums? +Short_Enums : Nat; -- Foreign enums use short size? Short_Size : Pos; -- Standard.Short_Integer'Size Strict_Alignment : Nat; -- Strict alignment? System_Allocator_Alignment : Nat; -- Alignment for malloc calls @@ -9437,6 +9437,32 @@ Wchar_T_Size : Pos; -- Interfaces.C.wchar_t'Size Words_BE : Nat; -- Words stored big-endian? @end example +@code{Bits_Per_Unit} is the number of bits in a storage unit, the equivalent of +GCC macro @code{BITS_PER_UNIT} documented as follows: @cite{Define this macro to be the number of bits in an addressable storage unit (byte); normally 8.} + +@code{Bits_Per_Word} is the number of bits in a machine word, the equivalent of +GCC macro @code{BITS_PER_WORD} documented as follows: @cite{Number of bits in a word; normally 32.} + +@code{Double_Scalar_Alignment} is the alignment for a scalar whose size is two +machine words. It should be the same as the alignment for C @code{long_long} on +most targets. + +@code{Maximum_Alignment} is the maximum alignment that the compiler might choose +by default for a type or object, which is also the maximum alignment that can +be specified in GNAT. It is computed for GCC backends as @code{BIGGEST_ALIGNMENT +/ BITS_PER_UNIT} where GCC macro @code{BIGGEST_ALIGNMENT} is documented as +follows: @cite{Biggest alignment that any data type can require on this machine@comma{} in bits.} + +@code{Max_Unaligned_Field} is the maximum size for unaligned bit field, which is +64 for the majority of GCC targets (but can be different on some targets like +AAMP). + +@code{Strict_Alignment} is the equivalent of GCC macro @code{STRICT_ALIGNMENT} +documented as follows: @cite{Define this macro to be the value 1 if instructions will fail to work if given data not on the nominal alignment. If instructions will merely go slower in that case@comma{} define this macro as 0.} + +@code{System_Allocator_Alignment} is the guaranteed alignment of data returned +by calls to @code{malloc}. + The format of the input file is as follows. First come the values of the variables defined above, with one line per value: