[Ada] Clarify documentation for Stack_Usage

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

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.

From-SVN: r275787

diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog
index 32d35b9257d028c27ed048a0dea5caa341d73186..f0d1f37dce7651000a6a300b9119c6082f939bd5 100644 (file)
--- a/gcc/ada/ChangeLog
+++ b/gcc/ada/ChangeLog
@@ -1,3 +1,10 @@
+2019-09-17  Bob Duff  <duff@adacore.com>
+
+       * doc/gnat_ugn/gnat_and_program_execution.rst: Clarify
+       documentation.
+       * gnat_ugn.texi: Regenerate.
+       * libgnat/s-stausa.ads: Clarify comments.
+
 2019-09-17  Steve Baird  <baird@adacore.com>
 
        * sem_util.adb (Wrong_Type): In deciding to suppress a message,

diff --git a/gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst b/gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst
index d2675c7c1511f801a0a59c66dee31910dff9dc3b..56ee1033eb86e7117a16c11f7ee93d369100c7ae 100644 (file)
--- a/gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst
+++ b/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

diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi
index eddd9e4500ad46c5da1310b90d420b61943d60c6..5db9c76eb15d8ffba566eb00980b20c6593b448e 100644 (file)
--- 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 , 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

diff --git a/gcc/ada/libgnat/s-stausa.ads b/gcc/ada/libgnat/s-stausa.ads
index 03bc7605b8d15da736d24738d777fbdc59705b78..2dfa7356bfbfffb9d64bd5948911664cee04fea7 100644 (file)
--- a/gcc/ada/libgnat/s-stausa.ads
+++ b/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: