BitcodeWriter.h revision 360784 
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
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  /// 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