[Docs] Expand -fstack-protector and -fstack-protector-all info

[carwil]

Summary

Improve the description of these command line options by providing specific heuristic information, as outlined for the ssp function attribute(s) in LLVM's documentation.

[lebedev.ri]

Please linewrap to 80 col.

[carwil]

Edited Options.td directly, rather than the generated docs file.

[thopre]

include/clang/Driver/Options.td

1634–1636 ↗

(On Diff #177239)

I'm not sure what's the policy for related options but I feel the description should stand on its own. I'd therefor start by:

"Enable stack protectors for some functions potentially vulnerable to stack smashing. Compared to -fstack-protector, this uses a stronger heuristic (....)"

If the policy is to avoid such repeatition then please ignore this comment.

1638 ↗

(On Diff #177239)

Not a native english speaker but I feel that "potentially" is redundant given you said it enables stack protector for *some* functions. Perhaps rewrite it along the lines of:

"Enable stack protectors for some of the functions vulnerable to stack smashing based on simple heuristic"

with a better word than "simple". This conveys both that not all functions are protected and suggests that a better heuristic is possible. You can then easily refer the reader to -fstack-protector-strong and -fstack-protector-all in a following sentence.

[carwil]

Make thopre's suggested changes.

[thopre]

include/clang/Driver/Options.td

1636 ↗

(On Diff #177668)

May I suggest to change it to "Enable stack protectors for all functions" for consistency with below entries? Rest LGTM otherwise.

[carwil]

Reworded -fstack-protector-all to bring it in line with the changes to the other two options.

[thopre]

LGTM. Thanks!

cfe/trunk/include/clang/Driver/Options.td

 def fspell_checking : Flag<["-"], "fspell-checking">, Group<f_Group>;
 def fspell_checking_limit_EQ : Joined<["-"], "fspell-checking-limit=">, Group<f_Group>;
 def fsigned_bitfields : Flag<["-"], "fsigned-bitfields">, Group<f_Group>;
 def fsigned_char : Flag<["-"], "fsigned-char">, Group<f_Group>;
 def fno_signed_char : Flag<["-"], "fno-signed-char">, Group<f_Group>,
     Flags<[CC1Option]>, HelpText<"Char is unsigned">;
 def fsplit_stack : Flag<["-"], "fsplit-stack">, Group<f_Group>;
 def fstack_protector_all : Flag<["-"], "fstack-protector-all">, Group<f_Group>,
-  HelpText<"Force the usage of stack protectors for all functions">;
+  HelpText<"Enable stack protectors for all functions">;
 def fstack_protector_strong : Flag<["-"], "fstack-protector-strong">, Group<f_Group>,
-  HelpText<"Use a strong heuristic to apply stack protectors to functions">;
+  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 functions potentially vulnerable to stack smashing">;
+  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">;
 def fstandalone_debug : Flag<["-"], "fstandalone-debug">, Group<f_Group>, Flags<[CoreOption]>,
   HelpText<"Emit full debug info for all types used by the program">;
 def fno_standalone_debug : Flag<["-"], "fno-standalone-debug">, Group<f_Group>, Flags<[CoreOption]>,
   HelpText<"Limit debug information produced to reduce size of debug binary">;
 def flimit_debug_info : Flag<["-"], "flimit-debug-info">, Flags<[CoreOption]>, Alias<fno_standalone_debug>;
 def fno_limit_debug_info : Flag<["-"], "fno-limit-debug-info">, Flags<[CoreOption]>, Alias<fstandalone_debug>;
 def fdebug_macro : Flag<["-"], "fdebug-macro">, Group<f_Group>, Flags<[CoreOption]>,
   HelpText<"Emit macro debug information">;