1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
llvm-ir2vec - IR2Vec Embedding Generation Tool
==============================================
.. program:: llvm-ir2vec
SYNOPSIS
--------
:program:`llvm-ir2vec` [*options*] *input-file*
DESCRIPTION
-----------
:program:`llvm-ir2vec` is a standalone command-line tool for IR2Vec. It
generates IR2Vec embeddings for LLVM IR and supports triplet generation
for vocabulary training. It provides two main operation modes:
1. **Triplet Mode**: Generates triplets (opcode, type, operands) for vocabulary
training from LLVM IR.
2. **Embedding Mode**: Generates IR2Vec embeddings using a trained vocabulary
at different granularity levels (instruction, basic block, or function).
The tool is designed to facilitate machine learning applications that work with
LLVM IR by converting the IR into numerical representations that can be used by
ML models.
.. note::
For information about using IR2Vec programmatically within LLVM passes and
the C++ API, see the `IR2Vec Embeddings <https://llvm.org/docs/MLGO.html#ir2vec-embeddings>`_
section in the MLGO documentation.
OPERATION MODES
---------------
Triplet Generation Mode
~~~~~~~~~~~~~~~~~~~~~~~
In triplet mode, :program:`llvm-ir2vec` analyzes LLVM IR and extracts triplets
consisting of opcodes, types, and operands. These triplets can be used to train
vocabularies for embedding generation.
Usage:
.. code-block:: bash
llvm-ir2vec --mode=triplets input.bc -o triplets.txt
Embedding Generation Mode
~~~~~~~~~~~~~~~~~~~~~~~~~~
In embedding mode, :program:`llvm-ir2vec` uses a pre-trained vocabulary to
generate numerical embeddings for LLVM IR at different levels of granularity.
Example Usage:
.. code-block:: bash
llvm-ir2vec --mode=embeddings --ir2vec-vocab-path=vocab.json --level=func input.bc -o embeddings.txt
OPTIONS
-------
.. option:: --mode=<mode>
Specify the operation mode. Valid values are:
* ``triplets`` - Generate triplets for vocabulary training
* ``embeddings`` - Generate embeddings using trained vocabulary (default)
.. option:: --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)
.. option:: --function=<name>
Process only the specified function instead of all functions in the module.
.. option:: --ir2vec-vocab-path=<path>
Specify the path to the vocabulary file (required for embedding mode).
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.
.. option:: --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.
.. option:: --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.
.. option:: --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.
.. option:: -o <filename>
Specify the output filename. Use ``-`` to write to standard output (default).
.. option:: --help
Print a summary of command line options.
.. note::
``--level``, ``--function``, ``--ir2vec-vocab-path``, ``--ir2vec-opc-weight``,
``--ir2vec-type-weight``, and ``--ir2vec-arg-weight`` are only used in embedding
mode. These options are ignored in triplet mode.
INPUT FILE FORMAT
-----------------
:program:`llvm-ir2vec` accepts LLVM bitcode files (``.bc``) and LLVM IR files
(``.ll``) as input. The input file should contain valid LLVM IR.
OUTPUT FORMAT
-------------
Triplet Mode Output
~~~~~~~~~~~~~~~~~~~
In triplet mode, the output consists of lines containing space-separated triplets:
.. code-block:: text
<opcode> <type> <operand1> <operand2> ...
Each line represents the information of one instruction, with the opcode, type,
and operands.
Embedding Mode Output
~~~~~~~~~~~~~~~~~~~~~
In embedding mode, the output format depends on the specified level:
* **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.
EXIT STATUS
-----------
:program:`llvm-ir2vec` returns 0 on success, and a non-zero value on failure.
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
SEE ALSO
--------
:doc:`../MLGO`
For more information about the IR2Vec algorithm and approach, see:
`IR2Vec: LLVM IR Based Scalable Program Embeddings <https://doi.org/10.1145/3418463>`_.
|
