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