From 86ae194fdb343487d37899f4f51fdf3e626822e0 Mon Sep 17 00:00:00 2001 From: Bob Duff Date: Tue, 17 Sep 2019 08:02:09 +0000 Subject: [PATCH] [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 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 --- gcc/ada/ChangeLog | 7 +++++++ gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst | 5 ++++- gcc/ada/gnat_ugn.texi | 7 +++++-- gcc/ada/libgnat/s-stausa.ads | 5 +++++ 4 files changed, 21 insertions(+), 3 deletions(-) diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog index 32d35b9257d..f0d1f37dce7 100644 --- a/gcc/ada/ChangeLog +++ b/gcc/ada/ChangeLog @@ -1,3 +1,10 @@ +2019-09-17 Bob Duff + + * 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 * 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 d2675c7c151..56ee1033eb8 100644 --- 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 eddd9e4500a..5db9c76eb15 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 , 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 03bc7605b8d..2dfa7356bfb 100644 --- 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: -- 2.30.2