Add documentation for -fsanitize-address-use-after-return.

[kda]

Summary

for issue: https://github.com/google/sanitizers/issues/1394

[vitalybuka]

clang/docs/AddressSanitizer.rst

18

Please check that this is formatted reasonable in preview.

clang/docs/ClangCommandLineReference.rst

889

"Code generated and always enabled." is implementation details.
Something like this?

Valid options are:
* ``always`` - Detect use-after-return.
* ``runtime`` - Detect use-after-return with runtime ON/OFF switch (environment variable `ASAN_OPTIONS=detect_stack_use_after_return=1`, default: 0)
* ``never`` - Do not detect use-after-return.

[kda]

• Revised according to feedback.

[MaskRay]

clang/docs/AddressSanitizer.rst

17–18

rst uses two backsticks instead of one.

[MaskRay]

clang/docs/ClangCommandLineReference.rst

3

This file is generated by clang-tblgen -gen-opt-docs.

You can edit clang/docs/UsersManual.rst and include the information that =never can reduce the object file size.

[kda]

• attempting to make documentation pretty.

[vitalybuka]

clang/docs/ClangCommandLineReference.rst

3

to clarify you need
configure -DLLVM_ENABLE_SPHINX=ON -DSPHINX_OUTPUT_HTML=ON -DSPHINX_OUTPUT_MAN=ON

and then: ninja docs-clang-html

AddressSanitizer.html will be somewhere in output, so you can check results

@MaskRay @rsmith However I am not sure what to do with ClangCommandLineReference.rst.
The one generated in build dir contains tens of missing flags. Still looks like the public doc https://clang.llvm.org/docs/ClangCommandLineReference.html is generated from the one committed here.
Should we just pick lines related to the feature and ignore the rest or don't touch at all and let?

[kda]

• more beauty, added UsersManual changes.

[kda]

• more consistency.

[kda]

clang/docs/AddressSanitizer.rst

18

See attached screenshot.

[MaskRay]

clang/docs/ClangCommandLineReference.rst

3

The current state isn't ideal but that is what I have now (https://lists.llvm.org/pipermail/cfe-dev/2020-September/066900.html)

[vitalybuka]

clang/docs/AddressSanitizer.rst

21

seems overloaded for the list of bug types:

Please create section, similar to

Stack Use After Return
---------------------
...
...
...
Memory leak detection
---------------------

and include additional information there

clang/docs/ClangCommandLineReference.rst

894

I believe the best solution for now is just revert changes in this file and replace it with auto-generated version in a separate patch.

clang/docs/UsersManual.rst

3737 ↗

(On Diff #352289)

How about we update Options.td (in this patch) with:
HelpText<"Select the mode of detecting stack use-after-return in AddressSanitizer: never | runtime (default) | always">,

then we put corresponding text here and move block from UsersManual.rst:1851 into AddressSanitizer.rst (separate section)

[kda]

• Responding to comments.

[vitalybuka]

clang/docs/AddressSanitizer.rst

19–20

I guess just flag name is enough here, the rest in the section below.

[vitalybuka]

clang/docs/AddressSanitizer.rst

143

Maybe -fsanitize=address is reduntant here, we are already in the -fsanitize=address document. Mentioning the flag in the line 11 seems more appropriate.

[kda]

• removed redundant mention of the flag.

clang/docs/AddressSanitizer.rst

 ================
 AddressSanitizer
 ================
 
 .. contents::
    :local:
 
 Introduction
 ============
 
 AddressSanitizer is a fast memory error detector. It consists of a compiler
 instrumentation module and a run-time library. The tool can detect the
 following types of bugs:
 
 * Out-of-bounds accesses to heap, stack and globals
 * Use-after-free
-* Use-after-return (runtime flag `ASAN_OPTIONS=detect_stack_use_after_return=1`)
+* Use-after-return (clang flag `-fsanitize-address-use-after-return=(always|runtime|never)` default: runtime)
+  * Add runtime flag `ASAN_OPTIONS=detect_stack_use_after_return=1` to enable when compiled with `-fsanitize-address-use-after-return=runtime`)
 * Use-after-scope (clang flag `-fsanitize-address-use-after-scope`)
 * Double-free, invalid free
 * Memory leaks (experimental)
 
 Typical slowdown introduced by AddressSanitizer is **2x**.
 
 How to build
 ============
 
 Build LLVM/Clang with `CMake <https://llvm.org/docs/CMake.html>`_.
 

 you should set environment variable
 ``ASAN_OPTIONS=check_initialization_order=1``.
 
 Note that this option is not supported on macOS.
 
 Memory leak detection
 ---------------------
 
 For more information on leak detector in AddressSanitizer, see
 :doc:`LeakSanitizer`. The leak detection is turned on by default on Linux,
 and can be enabled using ``ASAN_OPTIONS=detect_leaks=1`` on macOS;
 however, it is not yet supported on other platforms.
 
 Issue Suppression
 =================
 
 AddressSanitizer is not expected to produce false positives. If you see one,

clang/docs/ClangCommandLineReference.rst

 ..
   -------------------------------------------------------------------
   NOTE: This file is automatically generated by running clang-tblgen
   -gen-opt-docs. Do not edit this file by hand!!
   -------------------------------------------------------------------
 
 =====================================
 Clang command line argument reference
 =====================================
 .. contents::
    :local:

 These destructors are emitted to unregister instrumented global variables when
 code is unloaded (e.g. via `dlclose()`).
 
 Valid options are:
 
 * ``global`` - Emit module destructors that are called via a platform specific array (see `llvm.global_dtors`).
 * ``none`` - Do not emit module destructors.
 
+.. option:: -fsanitize-address-use-after-return=<arg>
+
+Select the enabling method of detecting stack use-after-return in AddressSanitizer.
+
+Valid options are:
+* ``always`` - Always detect use-after-return.  (Code generated and always enabled.)
+* ``runtime`` - Detect use-after-return at runtime if enabled by runtime command line (flag `ASAN_OPTIONS=detect_stack_use_after_return=1`)
+* ``never`` - Never detect use-after-return.  (Code not generated for detection.)
+
 .. option:: -fsanitize-ignorelist=<arg>
 
 Path to ignorelist file for sanitizers
 
 .. option:: -fsanitize-cfi-canonical-jump-tables, -fno-sanitize-cfi-canonical-jump-tables
 
 Make the jump table addresses canonical in the symbol table
 
 .. option:: -fsanitize-cfi-cross-dso, -fno-sanitize-cfi-cross-dso