LCOV - code coverage report
Current view: top level - include/llvm/DebugInfo/MSF - MSFBuilder.h (source / functions) Hit Total Coverage
Test: llvm-toolchain.info Lines: 0 1 0.0 %
Date: 2018-10-20 13:21:21 Functions: 0 1 0.0 %
Legend: Lines: hit not hit

          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

Generated by: LCOV version 1.13