LLVM-IR2VEC(1)

📦
version 22.1.8 · 6 versions
, in fedora 44

llvm-ir2vec(1) 💖

okay bestie, pull up a chair, grab a boba, because we're about to get extremely into embedding generation and honestly? it's giving iconic.

✨ NAME ✨

llvm-ir2vec — the IR2Vec and MIR2Vec Embedding Generation Tool 🦋

🌸 SYNOPSIS 🌸

llvm-ir2vec [subcommand] [options]

💅 DESCRIPTION 💅

So. llvm-ir2vec is a standalone command-line tool for IR2Vec and MIR2Vec. It generates embeddings for both LLVM IR and Machine IR (MIR), and it also does triplet generation for vocabulary training. Versatile queen behavior, honestly. 👑

The tool gives you three main subcommands:

  1. triplets: Generates numeric triplets in train2id format for vocabulary training from LLVM IR.
  2. entities: Generates entity mapping files (entity2id.txt) for vocabulary training.
  3. embeddings: Generates IR2Vec or MIR2Vec embeddings using a trained vocabulary at different granularity levels (instruction, basic block, or function).

And there are two operation modes:

  • LLVM IR mode (--mode=llvm): Process LLVM IR bitcode files and generate IR2Vec embeddings
  • Machine IR mode (--mode=mir): Process Machine IR (.mir) files and generate MIR2Vec embeddings

The tool is designed to facilitate machine learning applications that work with LLVM IR or Machine IR by converting them into numerical representations that can be used by ML models. And here's the slay part: the triplets subcommand generates numeric IDs directly instead of string triplets, streamlining the training data preparation workflow. no string-to-ID pre-processing era, we simply do not do that anymore. 🚫

Note: For information about using IR2Vec and MIR2Vec programmatically within LLVM passes and the C++ API, see the IR2Vec Embeddings section in the MLGO documentation: https://llvm.org/docs/MLGO.html#ir2vec-embeddings

🌈 OPERATION MODES 🌈

The tool operates in two modes: LLVM IR mode and Machine IR mode. The mode is selected using the --mode option (default: llvm).

Triplet Generation and Entity Mapping Modes are used for preparing vocabulary and training data for knowledge graph embeddings. The Embedding Mode is used for generating embeddings from LLVM IR using a pre-trained vocabulary.

The Seed Embedding Vocabulary of IR2Vec is trained on a large corpus of LLVM IR by modeling the relationships between opcodes, types, and operands as a knowledge graph. For this purpose, Triplet Generation and Entity Mapping Modes generate triplets and entity mappings in the standard format used for knowledge graph embedding training (see https://github.com/thunlp/OpenKE/tree/OpenKE-PyTorch?tab=readme-ov-file#data-format for details).

See llvm/utils/mlgo-utils/IR2Vec/generateTriplets.py for more details on how these two modes are used to generate the triplets and entity mappings. 🫶

🎀 Triplet Generation 🎀

With the triplets subcommand, llvm-ir2vec analyzes LLVM IR or Machine IR and extracts numeric triplets consisting of opcode IDs and operand IDs. These triplets are generated in the standard format used for knowledge graph embedding training. The tool outputs numeric IDs directly using the vocabulary mapping infrastructure, eliminating the need for string-to-ID preprocessing. (say it with me: no more preprocessing, we're free 💀)

Usage for LLVM IR:

llvm-ir2vec triplets --mode=llvm input.bc -o triplets_train2id.txt

Usage for Machine IR:

llvm-ir2vec triplets --mode=mir input.mir -o triplets_train2id.txt

🦋 Entity Mapping Generation 🦋

With the entities subcommand, llvm-ir2vec generates the entity mappings supported by IR2Vec or MIR2Vec in the standard format used for knowledge graph embedding training. This subcommand outputs all supported entities with their corresponding numeric IDs. full roster, no gatekeeping.

For LLVM IR, entities include opcodes, types, and operands. For Machine IR, entities include machine opcodes, common operands, and register classes (both physical and virtual).

Usage for LLVM IR:

llvm-ir2vec entities --mode=llvm -o entity2id.txt

Usage for Machine IR:

llvm-ir2vec entities --mode=mir input.mir -o entity2id.txt
Note: For LLVM IR mode, the entity mapping is target-independent and does not require an input file. For Machine IR mode, an input .mir file is required to determine the target architecture, as entity mappings vary by target (different architectures have different instruction sets and register classes). different targets, different lore, iykyk.

👑 Embedding Generation 👑

With the embeddings subcommand, llvm-ir2vec uses a pre-trained vocabulary to generate numerical embeddings for LLVM IR or Machine IR at different levels of granularity.

Example Usage for LLVM IR:

llvm-ir2vec embeddings --mode=llvm --ir2vec-vocab-path=vocab.json --ir2vec-kind=symbolic --level=func input.bc -o embeddings.txt

Example Usage for Machine IR:

llvm-ir2vec embeddings --mode=mir --mir2vec-vocab-path=vocab.json --level=func input.mir -o embeddings.txt

💖 OPTIONS 💖

Common options (applicable to both LLVM IR and Machine IR modes):

  • --mode=<mode> — Specify the operation mode. Valid values are:
    • llvm - Process LLVM IR bitcode files (default)
    • mir - Process Machine IR (.mir) files
  • -o <filename> — Specify the output filename. Use - to write to standard output (default). ✨
  • --help — Print a summary of command line options.

Subcommand-specific options:

embeddings subcommand:

  • <input-file> — The input LLVM IR/bitcode file (.ll/.bc) or Machine IR file (.mir) to process. This positional argument is required for the embeddings subcommand.
  • --level=<level> — Specify the embedding generation level. Valid values are:
    • inst - Generate instruction-level embeddings
    • bb - Generate basic block-level embeddings
    • func - Generate function-level embeddings (default)
  • --function=<name> — Process only the specified function instead of all functions in the module. one function only, main character energy 🎯

IR2Vec-specific options (for --mode=llvm):

  • --ir2vec-kind=<kind> — Specify the kind of IR2Vec embeddings to generate. Valid values are:
    • symbolic - Generate symbolic embeddings (default)
    • flow-aware - Generate flow-aware embeddings

Flow-aware embeddings consider control flow relationships between instructions, while symbolic embeddings focus on the symbolic representation of instructions.

  • --ir2vec-vocab-path=<path> — Specify the path to the IR2Vec vocabulary file (required for LLVM IR embedding generation). The vocabulary file should be in JSON format and contain the trained vocabulary for embedding generation. See llvm/lib/Analysis/models for pre-trained vocabulary files. 🔥
  • --ir2vec-opc-weight=<weight> — Specify the weight for opcode embeddings (default: 1.0). This controls the relative importance of instruction opcodes in the final embedding.
  • --ir2vec-type-weight=<weight> — Specify the weight for type embeddings (default: 0.5). This controls the relative importance of type information in the final embedding.
  • --ir2vec-arg-weight=<weight> — Specify the weight for argument embeddings (default: 0.2). This controls the relative importance of operand information in the final embedding.

MIR2Vec-specific options (for --mode=mir):

  • --mir2vec-vocab-path=<path> — Specify the path to the MIR2Vec vocabulary file (required for Machine IR embedding generation). The vocabulary file should be in JSON format and contain the trained vocabulary for embedding generation.
  • --mir2vec-kind=<kind> — Specify the kind of MIR2Vec embeddings to generate. Valid values are:
    • symbolic - Generate symbolic embeddings (default)
  • --mir2vec-opc-weight=<weight> — Specify the weight for machine opcode embeddings (default: 1.0). This controls the relative importance of machine instruction opcodes in the final embedding.
  • --mir2vec-common-operand-weight=<weight> — Specify the weight for common operand embeddings (default: 1.0). This controls the relative importance of common operand types in the final embedding.
  • --mir2vec-reg-operand-weight=<weight> — Specify the weight for register operand embeddings (default: 1.0). This controls the relative importance of register operands in the final embedding.

triplets subcommand:

  • <input-file> — The input LLVM IR/bitcode file (.ll/.bc) or Machine IR file (.mir) to process. This positional argument is required for the triplets subcommand.

entities subcommand:

  • <input-file> — The input Machine IR file (.mir) to process. This positional argument is required for the entities subcommand when using --mode=mir, as the entity mappings are target-specific. For --mode=llvm, no input file is required as IR2Vec entity mappings are target-independent. 💜

(pt. 2 is loading… don't go anywhere bestie 🍓)

🌈 OUTPUT FORMAT 🌈

okay bestie, so depending on which mode you picked, the output looks completely different. Let's break it down 💅

🎀 Triplet Mode Output 🎀

In triplet mode, the output consists of numeric triplets in train2id format with metadata headers. The format includes:

MAX_RELATION=<max_relation_count>
<head_entity_id> <tail_entity_id> <relation_id>
<head_entity_id> <tail_entity_id> <relation_id>
...

Every line after the metadata header is literally one instruction relationship — numeric IDs for head entity, tail entity, and relation type. And that metadata header (MAX_RELATION) tells you the maximum relation ID that got used. slay.

✨ Relation Types ✨

For LLVM IR (IR2Vec):

  • 0 = Type relationship (instruction to its type)
  • 1 = Next relationship (sequential instructions)
  • 2+ = Argument relationships (Arg0, Arg1, Arg2, ...)

For Machine IR (MIR2Vec):

  • 0 = Next relationship (sequential instructions)
  • 1+ = Argument relationships (Arg0, Arg1, Arg2, ...)

🌸 Entity IDs 🌸

For LLVM IR: Entity IDs represent opcodes, types, and operands as defined by the IR2Vec vocabulary.

For Machine IR: Entity IDs represent machine opcodes, common operands (immediate, frame index, etc.), physical register classes, and virtual register classes as defined by the MIR2Vec vocabulary. The entity layout is target-specific — iykyk, don't come for me about it, it depends on your target.

💖 Entity Mode Output 💖

In entity mode, the output is entity mappings, formatted like:

<total_entities>
<entity_string>      <numeric_id>
<entity_string>      <numeric_id>
...

First line = the total number of entities. After that, one entity mapping per line, with a tab-separated entity string and numeric ID. no cap.

For LLVM IR, entities include instruction opcodes (e.g., "Add", "Ret"), types (e.g., "INT", "PTR"), and operand kinds.

For Machine IR, entities include machine opcodes (e.g., "COPY", "ADD"), common operands (e.g., "Immediate", "FrameIndex"), physical register classes (e.g., "PhyReg_GR32"), and virtual register classes (e.g., "VirtReg_GR32"). iconic tbh.

🦋 Embedding Mode Output 🦋

In embedding mode, the output format depends on the level you specified:

  • Function Level: One embedding vector per function
  • Basic Block Level: One embedding vector per basic block, grouped by function
  • Instruction Level: One embedding vector per instruction, grouped by basic block and function

Each embedding is represented as a floating point vector. that's it, that's the vibe 💜

💀 EXIT STATUS 💀

llvm-ir2vec returns 0 on success, and a non-zero value on failure. periodt.

Common failure cases include:

  • Invalid or missing input file
  • Missing or invalid vocabulary file (in embedding mode)
  • Specified function not found in the module
  • Invalid command line options
if you're getting a non-zero exit and you're like "bestie why 😭" — check those four things first. nine times out of ten it's one of them.

👑 SEE ALSO 👑

Machine Learning - Guided Optimization (MLGO) <>

For more information about the IR2Vec algorithm and approach, see: IR2Vec: LLVM IR Based Scalable Program Embeddings https://doi.org/10.1145/3418463.

For more information about the MIR2Vec algorithm and approach, see: RL4ReAl: Reinforcement Learning for Register Allocation https://doi.org/10.1145/3578360.3580273.

🌟 Author 🌟

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

2003-2026, LLVM Project

and that's the whole page bestie 💅 big shoutout to the llvm-ir2vec(1) page itself — this is the 22-page version, dated 2026-07-16, living under the LLVM umbrella. go forth and embed, my love 🌈✨🎀

📦 where this page comes from