1LLVM-REMARK-SIZE-DIFF(1)             LLVM             LLVM-REMARK-SIZE-DIFF(1)
2
3
4

NAME

6       llvm-remark-size-diff - diff size remarks
7

SYNOPSIS

9       llvm-remark-size-diff [options] file_a file_b --parser parser
10

DESCRIPTION

12       llvm-remark-size-diff  diffs  size  remarks in two remark files: file_a
13       and file_b.
14
15       llvm-remark-size-diff can be used to gain insight into which  functions
16       were impacted the most by code generation changes.
17
18       In  most  common  use-cases file_a and file_b will be remarks output by
19       compiling a fixed source with differing compilers  or  differing  opti‐
20       mization settings.
21
22       llvm-remark-size-diff handles both YAML and bitstream remarks.
23

OPTIONS

25       --parser=<yaml|bitstream>
26              Select  the  type of input remark parser. Required.  * yaml: The
27              tool will parse YAML remarks.  * bitstream: The tool will  parse
28              bitstream remarks.
29
30       --report-style=<human|json>
31              Output  style.   * human: Human-readable textual report. Default
32              option.  * json: JSON report.
33
34       --pretty
35              Pretty-print JSON output. Optional.
36
37              If output is not set to JSON, this does nothing.
38
39       -o=<file>
40              Output file for the report. Outputs to stdout by default.
41

HUMAN-READABLE OUTPUT

43       The human-readable format for llvm-remark-size-diff is composed of  two
44       sections:
45
46       • Per-function changes.
47
48       • A high-level summary of all changes.
49
50   Changed Function Section
51       Suppose you are comparing two remark files OLD and NEW.
52
53       For  each  function  with  a  changed instruction count in OLD and NEW,
54       llvm-remark-size-diff will emit a line like below:
55
56          (++|--|==) (>|<) function_name, N instrs, M stack B
57
58       A breakdown of the format is below:
59
60       (++|--|==)
61              Which of OLD and NEW the function_name is present in.
62
63              • ++: Only in NEW. ("Added")
64
65              • --: Only in OLD. ("Removed")
66
67              • ==: In both.
68
69       (>|<)  Denotes if function_name has more instructions or fewer instruc‐
70              tions in the second file.
71
72              • >: More instructions in second file than first file.
73
74              • <: Fewer instructions in second file than in first file.
75
76       function_name
77              The name of the changed function.
78
79       N instrs
80              Second file instruction count - first file instruction count.
81
82       M stack B
83              Second file stack byte count - first file stack byte count.
84
85   Summary Section
86       llvm-remark-size-diff  will  output a high-level summary after printing
87       all changed functions.
88
89          instruction count: N (inst_pct_change%)
90          stack byte usage: M (sb_pct_change%)
91
92       N      Sum of all instruction count  changes  between  the  second  and
93              first file.
94
95       inst_pct_change%
96              Percent  increase  or  decrease in instruction count between the
97              second and first file.
98
99       M      Sum of all stack byte count changes between the second and first
100              file.
101
102       sb_pct_change%
103              Percent  increase  or  decrease  in stack byte usage between the
104              second and first file.
105

JSON OUTPUT

107   High-Level view
108       Suppose we are comparing two files, OLD and NEW.
109
110       llvm-remark-size-diff will output JSON as follows.
111
112          "Files": [
113            "A": "path/to/OLD",
114            "B": "path/to/NEW"
115          ]
116
117          "InBoth": [
118            ...
119          ],
120
121          "OnlyInA": [
122            ...
123          ],
124
125          "OnlyInB": [
126            ...
127          ]
128
129       Files  Original paths to remark files.
130
131              • A: Path to the first file.
132
133              • B: Path to the second file.
134
135       InBoth Functions present in both files.
136
137       OnlyInA
138              Functions only present in the first file.
139
140       OnlyInB
141              Functions only present in the second file.
142
143   Function JSON
144       The InBoth, OnlyInA, and OnlyInB sections contain size information  for
145       each function in the input remark files.
146
147          {
148            "FunctionName" : "function_name"
149            "InstCount": [
150                INST_COUNT_A,
151                INST_COUNT_B
152              ],
153            "StackSize": [
154                STACK_BYTES_A,
155                STACK_BYTES_B
156              ],
157          }
158
159       FunctionName
160              Name of the function.
161
162       InstCount
163              Instruction counts for the function.
164
165              • INST_COUNT_A: Instruction count in OLD.
166
167              • INST_COUNT_B: Instruction count in NEW.
168
169       StackSize
170              Stack byte counts for the function.
171
172              • STACK_BYTES_A: Stack bytes in OLD.
173
174              • STACK_BYTES_B: Stack bytes in NEW.
175
176   Computing Diffs From Function JSON
177       Function  JSON  does not contain the diffs. Tools consuming JSON output
178       from llvm-remark-size-diff are responsible for computing the diffs sep‐
179       arately.
180
181       To compute the diffs:
182
183       • Instruction count diff: INST_COUNT_B - INST_COUNT_A
184
185       • Stack byte count diff: STACK_BYTES_B - STACK_BYTES_A
186

EXIT STATUS

188       llvm-remark-size-diff returns 0 on success, and a non-zero value other‐
189       wise.
190

AUTHOR

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

195       2003-2023, LLVM Project
196
197
198
199
20016                                2023-07-20          LLVM-REMARK-SIZE-DIFF(1)
Impressum