1//===- llvm/Bitcode/BitcodeWriter.h - Bitcode writers -----------*- C++ -*-===//
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// This header defines interfaces to write LLVM bitcode files/streams.
10//
11//===----------------------------------------------------------------------===//
12
13#ifndef LLVM_BITCODE_BITCODEWRITER_H
14#define LLVM_BITCODE_BITCODEWRITER_H
15
16#include "llvm/ADT/StringRef.h"
17#include "llvm/IR/ModuleSummaryIndex.h"
18#include "llvm/MC/StringTableBuilder.h"
19#include "llvm/Support/Allocator.h"
20#include "llvm/Support/MemoryBufferRef.h"
21#include <map>
22#include <memory>
23#include <string>
24#include <vector>
25
26namespace llvm {
27
28class BitstreamWriter;
29class Module;
30class raw_ostream;
31
32 class BitcodeWriter {
33 SmallVectorImpl<char> &Buffer;
34 std::unique_ptr<BitstreamWriter> Stream;
35
36 StringTableBuilder StrtabBuilder{StringTableBuilder::RAW};
37
38 // Owns any strings created by the irsymtab writer until we create the
39 // string table.
40 BumpPtrAllocator Alloc;
41
42 bool WroteStrtab = false, WroteSymtab = false;
43
44 void writeBlob(unsigned Block, unsigned Record, StringRef Blob);
45
46 std::vector<Module *> Mods;
47
48 public:
49 /// Create a BitcodeWriter that writes to Buffer.
50 BitcodeWriter(SmallVectorImpl<char> &Buffer, raw_fd_stream *FS = nullptr);
51
52 ~BitcodeWriter();
53
54 /// Attempt to write a symbol table to the bitcode file. This must be called
55 /// at most once after all modules have been written.
56 ///
57 /// A reader does not require a symbol table to interpret a bitcode file;
58 /// the symbol table is needed only to improve link-time performance. So
59 /// this function may decide not to write a symbol table. It may so decide
60 /// if, for example, the target is unregistered or the IR is malformed.
61 void writeSymtab();
62
63 /// Write the bitcode file's string table. This must be called exactly once
64 /// after all modules and the optional symbol table have been written.
65 void writeStrtab();
66
67 /// Copy the string table for another module into this bitcode file. This
68 /// should be called after copying the module itself into the bitcode file.
69 void copyStrtab(StringRef Strtab);
70
71 /// Write the specified module to the buffer specified at construction time.
72 ///
73 /// If \c ShouldPreserveUseListOrder, encode the use-list order for each \a
74 /// Value in \c M. These will be reconstructed exactly when \a M is
75 /// deserialized.
76 ///
77 /// If \c Index is supplied, the bitcode will contain the summary index
78 /// (currently for use in ThinLTO optimization).
79 ///
80 /// \p GenerateHash enables hashing the Module and including the hash in the
81 /// bitcode (currently for use in ThinLTO incremental build).
82 ///
83 /// If \p ModHash is non-null, when GenerateHash is true, the resulting
84 /// hash is written into ModHash. When GenerateHash is false, that value
85 /// is used as the hash instead of computing from the generated bitcode.
86 /// Can be used to produce the same module hash for a minimized bitcode
87 /// used just for the thin link as in the regular full bitcode that will
88 /// be used in the backend.
89 void writeModule(const Module &M, bool ShouldPreserveUseListOrder = false,
90 const ModuleSummaryIndex *Index = nullptr,
91 bool GenerateHash = false, ModuleHash *ModHash = nullptr);
92
93 /// Write the specified thin link bitcode file (i.e., the minimized bitcode
94 /// file) to the buffer specified at construction time. The thin link
95 /// bitcode file is used for thin link, and it only contains the necessary
96 /// information for thin link.
97 ///
98 /// ModHash is for use in ThinLTO incremental build, generated while the
99 /// IR bitcode file writing.
100 void writeThinLinkBitcode(const Module &M, const ModuleSummaryIndex &Index,
101 const ModuleHash &ModHash);
102
103 void writeIndex(
104 const ModuleSummaryIndex *Index,
105 const std::map<std::string, GVSummaryMapTy> *ModuleToSummariesForIndex);
106 };
107
108 /// Write the specified module to the specified raw output stream.
109 ///
110 /// For streams where it matters, the given stream should be in "binary"
111 /// mode.
112 ///
113 /// If \c ShouldPreserveUseListOrder, encode the use-list order for each \a
114 /// Value in \c M. These will be reconstructed exactly when \a M is
115 /// deserialized.
116 ///
117 /// If \c Index is supplied, the bitcode will contain the summary index
118 /// (currently for use in ThinLTO optimization).
119 ///
120 /// \p GenerateHash enables hashing the Module and including the hash in the
121 /// bitcode (currently for use in ThinLTO incremental build).
122 ///
123 /// If \p ModHash is non-null, when GenerateHash is true, the resulting
124 /// hash is written into ModHash. When GenerateHash is false, that value
125 /// is used as the hash instead of computing from the generated bitcode.
126 /// Can be used to produce the same module hash for a minimized bitcode
127 /// used just for the thin link as in the regular full bitcode that will
128 /// be used in the backend.
129 void WriteBitcodeToFile(const Module &M, raw_ostream &Out,
130 bool ShouldPreserveUseListOrder = false,
131 const ModuleSummaryIndex *Index = nullptr,
132 bool GenerateHash = false,
133 ModuleHash *ModHash = nullptr);
134
135 /// Write the specified thin link bitcode file (i.e., the minimized bitcode
136 /// file) to the given raw output stream, where it will be written in a new
137 /// bitcode block. The thin link bitcode file is used for thin link, and it
138 /// only contains the necessary information for thin link.
139 ///
140 /// ModHash is for use in ThinLTO incremental build, generated while the IR
141 /// bitcode file writing.
142 void writeThinLinkBitcodeToFile(const Module &M, raw_ostream &Out,
143 const ModuleSummaryIndex &Index,
144 const ModuleHash &ModHash);
145
146 /// Write the specified module summary index to the given raw output stream,
147 /// where it will be written in a new bitcode block. This is used when
148 /// writing the combined index file for ThinLTO. When writing a subset of the
149 /// index for a distributed backend, provide the \p ModuleToSummariesForIndex
150 /// map.
151 void writeIndexToFile(const ModuleSummaryIndex &Index, raw_ostream &Out,
152 const std::map<std::string, GVSummaryMapTy>
153 *ModuleToSummariesForIndex = nullptr);
154
155 /// If EmbedBitcode is set, save a copy of the llvm IR as data in the
156 /// __LLVM,__bitcode section (.llvmbc on non-MacOS).
157 /// If available, pass the serialized module via the Buf parameter. If not,
158 /// pass an empty (default-initialized) MemoryBufferRef, and the serialization
159 /// will be handled by this API. The same behavior happens if the provided Buf
160 /// is not bitcode (i.e. if it's invalid data or even textual LLVM assembly).
161 /// If EmbedCmdline is set, the command line is also exported in
162 /// the corresponding section (__LLVM,_cmdline / .llvmcmd) - even if CmdArgs
163 /// were empty.
164 void embedBitcodeInModule(Module &M, MemoryBufferRef Buf, bool EmbedBitcode,
165 bool EmbedCmdline,
166 const std::vector<uint8_t> &CmdArgs);
167
168} // end namespace llvm
169
170#endif // LLVM_BITCODE_BITCODEWRITER_H
171

source code of llvm/include/llvm/Bitcode/BitcodeWriter.h