| llvm-remark-size-diff - diff size remarks |
| ========================================= |
| |
| .. program:: llvm-remark-size-diff |
| |
| SYNOPSIS |
| -------- |
| |
| :program:`llvm-remark-size-diff` [*options*] *file_a* *file_b* **--parser** *parser* |
| |
| DESCRIPTION |
| ----------- |
| |
| :program:`llvm-remark-size-diff` diffs size |
| `remarks <https://llvm.org/docs/Remarks.html>`_ in two remark files: ``file_a`` |
| and ``file_b``. |
| |
| :program:`llvm-remark-size-diff` can be used to gain insight into which |
| functions were impacted the most by code generation changes. |
| |
| In most common use-cases ``file_a`` and ``file_b`` will be remarks output by |
| compiling a **fixed source** with **differing compilers** or |
| **differing optimization settings**. |
| |
| :program:`llvm-remark-size-diff` handles both |
| `YAML <https://llvm.org/docs/Remarks.html#yaml-remarks>`_ and |
| `bitstream <https://llvm.org/docs/Remarks.html#llvm-bitstream-remarks>`_ |
| remarks. |
| |
| OPTIONS |
| ------- |
| |
| .. option:: --parser=<yaml|bitstream> |
| |
| Select the type of input remark parser. Required. |
| * ``yaml``: The tool will parse YAML remarks. |
| * ``bitstream``: The tool will parse bitstream remarks. |
| |
| .. option:: --report-style=<human|json> |
| |
| Output style. |
| * ``human``: Human-readable textual report. Default option. |
| * ``json``: JSON report. |
| |
| .. option:: --pretty |
| |
| Pretty-print JSON output. Optional. |
| |
| If output is not set to JSON, this does nothing. |
| |
| .. option:: -o=<file> |
| |
| Output file for the report. Outputs to stdout by default. |
| |
| HUMAN-READABLE OUTPUT |
| --------------------- |
| |
| The human-readable format for :program:`llvm-remark-size-diff` is composed of |
| two sections: |
| |
| * Per-function changes. |
| * A high-level summary of all changes. |
| |
| Changed Function Section |
| ######################## |
| |
| Suppose you are comparing two remark files OLD and NEW. |
| |
| For each function with a **changed instruction count** in OLD and NEW, |
| :program:`llvm-remark-size-diff` will emit a line like below: |
| |
| :: |
| |
| (++|--|==) (>|<) function_name, N instrs, M stack B |
| |
| A breakdown of the format is below: |
| |
| ``(++|--|==)`` |
| Which of OLD and NEW the ``function_name`` is present in. |
| |
| * ``++``: Only in NEW. ("Added") |
| * ``--``: Only in OLD. ("Removed") |
| * ``==``: In both. |
| |
| ``(>|<)`` |
| Denotes if ``function_name`` has more instructions or fewer instructions in |
| the second file. |
| |
| * ``>``: More instructions in second file than first file. |
| * ``<``: Fewer instructions in second file than in first file. |
| |
| ``function_name`` |
| The name of the changed function. |
| |
| ``N instrs`` |
| Second file instruction count - first file instruction count. |
| |
| ``M stack B`` |
| Second file stack byte count - first file stack byte count. |
| |
| Summary Section |
| ############### |
| |
| :program:`llvm-remark-size-diff` will output a high-level summary after |
| printing all changed functions. |
| |
| :: |
| |
| instruction count: N (inst_pct_change%) |
| stack byte usage: M (sb_pct_change%) |
| |
| ``N`` |
| Sum of all instruction count changes between the second and first file. |
| |
| ``inst_pct_change%`` |
| Percent increase or decrease in instruction count between the second and first |
| file. |
| |
| ``M`` |
| Sum of all stack byte count changes between the second and first file. |
| |
| ``sb_pct_change%`` |
| Percent increase or decrease in stack byte usage between the second and first |
| file. |
| |
| JSON OUTPUT |
| ----------- |
| |
| High-Level view |
| ############### |
| |
| Suppose we are comparing two files, OLD and NEW. |
| |
| :program:`llvm-remark-size-diff` will output JSON as follows. |
| |
| :: |
| |
| "Files": [ |
| "A": "path/to/OLD", |
| "B": "path/to/NEW" |
| ] |
| |
| "InBoth": [ |
| ... |
| ], |
| |
| "OnlyInA": [ |
| ... |
| ], |
| |
| "OnlyInB": [ |
| ... |
| ] |
| |
| |
| ``Files`` |
| Original paths to remark files. |
| |
| * ``A``: Path to the first file. |
| * ``B``: Path to the second file. |
| |
| ``InBoth`` |
| Functions present in both files. |
| |
| ``OnlyInA`` |
| Functions only present in the first file. |
| |
| ``OnlyInB`` |
| Functions only present in the second file. |
| |
| Function JSON |
| ############# |
| |
| The ``InBoth``, ``OnlyInA``, and ``OnlyInB`` sections contain size information |
| for each function in the input remark files. |
| |
| :: |
| |
| { |
| "FunctionName" : "function_name" |
| "InstCount": [ |
| INST_COUNT_A, |
| INST_COUNT_B |
| ], |
| "StackSize": [ |
| STACK_BYTES_A, |
| STACK_BYTES_B |
| ], |
| } |
| |
| ``FunctionName`` |
| Name of the function. |
| |
| ``InstCount`` |
| Instruction counts for the function. |
| |
| * ``INST_COUNT_A``: Instruction count in OLD. |
| * ``INST_COUNT_B``: Instruction count in NEW. |
| |
| ``StackSize`` |
| Stack byte counts for the function. |
| |
| * ``STACK_BYTES_A``: Stack bytes in OLD. |
| * ``STACK_BYTES_B``: Stack bytes in NEW. |
| |
| Computing Diffs From Function JSON |
| ********************************** |
| |
| Function JSON does not contain the diffs. Tools consuming JSON output from |
| :program:`llvm-remark-size-diff` are responsible for computing the diffs |
| separately. |
| |
| **To compute the diffs:** |
| |
| * Instruction count diff: ``INST_COUNT_B - INST_COUNT_A`` |
| * Stack byte count diff: ``STACK_BYTES_B - STACK_BYTES_A`` |
| |
| EXIT STATUS |
| ----------- |
| |
| :program:`llvm-remark-size-diff` returns 0 on success, and a non-zero value |
| otherwise. |