[Ada] Clarify documentation for Stack_Usage

[Ada] Clarify documentation for Stack_Usage

[Pierre-Marie de Rodat]

[-- Attachment #1: Type: text/plain, Size: 387 bytes --]

Clarify the documentation for Stack_Usage (both comments in the code,
and user documentation) to note that tools like Valgrind won't work.

Tested on x86_64-pc-linux-gnu, committed on trunk

2019-09-17  Bob Duff  <duff@adacore.com>

gcc/ada/

	* doc/gnat_ugn/gnat_and_program_execution.rst: Clarify
	documentation.
	* gnat_ugn.texi: Regenerate.
	* libgnat/s-stausa.ads: Clarify comments.

[-- Attachment #2: patch.diff --]
[-- Type: text/x-diff, Size: 2113 bytes --]

--- gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst
+++ gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst
@@ -3396,8 +3396,11 @@ adding a switch to ``gnatbind``, as:
 
       $ gnatbind -u0 file
 
-With this option, at each task termination, its stack usage is  output on
+With this option, at each task termination, its stack usage is output on
 :file:`stderr`.
+Note that this switch is not compatible with tools like
+Valgrind and DrMemory; they will report errors.
+
 It is not always convenient to output the stack usage when the program
 is still running. Hence, it is possible to delay this output until program
 termination. for a given number of tasks specified as the argument of the

--- gcc/ada/gnat_ugn.texi
+++ gcc/ada/gnat_ugn.texi
@@ -21,7 +21,7 @@
 
 @copying
 @quotation
-GNAT User's Guide for Native Platforms , Sep 13, 2019
+GNAT User's Guide for Native Platforms , Sep 14, 2019
 
 AdaCore
 
@@ -23321,8 +23321,11 @@ $ gnatbind -u0 file
 @end example
 @end quotation
 
-With this option, at each task termination, its stack usage is  output on
+With this option, at each task termination, its stack usage is output on
 @code{stderr}.
+Note that this switch is not compatible with tools like
+Valgrind and DrMemory; they will report errors.
+
 It is not always convenient to output the stack usage when the program
 is still running. Hence, it is possible to delay this output until program
 termination. for a given number of tasks specified as the argument of the

--- gcc/ada/libgnat/s-stausa.ads
+++ gcc/ada/libgnat/s-stausa.ads
@@ -67,6 +67,11 @@ package System.Stack_Usage is
    --  Type of the stack analyzer tool. It is used to fill a portion of the
    --  stack with Pattern, and to compute the stack used after some execution.
 
+   --  Note that Fill_Stack writes data past the current top of the stack
+   --  (i.e. at addresses less than the stack pointer register, assuming the
+   --  stack grows downward). Therefore, this package is incompatible with
+   --  tools like Valgrind and DrMemory.
+
    --  Usage:
 
    --  A typical use of the package is something like: