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(const ModuleSummaryIndex *Index, 104 const ModuleToSummariesForIndexTy *ModuleToSummariesForIndex, 105 const GVSummaryPtrSet *DecSummaries); 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. \p DecSummaries specifies the set of summaries for which the 151 /// corresponding value should be imported as a declaration (prototype). 152 void writeIndexToFile( 153 const ModuleSummaryIndex &Index, raw_ostream &Out, 154 const ModuleToSummariesForIndexTy *ModuleToSummariesForIndex = nullptr, 155 const GVSummaryPtrSet *DecSummaries = nullptr); 156 157 /// If EmbedBitcode is set, save a copy of the llvm IR as data in the 158 /// __LLVM,__bitcode section (.llvmbc on non-MacOS). 159 /// If available, pass the serialized module via the Buf parameter. If not, 160 /// pass an empty (default-initialized) MemoryBufferRef, and the serialization 161 /// will be handled by this API. The same behavior happens if the provided Buf 162 /// is not bitcode (i.e. if it's invalid data or even textual LLVM assembly). 163 /// If EmbedCmdline is set, the command line is also exported in 164 /// the corresponding section (__LLVM,_cmdline / .llvmcmd) - even if CmdArgs 165 /// were empty. 166 void embedBitcodeInModule(Module &M, MemoryBufferRef Buf, bool EmbedBitcode, 167 bool EmbedCmdline, 168 const std::vector<uint8_t> &CmdArgs); 169 170 } // end namespace llvm 171 172 #endif // LLVM_BITCODE_BITCODEWRITER_H 173