llvm-remark-size-diff-15(1)

Usage

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

Overview

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.