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/MemoryBuffer.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); 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 /// Save a copy of the llvm IR as data in the __LLVM,__bitcode section. 156 void EmbedBitcodeInModule(Module &M, MemoryBufferRef Buf, bool EmbedBitcode, 157 bool EmbedMarker, 158 const std::vector<uint8_t> *CmdArgs); 159 160 } // end namespace llvm 161 162 #endif // LLVM_BITCODE_BITCODEWRITER_H 163