LLVM  14.0.0git
MSFBuilder.h
Go to the documentation of this file.
1 //===- MSFBuilder.h - MSF Directory & Metadata Builder ----------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
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
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.
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.
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.
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.
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.
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.
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().
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.
114
115  /// Write the MSF layout to the underlying file.
117
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
130
131  bool IsGrowable;
132  uint32_t FreePageMap;
133  uint32_t Unknown1 = 0;
134  uint32_t BlockSize;
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
llvm::Check::Size
@ Size
Definition: FileCheck.h:73
llvm
---------------------— PointerInfo ------------------------------------—
Definition: AllocatorList.h:23
llvm::msf::MSFBuilder::generateLayout
Expected< MSFLayout > generateLayout()
Finalize the layout and build the headers and structures that describe the MSF layout and can be writ...
Definition: MSFBuilder.cpp:250
llvm::msf::MSFBuilder::create
static Expected< MSFBuilder > create(BumpPtrAllocator &Allocator, uint32_t BlockSize, uint32_t MinBlockCount=0, bool CanGrow=true)
Create a new MSFBuilder.
Definition: MSFBuilder.cpp:50
Request the block map to be at a specific block address.
Definition: MSFBuilder.cpp:62
Allocator.h
Error.h
Expected< uint32_t > addStream(uint32_t Size, ArrayRef< uint32_t > Blocks)
Add a stream to the MSF file with the given size, occupying the given list of blocks.
Definition: MSFBuilder.cpp:155
llvm::Expected
Tagged union holding either a T or a Error.
Definition: APFloat.h:42
llvm::msf::MSFBuilder
Definition: MSFBuilder.h:26
llvm::MutableArrayRef
MutableArrayRef - Represent a mutable reference to an array (0 or more elements consecutively in memo...
Definition: ArrayRef.h:307
llvm::msf::MSFLayout
Definition: MSFCommon.h:51
llvm::msf::MSFBuilder::commit
Expected< FileBufferByteStream > commit(StringRef Path, MSFLayout &Layout)
Write the MSF layout to the underlying file.
Definition: MSFBuilder.cpp:337
llvm::msf::MSFBuilder::isBlockFree
bool isBlockFree(uint32_t Idx) const
Check whether a particular block is allocated or free.
Definition: MSFBuilder.cpp:153
BitVector.h
llvm::msf::MSFBuilder::getNumFreeBlocks
uint32_t getNumFreeBlocks() const
Get the total number of blocks that exist in the MSF file but are not allocated to any valid data.
Definition: MSFBuilder.cpp:149
llvm::BitVector
Definition: BitVector.h:74
llvm::msf::MSFBuilder::setDirectoryBlocksHint
Error setDirectoryBlocksHint(ArrayRef< uint32_t > DirBlocks)
Definition: MSFBuilder.cpp:87
llvm::msf::MSFBuilder::getStreamSize
uint32_t getStreamSize(uint32_t StreamIdx) const
Get the size of a stream by index.
Definition: MSFBuilder.cpp:226
llvm::msf::MSFBuilder::getStreamBlocks
ArrayRef< uint32_t > getStreamBlocks(uint32_t StreamIdx) const
Get the list of blocks allocated to a particular stream.
Definition: MSFBuilder.cpp:230
llvm::msf::MSFBuilder::getNumUsedBlocks
uint32_t getNumUsedBlocks() const
Get the total number of blocks that will be allocated to actual data in this MSF file.
Definition: MSFBuilder.cpp:145
Definition: ELFObjHandler.cpp:80
llvm::msf::MSFBuilder::setUnknown1
void setUnknown1(uint32_t Unk1)
Definition: MSFBuilder.cpp:85
llvm::BumpPtrAllocatorImpl
Allocate memory in an ever growing pool, as if by bump-pointer.
Definition: Allocator.h:67
ArrayRef.h
llvm::msf::MSFBuilder::getTotalBlockCount
uint32_t getTotalBlockCount() const
Get the total number of blocks in the MSF file.
Definition: MSFBuilder.cpp:151
llvm::msf::MSFBuilder::setStreamSize
Error setStreamSize(uint32_t Idx, uint32_t Size)
Update the size of an existing stream.
Definition: MSFBuilder.cpp:192
llvm::ArrayRef< uint32_t >
llvm::StringRef
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:58
uint32_t
MSFCommon.h
llvm::msf::MSFBuilder::getAllocator
BumpPtrAllocator & getAllocator()
Definition: MSFBuilder.h:118
llvm::msf::MSFBuilder::getNumStreams
uint32_t getNumStreams() const
Get the total number of streams in the MSF layout.
Definition: MSFBuilder.cpp:224
llvm::Error
Lightweight error class with error context and mandatory checking.
Definition: Error.h:157
llvm::msf::MSFBuilder::setFreePageMap
void setFreePageMap(uint32_t Fpm)
Definition: MSFBuilder.cpp:83
Allocator
Basic Register Allocator
Definition: RegAllocBasic.cpp:146