include/llvm/DebugInfo/MSF/MSFBuilder.h

   1 //===- MSFBuilder.h - MSF Directory & Metadata Builder ----------*- 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 #ifndef LLVM_DEBUGINFO_MSF_MSFBUILDER_H
  10 #define LLVM_DEBUGINFO_MSF_MSFBUILDER_H
  11
  12 #include "llvm/ADT/ArrayRef.h"
  13 #include "llvm/ADT/BitVector.h"
  14 #include "llvm/DebugInfo/MSF/MSFCommon.h"
  15 #include "llvm/Support/Allocator.h"
  16 #include "llvm/Support/Error.h"
  17 #include <cstdint>
  18 #include <utility>
  19 #include <vector>
  20
  21 namespace llvm {
  22 class FileBufferByteStream;
  23 class WritableBinaryStream;
  24 namespace msf {
  25
  26 class MSFBuilder {
  27 public:
  28   /// Create a new `MSFBuilder`.
  29   ///
  30   /// \param BlockSize The internal block size used by the PDB file.  See
  31   /// isValidBlockSize() for a list of valid block sizes.
  32   ///
  33   /// \param MinBlockCount Causes the builder to reserve up front space for
  34   /// at least `MinBlockCount` blocks.  This is useful when using `MSFBuilder`
  35   /// to read an existing MSF that you want to write back out later.  The
  36   /// original MSF file's SuperBlock contains the exact number of blocks used
  37   /// by the file, so is a good hint as to how many blocks the new MSF file
  38   /// will contain.  Furthermore, it is actually necessary in this case.  To
  39   /// preserve stability of the file's layout, it is helpful to try to keep
  40   /// all streams mapped to their original block numbers.  To ensure that this
  41   /// is possible, space for all blocks must be allocated beforehand so that
  42   /// streams can be assigned to them.
  43   ///
  44   /// \param CanGrow If true, any operation which results in an attempt to
  45   /// locate a free block when all available blocks have been exhausted will
  46   /// allocate a new block, thereby growing the size of the final MSF file.
  47   /// When false, any such attempt will result in an error.  This is especially
  48   /// useful in testing scenarios when you know your test isn't going to do
  49   /// anything to increase the size of the file, so having an Error returned if
  50   /// it were to happen would catch a programming error
  51   ///
  52   /// \returns an llvm::Error representing whether the operation succeeded or
  53   /// failed.  Currently the only way this can fail is if an invalid block size
  54   /// is specified, or `MinBlockCount` does not leave enough room for the
  55   /// mandatory reserved blocks required by an MSF file.
  56   static Expected<MSFBuilder> create(BumpPtrAllocator &Allocator,
  57                                      uint32_t BlockSize,
  58                                      uint32_t MinBlockCount = 0,
  59                                      bool CanGrow = true);
  60
  61   /// Request the block map to be at a specific block address.  This is useful
  62   /// when editing a MSF and you want the layout to be as stable as possible.
  63   Error setBlockMapAddr(uint32_t Addr);
  64   Error setDirectoryBlocksHint(ArrayRef<uint32_t> DirBlocks);
  65   void setFreePageMap(uint32_t Fpm);
  66   void setUnknown1(uint32_t Unk1);
  67
  68   /// Add a stream to the MSF file with the given size, occupying the given
  69   /// list of blocks.  This is useful when reading a MSF file and you want a
  70   /// particular stream to occupy the original set of blocks.  If the given
  71   /// blocks are already allocated, or if the number of blocks specified is
  72   /// incorrect for the given stream size, this function will return an Error.
  73   Expected<uint32_t> addStream(uint32_t Size, ArrayRef<uint32_t> Blocks);
  74
  75   /// Add a stream to the MSF file with the given size, occupying any available
  76   /// blocks that the builder decides to use.  This is useful when building a
  77   /// new PDB file from scratch and you don't care what blocks a stream occupies
  78   /// but you just want it to work.
  79   Expected<uint32_t> addStream(uint32_t Size);
  80
  81   /// Update the size of an existing stream.  This will allocate or deallocate
  82   /// blocks as needed to match the requested size.  This can fail if `CanGrow`
  83   /// was set to false when initializing the `MSFBuilder`.
  84   Error setStreamSize(uint32_t Idx, uint32_t Size);
  85
  86   /// Get the total number of streams in the MSF layout.  This should return 1
  87   /// for every call to `addStream`.
  88   uint32_t getNumStreams() const;
  89
  90   /// Get the size of a stream by index.
  91   uint32_t getStreamSize(uint32_t StreamIdx) const;
  92
  93   /// Get the list of blocks allocated to a particular stream.
  94   ArrayRef<uint32_t> getStreamBlocks(uint32_t StreamIdx) const;
  95
  96   /// Get the total number of blocks that will be allocated to actual data in
  97   /// this MSF file.
  98   uint32_t getNumUsedBlocks() const;
  99
 100   /// Get the total number of blocks that exist in the MSF file but are not
 101   /// allocated to any valid data.
 102   uint32_t getNumFreeBlocks() const;
 103
 104   /// Get the total number of blocks in the MSF file.  In practice this is equal
 105   /// to `getNumUsedBlocks() + getNumFreeBlocks()`.
 106   uint32_t getTotalBlockCount() const;
 107
 108   /// Check whether a particular block is allocated or free.
 109   bool isBlockFree(uint32_t Idx) const;
 110
 111   /// Finalize the layout and build the headers and structures that describe the
 112   /// MSF layout and can be written directly to the MSF file.
 113   Expected<MSFLayout> generateLayout();
 114
 115   /// Write the MSF layout to the underlying file.
 116   Expected<FileBufferByteStream> commit(StringRef Path, MSFLayout &Layout);
 117
 118   BumpPtrAllocator &getAllocator() { return Allocator; }
 119
 120 private:
 121   MSFBuilder(uint32_t BlockSize, uint32_t MinBlockCount, bool CanGrow,
 122              BumpPtrAllocator &Allocator);
 123
 124   Error allocateBlocks(uint32_t NumBlocks, MutableArrayRef<uint32_t> Blocks);
 125   uint32_t computeDirectoryByteSize() const;
 126
 127   using BlockList = std::vector<uint32_t>;
 128
 129   BumpPtrAllocator &Allocator;
 130
 131   bool IsGrowable;
 132   uint32_t FreePageMap;
 133   uint32_t Unknown1 = 0;
 134   uint32_t BlockSize;
 135   uint32_t BlockMapAddr;
 136   BitVector FreeBlocks;
 137   std::vector<uint32_t> DirectoryBlocks;
 138   std::vector<std::pair<uint32_t, BlockList>> StreamData;
 139 };
 140
 141 } // end namespace msf
 142 } // end namespace llvm
 143
 144 #endif // LLVM_DEBUGINFO_MSF_MSFBUILDER_H