LLVM-REMARK-SIZE-DIFF(1)

💅 LLVM-REMARK-SIZE-DIFF(1) — bestie's guide to diffing size remarks ✨

okay so this is a page from the LLVM manual, and it's genuinely a little hidden gem — it's the llvm-remark-size-diff tool, and no cap, it's giving "which functions got bigger/smaller" main character energy. let's get into it 🫶

---

✨ NAME ✨

llvm-remark-size-diff — it diffs size remarks. that's it. that's the vibe.

---

🌸 SYNOPSIS 🌸

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

two files, some options, and a --parser — and --parser is required, so don't forget it, bestie 💀

---

🎀 DESCRIPTION 🎀

so llvm-remark-size-diff diffs the size remarks in two remark files: file_a and file_b. that's literally the whole gig 💅

you'd use it to get actual insight into which functions got impacted the most by code generation changes — like, who ate, and who got ate 😭

in most common use-cases, file_a and file_b are remarks output by compiling a fixed source with differing compilers or differing optimization settings. so same source, different compiler vibes, and this tool spills the tea on the differences.

and the good news? llvm-remark-size-diff handles both YAML and bitstream remarks. versatile icon 👑

---

🦋 OPTIONS 🦋

• --parser=<yaml|bitstream> — pick the type of input remark parser. this one is required, so no skipping it 🙈
  • yaml: the tool will parse YAML remarks.
  • bitstream: the tool will parse bitstream remarks.
• --report-style=<human|json> — the output style ✨
  • human: human-readable textual report. this is the default option.
  • json: JSON report.
• --pretty — pretty-print JSON output. optional.
  • > heads up: if output is not set to JSON, this does literally nothing. like, zero. nada. 🙃
• -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, bestie:

• 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 this:

(++|--|==) (>|<) function_name, N instrs, M stack B

a breakdown of the format is below — pay attention, this is the good part 👀

(++|--|==) 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. (iconic, honestly)

N instrs second file instruction count − first file instruction count. i.e. the diff, periodt.

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. so you get the whole picture at the end, and it's giving finale 🎬

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 🍓

okay important — Function JSON does not contain the diffs. tools consuming JSON output from llvm-remark-size-diff are responsible for computing the diffs separately. yeah, you gotta do the math yourself, sorry bestie 😭

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. classic. slay. ✨

---

🌟 AUTHOR 🌟

maintained by the LLVM Team (https://llvm.org/). kings of the compiler world, fr fr 🫶

---

🎀 COPYRIGHT 🎀

2003-2023, LLVM Project

---

and that's the whole page, bestie! 💖 sign-off time: this one's dated 2023-12-01, from the LLVM Project, year range 2003-2023, and it lives on page 17 of the manual. go diff some remarks and slay 💅✨🌈