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