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