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