Subversion Repositories QNX 8.QNX8 LLVM/Clang compiler suite

//===- MSFBuilder.h - MSF Directory & Metadata Builder ----------*- C++ -*-===//

//

// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.

// See https://llvm.org/LICENSE.txt for license information.

// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

//

//===----------------------------------------------------------------------===//

#ifndef LLVM_DEBUGINFO_MSF_MSFBUILDER_H

#define LLVM_DEBUGINFO_MSF_MSFBUILDER_H

#include "llvm/ADT/ArrayRef.h"

#include "llvm/ADT/BitVector.h"

#include "llvm/ADT/StringRef.h"

#include "llvm/Support/Allocator.h"

#include "llvm/Support/Error.h"

#include <cstdint>

#include <utility>

#include <vector>

namespace llvm {

class FileBufferByteStream;

namespace msf {

struct MSFLayout;

class MSFBuilder {

public:

  /// Create a new `MSFBuilder`.

  ///

  /// \param BlockSize The internal block size used by the PDB file.  See

  /// isValidBlockSize() for a list of valid block sizes.

  ///

  /// \param MinBlockCount Causes the builder to reserve up front space for

  /// at least `MinBlockCount` blocks.  This is useful when using `MSFBuilder`

  /// to read an existing MSF that you want to write back out later.  The

  /// original MSF file's SuperBlock contains the exact number of blocks used

  /// by the file, so is a good hint as to how many blocks the new MSF file

  /// will contain.  Furthermore, it is actually necessary in this case.  To

  /// preserve stability of the file's layout, it is helpful to try to keep

  /// all streams mapped to their original block numbers.  To ensure that this

  /// is possible, space for all blocks must be allocated beforehand so that

  /// streams can be assigned to them.

  ///

  /// \param CanGrow If true, any operation which results in an attempt to

  /// locate a free block when all available blocks have been exhausted will

  /// allocate a new block, thereby growing the size of the final MSF file.

  /// When false, any such attempt will result in an error.  This is especially

  /// useful in testing scenarios when you know your test isn't going to do

  /// anything to increase the size of the file, so having an Error returned if

  /// it were to happen would catch a programming error

  ///

  /// \returns an llvm::Error representing whether the operation succeeded or

  /// failed.  Currently the only way this can fail is if an invalid block size

  /// is specified, or `MinBlockCount` does not leave enough room for the

  /// mandatory reserved blocks required by an MSF file.

  static Expected<MSFBuilder> create(BumpPtrAllocator &Allocator,

                                     uint32_t BlockSize,

                                     uint32_t MinBlockCount = 0,

                                     bool CanGrow = true);

  /// Request the block map to be at a specific block address.  This is useful

  /// when editing a MSF and you want the layout to be as stable as possible.

  Error setBlockMapAddr(uint32_t Addr);

  Error setDirectoryBlocksHint(ArrayRef<uint32_t> DirBlocks);

  void setFreePageMap(uint32_t Fpm);

  void setUnknown1(uint32_t Unk1);

  /// Add a stream to the MSF file with the given size, occupying the given

  /// list of blocks.  This is useful when reading a MSF file and you want a

  /// particular stream to occupy the original set of blocks.  If the given

  /// blocks are already allocated, or if the number of blocks specified is

  /// incorrect for the given stream size, this function will return an Error.

  Expected<uint32_t> addStream(uint32_t Size, ArrayRef<uint32_t> Blocks);

  /// Add a stream to the MSF file with the given size, occupying any available

  /// blocks that the builder decides to use.  This is useful when building a

  /// new PDB file from scratch and you don't care what blocks a stream occupies

  /// but you just want it to work.

  Expected<uint32_t> addStream(uint32_t Size);

  /// Update the size of an existing stream.  This will allocate or deallocate

  /// blocks as needed to match the requested size.  This can fail if `CanGrow`

  /// was set to false when initializing the `MSFBuilder`.

  Error setStreamSize(uint32_t Idx, uint32_t Size);

  /// Get the total number of streams in the MSF layout.  This should return 1

  /// for every call to `addStream`.

  uint32_t getNumStreams() const;

  /// Get the size of a stream by index.

  uint32_t getStreamSize(uint32_t StreamIdx) const;

  /// Get the list of blocks allocated to a particular stream.

  ArrayRef<uint32_t> getStreamBlocks(uint32_t StreamIdx) const;

  /// Get the total number of blocks that will be allocated to actual data in

  /// this MSF file.

  uint32_t getNumUsedBlocks() const;

  /// Get the total number of blocks that exist in the MSF file but are not

  /// allocated to any valid data.

  uint32_t getNumFreeBlocks() const;

  /// Get the total number of blocks in the MSF file.  In practice this is equal

  /// to `getNumUsedBlocks() + getNumFreeBlocks()`.

  uint32_t getTotalBlockCount() const;

  /// Check whether a particular block is allocated or free.

  bool isBlockFree(uint32_t Idx) const;

  /// Finalize the layout and build the headers and structures that describe the

  /// MSF layout and can be written directly to the MSF file.

  Expected<MSFLayout> generateLayout();

  /// Write the MSF layout to the underlying file.

  Expected<FileBufferByteStream> commit(StringRef Path, MSFLayout &Layout);

  BumpPtrAllocator &getAllocator() { return Allocator; }

private:

  MSFBuilder(uint32_t BlockSize, uint32_t MinBlockCount, bool CanGrow,

             BumpPtrAllocator &Allocator);

  Error allocateBlocks(uint32_t NumBlocks, MutableArrayRef<uint32_t> Blocks);

  uint32_t computeDirectoryByteSize() const;

  using BlockList = std::vector<uint32_t>;

  BumpPtrAllocator &Allocator;

  bool IsGrowable;

  uint32_t FreePageMap;

  uint32_t Unknown1 = 0;

  uint32_t BlockSize;

  uint32_t BlockMapAddr;

  BitVector FreeBlocks;

  std::vector<uint32_t> DirectoryBlocks;

  std::vector<std::pair<uint32_t, BlockList>> StreamData;

};

} // end namespace msf

} // end namespace llvm

#endif // LLVM_DEBUGINFO_MSF_MSFBUILDER_H