Line data Source code
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 : #include "llvm/DebugInfo/MSF/MSFCommon.h"
16 : #include "llvm/Support/Allocator.h"
17 : #include "llvm/Support/Error.h"
18 : #include <cstdint>
19 : #include <utility>
20 : #include <vector>
21 :
22 : namespace llvm {
23 : class FileBufferByteStream;
24 : class WritableBinaryStream;
25 : namespace msf {
26 :
27 : class MSFBuilder {
28 : public:
29 : /// 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> generateLayout();
115 :
116 : /// Write the MSF layout to the underlying file.
117 : Expected<FileBufferByteStream> commit(StringRef Path, MSFLayout &Layout);
118 :
119 0 : BumpPtrAllocator &getAllocator() { return Allocator; }
120 :
121 : private:
122 : MSFBuilder(uint32_t BlockSize, uint32_t MinBlockCount, bool CanGrow,
123 : BumpPtrAllocator &Allocator);
124 :
125 : Error allocateBlocks(uint32_t NumBlocks, MutableArrayRef<uint32_t> Blocks);
126 : uint32_t computeDirectoryByteSize() const;
127 :
128 : using BlockList = std::vector<uint32_t>;
129 :
130 : BumpPtrAllocator &Allocator;
131 :
132 : bool IsGrowable;
133 : uint32_t FreePageMap;
134 : uint32_t Unknown1 = 0;
135 : uint32_t BlockSize;
136 : uint32_t BlockMapAddr;
137 : BitVector FreeBlocks;
138 : std::vector<uint32_t> DirectoryBlocks;
139 : std::vector<std::pair<uint32_t, BlockList>> StreamData;
140 : };
141 :
142 : } // end namespace msf
143 : } // end namespace llvm
144 :
145 : #endif // LLVM_DEBUGINFO_MSF_MSFBUILDER_H
|
