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 <map> 21 #include <memory> 22 #include <string> 23 #include <vector> 24 25 namespace llvm { 26 27 class BitstreamWriter; 28 class Module; 29 class raw_ostream; 30 31 class BitcodeWriter { 32 SmallVectorImpl<char> &Buffer; 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 51 ~BitcodeWriter(); 52 53 /// Attempt to write a symbol table to the bitcode file. This must be called 54 /// at most once after all modules have been written. 55 /// 56 /// A reader does not require a symbol table to interpret a bitcode file; 57 /// the symbol table is needed only to improve link-time performance. So 58 /// this function may decide not to write a symbol table. It may so decide 59 /// if, for example, the target is unregistered or the IR is malformed. 60 void writeSymtab(); 61 62 /// Write the bitcode file's string table. This must be called exactly once 63 /// after all modules and the optional symbol table have been written. 64 void writeStrtab(); 65 66 /// Copy the string table for another module into this bitcode file. This 67 /// should be called after copying the module itself into the bitcode file. 68 void copyStrtab(StringRef Strtab); 69 70 /// Write the specified module to the buffer specified at construction time. 71 /// 72 /// If \c ShouldPreserveUseListOrder, encode the use-list order for each \a 73 /// Value in \c M. These will be reconstructed exactly when \a M is 74 /// deserialized. 75 /// 76 /// If \c Index is supplied, the bitcode will contain the summary index 77 /// (currently for use in ThinLTO optimization). 78 /// 79 /// \p GenerateHash enables hashing the Module and including the hash in the 80 /// bitcode (currently for use in ThinLTO incremental build). 81 /// 82 /// If \p ModHash is non-null, when GenerateHash is true, the resulting 83 /// hash is written into ModHash. When GenerateHash is false, that value 84 /// is used as the hash instead of computing from the generated bitcode. 85 /// Can be used to produce the same module hash for a minimized bitcode 86 /// used just for the thin link as in the regular full bitcode that will 87 /// be used in the backend. 88 void writeModule(const Module &M, bool ShouldPreserveUseListOrder = false, 89 const ModuleSummaryIndex *Index = nullptr, 90 bool GenerateHash = false, ModuleHash *ModHash = nullptr); 91 92 /// Write the specified thin link bitcode file (i.e., the minimized bitcode 93 /// file) to the buffer specified at construction time. The thin link 94 /// bitcode file is used for thin link, and it only contains the necessary 95 /// information for thin link. 96 /// 97 /// ModHash is for use in ThinLTO incremental build, generated while the 98 /// IR bitcode file writing. 99 void writeThinLinkBitcode(const Module &M, const ModuleSummaryIndex &Index, 100 const ModuleHash &ModHash); 101 102 void writeIndex( 103 const ModuleSummaryIndex *Index, 104 const std::map<std::string, GVSummaryMapTy> *ModuleToSummariesForIndex); 105 }; 106 107 /// Write the specified module to the specified raw output stream. 108 /// 109 /// For streams where it matters, the given stream should be in "binary" 110 /// mode. 111 /// 112 /// If \c ShouldPreserveUseListOrder, encode the use-list order for each \a 113 /// Value in \c M. These will be reconstructed exactly when \a M is 114 /// deserialized. 115 /// 116 /// If \c Index is supplied, the bitcode will contain the summary index 117 /// (currently for use in ThinLTO optimization). 118 /// 119 /// \p GenerateHash enables hashing the Module and including the hash in the 120 /// bitcode (currently for use in ThinLTO incremental build). 121 /// 122 /// If \p ModHash is non-null, when GenerateHash is true, the resulting 123 /// hash is written into ModHash. When GenerateHash is false, that value 124 /// is used as the hash instead of computing from the generated bitcode. 125 /// Can be used to produce the same module hash for a minimized bitcode 126 /// used just for the thin link as in the regular full bitcode that will 127 /// be used in the backend. 128 void WriteBitcodeToFile(const Module &M, raw_ostream &Out, 129 bool ShouldPreserveUseListOrder = false, 130 const ModuleSummaryIndex *Index = nullptr, 131 bool GenerateHash = false, 132 ModuleHash *ModHash = nullptr); 133 134 /// Write the specified thin link bitcode file (i.e., the minimized bitcode 135 /// file) to the given raw output stream, where it will be written in a new 136 /// bitcode block. The thin link bitcode file is used for thin link, and it 137 /// only contains the necessary information for thin link. 138 /// 139 /// ModHash is for use in ThinLTO incremental build, generated while the IR 140 /// bitcode file writing. 141 void WriteThinLinkBitcodeToFile(const Module &M, raw_ostream &Out, 142 const ModuleSummaryIndex &Index, 143 const ModuleHash &ModHash); 144 145 /// Write the specified module summary index to the given raw output stream, 146 /// where it will be written in a new bitcode block. This is used when 147 /// writing the combined index file for ThinLTO. When writing a subset of the 148 /// index for a distributed backend, provide the \p ModuleToSummariesForIndex 149 /// map. 150 void WriteIndexToFile(const ModuleSummaryIndex &Index, raw_ostream &Out, 151 const std::map<std::string, GVSummaryMapTy> 152 *ModuleToSummariesForIndex = nullptr); 153 154 } // end namespace llvm 155 156 #endif // LLVM_BITCODE_BITCODEWRITER_H 157