include/llvm/Bitcode/BitcodeWriter.h

   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