[KeyInstr][Clang] Add Clang option -g[no-]key-instructions (#134627)

This needs to be driver level to pass an -mllvm flag to LLVM, though this may
change soon as the -mllvm flag will soon not be necessary.

Keep the flag help-hidden as the feature is under development.

This patch is part of a stack that teaches Clang to generate Key Instructions
metadata for C and C++.

RFC:
https://discourse.llvm.org/t/rfc-improving-is-stmt-placement-for-better-interactive-debugging/82668

The feature is only functional in LLVM if LLVM is built with CMake flag
LLVM_EXPERIMENTAL_KEY_INSTRUCTIONs. Eventually that flag will be removed.

Author: OCHyams

clang/include/clang/Basic/DebugOptions.def

@@ -75,6 +75,9 @@ DEBUGOPT(DebugOmitUnreferencedMethods, 1, 0) ///< Omit unreferenced member
 BENIGN_ENUM_DEBUGOPT(AssignmentTrackingMode, AssignmentTrackingOpts, 2,
                      AssignmentTrackingOpts::Disabled)
 
+/// Whether or not to use Key Instructions to determine breakpoint locations.
+BENIGN_DEBUGOPT(DebugKeyInstructions, 1, 0)
+
 DEBUGOPT(DebugColumnInfo, 1, 0) ///< Whether or not to use column information
                                 ///< in debug info.
 

clang/include/clang/Driver/Options.td

@@ -4664,6 +4664,12 @@ def gembed_source : Flag<["-"], "gembed-source">, Group<g_flags_Group>,
 def gno_embed_source : Flag<["-"], "gno-embed-source">, Group<g_flags_Group>,
     Flags<[NoXarchOption]>,
     HelpText<"Restore the default behavior of not embedding source text in DWARF debug sections">;
+defm key_instructions : BoolGOption<"key-instructions",
+    CodeGenOpts<"DebugKeyInstructions">, DefaultFalse,
+    NegFlag<SetFalse>, PosFlag<SetTrue, [], [],
+        "Enable Key Instructions, which reduces the jumpiness of optimized code stepping (DWARF only)."
+        " Requires LLVM built with LLVM_EXPERIMENTAL_KEY_INSTRUCTIONS.">,
+    BothFlags<[HelpHidden], [ClangOption, CLOption, CC1Option]>>;
 def headerpad__max__install__names : Joined<["-"], "headerpad_max_install_names">;
 def help : Flag<["-", "--"], "help">,
     Visibility<[ClangOption, CC1Option, CC1AsOption,

clang/lib/Driver/ToolChains/Clang.cpp

@@ -4776,6 +4776,13 @@ renderDebugOptions(const ToolChain &TC, const Driver &D, const llvm::Triple &T,
       CmdArgs.push_back("-gembed-source");
   }
 
+  if (Args.hasFlag(options::OPT_gkey_instructions,
+                   options::OPT_gno_key_instructions, false)) {
+    CmdArgs.push_back("-gkey-instructions");
+    CmdArgs.push_back("-mllvm");
+    CmdArgs.push_back("-dwarf-use-key-instructions");
+  }
+
   if (EmitCodeView) {
     CmdArgs.push_back("-gcodeview");
 

clang/test/CMakeLists.txt

@@ -26,6 +26,7 @@ llvm_canonicalize_cmake_booleans(
   PPC_LINUX_DEFAULT_IEEELONGDOUBLE
   LLVM_TOOL_LLVM_DRIVER_BUILD
   LLVM_INCLUDE_SPIRV_TOOLS_TESTS
+  LLVM_EXPERIMENTAL_KEY_INSTRUCTIONS
   )
 
 configure_lit_site_cfg(

clang/test/DebugInfo/KeyInstructions/flag.cpp

@@ -0,0 +1,15 @@
+// RUN: %clang -### -target x86_64 -c -gdwarf -gkey-instructions %s 2>&1 | FileCheck %s --check-prefixes=KEY-INSTRUCTIONS
+// RUN: %clang -### -target x86_64 -c -gdwarf -gno-key-instructions %s 2>&1 | FileCheck %s --check-prefixes=NO-KEY-INSTRUCTIONS
+//// Default: Off.
+// RUN: %clang -### -target x86_64 -c -gdwarf %s 2>&1 | FileCheck %s --check-prefixes=NO-KEY-INSTRUCTIONS
+
+//// Help hidden.
+// RUN %clang --help | FileCheck %s --check-prefix=HELP
+// HELP-NOT: key-instructions
+
+// KEY-INSTRUCTIONS: "-gkey-instructions"
+// KEY-INSTRUCTIONS: "-mllvm" "-dwarf-use-key-instructions"
+
+// NO-KEY-INSTRUCTIONS-NOT: key-instructions
+
+//// TODO: Add smoke test once some functionality has been added.

clang/test/DebugInfo/KeyInstructions/lit.local.cfg

@@ -0,0 +1,2 @@
+if not config.has_key_instructions:
+    config.unsupported = True

clang/test/lit.site.cfg.py.in

@@ -48,6 +48,7 @@ config.ppc_linux_default_ieeelongdouble = @PPC_LINUX_DEFAULT_IEEELONGDOUBLE@
 config.have_llvm_driver = @LLVM_TOOL_LLVM_DRIVER_BUILD@
 config.spirv_tools_tests = @LLVM_INCLUDE_SPIRV_TOOLS_TESTS@
 config.substitutions.append(("%llvm-version-major", "@LLVM_VERSION_MAJOR@"))
+config.has_key_instructions = @LLVM_EXPERIMENTAL_KEY_INSTRUCTIONS@
 
 import lit.llvm
 lit.llvm.initialize(lit_config, config)