include/llvm/Support/MemoryObject.h

   1 //===- MemoryObject.h - Abstract memory interface ---------------*- 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_SUPPORT_MEMORYOBJECT_H
  11 #define LLVM_SUPPORT_MEMORYOBJECT_H
  12
  13 #include "llvm/Support/DataTypes.h"
  14
  15 namespace llvm {
  16
  17 /// Interface to data which might be streamed. Streamability has 2 important
  18 /// implications/restrictions. First, the data might not yet exist in memory
  19 /// when the request is made. This just means that readByte/readBytes might have
  20 /// to block or do some work to get it. More significantly, the exact size of
  21 /// the object might not be known until it has all been fetched. This means that
  22 /// to return the right result, getExtent must also wait for all the data to
  23 /// arrive; therefore it should not be called on objects which are actually
  24 /// streamed (this would defeat the purpose of streaming). Instead,
  25 /// isValidAddress can be used to test addresses without knowing the exact size
  26 /// of the stream. Finally, getPointer can be used instead of readBytes to avoid
  27 /// extra copying.
  28 class MemoryObject {
  29 public:
  30   virtual ~MemoryObject();
  31
  32   /// Returns the size of the region in bytes.  (The region is contiguous, so
  33   /// the highest valid address of the region is getExtent() - 1).
  34   ///
  35   /// @result         - The size of the region.
  36   virtual uint64_t getExtent() const = 0;
  37
  38   /// Tries to read a contiguous range of bytes from the region, up to the end
  39   /// of the region.
  40   ///
  41   /// @param Buf      - A pointer to a buffer to be filled in.  Must be non-NULL
  42   ///                   and large enough to hold size bytes.
  43   /// @param Size     - The number of bytes to copy.
  44   /// @param Address  - The address of the first byte, in the same space as
  45   ///                   getBase().
  46   /// @result         - The number of bytes read.
  47   virtual uint64_t readBytes(uint8_t *Buf, uint64_t Size,
  48                              uint64_t Address) const = 0;
  49
  50   /// Ensures that the requested data is in memory, and returns a pointer to it.
  51   /// More efficient than using readBytes if the data is already in memory. May
  52   /// block until (address - base + size) bytes have been read
  53   /// @param address - address of the byte, in the same space as getBase()
  54   /// @param size    - amount of data that must be available on return
  55   /// @result        - valid pointer to the requested data
  56   virtual const uint8_t *getPointer(uint64_t address, uint64_t size) const = 0;
  57
  58   /// Returns true if the address is within the object (i.e. between base and
  59   /// base + extent - 1 inclusive). May block until (address - base) bytes have
  60   /// been read
  61   /// @param address - address of the byte, in the same space as getBase()
  62   /// @result        - true if the address may be read with readByte()
  63   virtual bool isValidAddress(uint64_t address) const = 0;
  64 };
  65
  66 }
  67
  68 #endif