LLVM-REMARK-SIZE-DIFF(1)

✨ NAME ✨

okay bestie, welcome to the llvm-remark-size-diff page from the LLVM manual 💖 this one is a diff tool for size remarks — like, it compares size remarks across two remark files and tells you what changed. that's the whole vibe.

---

🌸 SYNOPSIS 🌸

llvm-remark-size-diff [options] file_a file_b –parser parser

---

🦋 DESCRIPTION 🦋

so basically, llvm-remark-size-diff diffs size remarks in two remark files: file_a and file_b. two files, one glow-up comparison, we're obsessed. 💅

you'd reach for this when you wanna gain insight into which functions were impacted the most by code generation changes. like, which functions got the main character arc and which ones just stayed home. 👑

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. same source, different compiler settings, chaos ensues, we compare. 🔥

and the good news? llvm-remark-size-diff handles both YAML and bitstream remarks. it's giving versatile. ✨

---

🎀 OPTIONS 🎀

• --parser=<yaml|bitstream> — pick the type of input remark parser. this one is Required, no skipping it bestie.
  • yaml: the tool will parse YAML remarks.
  • bitstream: the tool will parse bitstream remarks.
• --report-style=<human|json> — output style, pick your aesthetic.
  • human: human-readable textual report. this is the Default option.
  • json: JSON report.
• --pretty — pretty-print JSON output. Optional.
  • if output is not set to JSON, this does literally nothing. not a single thing. 🫶
• -o=<file> — output file for the report. outputs to stdout by default.

---

🌈 HUMAN-READABLE OUTPUT 🌈

the human-readable format for 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, 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

llvm-remark-size-diff will output a high-level summary after printing all changed functions. the grand finale, if you will. 👑

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.

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

heads up bestie, this one matters: function JSON does not contain the diffs. tools consuming JSON output from llvm-remark-size-diff are responsible for computing the diffs separately. it's giving DIY. 💅

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 🔥

llvm-remark-size-diff returns 0 on success, and a non-zero value otherwise. slay when it works, sadness when it doesn't. ✨

---

💜 AUTHOR 💜

maintained by the LLVM Team (https://llvm.org/). iconic behavior, honestly.

---

🌈 COPYRIGHT 🌈

2003-2024, LLVM Project

---

and that's the whole page, bestie!! 🎀 this was page llvm-remark-size-diff(1) from the LLVM manual, version 15, dated 2024-04-14. go forth and diff some size remarks, you absolute legend. 🫶💖✨