[llvm] 73138d2 - Revert "[Docs] Add documentation for llvm-remark-size-diff"
Jessica Paquette via llvm-commits
llvm-commits at lists.llvm.org
Wed Mar 30 13:34:31 PDT 2022
Author: Jessica Paquette
Date: 2022-03-30T13:34:03-07:00
New Revision: 73138d280d91d40fb67c1f517779a4a883108293
URL: https://github.com/llvm/llvm-project/commit/73138d280d91d40fb67c1f517779a4a883108293
DIFF: https://github.com/llvm/llvm-project/commit/73138d280d91d40fb67c1f517779a4a883108293.diff
LOG: Revert "[Docs] Add documentation for llvm-remark-size-diff"
This reverts commit bdea2afc8c16e51edc8877479623e16261940e00.
Bot failure.
Added:
Modified:
Removed:
llvm/docs/CommandGuide/llvm-remark-size-diff.rst
################################################################################
diff --git a/llvm/docs/CommandGuide/llvm-remark-size-
diff .rst b/llvm/docs/CommandGuide/llvm-remark-size-
diff .rst
deleted file mode 100644
index 01d305320087e..0000000000000
--- a/llvm/docs/CommandGuide/llvm-remark-size-
diff .rst
+++ /dev/null
@@ -1,222 +0,0 @@
-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