contrib/llvm/include/llvm/Support/DataExtractor.h

   1 //===-- DataExtractor.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 LLVM_SUPPORT_DATAEXTRACTOR_H
  11 #define LLVM_SUPPORT_DATAEXTRACTOR_H
  12
  13 #include "llvm/ADT/DenseMap.h"
  14 #include "llvm/ADT/StringRef.h"
  15 #include "llvm/Support/DataTypes.h"
  16
  17 namespace llvm {
  18 class DataExtractor {
  19   StringRef Data;
  20   uint8_t IsLittleEndian;
  21   uint8_t PointerSize;
  22 public:
  23   /// Construct with a buffer that is owned by the caller.
  24   ///
  25   /// This constructor allows us to use data that is owned by the
  26   /// caller. The data must stay around as long as this object is
  27   /// valid.
  28   DataExtractor(StringRef Data, bool IsLittleEndian, uint8_t PointerSize)
  29     : Data(Data), IsLittleEndian(IsLittleEndian), PointerSize(PointerSize) {}
  30
  31   /// getData - Get the data pointed to by this extractor.
  32   StringRef getData() const { return Data; }
  33   /// isLittleEndian - Get the endianess for this extractor.
  34   bool isLittleEndian() const { return IsLittleEndian; }
  35   /// getAddressSize - Get the address size for this extractor.
  36   uint8_t getAddressSize() const { return PointerSize; }
  37
  38   /// Extract a C string from \a *offset_ptr.
  39   ///
  40   /// Returns a pointer to a C String from the data at the offset
  41   /// pointed to by \a offset_ptr. A variable length NULL terminated C
  42   /// string will be extracted and the \a offset_ptr will be
  43   /// updated with the offset of the byte that follows the NULL
  44   /// terminator byte.
  45   ///
  46   /// @param[in,out] offset_ptr
  47   ///     A pointer to an offset within the data that will be advanced
  48   ///     by the appropriate number of bytes if the value is extracted
  49   ///     correctly. If the offset is out of bounds or there are not
  50   ///     enough bytes to extract this value, the offset will be left
  51   ///     unmodified.
  52   ///
  53   /// @return
  54   ///     A pointer to the C string value in the data. If the offset
  55   ///     pointed to by \a offset_ptr is out of bounds, or if the
  56   ///     offset plus the length of the C string is out of bounds,
  57   ///     NULL will be returned.
  58   const char *getCStr(uint32_t *offset_ptr) const;
  59
  60   /// Extract an unsigned integer of size \a byte_size from \a
  61   /// *offset_ptr.
  62   ///
  63   /// Extract a single unsigned integer value and update the offset
  64   /// pointed to by \a offset_ptr. The size of the extracted integer
  65   /// is specified by the \a byte_size argument. \a byte_size should
  66   /// have a value greater than or equal to one and less than or equal
  67   /// to eight since the return value is 64 bits wide. Any
  68   /// \a byte_size values less than 1 or greater than 8 will result in
  69   /// nothing being extracted, and zero being returned.
  70   ///
  71   /// @param[in,out] offset_ptr
  72   ///     A pointer to an offset within the data that will be advanced
  73   ///     by the appropriate number of bytes if the value is extracted
  74   ///     correctly. If the offset is out of bounds or there are not
  75   ///     enough bytes to extract this value, the offset will be left
  76   ///     unmodified.
  77   ///
  78   /// @param[in] byte_size
  79   ///     The size in byte of the integer to extract.
  80   ///
  81   /// @return
  82   ///     The unsigned integer value that was extracted, or zero on
  83   ///     failure.
  84   uint64_t getUnsigned(uint32_t *offset_ptr, uint32_t byte_size) const;
  85
  86   /// Extract an signed integer of size \a byte_size from \a *offset_ptr.
  87   ///
  88   /// Extract a single signed integer value (sign extending if required)
  89   /// and update the offset pointed to by \a offset_ptr. The size of
  90   /// the extracted integer is specified by the \a byte_size argument.
  91   /// \a byte_size should have a value greater than or equal to one
  92   /// and less than or equal to eight since the return value is 64
  93   /// bits wide. Any \a byte_size values less than 1 or greater than
  94   /// 8 will result in nothing being extracted, and zero being returned.
  95   ///
  96   /// @param[in,out] offset_ptr
  97   ///     A pointer to an offset within the data that will be advanced
  98   ///     by the appropriate number of bytes if the value is extracted
  99   ///     correctly. If the offset is out of bounds or there are not
 100   ///     enough bytes to extract this value, the offset will be left
 101   ///     unmodified.
 102   ///
 103   /// @param[in] size
 104   ///     The size in bytes of the integer to extract.
 105   ///
 106   /// @return
 107   ///     The sign extended signed integer value that was extracted,
 108   ///     or zero on failure.
 109   int64_t getSigned(uint32_t *offset_ptr, uint32_t size) const;
 110
 111   //------------------------------------------------------------------
 112   /// Extract an pointer from \a *offset_ptr.
 113   ///
 114   /// Extract a single pointer from the data and update the offset
 115   /// pointed to by \a offset_ptr. The size of the extracted pointer
 116   /// comes from the \a m_addr_size member variable and should be
 117   /// set correctly prior to extracting any pointer values.
 118   ///
 119   /// @param[in,out] offset_ptr
 120   ///     A pointer to an offset within the data that will be advanced
 121   ///     by the appropriate number of bytes if the value is extracted
 122   ///     correctly. If the offset is out of bounds or there are not
 123   ///     enough bytes to extract this value, the offset will be left
 124   ///     unmodified.
 125   ///
 126   /// @return
 127   ///     The extracted pointer value as a 64 integer.
 128   uint64_t getAddress(uint32_t *offset_ptr) const {
 129     return getUnsigned(offset_ptr, PointerSize);
 130   }
 131
 132   /// Extract a uint8_t value from \a *offset_ptr.
 133   ///
 134   /// Extract a single uint8_t from the binary data at the offset
 135   /// pointed to by \a offset_ptr, and advance the offset on success.
 136   ///
 137   /// @param[in,out] offset_ptr
 138   ///     A pointer to an offset within the data that will be advanced
 139   ///     by the appropriate number of bytes if the value is extracted
 140   ///     correctly. If the offset is out of bounds or there are not
 141   ///     enough bytes to extract this value, the offset will be left
 142   ///     unmodified.
 143   ///
 144   /// @return
 145   ///     The extracted uint8_t value.
 146   uint8_t getU8(uint32_t *offset_ptr) const;
 147
 148   /// Extract \a count uint8_t values from \a *offset_ptr.
 149   ///
 150   /// Extract \a count uint8_t values from the binary data at the
 151   /// offset pointed to by \a offset_ptr, and advance the offset on
 152   /// success. The extracted values are copied into \a dst.
 153   ///
 154   /// @param[in,out] offset_ptr
 155   ///     A pointer to an offset within the data that will be advanced
 156   ///     by the appropriate number of bytes if the value is extracted
 157   ///     correctly. If the offset is out of bounds or there are not
 158   ///     enough bytes to extract this value, the offset will be left
 159   ///     unmodified.
 160   ///
 161   /// @param[out] dst
 162   ///     A buffer to copy \a count uint8_t values into. \a dst must
 163   ///     be large enough to hold all requested data.
 164   ///
 165   /// @param[in] count
 166   ///     The number of uint8_t values to extract.
 167   ///
 168   /// @return
 169   ///     \a dst if all values were properly extracted and copied,
 170   ///     NULL otherise.
 171   uint8_t *getU8(uint32_t *offset_ptr, uint8_t *dst, uint32_t count) const;
 172
 173   //------------------------------------------------------------------
 174   /// Extract a uint16_t value from \a *offset_ptr.
 175   ///
 176   /// Extract a single uint16_t from the binary data at the offset
 177   /// pointed to by \a offset_ptr, and update the offset on success.
 178   ///
 179   /// @param[in,out] offset_ptr
 180   ///     A pointer to an offset within the data that will be advanced
 181   ///     by the appropriate number of bytes if the value is extracted
 182   ///     correctly. If the offset is out of bounds or there are not
 183   ///     enough bytes to extract this value, the offset will be left
 184   ///     unmodified.
 185   ///
 186   /// @return
 187   ///     The extracted uint16_t value.
 188   //------------------------------------------------------------------
 189   uint16_t getU16(uint32_t *offset_ptr) const;
 190
 191   /// Extract \a count uint16_t values from \a *offset_ptr.
 192   ///
 193   /// Extract \a count uint16_t values from the binary data at the
 194   /// offset pointed to by \a offset_ptr, and advance the offset on
 195   /// success. The extracted values are copied into \a dst.
 196   ///
 197   /// @param[in,out] offset_ptr
 198   ///     A pointer to an offset within the data that will be advanced
 199   ///     by the appropriate number of bytes if the value is extracted
 200   ///     correctly. If the offset is out of bounds or there are not
 201   ///     enough bytes to extract this value, the offset will be left
 202   ///     unmodified.
 203   ///
 204   /// @param[out] dst
 205   ///     A buffer to copy \a count uint16_t values into. \a dst must
 206   ///     be large enough to hold all requested data.
 207   ///
 208   /// @param[in] count
 209   ///     The number of uint16_t values to extract.
 210   ///
 211   /// @return
 212   ///     \a dst if all values were properly extracted and copied,
 213   ///     NULL otherise.
 214   uint16_t *getU16(uint32_t *offset_ptr, uint16_t *dst, uint32_t count) const;
 215
 216   /// Extract a uint32_t value from \a *offset_ptr.
 217   ///
 218   /// Extract a single uint32_t from the binary data at the offset
 219   /// pointed to by \a offset_ptr, and update the offset on success.
 220   ///
 221   /// @param[in,out] offset_ptr
 222   ///     A pointer to an offset within the data that will be advanced
 223   ///     by the appropriate number of bytes if the value is extracted
 224   ///     correctly. If the offset is out of bounds or there are not
 225   ///     enough bytes to extract this value, the offset will be left
 226   ///     unmodified.
 227   ///
 228   /// @return
 229   ///     The extracted uint32_t value.
 230   uint32_t getU32(uint32_t *offset_ptr) const;
 231
 232   /// Extract \a count uint32_t values from \a *offset_ptr.
 233   ///
 234   /// Extract \a count uint32_t values from the binary data at the
 235   /// offset pointed to by \a offset_ptr, and advance the offset on
 236   /// success. The extracted values are copied into \a dst.
 237   ///
 238   /// @param[in,out] offset_ptr
 239   ///     A pointer to an offset within the data that will be advanced
 240   ///     by the appropriate number of bytes if the value is extracted
 241   ///     correctly. If the offset is out of bounds or there are not
 242   ///     enough bytes to extract this value, the offset will be left
 243   ///     unmodified.
 244   ///
 245   /// @param[out] dst
 246   ///     A buffer to copy \a count uint32_t values into. \a dst must
 247   ///     be large enough to hold all requested data.
 248   ///
 249   /// @param[in] count
 250   ///     The number of uint32_t values to extract.
 251   ///
 252   /// @return
 253   ///     \a dst if all values were properly extracted and copied,
 254   ///     NULL otherise.
 255   uint32_t *getU32(uint32_t *offset_ptr, uint32_t *dst, uint32_t count) const;
 256
 257   /// Extract a uint64_t value from \a *offset_ptr.
 258   ///
 259   /// Extract a single uint64_t from the binary data at the offset
 260   /// pointed to by \a offset_ptr, and update the offset on success.
 261   ///
 262   /// @param[in,out] offset_ptr
 263   ///     A pointer to an offset within the data that will be advanced
 264   ///     by the appropriate number of bytes if the value is extracted
 265   ///     correctly. If the offset is out of bounds or there are not
 266   ///     enough bytes to extract this value, the offset will be left
 267   ///     unmodified.
 268   ///
 269   /// @return
 270   ///     The extracted uint64_t value.
 271   uint64_t getU64(uint32_t *offset_ptr) const;
 272
 273   /// Extract \a count uint64_t values from \a *offset_ptr.
 274   ///
 275   /// Extract \a count uint64_t values from the binary data at the
 276   /// offset pointed to by \a offset_ptr, and advance the offset on
 277   /// success. The extracted values are copied into \a dst.
 278   ///
 279   /// @param[in,out] offset_ptr
 280   ///     A pointer to an offset within the data that will be advanced
 281   ///     by the appropriate number of bytes if the value is extracted
 282   ///     correctly. If the offset is out of bounds or there are not
 283   ///     enough bytes to extract this value, the offset will be left
 284   ///     unmodified.
 285   ///
 286   /// @param[out] dst
 287   ///     A buffer to copy \a count uint64_t values into. \a dst must
 288   ///     be large enough to hold all requested data.
 289   ///
 290   /// @param[in] count
 291   ///     The number of uint64_t values to extract.
 292   ///
 293   /// @return
 294   ///     \a dst if all values were properly extracted and copied,
 295   ///     NULL otherise.
 296   uint64_t *getU64(uint32_t *offset_ptr, uint64_t *dst, uint32_t count) const;
 297
 298   /// Extract a signed LEB128 value from \a *offset_ptr.
 299   ///
 300   /// Extracts an signed LEB128 number from this object's data
 301   /// starting at the offset pointed to by \a offset_ptr. The offset
 302   /// pointed to by \a offset_ptr will be updated with the offset of
 303   /// the byte following the last extracted byte.
 304   ///
 305   /// @param[in,out] offset_ptr
 306   ///     A pointer to an offset within the data that will be advanced
 307   ///     by the appropriate number of bytes if the value is extracted
 308   ///     correctly. If the offset is out of bounds or there are not
 309   ///     enough bytes to extract this value, the offset will be left
 310   ///     unmodified.
 311   ///
 312   /// @return
 313   ///     The extracted signed integer value.
 314   int64_t getSLEB128(uint32_t *offset_ptr) const;
 315
 316   /// Extract a unsigned LEB128 value from \a *offset_ptr.
 317   ///
 318   /// Extracts an unsigned LEB128 number from this object's data
 319   /// starting at the offset pointed to by \a offset_ptr. The offset
 320   /// pointed to by \a offset_ptr will be updated with the offset of
 321   /// the byte following the last extracted byte.
 322   ///
 323   /// @param[in,out] offset_ptr
 324   ///     A pointer to an offset within the data that will be advanced
 325   ///     by the appropriate number of bytes if the value is extracted
 326   ///     correctly. If the offset is out of bounds or there are not
 327   ///     enough bytes to extract this value, the offset will be left
 328   ///     unmodified.
 329   ///
 330   /// @return
 331   ///     The extracted unsigned integer value.
 332   uint64_t getULEB128(uint32_t *offset_ptr) const;
 333
 334   /// Test the validity of \a offset.
 335   ///
 336   /// @return
 337   ///     \b true if \a offset is a valid offset into the data in this
 338   ///     object, \b false otherwise.
 339   bool isValidOffset(uint32_t offset) const { return Data.size() > offset; }
 340
 341   /// Test the availability of \a length bytes of data from \a offset.
 342   ///
 343   /// @return
 344   ///     \b true if \a offset is a valid offset and there are \a
 345   ///     length bytes available at that offset, \b false otherwise.
 346   bool isValidOffsetForDataOfSize(uint32_t offset, uint32_t length) const {
 347     return offset + length >= offset && isValidOffset(offset + length - 1);
 348   }
 349 };
 350
 351 } // namespace llvm
 352
 353 #endif