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