[llvm-profdata] Add --output-format option

[ellis]

Summary

Add --output-format option for the llvm-profdata show command to select the type of output. The existing --text flag is used to emit text encoded profiles. To avoid confusion, --output-format=text-encoding indicates that the output will be profiles encoded in the text format, and --output-format=text indicates the default text output that doesn't necessarily represent a profile.
--output-format=json is an alias for --json and --output-format=yaml will be used in D134770.

[MaskRay]

llvm/tools/llvm-profdata/llvm-profdata.cpp

60

Should this be OutputFormat instead? Then you can use a different name for the variable...

[davidxl]

1. the CommandLine documentation file needs to be updated.
2. what is the use case of splitting text and text-encoding?

3. Please also add test cases.

llvm/tools/llvm-profdata/llvm-profdata.cpp

2742

fix typo "test-encoding'

[ellis]

In D135127#3835933, @davidxl wrote:

2. what is the use case of splitting text and text-encoding?

The existing --text option for the show command is used to emit the profile in the text-encoded format. I thought it would be confusing use --output-format=text to mean this, since I would expect this to mean "print normal text output". So I decided on the following flags:

• --output-format=text
  • The show command will print text that is useful to the user
• --output-format=text-encoding
  • Will emit the profile in the text-encoded format without additional output. This is identical to the --text flag.

I know this is a bit weird. So I'm wondering if it's better to leave the --text flag alone and only have --output-format=<json|yaml>. Let me know what you think!

llvm/tools/llvm-profdata/llvm-profdata.cpp

60

I thought the name OutputFormat would be confusing because one might think it had the meaning of ProfileFormat above. ProfileFormat specifies which profile format we should output, while ShowOutputFormat only specifies the output for the show command. We don't currently have YAML or JSON profile formats.

[ellis]

Don't add text and text-encoding to output-format type.

[ellis]

I decided to just stick with --output-format=<json|yaml> and removed changes to the --text option to make things cleaner.

[phosek]

LGTM

[ellis]

Rebase

[ellis]

Sorry, forgot to run clang-format

[wenlei]

llvm/tools/llvm-profdata/llvm-profdata.cpp

60

OutputFormat is indeed confusing. Before you make show output format selectable, output format has one to one mapping with profile format, so output format and profile format were interchangeable.. And we have this line:

cl::opt<ProfileFormat> OutputFormat

We tried to hold an invariant -- all file outputs are valid profile, non-profile output are all for stdout (users can redirect to file). Can we try to hold that invariant still? Can we disambiguate them by variable names as well as switch name? i.e. --show-format for show command, and --output-format for merge command. If you separate them in difference space, --show-format=text and --output-format=text could also co-exist if needed.

[ellis]

llvm/tools/llvm-profdata/llvm-profdata.cpp

60

I like your idea of --show-format. I've put up D135467 to rename the flag.

llvm/docs/CommandGuide/llvm-profdata.rst

 .. option:: --binary-ids
 
  Print embedded binary ids in a profile.
 
 .. option:: --counts
 
  Print the counter values for the displayed functions.
 
+.. option:: --output-format=<json|yaml>
+
+ Emit output in the selected format if supported by the provided profile type.
+
 .. option:: --function=<string>
 
  Print details for a function if the function's name contains the given string.
 
 .. option:: --help
 
  Print a summary of command line options.
 

llvm/test/tools/llvm-profdata/sample-profile-json.test

 RUN: llvm-profdata show --sample --json %p/Inputs/sample-profile.proftext | FileCheck %s --check-prefix=JSON
+RUN: llvm-profdata show --sample --output-format=json %p/Inputs/sample-profile.proftext | FileCheck %s --check-prefix=JSON
 JSON:      [
 JSON-NEXT:   {
 JSON-NEXT:     "name": "main",
 JSON-NEXT:     "total": 184019,
 JSON-NEXT:     "head": 0,
 JSON-NEXT:     "body": [
 JSON-NEXT:       {
 JSON-NEXT:         "line": 4,

llvm/tools/llvm-profdata/llvm-profdata.cpp

enum ProfileFormat {
   PF_None = 0,
   PF_Text,
   PF_Compact_Binary,
   PF_Ext_Binary,
   PF_GCC,
   PF_Binary
 };
 
+enum class OutputFormat { None, Json, Yaml };
+
 static void warn(Twine Message, std::string Whence = "",
                  std::string Hint = "") {
   WithColor::warning();
   if (!Whence.empty())
     errs() << Whence << ": ";
   errs() << Message << "\n";
   if (!Hint.empty())
     WithColor::note() << Hint << "\n";

 static int showInstrProfile(const std::string &Filename, bool ShowCounts,
                             uint32_t TopN, bool ShowIndirectCallTargets,
                             bool ShowMemOPSizes, bool ShowDetailedSummary,
                             std::vector<uint32_t> DetailedSummaryCutoffs,
                             bool ShowAllFunctions, bool ShowCS,
                             uint64_t ValueCutoff, bool OnlyListBelow,
                             const std::string &ShowFunction, bool TextFormat,
                             bool ShowBinaryIds, bool ShowCovered,
-                            bool ShowProfileVersion, raw_fd_ostream &OS) {
+                            bool ShowProfileVersion, OutputFormat OFormat,
+                            raw_fd_ostream &OS) {
+  if (OFormat == OutputFormat::Json)
+    exitWithError("JSON output is not supported for instr profiles");
+  if (OFormat == OutputFormat::Yaml)
+    exitWithError("YAML output is not supported for instr profiles");
   auto ReaderOrErr = InstrProfReader::create(Filename);
   std::vector<uint32_t> Cutoffs = std::move(DetailedSummaryCutoffs);
   if (ShowDetailedSummary && Cutoffs.empty()) {
     Cutoffs = ProfileSummaryBuilder::DefaultCutoffs;
   }
   InstrProfSummaryBuilder Builder(std::move(Cutoffs));
   if (Error E = ReaderOrErr.takeError())
     exitWithError(std::move(E), Filename);

 }
 
 static int showSampleProfile(const std::string &Filename, bool ShowCounts,
                              uint32_t TopN, bool ShowAllFunctions,
                              bool ShowDetailedSummary,
                              const std::string &ShowFunction,
                              bool ShowProfileSymbolList,
                              bool ShowSectionInfoOnly, bool ShowHotFuncList,
-                             bool JsonFormat, raw_fd_ostream &OS) {
+                             OutputFormat OFormat, raw_fd_ostream &OS) {
+  if (OFormat == OutputFormat::Yaml)
+    exitWithError("YAML output is not supported for sample profiles");
   using namespace sampleprof;
   LLVMContext Context;
   auto ReaderOrErr =
       SampleProfileReader::create(Filename, Context, FSDiscriminatorPassOption);
   if (std::error_code EC = ReaderOrErr.getError())
     exitWithErrorCode(EC, Filename);
 
   auto Reader = std::move(ReaderOrErr.get());
   if (ShowSectionInfoOnly) {
     showSectionInfo(Reader.get(), OS);
     return 0;
   }
 
   if (std::error_code EC = Reader->read())
     exitWithErrorCode(EC, Filename);
 
   if (ShowAllFunctions || ShowFunction.empty()) {
-    if (JsonFormat)
+    if (OFormat == OutputFormat::Json)
       Reader->dumpJson(OS);
     else
       Reader->dump(OS);
   } else {
-    if (JsonFormat)
+    if (OFormat == OutputFormat::Json)
       exitWithError(
           "the JSON format is supported only when all functions are to "
           "be printed");
 
     // TODO: parse context string to support filtering by contexts.
     Reader->dumpFunctionProfile(StringRef(ShowFunction), OS);
   }
 
static int showSampleProfile(const std::string &Filename, bool ShowCounts,
   if (ShowHotFuncList || TopN)
     showHotFunctionList(Reader->getProfiles(), Reader->getSummary(), TopN, OS);
 
   return 0;
 }
 
 static int showMemProfProfile(const std::string &Filename,
                               const std::string &ProfiledBinary,
-                              raw_fd_ostream &OS) {
+                              OutputFormat OFormat, raw_fd_ostream &OS) {
+  if (OFormat == OutputFormat::Json)
+    exitWithError("JSON output is not supported for MemProf");
   auto ReaderOr = llvm::memprof::RawMemProfReader::create(
       Filename, ProfiledBinary, /*KeepNames=*/true);
   if (Error E = ReaderOr.takeError())
     // Since the error can be related to the profile or the binary we do not
     // pass whence. Instead additional context is provided where necessary in
     // the error message.
     exitWithError(std::move(E), /*Whence*/ "");
 
   std::unique_ptr<llvm::memprof::RawMemProfReader> Reader(
       ReaderOr.get().release());
 
   Reader->printYAML(OS);
   return 0;
 }
 
 static int showDebugInfoCorrelation(const std::string &Filename,
                                     bool ShowDetailedSummary,
                                     bool ShowProfileSymbolList,
-                                    raw_fd_ostream &OS) {
+                                    OutputFormat OFormat, raw_fd_ostream &OS) {
+  if (OFormat == OutputFormat::Json)
+    exitWithError("JSON output is not supported for debug info correlation");
+  if (OFormat == OutputFormat::Yaml)
+    exitWithError("YAML output is not supported for debug info correlation");
   std::unique_ptr<InstrProfCorrelator> Correlator;
   if (auto Err = InstrProfCorrelator::get(Filename).moveInto(Correlator))
     exitWithError(std::move(Err), Filename);
+
   if (auto Err = Correlator->correlateProfileData())
     exitWithError(std::move(Err), Filename);
 
   InstrProfSymtab Symtab;
   if (auto Err = Symtab.create(
           StringRef(Correlator->getNamesPointer(), Correlator->getNamesSize())))
     exitWithError(std::move(Err), Filename);
 
static int showDebugInfoCorrelation(const std::string &Filename,
   return 0;
 }
 
 static int show_main(int argc, const char *argv[]) {
   cl::opt<std::string> Filename(cl::Positional, cl::desc("<profdata-file>"));
 
   cl::opt<bool> ShowCounts("counts", cl::init(false),
                            cl::desc("Show counter values for shown functions"));
+  cl::opt<OutputFormat> OFormat(
+      "output-format", cl::init(OutputFormat::None),
+      cl::desc("Emit output in the selected format if supported"),
+      cl::values(clEnumValN(OutputFormat::Json, "json", "emit JSON"),
+                 clEnumValN(OutputFormat::Yaml, "yaml", "emit YAML")));
   cl::opt<bool> TextFormat(
       "text", cl::init(false),
       cl::desc("Show instr profile data in text dump format"));
   cl::opt<bool> JsonFormat(
-      "json", cl::init(false),
-      cl::desc("Show sample profile data in the JSON format"));
+      "json", cl::desc("Show sample profile data in the JSON format "
+                       "(deprecated, please use --output-format=json)"));
   cl::opt<bool> ShowIndirectCallTargets(
       "ic-targets", cl::init(false),
       cl::desc("Show indirect call site target values for shown functions"));
   cl::opt<bool> ShowMemOPSizes(
       "memop-sizes", cl::init(false),
       cl::desc("Show the profiled sizes of the memory intrinsic calls "
                "for shown functions"));
   cl::opt<bool> ShowDetailedSummary("detailed-summary", cl::init(false),
exitWithError(
         "the positional argument '<profdata-file>' is required unless '--" +
         DebugInfoFilename.ArgStr + "' is provided");
 
   if (Filename == OutputFilename) {
     errs() << sys::path::filename(argv[0])
            << ": Input file name cannot be the same as the output file name!\n";
     return 1;
   }
+  if (JsonFormat)
+    OFormat = OutputFormat::Json;
 
   std::error_code EC;
   raw_fd_ostream OS(OutputFilename.data(), EC, sys::fs::OF_TextWithCRLF);
   if (EC)
     exitWithErrorCode(EC, OutputFilename);
 
   if (ShowAllFunctions && !ShowFunction.empty())
     WithColor::warning() << "-function argument ignored: showing all functions\n";
 
   if (!DebugInfoFilename.empty())
     return showDebugInfoCorrelation(DebugInfoFilename, ShowDetailedSummary,
-                                    ShowProfileSymbolList, OS);
+                                    ShowProfileSymbolList, OFormat, OS);
 
   if (ProfileKind == instr)
     return showInstrProfile(
         Filename, ShowCounts, TopNFunctions, ShowIndirectCallTargets,
         ShowMemOPSizes, ShowDetailedSummary, DetailedSummaryCutoffs,
         ShowAllFunctions, ShowCS, ValueCutoff, OnlyListBelow, ShowFunction,
-        TextFormat, ShowBinaryIds, ShowCovered, ShowProfileVersion, OS);
+        TextFormat, ShowBinaryIds, ShowCovered, ShowProfileVersion, OFormat,
+        OS);
   if (ProfileKind == sample)
-    return showSampleProfile(
-        Filename, ShowCounts, TopNFunctions, ShowAllFunctions,
-        ShowDetailedSummary, ShowFunction, ShowProfileSymbolList,
-        ShowSectionInfoOnly, ShowHotFuncList, JsonFormat, OS);
-  return showMemProfProfile(Filename, ProfiledBinary, OS);
+    return showSampleProfile(Filename, ShowCounts, TopNFunctions,
+                             ShowAllFunctions, ShowDetailedSummary,
+                             ShowFunction, ShowProfileSymbolList,
+                             ShowSectionInfoOnly, ShowHotFuncList, OFormat, OS);
+  return showMemProfProfile(Filename, ProfiledBinary, OFormat, OS);
 }
 
 int llvm_profdata_main(int argc, char **argvNonConst) {
   const char **argv = const_cast<const char **>(argvNonConst);
   InitLLVM X(argc, argv);
 
   StringRef ProgName(sys::path::filename(argv[0]));
   if (argc > 1) {