llvm/docs/CommandGuide/llvm-remarkutil.rst

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