| //===-- DataEncoder.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_DataEncoder_h_ |
| #define liblldb_DataEncoder_h_ |
| |
| #if defined (__cplusplus) |
| |
| #include "lldb/lldb-private.h" |
| #include <limits.h> |
| #include <stdint.h> |
| |
| namespace lldb_private { |
| |
| //---------------------------------------------------------------------- |
| /// @class DataEncoder DataEncoder.h "lldb/Core/DataEncoder.h" |
| /// @brief An binary data encoding class. |
| /// |
| /// DataEncoder is a class that can encode binary data (swapping if needed) |
| /// to a data buffer. The data buffer can be caller owned, or can be |
| /// shared data that can be shared between multiple DataEncoder or |
| /// DataEncoder instances. |
| /// |
| /// @see DataBuffer |
| //---------------------------------------------------------------------- |
| class DataEncoder |
| { |
| public: |
| //------------------------------------------------------------------ |
| /// Default constructor. |
| /// |
| /// Initialize all members to a default empty state. |
| //------------------------------------------------------------------ |
| DataEncoder (); |
| |
| //------------------------------------------------------------------ |
| /// 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. |
| //------------------------------------------------------------------ |
| DataEncoder (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. |
| //------------------------------------------------------------------ |
| DataEncoder (const lldb::DataBufferSP& data_sp, lldb::ByteOrder byte_order, uint8_t addr_size); |
| |
| //------------------------------------------------------------------ |
| /// 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. |
| //------------------------------------------------------------------ |
| ~DataEncoder (); |
| |
| //------------------------------------------------------------------ |
| /// 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 (); |
| |
| //------------------------------------------------------------------ |
| /// 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 |
| { |
| return m_addr_size; |
| } |
| |
| |
| //------------------------------------------------------------------ |
| /// 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 |
| { |
| return m_end - m_start; |
| } |
| |
| //------------------------------------------------------------------ |
| /// 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. |
| //------------------------------------------------------------------ |
| uint8_t * |
| GetDataEnd () |
| { |
| return m_end; |
| } |
| |
| const uint8_t * |
| GetDataEnd () const |
| { |
| return m_end; |
| } |
| |
| //------------------------------------------------------------------ |
| /// 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 the current byte order value. |
| /// |
| /// @return |
| /// The current byte order value from this object's internal |
| /// state. |
| //------------------------------------------------------------------ |
| lldb::ByteOrder |
| GetByteOrder() const |
| { |
| return m_byte_order; |
| } |
| |
| //------------------------------------------------------------------ |
| /// 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. |
| //------------------------------------------------------------------ |
| uint8_t * |
| GetDataStart () |
| { |
| return m_start; |
| } |
| |
| const uint8_t * |
| GetDataStart () const |
| { |
| return m_start; |
| } |
| |
| //------------------------------------------------------------------ |
| /// Encode unsigned integer values into the data at \a offset. |
| /// |
| /// @param[in] offset |
| /// The offset within the contained data at which to put the |
| /// data. |
| /// |
| /// @param[in] value |
| /// The value to encode into the data. |
| /// |
| /// @return |
| /// The next offset in the bytes of this data if the data |
| /// was successfully encoded, UINT32_MAX if the encoding failed. |
| //------------------------------------------------------------------ |
| uint32_t |
| PutU8 (uint32_t offset, uint8_t value); |
| |
| uint32_t |
| PutU16 (uint32_t offset, uint16_t value); |
| |
| uint32_t |
| PutU32 (uint32_t offset, uint32_t value); |
| |
| uint32_t |
| PutU64 (uint32_t offset, uint64_t value); |
| |
| //------------------------------------------------------------------ |
| /// Encode an unsigned integer of size \a byte_size to \a offset. |
| /// |
| /// Encode a single integer value at \a offset and return the offset |
| /// that follows the newly encoded integer when the data is successfully |
| /// encoded into the existing data. There must be enough room in the |
| /// data, else UINT32_MAX will be returned to indicate that encoding |
| /// failed. |
| /// |
| /// @param[in] offset |
| /// The offset within the contained data at which to put the |
| /// encoded integer. |
| /// |
| /// @param[in] byte_size |
| /// The size in byte of the integer to encode. |
| /// |
| /// @param[in] value |
| /// The integer value to write. The least significate bytes of |
| /// the integer value will be written if the size is less than |
| /// 8 bytes. |
| /// |
| /// @return |
| /// The next offset in the bytes of this data if the integer |
| /// was successfully encoded, UINT32_MAX if the encoding failed. |
| //------------------------------------------------------------------ |
| uint32_t |
| PutMaxU64 (uint32_t offset, uint32_t byte_size, uint64_t value); |
| |
| //------------------------------------------------------------------ |
| /// Encode an arbitrary number of bytes. |
| /// |
| /// @param[in] offset |
| /// The offset in bytes into the contained data at which to |
| /// start encoding. |
| /// |
| /// @param[int] src |
| /// The buffer that contains the the bytes to encode. |
| /// |
| /// @param[in] src_len |
| /// The number of bytes to encode. |
| /// |
| /// @return |
| /// The next valid offset within data if the put operation |
| /// was successful, else UINT32_MAX to indicate the put failed. |
| //------------------------------------------------------------------ |
| uint32_t |
| PutData (uint32_t offset, |
| const void *src, |
| uint32_t src_len); |
| |
| //------------------------------------------------------------------ |
| /// Encode an address in the existing buffer at \a offset bytes into |
| /// the buffer. |
| /// |
| /// Encode a single address (honoring the m_addr_size member) to |
| /// the data and return the next offset where subsequent data would |
| /// go. |
| /// 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 next valid offset within data if the put operation |
| /// was successful, else UINT32_MAX to indicate the put failed. |
| //------------------------------------------------------------------ |
| uint32_t |
| PutAddress (uint32_t offset, lldb::addr_t addr); |
| |
| //------------------------------------------------------------------ |
| /// Put a C string to \a offset. |
| /// |
| /// Encodes a C string into the existing data including the |
| /// terminating |
| /// |
| /// @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. |
| //------------------------------------------------------------------ |
| uint32_t |
| PutCString (uint32_t offset_ptr, const char *cstr); |
| |
| lldb::DataBufferSP & |
| GetSharedDataBuffer () |
| { |
| return m_data_sp; |
| } |
| |
| //------------------------------------------------------------------ |
| /// 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) |
| { |
| m_addr_size = 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 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) |
| { |
| m_byte_order = byte_order; |
| } |
| |
| |
| //------------------------------------------------------------------ |
| /// 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 |
| { |
| return offset < GetByteSize(); |
| } |
| |
| //------------------------------------------------------------------ |
| /// 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 |
| //------------------------------------------------------------------ |
| uint8_t *m_start; ///< A pointer to the first byte of data. |
| 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 |
| |
| private: |
| DISALLOW_COPY_AND_ASSIGN (DataEncoder); |
| |
| }; |
| |
| } // namespace lldb_private |
| |
| #endif // #if defined (__cplusplus) |
| #endif // #ifndef liblldb_DataEncoder_h_ |
