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 std::unique_ptr<BitstreamWriter> Stream; 34 35 StringTableBuilder StrtabBuilder{StringTableBuilder::RAW}; 36 37 // Owns any strings created by the irsymtab writer until we create the 38 // string table. 39 BumpPtrAllocator Alloc; 40 41 bool WroteStrtab = false, WroteSymtab = false; 42 43 void writeBlob(unsigned Block, unsigned Record, StringRef Blob); 44 45 std::vector<Module *> Mods; 46 47 public: 48 /// Create a BitcodeWriter that writes to Buffer. 49 BitcodeWriter(SmallVectorImpl<char> &Buffer); 50 BitcodeWriter(raw_ostream &FS); 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 const GVSummaryPtrSet *DecSummaries); 107 }; 108 109 /// Write the specified module to the specified raw output stream. 110 /// 111 /// For streams where it matters, the given stream should be in "binary" 112 /// mode. 113 /// 114 /// If \c ShouldPreserveUseListOrder, encode the use-list order for each \a 115 /// Value in \c M. These will be reconstructed exactly when \a M is 116 /// deserialized. 117 /// 118 /// If \c Index is supplied, the bitcode will contain the summary index 119 /// (currently for use in ThinLTO optimization). 120 /// 121 /// \p GenerateHash enables hashing the Module and including the hash in the 122 /// bitcode (currently for use in ThinLTO incremental build). 123 /// 124 /// If \p ModHash is non-null, when GenerateHash is true, the resulting 125 /// hash is written into ModHash. When GenerateHash is false, that value 126 /// is used as the hash instead of computing from the generated bitcode. 127 /// Can be used to produce the same module hash for a minimized bitcode 128 /// used just for the thin link as in the regular full bitcode that will 129 /// be used in the backend. 130 void WriteBitcodeToFile(const Module &M, raw_ostream &Out, 131 bool ShouldPreserveUseListOrder = false, 132 const ModuleSummaryIndex *Index = nullptr, 133 bool GenerateHash = false, 134 ModuleHash *ModHash = nullptr); 135 136 /// Write the specified thin link bitcode file (i.e., the minimized bitcode 137 /// file) to the given raw output stream, where it will be written in a new 138 /// bitcode block. The thin link bitcode file is used for thin link, and it 139 /// only contains the necessary information for thin link. 140 /// 141 /// ModHash is for use in ThinLTO incremental build, generated while the IR 142 /// bitcode file writing. 143 void writeThinLinkBitcodeToFile(const Module &M, raw_ostream &Out, 144 const ModuleSummaryIndex &Index, 145 const ModuleHash &ModHash); 146 147 /// Write the specified module summary index to the given raw output stream, 148 /// where it will be written in a new bitcode block. This is used when 149 /// writing the combined index file for ThinLTO. When writing a subset of the 150 /// index for a distributed backend, provide the \p ModuleToSummariesForIndex 151 /// map. \p DecSummaries specifies the set of summaries for which the 152 /// corresponding value should be imported as a declaration (prototype). 153 void writeIndexToFile(const ModuleSummaryIndex &Index, raw_ostream &Out, 154 const std::map<std::string, GVSummaryMapTy> 155 *ModuleToSummariesForIndex = nullptr, 156 const GVSummaryPtrSet *DecSummaries = nullptr); 157 158 /// If EmbedBitcode is set, save a copy of the llvm IR as data in the 159 /// __LLVM,__bitcode section (.llvmbc on non-MacOS). 160 /// If available, pass the serialized module via the Buf parameter. If not, 161 /// pass an empty (default-initialized) MemoryBufferRef, and the serialization 162 /// will be handled by this API. The same behavior happens if the provided Buf 163 /// is not bitcode (i.e. if it's invalid data or even textual LLVM assembly). 164 /// If EmbedCmdline is set, the command line is also exported in 165 /// the corresponding section (__LLVM,_cmdline / .llvmcmd) - even if CmdArgs 166 /// were empty. 167 void embedBitcodeInModule(Module &M, MemoryBufferRef Buf, bool EmbedBitcode, 168 bool EmbedCmdline, 169 const std::vector<uint8_t> &CmdArgs); 170 171 } // end namespace llvm 172 173 #endif // LLVM_BITCODE_BITCODEWRITER_H 174