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 | |
26 | namespace llvm { |
27 | |
28 | class BitstreamWriter; |
29 | class Module; |
30 | class 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 | |