Improve -ftrivial-auto-var-init description

Signed-off-by: Thomas Nyman <[email protected]>

Author: thomasnyman

docs/Compiler-Hardening-Guides/Compiler-Options-Hardening-Guide-for-C-and-C++.md

@@ -231,7 +231,7 @@ Table 2: Recommended compiler options that enable run-time protection mechanisms
 | [`-fno-delete-null-pointer-checks`](#-fno-delete-null-pointer-checks)                     | GCC 3.0.0<br/>Clang 7.0.0            | Force retention of null pointer checks                                                       |
 | [`-fno-strict-overflow`](#-fno-strict-overflow)                                           | GCC 4.2.0                            | Define behavior for signed integer and pointer arithmetic overflows                        |
 | [`-fno-strict-aliasing`](#-fno-strict-aliasing)                                           | GCC 2.95.3<br/>Clang 2.9.0        | Do not assume strict aliasing                                                                |
-| [`-ftrivial-auto-var-init`](#-ftrivial-auto-var-init)                                     | GCC 12.0.0<br/>Clang 8.0.0               | Perform trivial auto variable initialization                                                 |
+| [`-ftrivial-auto-var-init`](#-ftrivial-auto-var-init)                                     | GCC 12.0.0<br/>Clang 8.0.0           | Initialize automatic variables that lack explicit initializers |
 | [`-fexceptions`](#-fexceptions)                                                           | GCC 2.95.3<br/>Clang 2.6.0           | Enable exception propagation to harden multi-threaded C code                                 |
 | [`-fhardened`](#-fhardened)                                                               | GCC 14.0.0                           | Enable pre-determined set of hardening options in GCC                                        |
 | [`-Wl,--as-needed`](#-Wl,--as-needed)<br/>[`-Wl,--no-copy-dt-needed-entries`](#-Wl,--no-copy-dt-needed-entries) | Binutils 2.20.0 | Allow linker to omit libraries specified on the command line to link against if they are not used |
@@ -1037,15 +1037,15 @@ This option eliminates this problem. It's used by the Linux kernel.
 
 ---
 
-### Perform trivial auto variable initialization
+### Initialize automatic variables that lack explicit initializers
 
-| Compiler Flag                                                       | Supported since     | Description                                  |
-|:--------------------------------------------------------------------|:-------------------:|:---------------------------------------------|
-| <span id="-ftrivial-auto-var-init">`-ftrivial-auto-var-init`</span> | GCC 12.0.0<br/>Clang 8.0.0| Perform trivial auto variable initialization |
+| Compiler Flag                                                       | Supported since            | Description                                                    |
+|:--------------------------------------------------------------------|:--------------------------:|:---------------------------------------------------------------|
+| <span id="-ftrivial-auto-var-init">`-ftrivial-auto-var-init`</span> | GCC 12.0.0<br/>Clang 8.0.0 | Initialize automatic variables that lack explicit initializers |
 
 #### Synopsis
 
-This option controls if (and how) automatic variables are initialized. Even with the option, the compiler will consider an automatic variable as uninitialized unless it is explicitly initialized.
+This option controls if (and how) automatic, (i.e., stack-allocated) variables are initialized by the compiler in the absence of an explicit initializer.
 
 This option has three choices:
 
@@ -1055,7 +1055,27 @@ This option has three choices:
 
 We recommend using `zero` for production code, to reduce the risk of a logic bug leading to a security vulnerability.
 
-This setting can sometimes interfere with other tools that are being used to monitor executable code, since it is expressly setting a value that was not set by the source code.
+Even when this option is used, GCC will still considers an automatic variable without an explicit initializer as uninitialized for the purpoes of the static analysis performed by `-Wuninitialized` and `-Wanalyzer-use-of-uninitialized-value` and report warning diagnostics accordingly[^gcc-trivial-auto-var-init]. GCC will also perform optimization as if the variable were uninitialized.
+
+#### Performance implications
+
+This option initializes automatic variables at the time they are allocated which can add overhead to programs. For example, in performance-critical code, the initialization of variables might be required to happen at a specific point in the code later than when storage for the variable is allocated on the stack, and the code generated by the compiler when can `-ftrivial-auto-var-init` slow down execution if the generated initialization occurs in a performance-critical code path.
+
+The overhead added by `-ftrivial-auto-var-init` scales with the size and frequency of allocations for which the compiler generates initialization code.
+
+#### When not to use?
+
+Automatic initialization can interfere with dynamic analysis tools such as Valgrind[^valgrind], Dr. Memory[^drmemory], and Clang's Memory Sanitizer[^msan], since it is expressly setting a value that was not set by the source code. This can mask issues with uninitialized variables that could otherwise be detected and fixed, making it less suitable for debugging and software testing. Consequently, we discourage the use of `-ftrivial-auto-var-init` for instrumented test code intended to be used for dynamic analysis of unitialized variables issues.
+
+In specific cases, the `pattern` variant of this option can make uninitialized memory easier to spot when debugging because the patterns used are less likely to be used as real values[^arm-ftrivial-auto-var-init]. For example, the pointer values are chosen to be invalid for many systems.
+
+In addition, initializing all automatic variables can lead to an increase in the binary size of the compiled program[^arm-ftrivial-auto-var-init]. This can be an issue in embedded environments where memory is limited.
+
+[^gcc-trivial-auto-var-init]: GCC team, [Options That Control Optimization: `-ftrivial-auto-var-init`](https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-ftrivial-auto-var-init), GCC Manual, 2025-05-30..
+[^arm-ftrivial-auto-var-init]: Arm, [Arm Compiler for Embedded Reference Guide: `-ftrivial-auto-var-init`](https://developer.arm.com/documentation/101754/0624/armclang-Reference/armclang-Command-line-Options/-ftrivial-auto-var-init), Arm Compiler for Embedded Reference Guide, Version 6.24, 2025-05-31.
+[^valgrind]: Valgrind Developers, [Valgrind](https://valgrind.org/), 2025-05-20.
+[^drmemory]: Dr. memory team, [Dr. Memory](https://drmemory.org/), 2025-04-11.
+[^msan]: LLVM Sanitizers team, [NemorySanitizer](https://github.com/google/sanitizers/wiki/memorysanitizerr), GitHub google/sanitizers Wiki, 2024-06-09.
 
 <!-- More information
 https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-ftrivial-auto-var-init