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

[kda]

Summary

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

[vitalybuka]

clang/docs/AddressSanitizer.rst

17

Please check that this is formatted reasonable in preview.

clang/docs/ClangCommandLineReference.rst

889 ↗

(On Diff #351566)

"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

16–17

rst uses two backsticks instead of one.

[MaskRay]

clang/docs/ClangCommandLineReference.rst

3 ↗

(On Diff #351571)

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 ↗

(On Diff #351571)

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

17

See attached screenshot.

[MaskRay]

clang/docs/ClangCommandLineReference.rst

3 ↗

(On Diff #351571)

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

19

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 ↗

(On Diff #352289)

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

3747

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

17–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-scope (clang flag `-fsanitize-address-use-after-scope`)
+* Use-after-return (clang flag ``-fsanitize-address-use-after-return=(never|runtime|always)`` default: ``runtime``)
+    * Enable ``runtime`` with: ``ASAN_OPTIONS=detect_stack_use_after_return=1``
+* 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>`_.

 AddressSanitizer can optionally detect dynamic initialization order problems,
 when initialization of globals defined in one translation unit uses
 globals defined in another translation unit. To enable this check at runtime,
 you should set environment variable
 ``ASAN_OPTIONS=check_initialization_order=1``.
 
 Note that this option is not supported on macOS.
 
+Stack Use After Return (UAR)
+----------------------------
+
+AddressSanitizer can optionally detect stack use after return problems.
+This is available by default, or explicitly
+(``-fsanitize-address-use-after-return=runtime``).
+To enable this check at runtime, set the environment variable
+``ASAN_OPTIONS=detect_stack_use_after_return=1``.
+
+Enabling this check (``-fsanitize-address-use-after-return=always``) will
+reduce code size.  The code size may be reduced further by completely
+eliminating this check (``-fsanitize-address-use-after-return=never``).
+
+To summarize: ``-fsanitize-address-use-after-return=<mode>``
+  * ``never``: Completely disables detection of UAR errors (reduces code size).
+  * ``runtime``: Adds the code for detection, but must be enabled via the
+    runtime environment (``ASAN_OPTIONS=detect_stack_use_after_return=1``).
+  * ``always``: Enables detection of UAR errors in all cases. (reduces code
+    size, but not as much as ``never``).
+
 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.
 

clang/docs/UsersManual.rst

OPTIONS:
       -fprofile-list=<file>
                               Filename defining the list of functions/files to instrument
       -fsanitize-address-field-padding=<value>
                               Level of field padding for AddressSanitizer
       -fsanitize-address-globals-dead-stripping
                               Enable linker dead stripping of globals in AddressSanitizer
       -fsanitize-address-poison-custom-array-cookie
                               Enable poisoning array cookies when using custom operator new[] in AddressSanitizer
+      -fsanitize-address-use-after-return=<mode>
+                              Select the mode of detecting stack use-after-return in AddressSanitizer: never | runtime (default) | always
       -fsanitize-address-use-after-scope
                               Enable use-after-scope detection in AddressSanitizer
       -fsanitize-address-use-odr-indicator
                               Enable ODR indicator globals to avoid false ODR violation reports in partially sanitized programs at the cost of an increase in binary size
       -fsanitize-ignorelist=<value>
                               Path to ignorelist file for sanitizers
       -fsanitize-cfi-cross-dso
                               Enable control flow integrity (CFI) checks for cross-DSO calls.

clang/include/clang/Driver/Options.td

defm sanitize_address_use_after_scope : BoolOption<"f", "sanitize-address-use-after-scope",
   CodeGenOpts<"SanitizeAddressUseAfterScope">, DefaultFalse,
   PosFlag<SetTrue, [], "Enable">, NegFlag<SetFalse, [CoreOption, NoXarchOption], "Disable">,
   BothFlags<[], " use-after-scope detection in AddressSanitizer">>,
   Group<f_clang_Group>;
 def sanitize_address_use_after_return_EQ
   : Joined<["-"], "fsanitize-address-use-after-return=">,
     MetaVarName<"<mode>">,
     Flags<[CC1Option]>,
-    HelpText<"Select the mode of detecting stack use-after-return in AddressSanitizer">,
+    HelpText<"Select the mode of detecting stack use-after-return in AddressSanitizer: never | runtime (default) | always">,
     Group<f_clang_Group>,
     Values<"never,runtime,always">,
     NormalizedValuesScope<"llvm::AsanDetectStackUseAfterReturnMode">,
     NormalizedValues<["Never", "Runtime", "Always"]>,
     MarshallingInfoEnum<CodeGenOpts<"SanitizeAddressUseAfterReturn">, "Runtime">;
 defm sanitize_address_poison_custom_array_cookie : BoolOption<"f", "sanitize-address-poison-custom-array-cookie",
   CodeGenOpts<"SanitizeAddressPoisonCustomArrayCookie">, DefaultFalse,
   PosFlag<SetTrue, [], "Enable">, NegFlag<SetFalse, [], "Disable">,