350 lines · plain
1llvm-ir2vec - IR2Vec and MIR2Vec Embedding Generation Tool2==========================================================3 4.. program:: llvm-ir2vec5 6SYNOPSIS7--------8 9:program:`llvm-ir2vec` [*subcommand*] [*options*]10 11DESCRIPTION12-----------13 14:program:`llvm-ir2vec` is a standalone command-line tool for IR2Vec and MIR2Vec.15It generates embeddings for both LLVM IR and Machine IR (MIR) and supports 16triplet generation for vocabulary training. 17 18The tool provides three main subcommands:19 201. **triplets**: Generates numeric triplets in train2id format for vocabulary21 training from LLVM IR.22 232. **entities**: Generates entity mapping files (entity2id.txt) for vocabulary 24 training.25 263. **embeddings**: Generates IR2Vec or MIR2Vec embeddings using a trained vocabulary27 at different granularity levels (instruction, basic block, or function).28 29The tool supports two operation modes:30 31* **LLVM IR mode** (``--mode=llvm``): Process LLVM IR bitcode files and generate32 IR2Vec embeddings33* **Machine IR mode** (``--mode=mir``): Process Machine IR (.mir) files and generate34 MIR2Vec embeddings35 36The tool is designed to facilitate machine learning applications that work with37LLVM IR or Machine IR by converting them into numerical representations that can 38be used by ML models. The `triplets` subcommand generates numeric IDs directly 39instead of string triplets, streamlining the training data preparation workflow.40 41.. note::42 43 For information about using IR2Vec and MIR2Vec programmatically within LLVM 44 passes and the C++ API, see the `IR2Vec Embeddings <https://llvm.org/docs/MLGO.html#ir2vec-embeddings>`_ 45 section in the MLGO documentation.46 47OPERATION MODES48---------------49 50The tool operates in two modes: **LLVM IR mode** and **Machine IR mode**. The mode51is selected using the ``--mode`` option (default: ``llvm``).52 53Triplet Generation and Entity Mapping Modes are used for preparing54vocabulary and training data for knowledge graph embeddings. The Embedding Mode55is used for generating embeddings from LLVM IR using a pre-trained vocabulary.56 57The Seed Embedding Vocabulary of IR2Vec is trained on a large corpus of LLVM IR58by modeling the relationships between opcodes, types, and operands as a knowledge59graph. For this purpose, Triplet Generation and Entity Mapping Modes generate60triplets and entity mappings in the standard format used for knowledge graph61embedding training (see 62<https://github.com/thunlp/OpenKE/tree/OpenKE-PyTorch?tab=readme-ov-file#data-format> 63for details).64 65See `llvm/utils/mlgo-utils/IR2Vec/generateTriplets.py` for more details on how66these two modes are used to generate the triplets and entity mappings.67 68Triplet Generation69~~~~~~~~~~~~~~~~~~70 71With the `triplets` subcommand, :program:`llvm-ir2vec` analyzes LLVM IR or Machine IR72and extracts numeric triplets consisting of opcode IDs and operand IDs. These triplets73are generated in the standard format used for knowledge graph embedding training.74The tool outputs numeric IDs directly using the vocabulary mapping infrastructure,75eliminating the need for string-to-ID preprocessing.76 77Usage for LLVM IR:78 79.. code-block:: bash80 81 llvm-ir2vec triplets --mode=llvm input.bc -o triplets_train2id.txt82 83Usage for Machine IR:84 85.. code-block:: bash86 87 llvm-ir2vec triplets --mode=mir input.mir -o triplets_train2id.txt88 89Entity Mapping Generation90~~~~~~~~~~~~~~~~~~~~~~~~~91 92With the `entities` subcommand, :program:`llvm-ir2vec` generates the entity mappings93supported by IR2Vec or MIR2Vec in the standard format used for knowledge graph embedding94training. This subcommand outputs all supported entities with their corresponding numeric IDs.95 96For LLVM IR, entities include opcodes, types, and operands. For Machine IR, entities include97machine opcodes, common operands, and register classes (both physical and virtual).98 99Usage for LLVM IR:100 101.. code-block:: bash102 103 llvm-ir2vec entities --mode=llvm -o entity2id.txt104 105Usage for Machine IR:106 107.. code-block:: bash108 109 llvm-ir2vec entities --mode=mir input.mir -o entity2id.txt110 111.. note::112 113 For LLVM IR mode, the entity mapping is target-independent and does not require an input file.114 For Machine IR mode, an input .mir file is required to determine the target architecture,115 as entity mappings vary by target (different architectures have different instruction sets116 and register classes).117 118Embedding Generation119~~~~~~~~~~~~~~~~~~~~120 121With the `embeddings` subcommand, :program:`llvm-ir2vec` uses a pre-trained vocabulary to122generate numerical embeddings for LLVM IR or Machine IR at different levels of granularity.123 124Example Usage for LLVM IR:125 126.. code-block:: bash127 128 llvm-ir2vec embeddings --mode=llvm --ir2vec-vocab-path=vocab.json --ir2vec-kind=symbolic --level=func input.bc -o embeddings.txt129 130Example Usage for Machine IR:131 132.. code-block:: bash133 134 llvm-ir2vec embeddings --mode=mir --mir2vec-vocab-path=vocab.json --level=func input.mir -o embeddings.txt135 136OPTIONS137-------138 139Common options (applicable to both LLVM IR and Machine IR modes):140 141.. option:: --mode=<mode>142 143 Specify the operation mode. Valid values are:144 145 * ``llvm`` - Process LLVM IR bitcode files (default)146 * ``mir`` - Process Machine IR (.mir) files147 148.. option:: -o <filename>149 150 Specify the output filename. Use ``-`` to write to standard output (default).151 152.. option:: --help153 154 Print a summary of command line options.155 156Subcommand-specific options:157 158**embeddings** subcommand:159 160.. option:: <input-file>161 162 The input LLVM IR/bitcode file (.ll/.bc) or Machine IR file (.mir) to process. 163 This positional argument is required for the `embeddings` subcommand.164 165.. option:: --level=<level>166 167 Specify the embedding generation level. Valid values are:168 169 * ``inst`` - Generate instruction-level embeddings170 * ``bb`` - Generate basic block-level embeddings 171 * ``func`` - Generate function-level embeddings (default)172 173.. option:: --function=<name>174 175 Process only the specified function instead of all functions in the module.176 177**IR2Vec-specific options** (for ``--mode=llvm``):178 179.. option:: --ir2vec-kind=<kind>180 181 Specify the kind of IR2Vec embeddings to generate. Valid values are:182 183 * ``symbolic`` - Generate symbolic embeddings (default)184 * ``flow-aware`` - Generate flow-aware embeddings185 186 Flow-aware embeddings consider control flow relationships between instructions,187 while symbolic embeddings focus on the symbolic representation of instructions.188 189.. option:: --ir2vec-vocab-path=<path>190 191 Specify the path to the IR2Vec vocabulary file (required for LLVM IR embedding 192 generation). The vocabulary file should be in JSON format and contain the trained193 vocabulary for embedding generation. See `llvm/lib/Analysis/models`194 for pre-trained vocabulary files.195 196.. option:: --ir2vec-opc-weight=<weight>197 198 Specify the weight for opcode embeddings (default: 1.0). This controls199 the relative importance of instruction opcodes in the final embedding.200 201.. option:: --ir2vec-type-weight=<weight>202 203 Specify the weight for type embeddings (default: 0.5). This controls204 the relative importance of type information in the final embedding.205 206.. option:: --ir2vec-arg-weight=<weight>207 208 Specify the weight for argument embeddings (default: 0.2). This controls209 the relative importance of operand information in the final embedding.210 211**MIR2Vec-specific options** (for ``--mode=mir``):212 213.. option:: --mir2vec-vocab-path=<path>214 215 Specify the path to the MIR2Vec vocabulary file (required for Machine IR 216 embedding generation). The vocabulary file should be in JSON format and 217 contain the trained vocabulary for embedding generation.218 219.. option:: --mir2vec-kind=<kind>220 221 Specify the kind of MIR2Vec embeddings to generate. Valid values are:222 223 * ``symbolic`` - Generate symbolic embeddings (default)224 225.. option:: --mir2vec-opc-weight=<weight>226 227 Specify the weight for machine opcode embeddings (default: 1.0). This controls228 the relative importance of machine instruction opcodes in the final embedding.229 230.. option:: --mir2vec-common-operand-weight=<weight>231 232 Specify the weight for common operand embeddings (default: 1.0). This controls233 the relative importance of common operand types in the final embedding.234 235.. option:: --mir2vec-reg-operand-weight=<weight>236 237 Specify the weight for register operand embeddings (default: 1.0). This controls238 the relative importance of register operands in the final embedding.239 240 241**triplets** subcommand:242 243.. option:: <input-file>244 245 The input LLVM IR/bitcode file (.ll/.bc) or Machine IR file (.mir) to process. 246 This positional argument is required for the `triplets` subcommand.247 248**entities** subcommand:249 250.. option:: <input-file>251 252 The input Machine IR file (.mir) to process. This positional argument is required253 for the `entities` subcommand when using ``--mode=mir``, as the entity mappings254 are target-specific. For ``--mode=llvm``, no input file is required as IR2Vec255 entity mappings are target-independent.256 257OUTPUT FORMAT258-------------259 260Triplet Mode Output261~~~~~~~~~~~~~~~~~~~262 263In triplet mode, the output consists of numeric triplets in train2id format with264metadata headers. The format includes:265 266.. code-block:: text267 268 MAX_RELATION=<max_relation_count>269 <head_entity_id> <tail_entity_id> <relation_id>270 <head_entity_id> <tail_entity_id> <relation_id>271 ...272 273Each line after the metadata header represents one instruction relationship,274with numeric IDs for head entity, tail entity, and relation type. The metadata 275header (MAX_RELATION) indicates the maximum relation ID used.276 277**Relation Types:**278 279For LLVM IR (IR2Vec):280 * **0** = Type relationship (instruction to its type)281 * **1** = Next relationship (sequential instructions)282 * **2+** = Argument relationships (Arg0, Arg1, Arg2, ...)283 284For Machine IR (MIR2Vec):285 * **0** = Next relationship (sequential instructions)286 * **1+** = Argument relationships (Arg0, Arg1, Arg2, ...)287 288**Entity IDs:**289 290For LLVM IR: Entity IDs represent opcodes, types, and operands as defined by the IR2Vec vocabulary.291 292For Machine IR: Entity IDs represent machine opcodes, common operands (immediate, frame index, etc.),293physical register classes, and virtual register classes as defined by the MIR2Vec vocabulary. The entity layout is target-specific.294 295Entity Mode Output296~~~~~~~~~~~~~~~~~~297 298In entity mode, the output consists of entity mappings in the format:299 300.. code-block:: text301 302 <total_entities>303 <entity_string> <numeric_id>304 <entity_string> <numeric_id>305 ...306 307The first line contains the total number of entities, followed by one entity308mapping per line with tab-separated entity string and numeric ID.309 310For LLVM IR, entities include instruction opcodes (e.g., "Add", "Ret"), types 311(e.g., "INT", "PTR"), and operand kinds.312 313For Machine IR, entities include machine opcodes (e.g., "COPY", "ADD"), 314common operands (e.g., "Immediate", "FrameIndex"), physical register classes 315(e.g., "PhyReg_GR32"), and virtual register classes (e.g., "VirtReg_GR32").316 317Embedding Mode Output318~~~~~~~~~~~~~~~~~~~~~319 320In embedding mode, the output format depends on the specified level:321 322* **Function Level**: One embedding vector per function323* **Basic Block Level**: One embedding vector per basic block, grouped by function324* **Instruction Level**: One embedding vector per instruction, grouped by basic block and function325 326Each embedding is represented as a floating point vector.327 328EXIT STATUS329-----------330 331:program:`llvm-ir2vec` returns 0 on success, and a non-zero value on failure.332 333Common failure cases include:334 335* Invalid or missing input file336* Missing or invalid vocabulary file (in embedding mode)337* Specified function not found in the module338* Invalid command line options339 340SEE ALSO341--------342 343:doc:`../MLGO`344 345For more information about the IR2Vec algorithm and approach, see:346`IR2Vec: LLVM IR Based Scalable Program Embeddings <https://doi.org/10.1145/3418463>`_.347 348For more information about the MIR2Vec algorithm and approach, see:349`RL4ReAl: Reinforcement Learning for Register Allocation <https://doi.org/10.1145/3578360.3580273>`_.350