LLVM-REMARKUTIL(1)

📦

version 22.1.8 · 6 versions

✨ NAME ✨

llvm-remarkutil — the remark utility, bestie 💅

🌈 SYNOPSIS 🌈

llvm-remarkutil [subcommmand] [options]

(Yes, "subcommmand" with three m's, we don't make the rules, we just report them 🫶)

💖 DESCRIPTION 💖

Okay so picture this: it's a utility for displaying info from and converting between different remark formats. And when we say remark formats we mean the [remark](https://llvm.org/docs/Remarks.html) formats, obviously. iykyk ✨

🎀 SUBCOMMANDS 🎀

Pick your fighter, bestie — there's five:

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

You hand it a bitstream remark file as the input, and it reserializes that whole file as YAML. Glow up, but for file formats 💅

🍓 yaml2bitstream 🍓

USAGE

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

Summary

You hand it a YAML remark file as the input, and it reserializes that file in the bitstream format. The reverse glow up, iconic 🌈

🌸 instruction-count 🌸

USAGE

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

Summary

It outputs instruction count remarks for every single function, no skips. An instruction count remark encodes how many instructions are in a function at assembly printing time.

Heads up bestie: instruction count remarks require asm-printer remarks. No asm-printer remarks, no counts, that's just the deal 😭

The CSV format goes like this:

Function,InstructionCount
foo,123

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

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

It outputs a count for the annotation-type <type> remark, for every function. And that count is literally expressing the number of remark checks inserted at the function. Main character counting energy 👑

Also a requirement situation: annotation count remarks require AnnotationRemarksPass remarks. Periodt.

CSV format:

Function,Count
foo,123

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

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

💜 count 💜

USAGE

llvm-remarkutil count [options] <input file>

Summary

llvm-remarkutil count counts [remarks](https://llvm.org/docs/Remarks.html) based on specified properties. By default, the tool counts remarks based on how many occur in a source file, or in a function, or the total for the generated remark file. It also supports collecting counts based on specific remark arguments — but the specified arguments have to have an integer value to be able to report a count. No integer, no count, sorry bestie 🙈

The tool also contains utilities to filter the remark count based on remark name, pass name, argument value and remark type. So many little knobs, we love a customizable queen 💅

Options

--parser=<yaml|bitstream> — selects the type of input remark parser. Required. Like, actually required.
- yaml : the tool will parse YAML remarks.
- bitstream : the tool will parse bitstream remarks.
--count-by=<value> — select the option to collect remarks by.
- remark-name : counts how many individual remarks exist.
- arg : counts remarks based on specified arguments passed by --(r)args. The argument value must be a number.
--group-by=<value> — group the count of remarks by property.
- source : the count gets collected per source path. Remarks with no debug location will not be counted.
- function : the count is collected per function.
- function-with-loc : the count is collected per function per source. Remarks with no debug location will not be counted.
- Total : reports 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 expressions. 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 these 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](https://llvm.org/docs/Remarks.html) in two remark files: file_a and file_b.

It can be used to gain insight into which functions were impacted the most by code generation changes. So dramatic, we love a forensic moment 🕵️

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.

And ngl, it handles both [YAML](https://llvm.org/docs/Remarks.html#yaml-remarks) remarks and [bitstream](https://llvm.org/docs/Remarks.html#llvm-bitstream-remarks) remarks. Versatile icon ✨

Options

--parser=<yaml|bitstream> — selects 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. Literally nothing. A decorative flag 💀
-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're 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 the one 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 the second file than the first file.
- <: fewer instructions in the second file than in the first file.
function_name — the name of the changed function.
N instrs — second file instruction count minus first file instruction count.
M stack B — second file stack byte count minus first file stack byte count.

Summary Section

llvm-remarkutil size-diff will output a high-level summary after printing all the changed functions:

instruction count: N (inst_pct_change%)
stack byte usage: M (sb_pct_change%)

N — the sum of all instruction count changes between the second and first file.
inst_pct_change% — the percent increase or decrease in instruction count between the second and first file.
M — the sum of all stack byte count changes between the second and first file.
sb_pct_change% — the percent increase or decrease in stack byte usage between the second and first file.

JSON OUTPUT

High-Level view

Suppose we're comparing two files, OLD and NEW.

llvm-remarkutil size-diff will output JSON like this:

"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. Do your own math, bestie, we're not doing it for you 💅

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. Success slay, failure not so much 💀

👑 Author

Maintained by the LLVM Team (https://llvm.org/).

🎀 Copyright

2003-2026, LLVM Project

okay bestie that's the whole page, no notes 🫶 this was llvm-remarkutil from the LLVM manual, version 22, dated 2026-07-16 — go count some remarks, you absolute legend ✨💖

📦 where this page comes from

fedora 44: llvm 22.1.8-4.fc44 · Apache-2.0 WITH LLVM-exception OR NCSA
fedora 44: llvm 22.1.8-4.fc44 · Apache-2.0 WITH LLVM-exception OR NCSA
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms