[DOCS] Add more detail to stack protector documentation

[psmith]

Summary

The Clang -fstack-protector documentation mentions what functions are considered vulnerable but does not mention the details of the
implementation such as the use of a global variable for the guard value. This brings the documentation more in line with the GCC
documentation at: https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html and gives someone using the option more idea about what is protected.

This partly addresses https://bugs.llvm.org/show_bug.cgi?id=42764

[probinson]

Looks okay (one grammar nit), probably worth waiting for someone else to chime in.

clang/docs/ClangCommandLineReference.rst

2139

"overwrite to the guard variable" -> "overwrite the guard variable"

[MaskRay]

This file is auto generated. The real documentation should go to clang/include/clang/Driver/Options.td

[psmith]

In D85239#2194604, @MaskRay wrote:

This file is auto generated. The real documentation should go to clang/include/clang/Driver/Options.td

Thanks for pointing that out! I regenerated the ClangCommandLineReference.rst from Options.td but it looks like I'm not the only one that missed the comment on the top line. There are 27 differences in the file including some that are not in Options.td. I'm loathe to lose work by regenerating the whole file so I've included just the diff created by the change to Options.td. At least if the file is synched up again then we'll keep the edits.

Assuming this is still OK I'll commit tomorrow.

[psmith]

uploaded diff with both Options.td and ClangCommandLineReference.rst

[psmith]

clang/docs/ClangCommandLineReference.rst

2139

Thanks, now updated

[probinson]

Whoa--that's the *help* text? Well, if that's the only documentation for options that there is, I guess it has to go there; but it seems pretty excessive for the (ideally concise) output of clang --help.

[psmith]

I agree it's not what I'd like. I'm not sure how to react to MaskRays comment. The top of the ClangCommandLineReference.rst says:

-------------------------------------------------------------------
NOTE: This file is automatically generated by running clang-tblgen
-gen-opt-docs. Do not edit this file by hand!!
-------------------------------------------------------------------

This uses Options.td to generate the file. I don't know how true this is anymore given that both files are checked in. They may have been separated. I've seen at least one instance in the log where the whole file has been regenerated.

I'm happy to revert the Options.td change if there is another way?

[MaskRay]

The file is auto-generated by:
path/to/clang-tblgen -gen-opt-docs -I clang/include/clang/Driver -I llvm/include/ clang/include/clang/Driver/ClangOptionDocs.td > clang/docs/ClangCommandLineReference.rst

The description is retrieved from DocBrief. If DocBrief does not exist, HelpText provides a fallback. I think there needs to be a better way to organize detailed help messages. Inlined help is just too cumbersome. For attributes, there is a TableGen file clang/include/clang/Basic/AttrDocs.td

@rsmith

clang/docs/ClangCommandLineReference.rst

 .. option:: -fsplit-stack
 
 .. option:: -fstack-clash-protection
 
 Enable stack clash protection
 
 .. option:: -fstack-protector, -fno-stack-protector
 
-Enable stack protectors for some functions vulnerable to stack smashing. This uses a loose heuristic which considers functions vulnerable if they contain a char (or 8bit integer) array or constant sized calls to alloca, which are of greater size than ssp-buffer-size (default: 8 bytes). All variable sized calls to alloca are considered vulnerable
+Enable stack protectors for some functions vulnerable to stack smashing. This uses a loose heuristic which considers functions vulnerable if they contain a char (or 8bit integer) array or constant sized calls to alloca , which are of greater size than ssp-buffer-size (default: 8 bytes). All variable sized calls to alloca are considered vulnerable. A function witha stack protector has a guard value added to the stack frame that is checked on function exit. The guard value must be positioned in the stack frame such that a buffer overflow from a vulnerable variable will overwrite the guard value before overwriting the function's return address. The reference stack guard value is stored in a global variable.
 
 .. option:: -fstack-protector-all
 
 Enable stack protectors for all functions
 
 .. option:: -fstack-protector-strong
 
 Enable stack protectors for some functions vulnerable to stack smashing. Compared to -fstack-protector, this uses a stronger heuristic that includes functions containing arrays of any size (and any type), as well as any calls to alloca or the taking of an address from a local variable

clang/include/clang/Driver/Options.td

def fnostack_clash_protection : Flag<["-"], "fnostack-clash-protection">, Group<f_Group>,
   HelpText<"Disable stack clash protection">;
 def fstack_protector_strong : Flag<["-"], "fstack-protector-strong">, Group<f_Group>,
   HelpText<"Enable stack protectors for some functions vulnerable to stack smashing. "
            "Compared to -fstack-protector, this uses a stronger heuristic "
            "that includes functions containing arrays of any size (and any type), "
            "as well as any calls to alloca or the taking of an address from a local variable">;
 def fstack_protector : Flag<["-"], "fstack-protector">, Group<f_Group>,
   HelpText<"Enable stack protectors for some functions vulnerable to stack smashing. "
-           "This uses a loose heuristic which considers functions vulnerable "
-           "if they contain a char (or 8bit integer) array or constant sized calls to "
-           "alloca, which are of greater size than ssp-buffer-size (default: 8 bytes). "
-           "All variable sized calls to alloca are considered vulnerable">;
+           "This uses a loose heuristic which considers functions vulnerable if they "
+           "contain a char (or 8bit integer) array or constant sized calls to alloca "
+           ", which are of greater size than ssp-buffer-size (default: 8 bytes). All "
+           "variable sized calls to alloca are considered vulnerable. A function with"
+           "a stack protector has a guard value added to the stack frame that is "
+           "checked on function exit. The guard value must be positioned in the "
+           "stack frame such that a buffer overflow from a vulnerable variable will "
+           "overwrite the guard value before overwriting the function's return "
+           "address. The reference stack guard value is stored in a global variable.">;
 def ftrivial_auto_var_init : Joined<["-"], "ftrivial-auto-var-init=">, Group<f_Group>,
   Flags<[CC1Option, CoreOption]>, HelpText<"Initialize trivial automatic stack variables: uninitialized (default)"
   " | pattern">, Values<"uninitialized,pattern">;
 def enable_trivial_var_init_zero : Flag<["-"], "enable-trivial-auto-var-init-zero-knowing-it-will-be-removed-from-clang">,
   Flags<[CC1Option, CoreOption]>,
   HelpText<"Trivial automatic variable initialization to zero is only here for benchmarks, it'll eventually be removed, and I'm OK with that because I'm only using it to benchmark">;
 def ftrivial_auto_var_init_stop_after : Joined<["-"], "ftrivial-auto-var-init-stop-after=">, Group<f_Group>,
   Flags<[CC1Option, CoreOption]>, HelpText<"Stop initializing trivial automatic stack variables after the specified number of instances">;