.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "LLVM-REMARK-SIZE-DIFF" "1" "2024-02-26" "15" "LLVM"
.SH NAME
llvm-remark-size-diff \- diff size remarks
.SH SYNOPSIS
.sp
\fBllvm\-remark\-size\-diff\fP [\fIoptions\fP] \fIfile_a\fP \fIfile_b\fP \fB–parser\fP \fIparser\fP
.SH DESCRIPTION
.sp
\fBllvm\-remark\-size\-diff\fP diffs size
\fI\%remarks\fP in two remark files: \fBfile_a\fP
and \fBfile_b\fP\&.
.sp
\fBllvm\-remark\-size\-diff\fP can be used to gain insight into which
functions were impacted the most by code generation changes.
.sp
In most common use\-cases \fBfile_a\fP and \fBfile_b\fP will be remarks output by
compiling a \fBfixed source\fP with \fBdiffering compilers\fP or
\fBdiffering optimization settings\fP\&.
.sp
\fBllvm\-remark\-size\-diff\fP handles both
\fI\%YAML\fP and
\fI\%bitstream\fP
remarks.
.SH OPTIONS
.INDENT 0.0
.TP
.B \-\-parser=<yaml|bitstream>
Select the type of input remark parser. Required.
* \fByaml\fP: The tool will parse YAML remarks.
* \fBbitstream\fP: The tool will parse bitstream remarks.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-report\-style=<human|json>
Output style.
* \fBhuman\fP: Human\-readable textual report. Default option.
* \fBjson\fP: JSON report.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-pretty
Pretty\-print JSON output. Optional.
.sp
If output is not set to JSON, this does nothing.
.UNINDENT
.INDENT 0.0
.TP
.B \-o=<file>
Output file for the report. Outputs to stdout by default.
.UNINDENT
.SH HUMAN-READABLE OUTPUT
.sp
The human\-readable format for \fBllvm\-remark\-size\-diff\fP is composed of
two sections:
.INDENT 0.0
.IP \(bu 2
Per\-function changes.
.IP \(bu 2
A high\-level summary of all changes.
.UNINDENT
.SS Changed Function Section
.sp
Suppose you are comparing two remark files OLD and NEW.
.sp
For each function with a \fBchanged instruction count\fP in OLD and NEW,
\fBllvm\-remark\-size\-diff\fP will emit a line like below:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
(++|\-\-|==) (>|<) function_name, N instrs, M stack B
.EE
.UNINDENT
.UNINDENT
.sp
A breakdown of the format is below:
.INDENT 0.0
.TP
.B \fB(++|\-\-|==)\fP
Which of OLD and NEW the \fBfunction_name\fP is present in.
.INDENT 7.0
.IP \(bu 2
\fB++\fP: Only in NEW. (“Added”)
.IP \(bu 2
\fB\-\-\fP: Only in OLD. (“Removed”)
.IP \(bu 2
\fB==\fP: In both.
.UNINDENT
.TP
.B \fB(>|<)\fP
Denotes if \fBfunction_name\fP has more instructions or fewer instructions in
the second file.
.INDENT 7.0
.IP \(bu 2
\fB>\fP: More instructions in second file than first file.
.IP \(bu 2
\fB<\fP: Fewer instructions in second file than in first file.
.UNINDENT
.TP
.B \fBfunction_name\fP
The name of the changed function.
.TP
.B \fBN instrs\fP
Second file instruction count \- first file instruction count.
.TP
.B \fBM stack B\fP
Second file stack byte count \- first file stack byte count.
.UNINDENT
.SS Summary Section
.sp
\fBllvm\-remark\-size\-diff\fP will output a high\-level summary after
printing all changed functions.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
instruction count: N (inst_pct_change%)
stack byte usage: M (sb_pct_change%)
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fBN\fP
Sum of all instruction count changes between the second and first file.
.TP
.B \fBinst_pct_change%\fP
Percent increase or decrease in instruction count between the second and first
file.
.TP
.B \fBM\fP
Sum of all stack byte count changes between the second and first file.
.TP
.B \fBsb_pct_change%\fP
Percent increase or decrease in stack byte usage between the second and first
file.
.UNINDENT
.SH JSON OUTPUT
.SS High\-Level view
.sp
Suppose we are comparing two files, OLD and NEW.
.sp
\fBllvm\-remark\-size\-diff\fP will output JSON as follows.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\(dqFiles\(dq: [
  \(dqA\(dq: \(dqpath/to/OLD\(dq,
  \(dqB\(dq: \(dqpath/to/NEW\(dq
]

\(dqInBoth\(dq: [
  ...
],

\(dqOnlyInA\(dq: [
  ...
],

\(dqOnlyInB\(dq: [
  ...
]
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fBFiles\fP
Original paths to remark files.
.INDENT 7.0
.IP \(bu 2
\fBA\fP: Path to the first file.
.IP \(bu 2
\fBB\fP: Path to the second file.
.UNINDENT
.TP
.B \fBInBoth\fP
Functions present in both files.
.TP
.B \fBOnlyInA\fP
Functions only present in the first file.
.TP
.B \fBOnlyInB\fP
Functions only present in the second file.
.UNINDENT
.SS Function JSON
.sp
The \fBInBoth\fP, \fBOnlyInA\fP, and \fBOnlyInB\fP sections contain size information
for each function in the input remark files.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{
  \(dqFunctionName\(dq : \(dqfunction_name\(dq
  \(dqInstCount\(dq: [
      INST_COUNT_A,
      INST_COUNT_B
    ],
  \(dqStackSize\(dq: [
      STACK_BYTES_A,
      STACK_BYTES_B
    ],
}
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fBFunctionName\fP
Name of the function.
.TP
.B \fBInstCount\fP
Instruction counts for the function.
.INDENT 7.0
.IP \(bu 2
\fBINST_COUNT_A\fP: Instruction count in OLD.
.IP \(bu 2
\fBINST_COUNT_B\fP: Instruction count in NEW.
.UNINDENT
.TP
.B \fBStackSize\fP
Stack byte counts for the function.
.INDENT 7.0
.IP \(bu 2
\fBSTACK_BYTES_A\fP: Stack bytes in OLD.
.IP \(bu 2
\fBSTACK_BYTES_B\fP: Stack bytes in NEW.
.UNINDENT
.UNINDENT
.SS Computing Diffs From Function JSON
.sp
Function JSON does not contain the diffs. Tools consuming JSON output from
\fBllvm\-remark\-size\-diff\fP are responsible for computing the diffs
separately.
.sp
\fBTo compute the diffs:\fP
.INDENT 0.0
.IP \(bu 2
Instruction count diff: \fBINST_COUNT_B \- INST_COUNT_A\fP
.IP \(bu 2
Stack byte count diff: \fBSTACK_BYTES_B \- STACK_BYTES_A\fP
.UNINDENT
.SH EXIT STATUS
.sp
\fBllvm\-remark\-size\-diff\fP returns 0 on success, and a non\-zero value
otherwise.
.SH AUTHOR
Maintained by the LLVM Team (https://llvm.org/).
.SH COPYRIGHT
2003-2024, LLVM Project
.\" Generated by docutils manpage writer.
.