• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 
getAllocator()119   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
146