NAME

       llvm-remark-size-diff - diff size remarks

SYNOPSIS

       llvm-remark-size-diff [options] file_a file_b –parser parser

DESCRIPTION

       llvm-remark-size-diff diffs size remarks in two remark files: file_a and file_b.

       llvm-remark-size-diff  can  be used to gain insight into which functions were impacted the
       most by code generation changes.

       In most common use-cases file_a and file_b will be remarks output  by  compiling  a  fixed
       source with differing compilers or differing optimization settings.

       llvm-remark-size-diff handles both YAML and bitstream remarks.

OPTIONS

       --parser=<yaml|bitstream>
              Select the type of input remark parser. Required.  * yaml: The tool will parse YAML
              remarks.  * bitstream: The tool will parse bitstream remarks.

       --report-style=<human|json>
              Output style.  * human: Human-readable textual report.  Default  option.   *  json:
              JSON report.

       --pretty
              Pretty-print JSON output. Optional.

              If output is not set to JSON, this does nothing.

       -o=<file>
              Output file for the report. Outputs to stdout by default.

HUMAN-READABLE OUTPUT

       The human-readable format for llvm-remark-size-diff is composed of two sections:

       • Per-function changes.

       • A high-level summary of all changes.

   Changed Function Section
       Suppose you are comparing two remark files OLD and NEW.

       For  each  function with a changed instruction count in OLD and NEW, llvm-remark-size-diff
       will emit a line like below:

          (++|--|==) (>|<) function_name, N instrs, M stack B

       A breakdown of the format is below:

       (++|--|==)
              Which of OLD and NEW the function_name is present in.

              • ++: Only in NEW. (“Added”)

              • --: Only in OLD. (“Removed”)

              • ==: In both.

       (>|<)  Denotes if function_name has more instructions or fewer instructions in the  second
              file.

              • >: More instructions in second file than first file.

              • <: Fewer instructions in second file than in first file.

       function_name
              The name of the changed function.

       N instrs
              Second file instruction count - first file instruction count.

       M stack B
              Second file stack byte count - first file stack byte count.

   Summary Section
       llvm-remark-size-diff  will  output  a  high-level  summary  after  printing  all  changed
       functions.

          instruction count: N (inst_pct_change%)
          stack byte usage: M (sb_pct_change%)

       N      Sum of all instruction count changes between the second and first file.

       inst_pct_change%
              Percent increase or decrease in instruction count  between  the  second  and  first
              file.

       M      Sum of all stack byte count changes between the second and first file.

       sb_pct_change%
              Percent increase or decrease in stack byte usage between the second and first file.

JSON OUTPUT

   High-Level view
       Suppose we are comparing two files, OLD and NEW.

       llvm-remark-size-diff will output JSON as follows.

          "Files": [
            "A": "path/to/OLD",
            "B": "path/to/NEW"
          ]

          "InBoth": [
            ...
          ],

          "OnlyInA": [
            ...
          ],

          "OnlyInB": [
            ...
          ]

       Files  Original paths to remark files.

              • A: Path to the first file.

              • B: Path to the second file.

       InBoth Functions present in both files.

       OnlyInA
              Functions only present in the first file.

       OnlyInB
              Functions only present in the second file.

   Function JSON
       The  InBoth,  OnlyInA,  and OnlyInB sections contain size information for each function in
       the input remark files.

          {
            "FunctionName" : "function_name"
            "InstCount": [
                INST_COUNT_A,
                INST_COUNT_B
              ],
            "StackSize": [
                STACK_BYTES_A,
                STACK_BYTES_B
              ],
          }

       FunctionName
              Name of the function.

       InstCount
              Instruction counts for the function.

              • INST_COUNT_A: Instruction count in OLD.

              • INST_COUNT_B: Instruction count in NEW.

       StackSize
              Stack byte counts for the function.

              • STACK_BYTES_A: Stack bytes in OLD.

              • STACK_BYTES_B: Stack bytes in NEW.

   Computing Diffs From Function JSON
       Function  JSON  does  not  contain  the  diffs.   Tools   consuming   JSON   output   from
       llvm-remark-size-diff are responsible for computing the diffs separately.

       To compute the diffs:

       • Instruction count diff: INST_COUNT_B - INST_COUNT_A

       • Stack byte count diff: STACK_BYTES_B - STACK_BYTES_A

EXIT STATUS

       llvm-remark-size-diff returns 0 on success, and a non-zero value otherwise.

AUTHOR

       Maintained by the LLVM Team (https://llvm.org/).

COPYRIGHT

       2003-2022, LLVM Project