1//===- llvm/Bitcode/BitcodeWriter.h - Bitcode writers -----------*- C++ -*-===//
2//
3// The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9//
10// This header defines interfaces to write LLVM bitcode files/streams.
11//
12//===----------------------------------------------------------------------===//
13
14#ifndef LLVM_BITCODE_BITCODEWRITER_H
15#define LLVM_BITCODE_BITCODEWRITER_H
16
17#include "llvm/ADT/StringRef.h"
18#include "llvm/IR/ModuleSummaryIndex.h"
19#include "llvm/MC/StringTableBuilder.h"
20#include "llvm/Support/Allocator.h"
21#include <map>
22#include <memory>
23#include <string>
24#include <vector>
25
26namespace llvm {
27
28class BitstreamWriter;
29class Module;
30class 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} // end namespace llvm
156
157#endif // LLVM_BITCODE_BITCODEWRITER_H
158