contrib/llvm/tools/lldb/include/lldb/Core/DataBufferMemoryMap.h

   1 //===-- DataBufferMemoryMap.h -----------------------------------*- 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 liblldb_DataBufferMemoryMap_h_
  11 #define liblldb_DataBufferMemoryMap_h_
  12 #if defined(__cplusplus)
  13
  14
  15 #include "lldb/lldb-private.h"
  16 #include "lldb/Core/DataBuffer.h"
  17 #include "lldb/Core/Error.h"
  18 #include <string>
  19
  20 namespace lldb_private {
  21
  22 //----------------------------------------------------------------------
  23 /// @class DataBufferMemoryMap DataBufferMemoryMap.h "lldb/Core/DataBufferMemoryMap.h"
  24 /// @brief A subclass of DataBuffer that memory maps data.
  25 ///
  26 /// This class memory maps data and stores any needed data for the
  27 /// memory mapping in its internal state. Memory map requests are not
  28 /// required to have any alignment or size constraints, this class will
  29 /// work around any host OS issues regarding such things.
  30 ///
  31 /// This class is designed to allow pages to be faulted in as needed and
  32 /// works well data from large files that won't be accessed all at once.
  33 //----------------------------------------------------------------------
  34 class DataBufferMemoryMap : public DataBuffer
  35 {
  36 public:
  37     //------------------------------------------------------------------
  38     /// Default Constructor
  39     //------------------------------------------------------------------
  40     DataBufferMemoryMap ();
  41
  42     //------------------------------------------------------------------
  43     /// Destructor.
  44     ///
  45     /// Virtual destructor since this class inherits from a pure virtual
  46     /// base class #DataBuffer.
  47     //------------------------------------------------------------------
  48     virtual
  49     ~DataBufferMemoryMap ();
  50
  51     //------------------------------------------------------------------
  52     /// Reverts this object to an empty state by unmapping any memory
  53     /// that is currently owned.
  54     //------------------------------------------------------------------
  55     void
  56     Clear ();
  57
  58     //------------------------------------------------------------------
  59     /// @copydoc DataBuffer::GetBytes()
  60     //------------------------------------------------------------------
  61     virtual uint8_t *
  62     GetBytes ();
  63
  64     //------------------------------------------------------------------
  65     /// @copydoc DataBuffer::GetBytes() const
  66     //------------------------------------------------------------------
  67     virtual const uint8_t *
  68     GetBytes () const;
  69
  70     //------------------------------------------------------------------
  71     /// @copydoc DataBuffer::GetByteSize() const
  72     //------------------------------------------------------------------
  73     virtual lldb::offset_t
  74     GetByteSize () const;
  75
  76     //------------------------------------------------------------------
  77     /// Error get accessor.
  78     ///
  79     /// @return
  80     ///     A const reference to Error object in case memory mapping
  81     ///     fails.
  82     //------------------------------------------------------------------
  83     const Error &
  84     GetError() const;
  85
  86     //------------------------------------------------------------------
  87     /// Memory map all or part of a file.
  88     ///
  89     /// Memory map \a length bytes from \a file starting \a offset
  90     /// bytes into the file. If \a length is set to \c SIZE_MAX,
  91     /// then map as many bytes as possible.
  92     ///
  93     /// @param[in] file
  94     ///     The file specification from which to map data.
  95     ///
  96     /// @param[in] offset
  97     ///     The offset in bytes from the beginning of the file where
  98     ///     memory mapping should begin.
  99     ///
 100     /// @param[in] length
 101     ///     The size in bytes that should be mapped starting \a offset
 102     ///     bytes into the file. If \a length is \c SIZE_MAX, map
 103     ///     as many bytes as possible.  Even though it may be possible
 104     ///     for a 32-bit host debugger to debug a 64-bit target, size_t
 105     ///     still dictates the maximum possible size that can be mapped
 106     ///     into this process.  For this kind of cross-arch debugging
 107     ///     scenario, mappings and views should be managed at a higher
 108     ///     level.
 109     ///
 110     /// @return
 111     ///     The number of bytes mapped starting from the \a offset.
 112     //------------------------------------------------------------------
 113     size_t
 114     MemoryMapFromFileSpec (const FileSpec* file,
 115                            lldb::offset_t offset = 0,
 116                            size_t length = SIZE_MAX,
 117                            bool writeable = false);
 118
 119     //------------------------------------------------------------------
 120     /// Memory map all or part of a file.
 121     ///
 122     /// Memory map \a length bytes from an opened file descriptor \a fd
 123     /// starting \a offset bytes into the file. If \a length is set to
 124     /// \c SIZE_MAX, then map as many bytes as possible.
 125     ///
 126     /// @param[in] fd
 127     ///     The posix file descriptor for an already opened file
 128     ///     from which to map data.
 129     ///
 130     /// @param[in] offset
 131     ///     The offset in bytes from the beginning of the file where
 132     ///     memory mapping should begin.
 133     ///
 134     /// @param[in] length
 135     ///     The size in bytes that should be mapped starting \a offset
 136     ///     bytes into the file. If \a length is \c SIZE_MAX, map
 137     ///     as many bytes as possible.
 138     ///
 139     /// @return
 140     ///     The number of bytes mapped starting from the \a offset.
 141     //------------------------------------------------------------------
 142     size_t
 143     MemoryMapFromFileDescriptor (int fd,
 144                                  lldb::offset_t offset,
 145                                  size_t length,
 146                                  bool write,
 147                                  bool fd_is_file);
 148
 149 protected:
 150     //------------------------------------------------------------------
 151     // Classes that inherit from DataBufferMemoryMap can see and modify these
 152     //------------------------------------------------------------------
 153     uint8_t * m_mmap_addr;  ///< The actual pointer that was returned from \c mmap()
 154     size_t m_mmap_size;     ///< The actual number of bytes that were mapped when \c mmap() was called
 155     uint8_t *m_data;        ///< The data the user requested somewhere within the memory mapped data.
 156     lldb::offset_t m_size;  ///< The size of the data the user got when data was requested
 157
 158 private:
 159     DISALLOW_COPY_AND_ASSIGN (DataBufferMemoryMap);
 160 };
 161
 162 } // namespace lldb_private
 163
 164 #endif  // #if defined(__cplusplus)
 165 #endif  // liblldb_DataBufferMemoryMap_h_