Add --print-supported-cpus flag for clang.

[ziangwan]

Summary

This patch allows clang users to print out a list of supported CPU models using

clang [--target=<target triple>] --print-supported-cpus

Then, users can select the CPU model to compile to using

clang --target=<triple> -mcpu=<model> a.c

It is a handy feature to help cross compilation.

While the flag seems to be a front-end option, the supported CPU models are stored in each target machine in the back-end. This patch attempts to create a short cut to directly retrieve information from the back-end target machines at the front-end.

[kongyi]

Please include diff context. https://llvm.org/docs/Phabricator.html#requesting-a-review-via-the-web-interface

[ziangwan]

Add full context. Change the name of the static variable from "Printed" to "PrintOnce". Add a newline for the test file.

[kongyi]

clang/docs/ClangCommandLineReference.rst

613

L615 should be after L609.

clang/test/Driver/print-supported-cpus.c

4

Add test for a different architecture to verify that --target works.

clang/tools/driver/cc1_main.cpp

185

RM seems to be unused. Can you use None?

186

Use unique_ptr instead.

[lebedev.ri]

clang/docs/ClangCommandLineReference.rst

613

this line seems out-of-place, it's already documented in Target-dependent compilation options section

llvm/lib/MC/MCSubtargetInfo.cpp

143

Is this correct? Is this due to the --target?
I've never ever seen that flag used, on x86 -march/-mtune is pretty much always used.

[ziangwan]

Adjust the docs: remove the redundant -mcpu flag. Add an explanation for --print-supported-cpus.
Replace one manual delete with std::unique_ptr.
Use None for an llvm::Optional value.
Add one more test case.
Adjust the message printout to include the usage of -mtune.

[ziangwan]

llvm/lib/MC/MCSubtargetInfo.cpp

143

Both -mtune and -mcpu accept the processor names listed by --print-supported-cpus. The difference is that -mcpu also specify the instruction set given the processor while -mtune will use a more generic instruction set.

[kongyi]

LGTM.

[ziangwan]

Committed. SVN Revision: 363464.

[dyung]

Hi Ziang,

Your test fails if the the compiler does not include the x86_64 and ARM backends. For example, the PS4 target compiler only includes the x86_64 backend, so it fails when trying to use ARM like you are attempting to do.

http://lab.llvm.org:8011/builders/llvm-clang-lld-x86_64-scei-ps4-windows10pro-fast/builds/22/steps/test/logs/stdio

FAIL: Clang :: Driver/print-supported-cpus.c (8911 of 50224)
******************** TEST 'Clang :: Driver/print-supported-cpus.c' FAILED ********************
Script:
--
: 'RUN: at line 3';   c:\ps4-buildslave2\llvm-clang-lld-x86_64-scei-ps4-windows10pro-fast\llvm.obj\bin\clang.exe --target=x86_64-unknown-linux-gnu    --print-supported-cpus 2>&1    | c:\ps4-buildslave2\llvm-clang-lld-x86_64-scei-ps4-windows10pro-fast\llvm.obj\bin\filecheck.exe C:\ps4-buildslave2\llvm-clang-lld-x86_64-scei-ps4-windows10pro-fast\llvm.src\tools\clang\test\Driver\print-supported-cpus.c --check-prefix=CHECK-X86
: 'RUN: at line 10';   c:\ps4-buildslave2\llvm-clang-lld-x86_64-scei-ps4-windows10pro-fast\llvm.obj\bin\clang.exe --target=arm-unknown-linux-android    --print-supported-cpus 2>&1    | c:\ps4-buildslave2\llvm-clang-lld-x86_64-scei-ps4-windows10pro-fast\llvm.obj\bin\filecheck.exe C:\ps4-buildslave2\llvm-clang-lld-x86_64-scei-ps4-windows10pro-fast\llvm.src\tools\clang\test\Driver\print-supported-cpus.c --check-prefix=CHECK-ARM
--
Exit Code: 1

Command Output (stdout):
--
$ ":" "RUN: at line 3"
$ "c:\ps4-buildslave2\llvm-clang-lld-x86_64-scei-ps4-windows10pro-fast\llvm.obj\bin\clang.exe" "--target=x86_64-unknown-linux-gnu" "--print-supported-cpus"
$ "c:\ps4-buildslave2\llvm-clang-lld-x86_64-scei-ps4-windows10pro-fast\llvm.obj\bin\filecheck.exe" "C:\ps4-buildslave2\llvm-clang-lld-x86_64-scei-ps4-windows10pro-fast\llvm.src\tools\clang\test\Driver\print-supported-cpus.c" "--check-prefix=CHECK-X86"
$ ":" "RUN: at line 10"
$ "c:\ps4-buildslave2\llvm-clang-lld-x86_64-scei-ps4-windows10pro-fast\llvm.obj\bin\clang.exe" "--target=arm-unknown-linux-android" "--print-supported-cpus"
note: command had no output on stdout or stderr
error: command failed with exit status: 1
$ "c:\ps4-buildslave2\llvm-clang-lld-x86_64-scei-ps4-windows10pro-fast\llvm.obj\bin\filecheck.exe" "C:\ps4-buildslave2\llvm-clang-lld-x86_64-scei-ps4-windows10pro-fast\llvm.src\tools\clang\test\Driver\print-supported-cpus.c" "--check-prefix=CHECK-ARM"
# command stderr:
C:\ps4-buildslave2\llvm-clang-lld-x86_64-scei-ps4-windows10pro-fast\llvm.src\tools\clang\test\Driver\print-supported-cpus.c:14:15: error: CHECK-ARM: expected string not found in input

// CHECK-ARM: cortex-a73

              ^

<stdin>:3:1: note: scanning from here

Thread model: posix

^

<stdin>:5:64: note: possible intended match here

No available targets are compatible with triple "armv4t-unknown-linux-android"

                                                               ^


error: command failed with exit status: 1

Can you fix the test so that it does not depend on the backend being present if possible, or find another way to test the feature?

[nickdesaulniers]

There are lots of tests under clang/test/ that target arm-- as a -triple. How is it that they don't fail in the same way? %clang_cc1 -triple arm-- is somehow different?

[nickdesaulniers]

https://llvm.org/docs/TestingGuide.html mentions .cfg files, but tests I've looked at don't seem to have a .cfg in their directory.

[dyung]

In D63105#1544519, @nickdesaulniers wrote:

There are lots of tests under clang/test/ that target arm-- as a -triple. How is it that they don't fail in the same way? %clang_cc1 -triple arm-- is somehow different?

I can't answer in general, but a quick scan of the test/Driver directory shows most tests use "-###", so it doesn't matter if a particular target is present or not in the backend.

[nickdesaulniers]

@pirama and @kongyi pointed out to me that -emit-llvm tests don't require backend support, and that the undocumented (https://llvm.org/docs/CommandGuide/FileCheck.html) REQUIRES: tag would fix this.

[ziangwan]

I am working on fixing the test file right now. I will add REQUIRES: x86-registered-target and REQUIRES: arm-registered-target before each test correspondingly.

[ziangwan]

@dyung I pushed another commit to fix the test. Let me know if the problem persists.

[MaskRay]

This option is useful but may be hard to discover. Will something like -march=? and -mtune=? make the feature more discoverable?

[ziangwan]

This option is useful but may be hard to discover. Will something like -march=? and -mtune=? make the feature more discoverable?

That's a good idea. Currently, my change has nothing to do with -march or -mtune. I might work on that later.

clang/docs/ClangCommandLineReference.rst

 .. option:: --sysroot=<arg>, --sysroot <arg>
 
 .. option:: --target-help
 
 .. option:: --target=<arg>, -target <arg>
 
 Generate code for the given target
 
+.. option:: --print-supported-cpus
+
+Print supported cpu models for the given target
+
 .. option:: -time
 
 Time individual commands
 
 .. option:: -traditional, --traditional
 
 .. option:: -traditional-cpp, --traditional-cpp
 

clang/docs/CommandGuide/clang.rst

.. option:: -mmacosx-version-min=<version>
   When building for macOS, specify the minimum version supported by your
   application.
 
 .. option:: -miphoneos-version-min
 
   When building for iPhone OS, specify the minimum version supported by your
   application.
 
+.. option:: --print-supported-cpus
+
+  Print out a list of supported processors for the given target (specified 
+  through --target=<architecture> or -arch <architecture>). If no target is 
+  specified, the system default target will be used.
+
 .. option:: -march=<cpu>
 
   Specify that Clang should generate code for a specific processor family
   member and later.  For example, if you specify -march=i486, the compiler is
   allowed to generate instructions that are valid on i486 and later processors,
   but which may not exist on earlier ones.
 
 

clang/include/clang/Driver/Options.td

 def no_system_header_prefix : Joined<["--"], "no-system-header-prefix=">,
   Group<clang_i_Group>, Flags<[CC1Option]>, MetaVarName<"<prefix>">,
   HelpText<"Treat all #include paths starting with <prefix> as not including a "
            "system header.">;
 def : Separate<["--"], "no-system-header-prefix">, Alias<no_system_header_prefix>;
 def s : Flag<["-"], "s">, Group<Link_Group>;
 def target : Joined<["--"], "target=">, Flags<[DriverOption, CoreOption]>,
   HelpText<"Generate code for the given target">;
+def _print_supported_cpus : Flag<["-", "--"], "print-supported-cpus">,
+  Group<CompileOnly_Group>, Flags<[CC1Option, CoreOption]>,
+  HelpText<"Print supported cpu models for the given target (if target is not specified,"
+           " it will print the supported cpus for the default target)">;
 def gcc_toolchain : Joined<["--"], "gcc-toolchain=">, Flags<[DriverOption]>,
   HelpText<"Use the gcc toolchain at the given directory">;
 def time : Flag<["-"], "time">,
   HelpText<"Time individual commands">;
 def traditional_cpp : Flag<["-", "--"], "traditional-cpp">, Flags<[CC1Option]>,
   HelpText<"Enable some traditional CPP emulation">;
 def traditional : Flag<["-", "--"], "traditional">;
 def trigraphs : Flag<["-", "--"], "trigraphs">, Alias<ftrigraphs>,

clang/include/clang/Frontend/FrontendOptions.h

public:
   unsigned ShowHelp : 1;
 
   /// Show frontend performance metrics and statistics.
   unsigned ShowStats : 1;
 
   /// Show timers for individual actions.
   unsigned ShowTimers : 1;
 
+  /// print the supported cpus for the current target
+  unsigned PrintSupportedCPUs : 1;
+
   /// Output time trace profile.
   unsigned TimeTrace : 1;
 
   /// Show the -version text.
   unsigned ShowVersion : 1;
 
   /// Apply fixes even if there are unfixable errors.
   unsigned FixWhatYouCan : 1;

clang/lib/Driver/Driver.cpp

bool Driver::HandleImmediateArgs(const Compilation &C) {
 
   if (C.getArgs().hasArg(options::OPT__version)) {
     // Follow gcc behavior and use stdout for --version and stderr for -v.
     PrintVersion(C, llvm::outs());
     return false;
   }
 
   if (C.getArgs().hasArg(options::OPT_v) ||
-      C.getArgs().hasArg(options::OPT__HASH_HASH_HASH)) {
+      C.getArgs().hasArg(options::OPT__HASH_HASH_HASH) ||
+      C.getArgs().hasArg(options::OPT__print_supported_cpus)) {
     PrintVersion(C, llvm::errs());
     SuppressMissingInputWarning = true;
   }
 
   if (C.getArgs().hasArg(options::OPT_v)) {
     if (!SystemConfigDir.empty())
       llvm::errs() << "System configuration file directory: "
                    << SystemConfigDir << "\n";
void Driver::BuildActions(Compilation &C, DerivedArgList &Args,
 
   // If we are linking, claim any options which are obviously only used for
   // compilation.
   if (FinalPhase == phases::Link && PL.size() == 1) {
     Args.ClaimAllArgs(options::OPT_CompileOnly_Group);
     Args.ClaimAllArgs(options::OPT_cl_compile_Group);
   }
 
+  // If the use specify --print-supported-cpus, clang will only print out
+  // supported cpu names without doing compilation.
+  if (Arg *A = Args.getLastArg(options::OPT__print_supported_cpus)) {
+    Actions.clear();
+    // the compilation now has only two phases: Input and Compile
+    // use the --prints-supported-cpus flag as the dummy input to cc1
+    Action *InputAc = C.MakeAction<InputAction>(*A, types::TY_C);
+    Actions.push_back(C.MakeAction<PrecompileJobAction>(InputAc, types::TY_Nothing));
+  }
+
   // Claim ignored clang-cl options.
   Args.ClaimAllArgs(options::OPT_cl_ignored_Group);
 
   // Claim --cuda-host-only and --cuda-compile-host-device, which may be passed
   // to non-CUDA compilations and should not trigger warnings there.
   Args.ClaimAllArgs(options::OPT_cuda_host_only);
   Args.ClaimAllArgs(options::OPT_cuda_compile_host_device);
 }

clang/lib/Frontend/CompilerInvocation.cpp

static InputKind ParseFrontendArgs(FrontendOptions &Opts, ArgList &Args,
   Opts.DisableFree = Args.hasArg(OPT_disable_free);
 
   Opts.OutputFile = Args.getLastArgValue(OPT_o);
   Opts.Plugins = Args.getAllArgValues(OPT_load);
   Opts.RelocatablePCH = Args.hasArg(OPT_relocatable_pch);
   Opts.ShowHelp = Args.hasArg(OPT_help);
   Opts.ShowStats = Args.hasArg(OPT_print_stats);
   Opts.ShowTimers = Args.hasArg(OPT_ftime_report);
+  Opts.PrintSupportedCPUs = Args.hasArg(OPT__print_supported_cpus);
   Opts.TimeTrace = Args.hasArg(OPT_ftime_trace);
   Opts.ShowVersion = Args.hasArg(OPT_version);
   Opts.ASTMergeFiles = Args.getAllArgValues(OPT_ast_merge);
   Opts.LLVMArgs = Args.getAllArgValues(OPT_mllvm);
   Opts.FixWhatYouCan = Args.hasArg(OPT_fix_what_you_can);
   Opts.FixOnlyWarnings = Args.hasArg(OPT_fix_only_warnings);
   Opts.FixAndRecompile = Args.hasArg(OPT_fixit_recompile);
   Opts.FixToTemporaries = Args.hasArg(OPT_fixit_to_temp);

clang/test/Driver/print-supported-cpus.c

+// Test that the --print-supported-cpus flag works
+
+// RUN: %clang --target=x86_64-unknown-linux-gnu \
+// RUN:   --print-supported-cpus 2>&1 \
+// RUN:   | FileCheck %s --check-prefix=CHECK-X86
+// CHECK-X86: Target: x86_64-unknown-linux-gnu
+// CHECK-X86: corei7
+// CHECK-X86: Use -mcpu or -mtune to specify the target's processor.
+
+// RUN: %clang --target=arm-unknown-linux-android \
+// RUN:   --print-supported-cpus 2>&1 \
+// RUN:   | FileCheck %s --check-prefix=CHECK-ARM
+// CHECK-ARM: Target: arm-unknown-linux-android
+// CHECK-ARM: cortex-a73
+// CHECK-ARM: cortex-a75
+// CHECK-ARM: Use -mcpu or -mtune to specify the target's processor.

clang/tools/driver/cc1_main.cpp

 //===-- cc1_main.cpp - Clang CC1 Compiler Frontend ------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
 // This is the entry point to the clang -cc1 functionality, which implements the
 // core compiler functionality along with a number of additional tools for
 // demonstration and testing purposes.
 //
 //===----------------------------------------------------------------------===//
 
 #include "clang/Basic/Stack.h"
+#include "clang/Basic/TargetOptions.h"
 #include "clang/CodeGen/ObjectFilePCHContainerOperations.h"
 #include "clang/Config/config.h"
 #include "clang/Driver/DriverDiagnostic.h"
 #include "clang/Driver/Options.h"
 #include "clang/Frontend/CompilerInstance.h"
 #include "clang/Frontend/CompilerInvocation.h"
 #include "clang/Frontend/FrontendDiagnostic.h"
 #include "clang/Frontend/TextDiagnosticBuffer.h"
 #include "clang/Frontend/TextDiagnosticPrinter.h"
 #include "clang/Frontend/Utils.h"
 #include "clang/FrontendTool/Utils.h"
 #include "llvm/ADT/Statistic.h"
 #include "llvm/Config/llvm-config.h"
 #include "llvm/LinkAllPasses.h"
 #include "llvm/Option/Arg.h"
 #include "llvm/Option/ArgList.h"
 #include "llvm/Option/OptTable.h"
 #include "llvm/Support/BuryPointer.h"
 #include "llvm/Support/Compiler.h"
 #include "llvm/Support/ErrorHandling.h"
 #include "llvm/Support/ManagedStatic.h"
 #include "llvm/Support/Path.h"
 #include "llvm/Support/Signals.h"
+#include "llvm/Support/TargetRegistry.h"
 #include "llvm/Support/TargetSelect.h"
 #include "llvm/Support/TimeProfiler.h"
 #include "llvm/Support/Timer.h"
 #include "llvm/Support/raw_ostream.h"
+#include "llvm/Target/TargetMachine.h"
 #include <cstdio>
 
 #ifdef CLANG_HAVE_RLIMITS
 #include <sys/resource.h>
 #endif
 
 using namespace clang;
 using namespace llvm::opt;
static void ensureSufficientStack() {
   // We should now have a stack of size at least DesiredStackSize. Ensure
   // that we can actually use that much, if necessary.
   ensureStackAddressSpace();
 }
 #else
 static void ensureSufficientStack() {}
 #endif
 
+/// print supported cpus of the given target
+int PrintSupportedCPUs(std::string TargetStr) {
+  std::string Error;
+  const llvm::Target *TheTarget = llvm::TargetRegistry::lookupTarget(TargetStr, Error);
+  if (!TheTarget) {
+    llvm::errs() << Error;
+    return 1;
+  }
+
+  // the target machine will handle the mcpu printing
+  llvm::TargetOptions Options;
+  std::unique_ptr<llvm::TargetMachine> TheTargetMachine(
+    TheTarget->createTargetMachine(TargetStr, "", "+cpuHelp", Options, None));
+  return 0;
+}
+
 int cc1_main(ArrayRef<const char *> Argv, const char *Argv0, void *MainAddr) {
   ensureSufficientStack();
 
   std::unique_ptr<CompilerInstance> Clang(new CompilerInstance());
   IntrusiveRefCntPtr<DiagnosticIDs> DiagID(new DiagnosticIDs());
 
   // Register the support for object-file-wrapped Clang modules.
   auto PCHOps = Clang->getPCHContainerOperations();
#endif
   TextDiagnosticBuffer *DiagsBuffer = new TextDiagnosticBuffer;
   DiagnosticsEngine Diags(DiagID, &*DiagOpts, DiagsBuffer);
   bool Success = CompilerInvocation::CreateFromArgs(
       Clang->getInvocation(), Argv.begin(), Argv.end(), Diags);
 
   if (Clang->getFrontendOpts().TimeTrace)
     llvm::timeTraceProfilerInitialize();
 
+  // --print-supported-cpus takes priority over the actual compilation
+  if (Clang->getFrontendOpts().PrintSupportedCPUs) {
+    return PrintSupportedCPUs(Clang->getTargetOpts().Triple);
+  }
+
   // Infer the builtin include path if unspecified.
   if (Clang->getHeaderSearchOpts().UseBuiltinIncludes &&
       Clang->getHeaderSearchOpts().ResourceDir.empty())
     Clang->getHeaderSearchOpts().ResourceDir =
       CompilerInvocation::GetResourcesPath(Argv0, MainAddr);
 
   // Create the actual diagnostics engine.
   Clang->createDiagnostics();

llvm/lib/MC/MCSubtargetInfo.cpp

 template <typename T>
 static size_t getLongestEntryLength(ArrayRef<T> Table) {
   size_t MaxLen = 0;
   for (auto &I : Table)
     MaxLen = std::max(MaxLen, std::strlen(I.Key));
   return MaxLen;
 }
 
-/// Display help for feature choices.
+/// Display help for feature and mcpu choices.
 static void Help(ArrayRef<SubtargetSubTypeKV> CPUTable,
                  ArrayRef<SubtargetFeatureKV> FeatTable) {
+  // the static variable ensures that the help information only gets
+  // printed once even though a target machine creates multiple subtargets
+  static bool PrintOnce = false;
+  if (PrintOnce) {
+    return;
+  }
+
   // Determine the length of the longest CPU and Feature entries.
   unsigned MaxCPULen  = getLongestEntryLength(CPUTable);
   unsigned MaxFeatLen = getLongestEntryLength(FeatTable);
 
   // Print the CPU table.
   errs() << "Available CPUs for this target:\n\n";
   for (auto &CPU : CPUTable)
     errs() << format("  %-*s - Select the %s processor.\n", MaxCPULen, CPU.Key,
                      CPU.Key);
   errs() << '\n';
 
   // Print the Feature table.
   errs() << "Available features for this target:\n\n";
   for (auto &Feature : FeatTable)
     errs() << format("  %-*s - %s.\n", MaxFeatLen, Feature.Key, Feature.Desc);
   errs() << '\n';
 
   errs() << "Use +feature to enable a feature, or -feature to disable it.\n"
             "For example, llc -mcpu=mycpu -mattr=+feature1,-feature2\n";
+  
+  PrintOnce = true;
+}
+
+/// Display help for mcpu choices only
+static void cpuHelp(ArrayRef<SubtargetSubTypeKV> CPUTable) {
+  // the static variable ensures that the help information only gets
+  // printed once even though a target machine creates multiple subtargets
+  static bool PrintOnce = false;
+  if (PrintOnce) {
+    return;
+  }
+
+  // Print the CPU table.
+  errs() << "Available CPUs for this target:\n\n";
+  for (auto &CPU : CPUTable)
+    errs() << "\t" << CPU.Key << "\n";
+  errs() << '\n';
+
+  errs() << "Use -mcpu or -mtune to specify the target's processor.\n"
+            "For example, clang --target=aarch64-unknown-linux-gui -mcpu=cortex-a35\n";
+  
+  PrintOnce = true;
 }
 
 static FeatureBitset getFeatures(StringRef CPU, StringRef FS,
                                  ArrayRef<SubtargetSubTypeKV> ProcDesc,
                                  ArrayRef<SubtargetFeatureKV> ProcFeatures) {
   SubtargetFeatures Features(FS);
 
   if (ProcDesc.empty() || ProcFeatures.empty())
else if (!CPU.empty()) {
     }
   }
 
   // Iterate through each feature
   for (const std::string &Feature : Features.getFeatures()) {
     // Check for help
     if (Feature == "+help")
       Help(ProcDesc, ProcFeatures);
+    else if (Feature == "+cpuHelp")
+      cpuHelp(ProcDesc);
     else
       ApplyFeatureFlag(Bits, Feature, ProcFeatures);
   }
 
   return Bits;
 }
 
 void MCSubtargetInfo::InitMCProcessorInfo(StringRef CPU, StringRef FS) {