[clang] [clang-cl] Document behavior difference of strict aliasing in clang-cl vs clang. (PR #68460)

[Huihui Zhang via cfe-commits]

https://github.com/huihzhang created https://github.com/llvm/llvm-project/pull/68460

Add an user note to pass -fstrict-aliasing explicitly for clang-cl at optimization levels O3 and below to enable TBAA.
Also add help text for -f[no-]strict-aliasing.

>From 866ebc3da4208f2be206cc9839fc06d689d9bf34 Mon Sep 17 00:00:00 2001
From: Huihui Zhang <huihuiz at quicinc.com>
Date: Fri, 6 Oct 2023 17:37:03 -0700
Subject: [PATCH] [clang-cl] Document behavior difference of strict aliasing in
 clang-cl vs clang.

Add an user note to pass -fstrict-aliasing explicitly for clang-cl at
optimization levels O3 and below to enable TBAA.
Also add help text for -f[no-]strict-aliasing.
---
 clang/docs/UsersManual.rst            | 16 ++++++++++++++++
 clang/include/clang/Driver/Options.td |  6 ++++--
 2 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index 25bbd72c81f7a3b..704a634ffd8c8c4 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -4383,6 +4383,7 @@ Execute ``clang-cl /?`` to see a list of supported options:
       -fno-sanitize-trap=<value>
                               Disable trapping for specified sanitizers
       -fno-standalone-debug   Limit debug information produced to reduce size of debug binary
+      -fno-strict-aliasing    Disable optimizations based on strict aliasing rules (default)
       -fobjc-runtime=<value>  Specify the target Objective-C runtime kind and version
       -fprofile-exclude-files=<value>
                               Instrument only functions from files where names don't match all the regexes separated by a semi-colon
@@ -4444,6 +4445,7 @@ Execute ``clang-cl /?`` to see a list of supported options:
                               behavior. See user manual for available checks
       -fsplit-lto-unit        Enables splitting of the LTO unit.
       -fstandalone-debug      Emit full debug info for all types used by the program
+      -fstrict-aliasing	      Enable optimizations based on strict aliasing rules
       -fsyntax-only           Run the preprocessor, parser and semantic analysis stages
       -fwhole-program-vtables Enables whole-program vtable optimization. Requires -flto
       -gcodeview-ghash        Emit type record hashes in a .debug$H section
@@ -4722,3 +4724,17 @@ The Visual C++ Toolset has a slightly more elaborate mechanism for detection.
     The registry information is used to help locate the installation as a final
     fallback.  This is only possible for pre-VS2017 installations and is
     considered deprecated.
+
+Restrictions and Limitations compared to Clang
+----------------------------------------------
+
+Strict Aliasing
+^^^^^^^^^^^^^^^
+
+Strict aliasing (TBAA) is turned off by default in clang-cl at optimization
+levels O3 and below, and turned on at Ofast. Whereas in clang, strict aliasing
+is turned on by default for all optimization levels.
+
+To enable LLVM optimizations based on strict aliasing rules (e.g., optimizations
+based on type of expressions in C/C++), user will need to explicitly pass
+`-fstrict-aliasing` to clang-cl when compiling at O3 and below.
diff --git a/clang/include/clang/Driver/Options.td b/clang/include/clang/Driver/Options.td
index 5415b18d3f406df..2109513364dba14 100644
--- a/clang/include/clang/Driver/Options.td
+++ b/clang/include/clang/Driver/Options.td
@@ -3152,7 +3152,8 @@ defm diagnostics_show_line_numbers : BoolFOption<"diagnostics-show-line-numbers"
 def fno_stack_protector : Flag<["-"], "fno-stack-protector">, Group<f_Group>,
   HelpText<"Disable the use of stack protectors">;
 def fno_strict_aliasing : Flag<["-"], "fno-strict-aliasing">, Group<f_Group>,
-  Flags<[NoXarchOption]>, Visibility<[ClangOption, CLOption, DXCOption]>;
+  Flags<[NoXarchOption]>, Visibility<[ClangOption, CLOption, DXCOption]>,
+  HelpText<"Disable optimizations based on strict aliasing rules (default)">;
 def fstruct_path_tbaa : Flag<["-"], "fstruct-path-tbaa">, Group<f_Group>;
 def fno_struct_path_tbaa : Flag<["-"], "fno-struct-path-tbaa">, Group<f_Group>;
 def fno_strict_enums : Flag<["-"], "fno-strict-enums">, Group<f_Group>;
@@ -3595,7 +3596,8 @@ def fno_debug_macro : Flag<["-"], "fno-debug-macro">, Group<f_Group>,
   Visibility<[ClangOption, CLOption, DXCOption]>,
   HelpText<"Do not emit macro debug information">;
 def fstrict_aliasing : Flag<["-"], "fstrict-aliasing">, Group<f_Group>,
-  Flags<[NoXarchOption]>, Visibility<[ClangOption, CLOption, DXCOption]>;
+  Flags<[NoXarchOption]>, Visibility<[ClangOption, CLOption, DXCOption]>,
+  HelpText<"Enable optimizations based on strict aliasing rules">;
 def fstrict_enums : Flag<["-"], "fstrict-enums">, Group<f_Group>,
   Visibility<[ClangOption, CC1Option]>,
   HelpText<"Enable optimizations based on the strict definition of an enum's "