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_nameis present in.- ++: Only in NEW. (“Added”)
- --: Only in OLD. (“Removed”)
- ==: In both.
 
- (>|<)
- Denotes if - function_namehas 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.
