From: Patrick Bernardi Date: Mon, 28 May 2018 08:53:49 +0000 (+0000) Subject: [Ada] Update user manual for the -D binder switch X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=f5a9ad2577ddea7a5646040b1d301515d834a8d1;p=gcc.git [Ada] Update user manual for the -D binder switch 2018-05-28 Patrick Bernardi gcc/ada/ * doc/gnat_ugn/building_executable_programs_with_gnat.rst: Update the description of the -D binder switch to reflect current usage. * gnat_ugn.texi: Regenerate. From-SVN: r260824 --- diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog index 5072b7eb547..8e4982aa2ab 100644 --- a/gcc/ada/ChangeLog +++ b/gcc/ada/ChangeLog @@ -1,3 +1,9 @@ +2018-05-28 Patrick Bernardi + + * doc/gnat_ugn/building_executable_programs_with_gnat.rst: Update the + description of the -D binder switch to reflect current usage. + * gnat_ugn.texi: Regenerate. + 2018-05-28 Gary Dismukes * exp_ch3.adb: Minor reformatting 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 feff02f4062..8c76a74683e 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 @@ -6198,28 +6198,25 @@ be presented in subsequent sections. .. index:: -D (gnatbind) :switch:`-D{nn}[k|m]` - This switch can be used to change the default secondary stack size value - to a specified size ``nn``, which is expressed in bytes by default, or - in kilobytes when suffixed with ``k`` or in megabytes when suffixed - with ``m``. - - The secondary stack is used to deal with functions that return a variable - sized result, for example a function returning an unconstrained - String. There are two ways in which this secondary stack is allocated. - - For most targets, the secondary stack grows on demand and is allocated - as a chain of blocks in the heap. The -D option is not very - relevant. It only give some control over the size of the allocated - blocks (whose size is the minimum of the default secondary stack size value, - and the actual size needed for the current allocation request). - - For certain targets, notably VxWorks 653 and bare board targets, - the secondary stack is allocated by carving off a chunk of the primary task - stack. By default this is a fixed percentage of the primary task stack as - defined by System.Parameter.Sec_Stack_Percentage. This can be overridden per - task using the Secondary_Stack_Size pragma/aspect. The -D option is used to - define the size of the environment task's secondary stack. - + Set the default secondary stack size to ``nn``. The suffix indicates whether + the size is in bytes (no suffix), kilobytes (``k`` suffix) or megabytes + (``m`` suffix). + + The secondary stack holds objects of unconstrained types that are returned by + functions, for example unconstrained Strings. The size of the secondary stack + can be dynamic or fixed depending on the target. + + For most targets, the secondary stack grows on demand and is implemented as + a chain of blocks in the heap. In this case, the default secondary stack size + determines the initial size of the secondary stack for each task and the + smallest amount the secondary stack can grow by. + + For Ravenscar, ZFP, and Cert run-times the size of the secondary stack is + fixed. This switch can be used to change the default size of these stacks. + The default secondary stack size can be overridden on a per-task basis if + individual tasks have different secondary stack requirements. This is + achieved through the Secondary_Stack_Size aspect that takes the size of the + secondary stack in bytes. .. index:: -e (gnatbind) diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi index 30ef6c75466..ceadb57ef0b 100644 --- a/gcc/ada/gnat_ugn.texi +++ b/gcc/ada/gnat_ugn.texi @@ -3,7 +3,7 @@ @setfilename gnat_ugn.info @documentencoding UTF-8 @ifinfo -@*Generated by Sphinx 1.3.6.@* +@*Generated by Sphinx 1.4.6.@* @end ifinfo @settitle GNAT User's Guide for Native Platforms @defindex ge @@ -21,7 +21,7 @@ @copying @quotation -GNAT User's Guide for Native Platforms , April 25, 2018 +GNAT User's Guide for Native Platforms , May 22, 2018 AdaCore @@ -15512,27 +15512,25 @@ When they do not already have such a pragma. @item @code{-D@emph{nn}[k|m]} -This switch can be used to change the default secondary stack size value -to a specified size @code{nn}, which is expressed in bytes by default, or -in kilobytes when suffixed with @code{k} or in megabytes when suffixed -with @code{m}. - -The secondary stack is used to deal with functions that return a variable -sized result, for example a function returning an unconstrained -String. There are two ways in which this secondary stack is allocated. - -For most targets, the secondary stack grows on demand and is allocated -as a chain of blocks in the heap. The -D option is not very -relevant. It only give some control over the size of the allocated -blocks (whose size is the minimum of the default secondary stack size value, -and the actual size needed for the current allocation request). - -For certain targets, notably VxWorks 653 and bare board targets, -the secondary stack is allocated by carving off a chunk of the primary task -stack. By default this is a fixed percentage of the primary task stack as -defined by System.Parameter.Sec_Stack_Percentage. This can be overridden per -task using the Secondary_Stack_Size pragma/aspect. The -D option is used to -define the size of the environment task's secondary stack. +Set the default secondary stack size to @code{nn}. The suffix indicates whether +the size is in bytes (no suffix), kilobytes (@code{k} suffix) or megabytes +(@code{m} suffix). + +The secondary stack holds objects of unconstrained types that are returned by +functions, for example unconstrained Strings. The size of the secondary stack +can be dynamic or fixed depending on the target. + +For most targets, the secondary stack grows on demand and is implemented as +a chain of blocks in the heap. In this case, the default secondary stack size +determines the initial size of the secondary stack for each task and the +smallest amount the secondary stack can grow by. + +For Ravenscar, ZFP, and Cert run-times the size of the secondary stack is +fixed. This switch can be used to change the default size of these stacks. +The default secondary stack size can be overridden on a per-task basis if +individual tasks have different secondary stack requirements. This is +achieved through the Secondary_Stack_Size aspect that takes the size of the +secondary stack in bytes. @end table @geindex -e (gnatbind)