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

Generated by: LCOV version 1.13