1llvm-remarkutil - Remark utility 2================================ 3 4.. program:: llvm-remarkutil 5 6Synopsis 7-------- 8 9:program:`llvm-remarkutil` [*subcommmand*] [*options*] 10 11Description 12----------- 13 14Utility for displaying information from, and converting between different 15`remark <https://llvm.org/docs/Remarks.html>`_ formats. 16 17Subcommands 18----------- 19 20 * :ref:`bitstream2yaml_subcommand` - Reserialize bitstream remarks to YAML. 21 * :ref:`yaml2bitstream_subcommand` - Reserialize YAML remarks to bitstream. 22 * :ref:`instruction-count_subcommand` - Output function instruction counts. 23 * :ref:`annotation-count_subcommand` - Output remark type count from annotation remarks. 24 * :ref:`size-diff_subcommand` - Compute diff in size remarks. 25 26.. _bitstream2yaml_subcommand: 27 28bitstream2yaml 29~~~~~~~~~~~~~~ 30 31.. program:: llvm-remarkutil bitstream2yaml 32 33USAGE: :program:`llvm-remarkutil` bitstream2yaml <input file> -o <output file> 34 35Summary 36^^^^^^^ 37 38Takes a bitstream remark file as input, and reserializes that file as YAML. 39 40.. _yaml2bitstream_subcommand: 41 42yaml2bitstream 43~~~~~~~~~~~~~~ 44 45.. program:: llvm-remarkutil yaml2bitstream 46 47USAGE: :program:`llvm-remarkutil` yaml2bitstream <input file> -o <output file> 48 49Summary 50^^^^^^^ 51 52Takes a YAML remark file as input, and reserializes that file in the bitstream 53format. 54 55.. _instruction-count_subcommand: 56 57instruction-count 58~~~~~~~~~~~~~~~~~ 59 60.. program:: llvm-remarkutil instruction-count 61 62USAGE: :program:`llvm-remarkutil` instruction-count <input file> --parser=<bitstream|yaml> [--use-debug-loc] -o <output file> 63 64Summary 65^^^^^^^ 66 67Outputs instruction count remarks for every function. Instruction count remarks 68encode the number of instructions in a function at assembly printing time. 69 70Instruction count remarks require asm-printer remarks. 71 72CSV format is as follows: 73 74:: 75 76 Function,InstructionCount 77 foo,123 78 79if `--use-debug-loc` is passed then the CSV will include the source path, line number and column. 80 81:: 82 83 Source,Function,InstructionCount 84 path:line:column,foo,3 85 86.. _annotation-count_subcommand: 87 88annotation-count 89~~~~~~~~~~~~~~~~~ 90 91.. program:: llvm-remarkutil annotation-count 92 93USAGE: :program:`llvm-remarkutil` annotation-count <input file> --parser=<bitstream|yaml> --annotation-type=<type> [--use-debug-loc] -o <output file> 94 95Summary 96^^^^^^^ 97 98Outputs a count for annotation-type `<type>` remark for every function. The count expresses 99the number of remark checks inserted at the function. 100 101Annotation count remarks require AnnotationRemarksPass remarks. 102 103CSV format is as follows: 104 105:: 106 107 Function,Count 108 foo,123 109 110if `--use-debug-loc` is passed then the CSV will include the source path, line number and column. 111 112:: 113 114 Source,Function,Count 115 path:line:column,foo,3 116 117.. _count_subcommand: 118 119count 120~~~~~ 121 122.. program:: llvm-remarkutil count 123 124USAGE: :program:`llvm-remarkutil` count [*options*] <input file> 125 126Summary 127^^^^^^^ 128 129:program:`llvm-remarkutil count` counts `remarks <https://llvm.org/docs/Remarks.html>`_ based on specified properties. 130By default the tool counts remarks based on how many occur in a source file or function or total for the generated remark file. 131The tool also supports collecting count based on specific remark arguments. The specified arguments should have an integer value to be able to report a count. 132 133The tool contains utilities to filter the remark count based on remark name, pass name, argument value and remark type. 134 135Options 136^^^^^^^ 137 138.. option:: --parser=<yaml|bitstream> 139 140 Select the type of input remark parser. Required. 141 142 * ``yaml`` : The tool will parse YAML remarks. 143 * ``bitstream`` : The tool will parse bitstream remarks. 144 145.. option:: --count-by=<value> 146 147 Select option to collect remarks by. 148 149 * ``remark-name`` : count how many individual remarks exist. 150 * ``arg`` : count remarks based on specified arguments passed by --(r)args. The argument value must be a number. 151 152.. option:: --group-by=<value> 153 154 group count of remarks by property. 155 156 * ``source`` : Count will be collected per source path. Remarks with no debug location will not be counted. 157 * ``function`` : Count is collected per function. 158 * ``function-with-loc`` : Count is collected per function per source. Remarks with no debug location will not be counted. 159 * ``Total`` : Report a count for the provided remark file. 160 161.. option:: --args[=arguments] 162 163 If `count-by` is set to `arg` this flag can be used to collect from specified remark arguments represented as a comma separated string. 164 The arguments must have a numeral value to be able to count remarks by 165 166.. option:: --rargs[=arguments] 167 168 If `count-by` is set to `arg` this flag can be used to collect from specified remark arguments using regular expression. 169 The arguments must have a numeral value to be able to count remarks by 170 171.. option:: --pass-name[=<string>] 172 173 Filter count by pass name. 174 175.. option:: --rpass-name[=<string>] 176 177 Filter count by pass name using regular expressions. 178 179.. option:: --remark-name[=<string>] 180 181 Filter count by remark name. 182 183.. option:: --rremark-name[=<string>] 184 185 Filter count by remark name using regular expressions. 186 187.. option:: --filter-arg-by[=<string>] 188 189 Filter count by argument value. 190 191.. option:: --rfilter-arg-by[=<string>] 192 193 Filter count by argument value using regular expressions. 194 195.. option:: --remark-type=<value> 196 197 Filter remarks by type with the following options. 198 199 * ``unknown`` 200 * ``passed`` 201 * ``missed`` 202 * ``analysis`` 203 * ``analysis-fp-commute`` 204 * ``analysis-aliasing`` 205 * ``failure`` 206 207.. _size-diff_subcommand: 208 209size-diff 210~~~~~~~~~ 211.. program:: llvm-remarkutil size-diff 212 213USAGE: :program:`llvm-remarkutil` size-diff [*options*] *file_a* *file_b* **--parser** *parser* 214 215Summary 216^^^^^^^ 217 218:program:`llvm-remarkutil size-diff` diffs size `remarks <https://llvm.org/docs/Remarks.html>`_ in two remark files: ``file_a`` 219and ``file_b``. 220 221:program:`llvm-remarkutil size-diff` can be used to gain insight into which 222functions were impacted the most by code generation changes. 223 224In most common use-cases ``file_a`` and ``file_b`` will be remarks output by 225compiling a **fixed source** with **differing compilers** or 226**differing optimization settings**. 227 228:program:`llvm-remarkutil size-diff` handles both 229`YAML <https://llvm.org/docs/Remarks.html#yaml-remarks>`_ and 230`bitstream <https://llvm.org/docs/Remarks.html#llvm-bitstream-remarks>`_ 231remarks. 232 233Options 234^^^^^^^ 235 236.. option:: --parser=<yaml|bitstream> 237 238Select the type of input remark parser. Required. 239 240* ``yaml`` : The tool will parse YAML remarks. 241* ``bitstream`` : The tool will parse bitstream remarks. 242 243.. option:: --report-style=<human|json> 244 245 Output style. 246 247 * ``human`` : Human-readable textual report. Default option. 248 * ``json`` : JSON report. 249 250.. option:: --pretty 251 252 Pretty-print JSON output. Optional. 253 254 If output is not set to JSON, this does nothing. 255 256.. option:: -o=<file> 257 258 Output file for the report. Outputs to stdout by default. 259 260Human-Readable Output 261^^^^^^^^^^^^^^^^^^^^^ 262 263The human-readable format for :program:`llvm-remarkutil size-diff` is composed of 264two sections: 265 266* Per-function changes. 267* A high-level summary of all changes. 268 269Changed Function Section 270^^^^^^^^^^^^^^^^^^^^^^^^ 271 272Suppose you are comparing two remark files OLD and NEW. 273 274For each function with a **changed instruction count** in OLD and NEW, 275:program:`llvm-remarkutil size-diff` will emit a line like below: 276 277:: 278 279 (++|--|==) (>|<) function_name, N instrs, M stack B 280 281A breakdown of the format is below: 282 283``(++|--|==)`` 284 Which of OLD and NEW the ``function_name`` is present in. 285 286 * ``++``: Only in NEW. ("Added") 287 * ``--``: Only in OLD. ("Removed") 288 * ``==``: In both. 289 290``(>|<)`` 291 Denotes if ``function_name`` has more instructions or fewer instructions in 292 the second file. 293 294 * ``>``: More instructions in second file than first file. 295 * ``<``: Fewer instructions in second file than in first file. 296 297``function_name`` 298 The name of the changed function. 299 300``N instrs`` 301 Second file instruction count - first file instruction count. 302 303``M stack B`` 304 Second file stack byte count - first file stack byte count. 305 306Summary Section 307^^^^^^^^^^^^^^^ 308 309:program:`llvm-remarkutil size-diff` will output a high-level summary after 310printing all changed functions. 311 312:: 313 314 instruction count: N (inst_pct_change%) 315 stack byte usage: M (sb_pct_change%) 316 317``N`` 318 Sum of all instruction count changes between the second and first file. 319 320``inst_pct_change%`` 321 Percent increase or decrease in instruction count between the second and first 322 file. 323 324``M`` 325 Sum of all stack byte count changes between the second and first file. 326 327``sb_pct_change%`` 328 Percent increase or decrease in stack byte usage between the second and first 329 file. 330 331JSON OUTPUT 332^^^^^^^^^^^^ 333 334High-Level view 335^^^^^^^^^^^^^^^ 336 337Suppose we are comparing two files, OLD and NEW. 338 339:program:`llvm-remarkutil size-diff` will output JSON as follows. 340 341:: 342 343 "Files": [ 344 "A": "path/to/OLD", 345 "B": "path/to/NEW" 346 ] 347 348 "InBoth": [ 349 ... 350 ], 351 352 "OnlyInA": [ 353 ... 354 ], 355 356 "OnlyInB": [ 357 ... 358 ] 359 360 361``Files`` 362 Original paths to remark files. 363 364 * ``A``: Path to the first file. 365 * ``B``: Path to the second file. 366 367``InBoth`` 368 Functions present in both files. 369 370``OnlyInA`` 371 Functions only present in the first file. 372 373``OnlyInB`` 374 Functions only present in the second file. 375 376Function JSON 377^^^^^^^^^^^^^ 378 379The ``InBoth``, ``OnlyInA``, and ``OnlyInB`` sections contain size information 380for each function in the input remark files. 381 382:: 383 384 { 385 "FunctionName" : "function_name" 386 "InstCount": [ 387 INST_COUNT_A, 388 INST_COUNT_B 389 ], 390 "StackSize": [ 391 STACK_BYTES_A, 392 STACK_BYTES_B 393 ], 394 } 395 396``FunctionName`` 397 Name of the function. 398 399``InstCount`` 400 Instruction counts for the function. 401 402 * ``INST_COUNT_A``: Instruction count in OLD. 403 * ``INST_COUNT_B``: Instruction count in NEW. 404 405``StackSize`` 406 Stack byte counts for the function. 407 408 * ``STACK_BYTES_A``: Stack bytes in OLD. 409 * ``STACK_BYTES_B``: Stack bytes in NEW. 410 411Computing Diffs From Function JSON 412^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 413 414Function JSON does not contain the diffs. Tools consuming JSON output from 415:program:`llvm-remarkutil size-diff` are responsible for computing the diffs 416separately. 417 418**To compute the diffs:** 419 420* Instruction count diff: ``INST_COUNT_B - INST_COUNT_A`` 421* Stack byte count diff: ``STACK_BYTES_B - STACK_BYTES_A`` 422 423EXIT STATUS 424^^^^^^^^^^^ 425 426:program:`llvm-remarkutil size-diff` returns 0 on success, and a non-zero value 427otherwise. 428