LLVM-REMARKUTIL(1)

📦 version 23.1.3, in centos-stream 9

🌸 LLVM-REMARKUTIL — the `llvm-remarkutil` page, but make it make sense 💅

okay so bestie, welcome to the LLVM manual, and specifically to llvm-remarkutil. this is the page where all the remark-utility lore lives, and honestly? it ate. let's get into it 🫶

✨ NAME ✨

llvm-remarkutil — Remark utility. that's it, that's the name. short, sweet, iconic 👑

✨ SYNOPSIS ✨

llvm-remarkutil [subcommmand] [options]

(yes, subcommmand with three m's — that's how the original spells it, we do not fix, we respect 💀)

✨ DESCRIPTION ✨

it's a utility for displaying info from different remark formats, and for converting between them. so like, a little remark-format translator bestie. no cap. 🌈

✨ SUBCOMMANDS ✨

bitstream2yaml — reserialize bitstream remarks to YAML.
yaml2bitstream — reserialize YAML remarks to bitstream.
instruction-count — output function instruction counts.
annotation-count — output remark type count from annotation remarks.
size-diff — compute diff in size remarks.

🎀 bitstream2yaml 🎀

USAGE: llvm-remarkutil bitstream2yaml <input file> -o <output file>

Summary

takes a bitstream remark file as input and reserializes that file as YAML. glow-up in file format form ✨

🎀 yaml2bitstream 🎀

USAGE: llvm-remarkutil yaml2bitstream <input file> -o <output file>

Summary

takes a YAML remark file as input and reserializes that file in the bitstream format. the reverse glow-up, we love a two-way street 💖

🎀 instruction-count 🎀

USAGE: llvm-remarkutil instruction-count <input file>
--parser=<bitstream|yaml> [--use-debug-loc] -o <output file>

Summary

outputs instruction count remarks for every function. and what's an instruction count remark, you ask? it encodes the number of instructions in a function at assembly printing time. literally a headcount for instructions 🧮

⚠️ instruction count remarks require asm-printer remarks. no asm-printer remarks, no count, that's the vibe check.

the CSV format is as follows:

Function,InstructionCount
foo,123

if --use-debug-loc is passed then the CSV will include the source path, line number and column. so bougie, so detailed:

Source,Function,InstructionCount
path:line:column,foo,3

🎀 annotation-count 🎀

USAGE: llvm-remarkutil annotation-count <input file>
--parser=<bitstream|yaml> --annotation-type=<type>  [--use-debug-loc] -o
<output file>

Summary

outputs a count for annotation-type <type> remark for every function. the count expresses the number of remark checks inserted at the function. like a little attendance sheet for checks 🎀

⚠️ annotation count remarks require AnnotationRemarksPass remarks.

CSV format go brrr:

Function,Count
foo,123

if --use-debug-loc is passed then the CSV will include the source path, line number and column:

Source,Function,Count
path:line:column,foo,3

🎀 count 🎀

USAGE: llvm-remarkutil count [options] <input file>

Summary

llvm-remarkutil count counts remarks based on specified properties. by default the tool counts remarks based on how many occur in a source file or function or total for the generated remark file. the tool also supports collecting count based on specific remark arguments. the specified arguments should have an integer value to be able to report a count.

and it gets better — the tool contains utilities to filter the remark count based on remark name, pass name, argument value and remark type. filtering queen behavior fr fr 👑

Options

--parser=<yaml|bitstream> — select the type of input remark parser. Required. and the options are:
- yaml : the tool will parse YAML remarks.
- bitstream : the tool will parse bitstream remarks.
--count-by=<value> — select option to collect remarks by.
- remark-name : count how many individual remarks exist.
- arg : count remarks based on specified arguments passed by --(r)args. the argument value must be a number.
--group-by=<value> — group count of remarks by property.
- source : count will be collected per source path. remarks with no debug location will not be counted.
- function : count is collected per function.
- function-with-loc : count is collected per function per source. remarks with no debug location will not be counted.
- Total : report a count for the provided remark file.
--args[=arguments] — if count-by is set to arg this flag can be used to collect from specified remark arguments represented as a comma separated string. the arguments must have a numeral value to be able to count remarks by.
--rargs[=arguments] — if count-by is set to arg this flag can be used to collect from specified remark arguments using regular expression. the arguments must have a numeral value to be able to count remarks by.
--pass-name[=<string>] — filter count by pass name.
--rpass-name[=<string>] — filter count by pass name using regular expressions.
--remark-name[=<string>] — filter count by remark name.
--rremark-name[=<string>] — filter count by remark name using regular expressions.
--filter-arg-by[=<string>] — filter count by argument value.
--rfilter-arg-by[=<string>] — filter count by argument value using regular expressions.
--remark-type=<value> — filter remarks by type with the following options:
- unknown
- passed
- missed
- analysis
- analysis-fp-commute
- analysis-aliasing
- failure

🎀 size-diff 🎀

USAGE: llvm-remarkutil size-diff [options] file_a file_b --parser parser

Summary

llvm-remarkutil size-diff diffs size remarks in two remark files: file_a and file_b.

llvm-remarkutil size-diff can be used to gain insight into which functions were impacted the most by code generation changes. detective mode activated 🔍

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. so like, same source, different eras ✨

llvm-remarkutil size-diff handles both YAML and bitstream remarks. inclusive icon 💅

Options

--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.
--report-style=<human|json> — output style.
- human : human-readable textual report. Default option.
- json : JSON report.
--pretty — pretty-print JSON output. Optional.
- if output is not set to JSON, this does nothing. yes, it just sits there looking cute 🙈
-o=<file> — output file for the report. outputs to stdout by default.

💖 Human-Readable Output 💖

the human-readable format for llvm-remarkutil 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-remarkutil 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-remarkutil 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.

llvm-remarkutil 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 llvm-remarkutil size-diff are responsible for computing the diffs separately. you gotta do the math yourself bestie, the tool is not your calculator 😭

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-remarkutil size-diff returns 0 on success, and a non-zero value otherwise. successful slay vs. not-so-successful slay 💀

✨ AUTHOR ✨

maintained by the LLVM Team (https://llvm.org/). periodt. 🫶

✨ COPYRIGHT ✨

2003-2026, LLVM Project — iconic run, honestly 👑

and that's the whole page, bestie!! this was page 23 of the LLVM manual, dated 2026-10-06, and the manual name is LLVM-REMARKUTIL(1) in case you forgot already 💖 mwah, go count some remarks ✨🎀🦋

📦 where this page comes from

centos-stream 9: llvm 23.1.3-1.el9 · Apache-2.0 WITH LLVM-exception OR NCSA
centos-stream 9: llvm 23.1.3-1.el9 · Apache-2.0 WITH LLVM-exception OR NCSA
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

LLVM-REMARKUTIL(1)

🌸 LLVM-REMARKUTIL — the llvm-remarkutil page, but make it make sense 💅

✨ NAME ✨

✨ SYNOPSIS ✨

✨ DESCRIPTION ✨

✨ SUBCOMMANDS ✨

🎀 bitstream2yaml 🎀

Summary

🎀 yaml2bitstream 🎀

Summary

🎀 instruction-count 🎀

Summary

🎀 annotation-count 🎀

Summary

🎀 count 🎀

Summary

Options

🎀 size-diff 🎀

Summary

Options

💖 Human-Readable Output 💖

🌸 Changed Function Section 🌸

🌸 Summary Section 🌸

🌈 JSON OUTPUT 🌈

High-Level view

Function JSON

Computing Diffs From Function JSON

✨ EXIT STATUS ✨

✨ AUTHOR ✨

✨ COPYRIGHT ✨

🌸 LLVM-REMARKUTIL — the `llvm-remarkutil` page, but make it make sense 💅