[llvm] bdea2af - [Docs] Add documentation for llvm-remark-size-diff
Jessica Paquette via llvm-commits
llvm-commits at lists.llvm.org
Wed Mar 30 13:27:27 PDT 2022
Author: Jessica Paquette
Date: 2022-03-30T13:27:18-07:00
New Revision: bdea2afc8c16e51edc8877479623e16261940e00
URL: https://github.com/llvm/llvm-project/commit/bdea2afc8c16e51edc8877479623e16261940e00
DIFF: https://github.com/llvm/llvm-project/commit/bdea2afc8c16e51edc8877479623e16261940e00.diff
LOG: [Docs] Add documentation for llvm-remark-size-diff
Add documentation describing how to
- Use `llvm-remark-size-diff`
- Interpret the output from the tool
Differential Revision: https://reviews.llvm.org/D122744
Added:
llvm/docs/CommandGuide/llvm-remark-size-diff.rst
Modified:
Removed:
################################################################################
diff --git a/llvm/docs/CommandGuide/llvm-remark-size-
diff .rst b/llvm/docs/CommandGuide/llvm-remark-size-
diff .rst
new file mode 100644
index 0000000000000..01d305320087e
--- /dev/null
+++ b/llvm/docs/CommandGuide/llvm-remark-size-
diff .rst
@@ -0,0 +1,222 @@
+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 `
diff s 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 **
diff ering compilers** or
+**
diff ering 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
diff s. Tools consuming JSON output from
+:program:`llvm-remark-size-
diff ` are responsible for computing the
diff s
+separately.
+
+**To compute the
diff s:**
+
+* 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.
More information about the llvm-commits
mailing list