1llvm-remark-size-diff - diff size remarks 2========================================= 3 4.. program:: llvm-remark-size-diff 5 6SYNOPSIS 7-------- 8 9:program:`llvm-remark-size-diff` [*options*] *file_a* *file_b* **--parser** *parser* 10 11DESCRIPTION 12----------- 13 14:program:`llvm-remark-size-diff` diffs size 15`remarks <https://llvm.org/docs/Remarks.html>`_ in two remark files: ``file_a`` 16and ``file_b``. 17 18:program:`llvm-remark-size-diff` can be used to gain insight into which 19functions were impacted the most by code generation changes. 20 21In most common use-cases ``file_a`` and ``file_b`` will be remarks output by 22compiling a **fixed source** with **differing compilers** or 23**differing optimization settings**. 24 25:program:`llvm-remark-size-diff` handles both 26`YAML <https://llvm.org/docs/Remarks.html#yaml-remarks>`_ and 27`bitstream <https://llvm.org/docs/Remarks.html#llvm-bitstream-remarks>`_ 28remarks. 29 30OPTIONS 31------- 32 33.. option:: --parser=<yaml|bitstream> 34 35 Select the type of input remark parser. Required. 36 * ``yaml``: The tool will parse YAML remarks. 37 * ``bitstream``: The tool will parse bitstream remarks. 38 39.. option:: --report-style=<human|json> 40 41 Output style. 42 * ``human``: Human-readable textual report. Default option. 43 * ``json``: JSON report. 44 45.. option:: --pretty 46 47 Pretty-print JSON output. Optional. 48 49 If output is not set to JSON, this does nothing. 50 51.. option:: -o=<file> 52 53 Output file for the report. Outputs to stdout by default. 54 55HUMAN-READABLE OUTPUT 56--------------------- 57 58The human-readable format for :program:`llvm-remark-size-diff` is composed of 59two sections: 60 61* Per-function changes. 62* A high-level summary of all changes. 63 64Changed Function Section 65######################## 66 67Suppose you are comparing two remark files OLD and NEW. 68 69For each function with a **changed instruction count** in OLD and NEW, 70:program:`llvm-remark-size-diff` will emit a line like below: 71 72:: 73 74 (++|--|==) (>|<) function_name, N instrs, M stack B 75 76A breakdown of the format is below: 77 78``(++|--|==)`` 79 Which of OLD and NEW the ``function_name`` is present in. 80 81 * ``++``: Only in NEW. ("Added") 82 * ``--``: Only in OLD. ("Removed") 83 * ``==``: In both. 84 85``(>|<)`` 86 Denotes if ``function_name`` has more instructions or fewer instructions in 87 the second file. 88 89 * ``>``: More instructions in second file than first file. 90 * ``<``: Fewer instructions in second file than in first file. 91 92``function_name`` 93 The name of the changed function. 94 95``N instrs`` 96 Second file instruction count - first file instruction count. 97 98``M stack B`` 99 Second file stack byte count - first file stack byte count. 100 101Summary Section 102############### 103 104:program:`llvm-remark-size-diff` will output a high-level summary after 105printing all changed functions. 106 107:: 108 109 instruction count: N (inst_pct_change%) 110 stack byte usage: M (sb_pct_change%) 111 112``N`` 113 Sum of all instruction count changes between the second and first file. 114 115``inst_pct_change%`` 116 Percent increase or decrease in instruction count between the second and first 117 file. 118 119``M`` 120 Sum of all stack byte count changes between the second and first file. 121 122``sb_pct_change%`` 123 Percent increase or decrease in stack byte usage between the second and first 124 file. 125 126JSON OUTPUT 127----------- 128 129High-Level view 130############### 131 132Suppose we are comparing two files, OLD and NEW. 133 134:program:`llvm-remark-size-diff` will output JSON as follows. 135 136:: 137 138 "Files": [ 139 "A": "path/to/OLD", 140 "B": "path/to/NEW" 141 ] 142 143 "InBoth": [ 144 ... 145 ], 146 147 "OnlyInA": [ 148 ... 149 ], 150 151 "OnlyInB": [ 152 ... 153 ] 154 155 156``Files`` 157 Original paths to remark files. 158 159 * ``A``: Path to the first file. 160 * ``B``: Path to the second file. 161 162``InBoth`` 163 Functions present in both files. 164 165``OnlyInA`` 166 Functions only present in the first file. 167 168``OnlyInB`` 169 Functions only present in the second file. 170 171Function JSON 172############# 173 174The ``InBoth``, ``OnlyInA``, and ``OnlyInB`` sections contain size information 175for each function in the input remark files. 176 177:: 178 179 { 180 "FunctionName" : "function_name" 181 "InstCount": [ 182 INST_COUNT_A, 183 INST_COUNT_B 184 ], 185 "StackSize": [ 186 STACK_BYTES_A, 187 STACK_BYTES_B 188 ], 189 } 190 191``FunctionName`` 192 Name of the function. 193 194``InstCount`` 195 Instruction counts for the function. 196 197 * ``INST_COUNT_A``: Instruction count in OLD. 198 * ``INST_COUNT_B``: Instruction count in NEW. 199 200``StackSize`` 201 Stack byte counts for the function. 202 203 * ``STACK_BYTES_A``: Stack bytes in OLD. 204 * ``STACK_BYTES_B``: Stack bytes in NEW. 205 206Computing Diffs From Function JSON 207********************************** 208 209Function JSON does not contain the diffs. Tools consuming JSON output from 210:program:`llvm-remark-size-diff` are responsible for computing the diffs 211separately. 212 213**To compute the diffs:** 214 215* Instruction count diff: ``INST_COUNT_B - INST_COUNT_A`` 216* Stack byte count diff: ``STACK_BYTES_B - STACK_BYTES_A`` 217 218EXIT STATUS 219----------- 220 221:program:`llvm-remark-size-diff` returns 0 on success, and a non-zero value 222otherwise. 223