//===-- DataExtractor.h -----------------------------------------*- C++ -*-===// // // The LLVM Compiler Infrastructure // // This file is distributed under the University of Illinois Open Source // License. See LICENSE.TXT for details. // //===----------------------------------------------------------------------===// #ifndef liblldb_DataExtractor_h_ #define liblldb_DataExtractor_h_ #if defined (__cplusplus) #include "lldb/lldb-private.h" #include <limits.h> #include <stdint.h> #include <string.h> namespace lldb_private { //---------------------------------------------------------------------- /// @class DataExtractor DataExtractor.h "lldb/Core/DataExtractor.h" /// @brief An data extractor class. /// /// DataExtractor is a class that can extract data (swapping if needed) /// from a data buffer. The data buffer can be caller owned, or can be /// shared data that can be shared between multiple DataExtractor /// instances. Multiple DataExtractor objects can share the same data, /// yet extract values in different address sizes and byte order modes. /// Each object can have a unique position in the shared data and extract /// data from different offsets. /// /// @see DataBuffer //---------------------------------------------------------------------- class DataExtractor { public: //------------------------------------------------------------------ /// @typedef DataExtractor::Type /// @brief Type enumerations used in the dump routines. /// @see DataExtractor::Dump() /// @see DataExtractor::DumpRawHexBytes() //------------------------------------------------------------------ typedef enum { TypeUInt8, ///< Format output as unsigned 8 bit integers TypeChar, ///< Format output as characters TypeUInt16, ///< Format output as unsigned 16 bit integers TypeUInt32, ///< Format output as unsigned 32 bit integers TypeUInt64, ///< Format output as unsigned 64 bit integers TypePointer, ///< Format output as pointers TypeULEB128, ///< Format output as ULEB128 numbers TypeSLEB128 ///< Format output as SLEB128 numbers } Type; static void DumpHexBytes (Stream *s, const void *src, size_t src_len, uint32_t bytes_per_line, lldb::addr_t base_addr); // Pass LLDB_INVALID_ADDRESS to not show address at start of line //------------------------------------------------------------------ /// Default constructor. /// /// Initialize all members to a default empty state. //------------------------------------------------------------------ DataExtractor (); //------------------------------------------------------------------ /// Construct with a buffer that is owned by the caller. /// /// This constructor allows us to use data that is owned by the /// caller. The data must stay around as long as this object is /// valid. /// /// @param[in] data /// A pointer to caller owned data. /// /// @param[in] data_length /// The length in bytes of \a data. /// /// @param[in] byte_order /// A byte order of the data that we are extracting from. /// /// @param[in] addr_size /// A new address byte size value. //------------------------------------------------------------------ DataExtractor (const void* data, uint32_t data_length, lldb::ByteOrder byte_order, uint8_t addr_size); //------------------------------------------------------------------ /// Construct with shared data. /// /// Copies the data shared pointer which adds a reference to the /// contained in \a data_sp. The shared data reference is reference /// counted to ensure the data lives as long as anyone still has a /// valid shared pointer to the data in \a data_sp. /// /// @param[in] data_sp /// A shared pointer to data. /// /// @param[in] byte_order /// A byte order of the data that we are extracting from. /// /// @param[in] addr_size /// A new address byte size value. //------------------------------------------------------------------ DataExtractor (const lldb::DataBufferSP& data_sp, lldb::ByteOrder byte_order, uint8_t addr_size); //------------------------------------------------------------------ /// Construct with a subset of \a data. /// /// Initialize this object with a subset of the data bytes in \a /// data. If \a data contains shared data, then a reference to the /// shared data will be added to ensure the shared data stays around /// as long as any objects have references to the shared data. The /// byte order value and the address size settings are copied from \a /// data. If \a offset is not a valid offset in \a data, then no /// reference to the shared data will be added. If there are not /// \a length bytes available in \a data starting at \a offset, /// the length will be truncated to contain as many bytes as /// possible. /// /// @param[in] data /// Another DataExtractor object that contains data. /// /// @param[in] offset /// The offset into \a data at which the subset starts. /// /// @param[in] length /// The length in bytes of the subset of data. //------------------------------------------------------------------ DataExtractor (const DataExtractor& data, uint32_t offset, uint32_t length); DataExtractor (const DataExtractor& rhs); //------------------------------------------------------------------ /// Assignment operator. /// /// Copies all data, byte order and address size settings from \a rhs into /// this object. If \a rhs contains shared data, a reference to that /// shared data will be added. /// /// @param[in] rhs /// Another DataExtractor object to copy. /// /// @return /// A const reference to this object. //------------------------------------------------------------------ const DataExtractor& operator= (const DataExtractor& rhs); //------------------------------------------------------------------ /// Destructor /// /// If this object contains a valid shared data reference, the /// reference count on the data will be decremented, and if zero, /// the data will be freed. //------------------------------------------------------------------ ~DataExtractor (); //------------------------------------------------------------------ /// Clears the object state. /// /// Clears the object contents back to a default invalid state, and /// release any references to shared data that this object may /// contain. //------------------------------------------------------------------ void Clear (); //------------------------------------------------------------------ /// Dumps the binary data as \a type objects to stream \a s (or to /// Log() if \a s is NULL) starting \a offset bytes into the data /// and stopping after dumping \a length bytes. The offset into the /// data is displayed at the beginning of each line and can be /// offset by base address \a base_addr. \a num_per_line objects /// will be displayed on each line. /// /// @param[in] s /// The stream to dump the output to. If NULL the output will /// be dumped to Log(). /// /// @param[in] offset /// The offset into the data at which to start dumping. /// /// @param[in] length /// The number of bytes to dump. /// /// @param[in] base_addr /// The base address that gets added to the offset displayed on /// each line. /// /// @param[in] num_per_line /// The number of \a type objects to display on each line. /// /// @param[in] type /// The type of objects to use when dumping data from this /// object. See DataExtractor::Type. /// /// @param[in] type_format /// The optional format to use for the \a type objects. If this /// is NULL, the default format for the \a type will be used. /// /// @return /// The offset at which dumping ended. //------------------------------------------------------------------ uint32_t PutToLog (Log *log, uint32_t offset, uint32_t length, uint64_t base_addr, uint32_t num_per_line, Type type, const char *type_format = NULL) const; //------------------------------------------------------------------ /// Dumps \a item_count objects into the stream \a s. /// /// Dumps \a item_count objects using \a item_format, each of which /// are \a item_byte_size bytes long starting at offset \a offset /// bytes into the contained data, into the stream \a s. \a /// num_per_line objects will be dumped on each line before a new /// line will be output. If \a base_addr is a valid address, then /// each new line of output will be prededed by the address value /// plus appropriate offset, and a colon and space. Bitfield values /// can be dumped by calling this function multiple times with the /// same start offset, format and size, yet differing \a /// item_bit_size and \a item_bit_offset values. /// /// @param[in] s /// The stream to dump the output to. This value can not be NULL. /// /// @param[in] offset /// The offset into the data at which to start dumping. /// /// @param[in] item_format /// The format to use when dumping each item. /// /// @param[in] item_byte_size /// The byte size of each item. /// /// @param[in] item_count /// The number of items to dump. /// /// @param[in] num_per_line /// The number of items to display on each line. /// /// @param[in] base_addr /// The base address that gets added to the offset displayed on /// each line if the value is valid. Is \a base_addr is /// LLDB_INVALID_ADDRESS then no address values will be prepended /// to any lines. /// /// @param[in] item_bit_size /// If the value to display is a bitfield, this value should /// be the number of bits that the bitfield item has within the /// item's byte size value. This function will need to be called /// multiple times with identical \a offset and \a item_byte_size /// values in order to display multiple bitfield values that /// exist within the same integer value. If the items being /// displayed are not bitfields, this value should be zero. /// /// @param[in] item_bit_offset /// If the value to display is a bitfield, this value should /// be the offset in bits, or shift right amount, that the /// bitfield item occupies within the item's byte size value. /// This function will need to be called multiple times with /// identical \a offset and \a item_byte_size values in order /// to display multiple bitfield values that exist within the /// same integer value. If the items being displayed are not /// bitfields, this value should be zero. /// /// @return /// The offset at which dumping ended. //------------------------------------------------------------------ uint32_t Dump(Stream *s, uint32_t offset, lldb::Format item_format, uint32_t item_byte_size, uint32_t item_count, uint32_t num_per_line, uint64_t base_addr, uint32_t item_bit_size, uint32_t item_bit_offset) const; //------------------------------------------------------------------ /// Dump a UUID value at \a offset. /// /// Dump a UUID starting at \a offset bytes into this object's data. /// If the stream \a s is NULL, the output will be sent to Log(). /// /// @param[in] s /// The stream to dump the output to. If NULL the output will /// be dumped to Log(). /// /// @param[in] offset /// The offset into the data at which to extract and dump a /// UUID value. //------------------------------------------------------------------ void DumpUUID (Stream *s, uint32_t offset) const; //------------------------------------------------------------------ /// Extract an arbitrary number of bytes in the specified byte /// order. /// /// Attemps to extract \a length bytes starting at \a offset bytes /// into this data in the requested byte order (\a dst_byte_order) /// and place the results in \a dst. \a dst must be at least \a /// length bytes long. /// /// @param[in] offset /// The offset in bytes into the contained data at which to /// start extracting. /// /// @param[in] length /// The number of bytes to extract. /// /// @param[in] dst_byte_order /// A byte order of the data that we want when the value in /// copied to \a dst. /// /// @param[out] dst /// The buffer that will receive the extracted value if there /// are enough bytes available in the current data. /// /// @return /// The number of bytes that were extracted which will be \a /// length when the value is successfully extracted, or zero /// if there aren't enough bytes at the specified offset. //------------------------------------------------------------------ size_t ExtractBytes (uint32_t offset, uint32_t length, lldb::ByteOrder dst_byte_order, void *dst) const; //------------------------------------------------------------------ /// Extract an address from \a *offset_ptr. /// /// Extract a single address from the data and update the offset /// pointed to by \a offset_ptr. The size of the extracted address /// comes from the \a m_addr_size member variable and should be /// set correctly prior to extracting any address values. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @return /// The extracted address value. //------------------------------------------------------------------ uint64_t GetAddress (uint32_t *offset_ptr) const; //------------------------------------------------------------------ /// Get the current address size. /// /// Return the size in bytes of any address values this object will /// extract. /// /// @return /// The size in bytes of address values that will be extracted. //------------------------------------------------------------------ uint8_t GetAddressByteSize () const; //------------------------------------------------------------------ /// Get the number of bytes contained in this object. /// /// @return /// The total number of bytes of data this object refers to. //------------------------------------------------------------------ size_t GetByteSize () const; //------------------------------------------------------------------ /// Extract a C string from \a *offset_ptr. /// /// Returns a pointer to a C String from the data at the offset /// pointed to by \a offset_ptr. A variable length NULL terminated C /// string will be extracted and the \a offset_ptr will be /// updated with the offset of the byte that follows the NULL /// terminator byte. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @return /// A pointer to the C string value in the data. If the offset /// pointed to by \a offset_ptr is out of bounds, or if the /// offset plus the length of the C string is out of bounds, /// NULL will be returned. //------------------------------------------------------------------ const char * GetCStr (uint32_t *offset_ptr) const; //------------------------------------------------------------------ /// Extract \a length bytes from \a *offset_ptr. /// /// Returns a pointer to a bytes in this object's data at the offset /// pointed to by \a offset_ptr. If \a length is zero or too large, /// then the offset pointed to by \a offset_ptr will not be updated /// and NULL will be returned. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @param[in] length /// The optional length of a string to extract. If the value is /// zero, a NULL terminated C string will be extracted. /// /// @return /// A pointer to the bytes in this object's data if the offset /// and length are valid, or NULL otherwise. //------------------------------------------------------------------ const void* GetData (uint32_t *offset_ptr, uint32_t length) const; //------------------------------------------------------------------ /// Copy \a dst_len bytes from \a *offset_ptr and ensure the copied /// data is treated as a value that can be swapped to match the /// specified byte order. /// /// For values that are larger than the supported integer sizes, /// this function can be used to extract data in a specified byte /// order. It can also be used to copy a smaller integer value from /// to a larger value. The extra bytes left over will be padded /// correctly according to the byte order of this object and the /// \a dst_byte_order. This can be very handy when say copying a /// partial data value into a register. /// /// @param[in] src_offset /// The offset into this data from which to start copying an /// endian entity /// /// @param[in] src_len /// The length of the endian data to copy from this object /// into the \a dst object /// /// @param[out] dst /// The buffer where to place the endian data. The data might /// need to be byte swapped (and appropriately padded with /// zeroes if \a src_len != \a dst_len) if \a dst_byte_order /// does not match the byte order in this object. /// /// @param[in] dst_len /// The length number of bytes that the endian value will /// occupy is \a dst. /// /// @param[in] byte_order /// The byte order that the endian value should be in the \a dst /// buffer. /// /// @return /// Returns the number of bytes that were copied, or zero if /// anything goes wrong. //------------------------------------------------------------------ uint32_t CopyByteOrderedData (uint32_t src_offset, uint32_t src_len, void *dst, uint32_t dst_len, lldb::ByteOrder dst_byte_order) const; //------------------------------------------------------------------ /// Get the data end pointer. /// /// @return /// Returns a pointer to the next byte contained in this /// object's data, or NULL of there is no data in this object. //------------------------------------------------------------------ const uint8_t * GetDataEnd () const; //------------------------------------------------------------------ /// Get the shared data offset. /// /// Get the offset of the first byte of data in the shared data (if /// any). /// /// @return /// If this object contains shared data, this function returns /// the offset in bytes into that shared data, zero otherwise. //------------------------------------------------------------------ size_t GetSharedDataOffset () const; //------------------------------------------------------------------ /// Get a the data start pointer. /// /// @return /// Returns a pointer to the first byte contained in this /// object's data, or NULL of there is no data in this object. //------------------------------------------------------------------ const uint8_t * GetDataStart () const; //------------------------------------------------------------------ /// Extract a float from \a *offset_ptr. /// /// Extract a single float value. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @return /// The integer value that was extracted, or zero on failure. //------------------------------------------------------------------ float GetFloat (uint32_t *offset_ptr) const; double GetDouble (uint32_t *offset_ptr) const; long double GetLongDouble (uint32_t *offset_ptr) const; //------------------------------------------------------------------ /// Extract a GNU encoded pointer value from \a *offset_ptr. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @param[in] eh_ptr_enc /// The GNU pointer encoding type. /// /// @param[in] pc_rel_addr /// The PC relative address to use when the encoding is /// \c DW_GNU_EH_PE_pcrel. /// /// @param[in] text_addr /// The text (code) relative address to use when the encoding is /// \c DW_GNU_EH_PE_textrel. /// /// @param[in] data_addr /// The data relative address to use when the encoding is /// \c DW_GNU_EH_PE_datarel. /// /// @return /// The extracted GNU encoded pointer value. //------------------------------------------------------------------ uint64_t GetGNUEHPointer (uint32_t *offset_ptr, uint32_t eh_ptr_enc, lldb::addr_t pc_rel_addr, lldb::addr_t text_addr, lldb::addr_t data_addr); //------------------------------------------------------------------ /// Extract an integer of size \a byte_size from \a *offset_ptr. /// /// Extract a single integer value and update the offset pointed to /// by \a offset_ptr. The size of the extracted integer is specified /// by the \a byte_size argument. \a byte_size should have a value /// >= 1 and <= 4 since the return value is only 32 bits wide. Any /// \a byte_size values less than 1 or greater than 4 will result in /// nothing being extracted, and zero being returned. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @param[in] byte_size /// The size in byte of the integer to extract. /// /// @return /// The integer value that was extracted, or zero on failure. //------------------------------------------------------------------ uint32_t GetMaxU32 (uint32_t *offset_ptr, uint32_t byte_size) const; //------------------------------------------------------------------ /// Extract an unsigned integer of size \a byte_size from \a /// *offset_ptr. /// /// Extract a single unsigned integer value and update the offset /// pointed to by \a offset_ptr. The size of the extracted integer /// is specified by the \a byte_size argument. \a byte_size should /// have a value greater than or equal to one and less than or equal /// to eight since the return value is 64 bits wide. Any /// \a byte_size values less than 1 or greater than 8 will result in /// nothing being extracted, and zero being returned. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @param[in] byte_size /// The size in byte of the integer to extract. /// /// @return /// The unsigned integer value that was extracted, or zero on /// failure. //------------------------------------------------------------------ uint64_t GetMaxU64 (uint32_t *offset_ptr, uint32_t byte_size) const; //------------------------------------------------------------------ /// Extract an signed integer of size \a byte_size from \a *offset_ptr. /// /// Extract a single signed integer value (sign extending if required) /// and update the offset pointed to by \a offset_ptr. The size of /// the extracted integer is specified by the \a byte_size argument. /// \a byte_size should have a value greater than or equal to one /// and less than or equal to eight since the return value is 64 /// bits wide. Any \a byte_size values less than 1 or greater than /// 8 will result in nothing being extracted, and zero being returned. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @param[in] byte_size /// The size in byte of the integer to extract. /// /// @return /// The sign extended signed integer value that was extracted, /// or zero on failure. //------------------------------------------------------------------ int64_t GetMaxS64 (uint32_t *offset_ptr, uint32_t size) const; //------------------------------------------------------------------ /// Extract an unsigned integer of size \a byte_size from \a /// *offset_ptr, then extract the bitfield from this value if /// \a bitfield_bit_size is non-zero. /// /// Extract a single unsigned integer value and update the offset /// pointed to by \a offset_ptr. The size of the extracted integer /// is specified by the \a byte_size argument. \a byte_size should /// have a value greater than or equal to one and less than or equal /// to 8 since the return value is 64 bits wide. Any /// \a byte_size values less than 1 or greater than 8 will result in /// nothing being extracted, and zero being returned. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @param[in] byte_size /// The size in byte of the integer to extract. /// /// @param[in] bitfield_bit_size /// The size in bits of the bitfield value to extract, or zero /// to just extract the entire integer value. /// /// @param[in] bitfield_bit_offset /// The bit offset of the bitfield value in the extracted /// integer (the number of bits to shift the integer to the /// right). /// /// @return /// The unsigned bitfield integer value that was extracted, or /// zero on failure. //------------------------------------------------------------------ uint64_t GetMaxU64Bitfield (uint32_t *offset_ptr, uint32_t size, uint32_t bitfield_bit_size, uint32_t bitfield_bit_offset) const; //------------------------------------------------------------------ /// Extract an signed integer of size \a byte_size from \a /// *offset_ptr, then extract and signe extend the bitfield from /// this value if \a bitfield_bit_size is non-zero. /// /// Extract a single signed integer value (sign extending if required) /// and update the offset pointed to by \a offset_ptr. The size of /// the extracted integer is specified by the \a byte_size argument. /// \a byte_size should have a value greater than or equal to one /// and less than or equal to eight since the return value is 64 /// bits wide. Any \a byte_size values less than 1 or greater than /// 8 will result in nothing being extracted, and zero being returned. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @param[in] byte_size /// The size in bytes of the integer to extract. /// /// @param[in] bitfield_bit_size /// The size in bits of the bitfield value to extract, or zero /// to just extract the entire integer value. /// /// @param[in] bitfield_bit_offset /// The bit offset of the bitfield value in the extracted /// integer (the number of bits to shift the integer to the /// right). /// /// @return /// The signed bitfield integer value that was extracted, or /// zero on failure. //------------------------------------------------------------------ int64_t GetMaxS64Bitfield (uint32_t *offset_ptr, uint32_t size, uint32_t bitfield_bit_size, uint32_t bitfield_bit_offset) const; //------------------------------------------------------------------ /// Extract an pointer from \a *offset_ptr. /// /// Extract a single pointer from the data and update the offset /// pointed to by \a offset_ptr. The size of the extracted pointer /// comes from the \a m_addr_size member variable and should be /// set correctly prior to extracting any pointer values. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @return /// The extracted pointer value as a 64 integer. //------------------------------------------------------------------ uint64_t GetPointer (uint32_t *offset_ptr) const; //------------------------------------------------------------------ /// Get the current byte order value. /// /// @return /// The current byte order value from this object's internal /// state. //------------------------------------------------------------------ lldb::ByteOrder GetByteOrder() const; //------------------------------------------------------------------ /// Extract a uint8_t value from \a *offset_ptr. /// /// Extract a single uint8_t from the binary data at the offset /// pointed to by \a offset_ptr, and advance the offset on success. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @return /// The extracted uint8_t value. //------------------------------------------------------------------ uint8_t GetU8 ( uint32_t *offset_ptr) const; uint8_t GetU8_unchecked (uint32_t *offset_ptr) const { uint8_t val = m_start[*offset_ptr]; *offset_ptr += 1; return val; } uint16_t GetU16_unchecked (uint32_t *offset_ptr) const; uint32_t GetU32_unchecked (uint32_t *offset_ptr) const; uint64_t GetU64_unchecked (uint32_t *offset_ptr) const; //------------------------------------------------------------------ /// Extract \a count uint8_t values from \a *offset_ptr. /// /// Extract \a count uint8_t values from the binary data at the /// offset pointed to by \a offset_ptr, and advance the offset on /// success. The extracted values are copied into \a dst. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @param[out] dst /// A buffer to copy \a count uint8_t values into. \a dst must /// be large enough to hold all requested data. /// /// @param[in] count /// The number of uint8_t values to extract. /// /// @return /// \a dst if all values were properly extracted and copied, /// NULL otherise. //------------------------------------------------------------------ void * GetU8 ( uint32_t *offset_ptr, void *dst, uint32_t count) const; //------------------------------------------------------------------ /// Extract a uint16_t value from \a *offset_ptr. /// /// Extract a single uint16_t from the binary data at the offset /// pointed to by \a offset_ptr, and update the offset on success. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @return /// The extracted uint16_t value. //------------------------------------------------------------------ uint16_t GetU16 (uint32_t *offset_ptr) const; //------------------------------------------------------------------ /// Extract \a count uint16_t values from \a *offset_ptr. /// /// Extract \a count uint16_t values from the binary data at the /// offset pointed to by \a offset_ptr, and advance the offset on /// success. The extracted values are copied into \a dst. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @param[out] dst /// A buffer to copy \a count uint16_t values into. \a dst must /// be large enough to hold all requested data. /// /// @param[in] count /// The number of uint16_t values to extract. /// /// @return /// \a dst if all values were properly extracted and copied, /// NULL otherise. //------------------------------------------------------------------ void * GetU16 (uint32_t *offset_ptr, void *dst, uint32_t count) const; //------------------------------------------------------------------ /// Extract a uint32_t value from \a *offset_ptr. /// /// Extract a single uint32_t from the binary data at the offset /// pointed to by \a offset_ptr, and update the offset on success. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @return /// The extracted uint32_t value. //------------------------------------------------------------------ uint32_t GetU32 (uint32_t *offset_ptr) const; //------------------------------------------------------------------ /// Extract \a count uint32_t values from \a *offset_ptr. /// /// Extract \a count uint32_t values from the binary data at the /// offset pointed to by \a offset_ptr, and advance the offset on /// success. The extracted values are copied into \a dst. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @param[out] dst /// A buffer to copy \a count uint32_t values into. \a dst must /// be large enough to hold all requested data. /// /// @param[in] count /// The number of uint32_t values to extract. /// /// @return /// \a dst if all values were properly extracted and copied, /// NULL otherise. //------------------------------------------------------------------ void * GetU32 (uint32_t *offset_ptr, void *dst, uint32_t count) const; //------------------------------------------------------------------ /// Extract a uint64_t value from \a *offset_ptr. /// /// Extract a single uint64_t from the binary data at the offset /// pointed to by \a offset_ptr, and update the offset on success. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @return /// The extracted uint64_t value. //------------------------------------------------------------------ uint64_t GetU64 (uint32_t *offset_ptr) const; //------------------------------------------------------------------ /// Extract \a count uint64_t values from \a *offset_ptr. /// /// Extract \a count uint64_t values from the binary data at the /// offset pointed to by \a offset_ptr, and advance the offset on /// success. The extracted values are copied into \a dst. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @param[out] dst /// A buffer to copy \a count uint64_t values into. \a dst must /// be large enough to hold all requested data. /// /// @param[in] count /// The number of uint64_t values to extract. /// /// @return /// \a dst if all values were properly extracted and copied, /// NULL otherise. //------------------------------------------------------------------ void * GetU64 ( uint32_t *offset_ptr, void *dst, uint32_t count) const; //------------------------------------------------------------------ /// Extract a signed LEB128 value from \a *offset_ptr. /// /// Extracts an signed LEB128 number from this object's data /// starting at the offset pointed to by \a offset_ptr. The offset /// pointed to by \a offset_ptr will be updated with the offset of /// the byte following the last extracted byte. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @return /// The extracted signed integer value. //------------------------------------------------------------------ int64_t GetSLEB128 (uint32_t *offset_ptr) const; //------------------------------------------------------------------ /// Extract a unsigned LEB128 value from \a *offset_ptr. /// /// Extracts an unsigned LEB128 number from this object's data /// starting at the offset pointed to by \a offset_ptr. The offset /// pointed to by \a offset_ptr will be updated with the offset of /// the byte following the last extracted byte. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @return /// The extracted unsigned integer value. //------------------------------------------------------------------ uint64_t GetULEB128 (uint32_t *offset_ptr) const; //------------------------------------------------------------------ /// Peek at a C string at \a offset. /// /// Peeks at a string in the contained data. No verification is done /// to make sure the entire string lies within the bounds of this /// object's data, only \a offset is verified to be a valid offset. /// /// @param[in] offset /// An offset into the data. /// /// @return /// A non-NULL C string pointer if \a offset is a valid offset, /// NULL otherwise. //------------------------------------------------------------------ const char * PeekCStr (uint32_t offset) const; //------------------------------------------------------------------ /// Peek at a bytes at \a offset. /// /// Returns a pointer to \a length bytes at \a offset as long as /// there are \a length bytes available starting at \a offset. /// /// @return /// A non-NULL data pointer if \a offset is a valid offset and /// there are \a length bytes available at that offset, NULL /// otherwise. //------------------------------------------------------------------ const uint8_t* PeekData (uint32_t offset, uint32_t length) const; //------------------------------------------------------------------ /// Set the address byte size. /// /// Set the size in bytes that will be used when extracting any /// address and pointer values from data contained in this object. /// /// @param[in] addr_size /// The size in bytes to use when extracting addresses. //------------------------------------------------------------------ void SetAddressByteSize (uint8_t addr_size); //------------------------------------------------------------------ /// Set data with a buffer that is caller owned. /// /// Use data that is owned by the caller when extracting values. /// The data must stay around as long as this object, or any object /// that copies a subset of this object's data, is valid. If \a /// bytes is NULL, or \a length is zero, this object will contain /// no data. /// /// @param[in] bytes /// A pointer to caller owned data. /// /// @param[in] length /// The length in bytes of \a bytes. /// /// @param[in] byte_order /// A byte order of the data that we are extracting from. /// /// @return /// The number of bytes that this object now contains. //------------------------------------------------------------------ uint32_t SetData (const void *bytes, uint32_t length, lldb::ByteOrder byte_order); //------------------------------------------------------------------ /// Adopt a subset of \a data. /// /// Set this object's data to be a subset of the data bytes in \a /// data. If \a data contains shared data, then a reference to the /// shared data will be added to ensure the shared data stays around /// as long as any objects have references to the shared data. The /// byte order and the address size settings are copied from \a /// data. If \a offset is not a valid offset in \a data, then no /// reference to the shared data will be added. If there are not /// \a length bytes available in \a data starting at \a offset, /// the length will be truncated to contains as many bytes as /// possible. /// /// @param[in] data /// Another DataExtractor object that contains data. /// /// @param[in] offset /// The offset into \a data at which the subset starts. /// /// @param[in] length /// The length in bytes of the subset of \a data. /// /// @return /// The number of bytes that this object now contains. //------------------------------------------------------------------ uint32_t SetData (const DataExtractor& data, uint32_t offset, uint32_t length); //------------------------------------------------------------------ /// Adopt a subset of shared data in \a data_sp. /// /// Copies the data shared pointer which adds a reference to the /// contained in \a data_sp. The shared data reference is reference /// counted to ensure the data lives as long as anyone still has a /// valid shared pointer to the data in \a data_sp. The byte order /// and address byte size settings remain the same. If /// \a offset is not a valid offset in \a data_sp, then no reference /// to the shared data will be added. If there are not \a length /// bytes available in \a data starting at \a offset, the length /// will be truncated to contains as many bytes as possible. /// /// @param[in] data_sp /// A shared pointer to data. /// /// @param[in] offset /// The offset into \a data_sp at which the subset starts. /// /// @param[in] length /// The length in bytes of the subset of \a data_sp. /// /// @return /// The number of bytes that this object now contains. //------------------------------------------------------------------ uint32_t SetData (const lldb::DataBufferSP& data_sp, uint32_t offset = 0, uint32_t length = UINT32_MAX); //------------------------------------------------------------------ /// Set the byte_order value. /// /// Sets the byte order of the data to extract. Extracted values /// will be swapped if necessary when decoding. /// /// @param[in] byte_order /// The byte order value to use when extracting data. //------------------------------------------------------------------ void SetByteOrder (lldb::ByteOrder byte_order); //------------------------------------------------------------------ /// Skip an LEB128 number at \a *offset_ptr. /// /// Skips a LEB128 number (signed or unsigned) from this object's /// data starting at the offset pointed to by \a offset_ptr. The /// offset pointed to by \a offset_ptr will be updated with the /// offset of the byte following the last extracted byte. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced /// by the appropriate number of bytes if the value is extracted /// correctly. If the offset is out of bounds or there are not /// enough bytes to extract this value, the offset will be left /// unmodified. /// /// @return // The number of bytes consumed during the extraction. //------------------------------------------------------------------ uint32_t Skip_LEB128 (uint32_t *offset_ptr) const; //------------------------------------------------------------------ /// Test the validity of \a offset. /// /// @return /// \b true if \a offset is a valid offset into the data in this /// object, \b false otherwise. //------------------------------------------------------------------ bool ValidOffset (uint32_t offset) const; //------------------------------------------------------------------ /// Test the availability of \a length bytes of data from \a offset. /// /// @return /// \b true if \a offset is a valid offset and there are \a /// length bytes available at that offset, \b false otherwise. //------------------------------------------------------------------ bool ValidOffsetForDataOfSize (uint32_t offset, uint32_t length) const; protected: //------------------------------------------------------------------ // Member variables //------------------------------------------------------------------ const uint8_t * m_start; ///< A pointer to the first byte of data. const uint8_t * m_end; ///< A pointer to the byte that is past the end of the data. lldb::ByteOrder m_byte_order; ///< The byte order of the data we are extracting from. uint8_t m_addr_size; ///< The address size to use when extracting pointers or addresses mutable lldb::DataBufferSP m_data_sp; ///< The shared pointer to data that can be shared among multilple instances }; } // namespace lldb_private #endif // #if defined (__cplusplus) #endif // #ifndef liblldb_DataExtractor_h_