[KeyInstr][Clang] Add Clang option -g[no-]key-instructions

This needs to be driver level to pass an -mllvm flag to LLVM.

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++.

The Key Instructions project is introduced, including a "quick summary" section
at the top which adds context for this PR, here:
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.

The Clang-side work is demoed here:
#130943

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

@@ -4588,6 +4588,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

@@ -4767,6 +4767,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

@@ -23,6 +23,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/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/KeyInstructions/lit.local.cfg

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

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

@@ -45,6 +45,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)