[gcc r14-4751] ada: Document gnatbind -Q switch

[gcc r14-4751] ada: Document gnatbind -Q switch

[Marc Poulhi?s]

https://gcc.gnu.org/g:1555d18143d7e261eed38188f7511f3075a0f3a5

commit r14-4751-g1555d18143d7e261eed38188f7511f3075a0f3a5
Author: Patrick Bernardi <bernardi@adacore.com>
Date:   Fri Sep 29 17:01:56 2023 -0400

    ada: Document gnatbind -Q switch
    
    Add documentation for the -Q gnatbind switch in GNAT User's Guide and
    improve gnatbind's help output for the switch to emphasize that it adds the
    requested number of stacks to the secondary stack pool generated by the
    binder.
    
    gcc/ada/
    
            * bindusg.adb (Display): Make it clear -Q adds to the number of
            secondary stacks generated by the binder.
            * doc/gnat_ugn/building_executable_programs_with_gnat.rst:
            Document the -Q gnatbind switch and fix references to old
            runtimes.
            * gnat-style.texi: Regenerate.
            * gnat_rm.texi: Regenerate.
            * gnat_ugn.texi: Regenerate.

Diff:
---
 gcc/ada/bindusg.adb                                |  2 +-
 .../building_executable_programs_with_gnat.rst     | 29 +++++++++++----
 gcc/ada/gnat-style.texi                            |  4 +--
 gcc/ada/gnat_rm.texi                               |  4 +--
 gcc/ada/gnat_ugn.texi                              | 41 ++++++++++++++++------
 5 files changed, 59 insertions(+), 21 deletions(-)

diff --git a/gcc/ada/bindusg.adb b/gcc/ada/bindusg.adb
index fca425b22441..89a6caedf314 100644
--- a/gcc/ada/bindusg.adb
+++ b/gcc/ada/bindusg.adb
@@ -234,7 +234,7 @@ package body Bindusg is
       --  Line for Q switch
 
       Write_Line
-        ("  -Qnnn     Generate nnn default-sized secondary stacks");
+        ("  -Qnnn     Generate nnn additional default-sized secondary stacks");
 
       --  Line for -r switch
 
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 6e80163d6d4a..a708ef4b995f 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
@@ -6524,12 +6524,12 @@ be presented in subsequent sections.
   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.
+  For Light, Light-Tasking, and Embedded 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, which takes the size of
+  the secondary stack in bytes.
 
 .. index:: -e  (gnatbind)
 
@@ -6739,6 +6739,23 @@ be presented in subsequent sections.
   Generate binder file suitable for CodePeer.
 
 
+.. index:: -Q  (gnatbind)
+
+:switch:`-Q{nnn}`
+  Generate ``nnn`` additional default-sized secondary stacks.
+
+  Tasks declared at the library level that use default-size secondary stacks
+  have their secondary stacks allocated from a pool of stacks generated by
+  gnatbind. This allows the default secondary stack size to be quickly changed
+  by rebinding the application.
+
+  While the binder sizes this pool to match the number of such tasks defined in
+  the application, the pool size may need to be increased with the :switch:`-Q`
+  switch to accommodate foreign threads registered with the Light run-time. For
+  more information, please see the *The Primary and Secondary Stack* chapter in
+  the *GNAT User’s Guide Supplement for Cross Platforms*.
+
+
   .. index:: -R  (gnatbind)
 
 :switch:`-R`
diff --git a/gcc/ada/gnat-style.texi b/gcc/ada/gnat-style.texi
index 5555bcdc1601..33bb1886985a 100644
--- a/gcc/ada/gnat-style.texi
+++ b/gcc/ada/gnat-style.texi
@@ -3,7 +3,7 @@
 @setfilename gnat-style.info
 @documentencoding UTF-8
 @ifinfo
-@*Generated by Sphinx 5.2.3.@*
+@*Generated by Sphinx 7.2.6.@*
 @end ifinfo
 @settitle GNAT Coding Style A Guide for GNAT Developers
 @defindex ge
@@ -19,7 +19,7 @@
 
 @copying
 @quotation
-GNAT Coding Style: A Guide for GNAT Developers , May 09, 2023
+GNAT Coding Style: A Guide for GNAT Developers , Oct 16, 2023
 
 AdaCore
 
diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi
index b7e098331e9a..9a6a0170ae87 100644
--- a/gcc/ada/gnat_rm.texi
+++ b/gcc/ada/gnat_rm.texi
@@ -3,7 +3,7 @@
 @setfilename gnat_rm.info
 @documentencoding UTF-8
 @ifinfo
-@*Generated by Sphinx 5.2.3.@*
+@*Generated by Sphinx 7.2.6.@*
 @end ifinfo
 @settitle GNAT Reference Manual
 @defindex ge
@@ -19,7 +19,7 @@
 
 @copying
 @quotation
-GNAT Reference Manual , Jul 17, 2023
+GNAT Reference Manual , Oct 16, 2023
 
 AdaCore
 
diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi
index 1562bee1f64a..897153bcfc79 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 5.2.3.@*
+@*Generated by Sphinx 7.2.6.@*
 @end ifinfo
 @settitle GNAT User's Guide for Native Platforms
 @defindex ge
@@ -19,7 +19,7 @@
 
 @copying
 @quotation
-GNAT User's Guide for Native Platforms , Sep 26, 2023
+GNAT User's Guide for Native Platforms , Oct 16, 2023
 
 AdaCore
 
@@ -15781,12 +15781,12 @@ 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.
+For Light, Light-Tasking, and Embedded 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, which takes the size of
+the secondary stack in bytes.
 @end table
 
 @geindex -e (gnatbind)
@@ -16047,6 +16047,27 @@ Pessimistic (worst-case) elaboration order.
 @item @code{-P}
 
 Generate binder file suitable for CodePeer.
+@end table
+
+@geindex -Q (gnatbind)
+
+
+@table @asis
+
+@item @code{-Q`nnn'}
+
+Generate @code{nnn} additional default-sized secondary stacks.
+
+Tasks declared at the library level that use default-size secondary stacks
+have their secondary stacks allocated from a pool of stacks generated by
+gnatbind. This allows the default secondary stack size to be quickly changed
+by rebinding the application.
+
+While the binder sizes this pool to match the number of such tasks defined in
+the application, the pool size may need to be increased with the @code{-Q}
+switch to accommodate foreign threads registered with the Light run-time. For
+more information, please see the `The Primary and Secondary Stack' chapter in
+the `GNAT User’s Guide Supplement for Cross Platforms'.
 
 @geindex -R (gnatbind)
 
@@ -22827,13 +22848,13 @@ Alternatively, you can specify @code{rts-sjlj/adainclude} in the file
 
 Selecting another run-time library temporarily can be
 achieved by using the @code{--RTS} switch, e.g., @code{--RTS=sjlj}
-@anchor{gnat_ugn/platform_specific_information choosing-the-scheduling-policy}@anchor{1bb}
+
 @geindex SCHED_FIFO scheduling policy
 
 @geindex SCHED_RR scheduling policy
 
 @geindex SCHED_OTHER scheduling policy
-
+@anchor{gnat_ugn/platform_specific_information choosing-the-scheduling-policy}@anchor{1bb}
 @menu
 * Choosing the Scheduling Policy::