1//===- IRUtils.h - IR2Vec Tool Class ------------------------------===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8///
9/// \file
10/// This file contains the IR2VecTool class definition for generating
11/// embeddings and triplets from LLVM IR. It has no dependency on Machine IR.
12///
13//===----------------------------------------------------------------------===//
14
15#ifndef LLVM_TOOLS_LLVM_IR2VEC_UTILS_IRUTILS_H
16#define LLVM_TOOLS_LLVM_IR2VEC_UTILS_IRUTILS_H
17
18#include "Common.h"
19#include "llvm/ADT/DenseMap.h"
20#include "llvm/Analysis/IR2Vec.h"
21#include "llvm/IR/Function.h"
22#include "llvm/IR/Module.h"
23#include "llvm/Support/Error.h"
24#include "llvm/Support/raw_ostream.h"
25#include <memory>
26
27#define DEBUG_TYPE "ir2vec"
28
29namespace llvm {
30
31/// Per-function embedding map: Function* -> Embedding
32using FuncEmbMap = DenseMap<const Function *, ir2vec::Embedding>;
33
34namespace ir2vec {
35
36/// Relation types for IR triplet generation
37enum RelationType {
38 TypeRelation = 0, ///< Instruction to type relationship
39 NextRelation = 1, ///< Sequential instruction relationship
40 ArgRelation = 2 ///< Instruction to operand relationship (ArgRelation + N)
41};
42
43/// Load an IR2Vec vocabulary from a JSON file on disk.
44Expected<std::shared_ptr<Vocabulary>> loadVocabulary(StringRef VocabPath);
45
46/// Helper class for collecting IR triplets and generating embeddings
47class IR2VecTool {
48private:
49 Module &M;
50
51 /// \note The API around vocab object is not thread-safe.
52 /// Specifically, calling setVocabulary() on an instance while
53 /// another thread reading the Vocab object with the same instance
54 /// can cause a data race on this internal shared_ptr<Vocabulary> member.
55 std::shared_ptr<Vocabulary> Vocab;
56
57public:
58 explicit IR2VecTool(Module &M) : M(M) {}
59
60 /// Creates the embedding object for downstream embedding streaming
61 Expected<std::unique_ptr<Embedder>>
62 createIR2VecEmbedder(const Function &F, IR2VecKind Kind) const;
63
64 /// Sets the vocabulary for this tool instance.
65 /// This allows sharing the same vocabulary instance across multiple
66 /// IR2VecTool instances, which is useful for generating embeddings for
67 /// multiple functions without needing to reload the vocabulary each time.
68 Error setVocabulary(std::shared_ptr<Vocabulary> V);
69
70 /// Generate triplets for a single function
71 /// Returns a TripletResult with:
72 /// - Triplets: vector of all (subject, object, relation) tuples
73 /// - MaxRelation: highest Arg relation ID used, or NextRelation if none
74 TripletResult generateTriplets(const Function &F) const;
75
76 /// Get triplets for the entire module
77 TripletResult generateTriplets() const;
78
79 /// Collect triplets for the module and dump output to stream
80 /// Output format: MAX_RELATION=N header followed by relationships
81 void writeTripletsToStream(raw_ostream &OS) const;
82
83 /// Generate entity mappings for the entire vocabulary
84 /// Returns EntityList containing all entity strings
85 static EntityList collectEntityMappings();
86
87 /// Dump entity ID to string mappings
88 static void writeEntitiesToStream(raw_ostream &OS);
89
90 /// Get embedding for a single function
91 Expected<Embedding> getFunctionEmbedding(const Function &F,
92 IR2VecKind Kind) const;
93
94 /// Get embeddings for all functions in the module
95 Expected<FuncEmbMap> getFunctionEmbeddingsMap(IR2VecKind Kind) const;
96
97 /// Get embeddings for all basic blocks in a function
98 Expected<BBEmbeddingsMap> getBBEmbeddingsMap(const Function &F,
99 IR2VecKind Kind) const;
100
101 /// Get embeddings for all instructions in a function
102 Expected<InstEmbeddingsMap> getInstEmbeddingsMap(const Function &F,
103 IR2VecKind Kind) const;
104
105 /// Generate embeddings for the entire module
106 void writeEmbeddingsToStream(raw_ostream &OS, EmbeddingLevel Level) const;
107
108 /// Generate embeddings for a single function
109 void writeEmbeddingsToStream(const Function &F, raw_ostream &OS,
110 EmbeddingLevel Level) const;
111};
112
113} // namespace ir2vec
114} // namespace llvm
115
116#endif // LLVM_TOOLS_LLVM_IR2VEC_UTILS_IRUTILS_H
117