EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2026-05-10 08:42:57
0001 //===-- DataEncoder.h -------------------------------------------*- C++ -*-===// 0002 // 0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 0004 // See https://llvm.org/LICENSE.txt for license information. 0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 0006 // 0007 //===----------------------------------------------------------------------===// 0008 0009 #ifndef LLDB_UTILITY_DATAENCODER_H 0010 #define LLDB_UTILITY_DATAENCODER_H 0011 0012 #include "lldb/lldb-defines.h" 0013 #include "lldb/lldb-enumerations.h" 0014 #include "lldb/lldb-forward.h" 0015 #include "lldb/lldb-types.h" 0016 0017 #include "llvm/ADT/ArrayRef.h" 0018 #include "llvm/ADT/StringRef.h" 0019 0020 #include <cstddef> 0021 #include <cstdint> 0022 0023 namespace lldb_private { 0024 0025 /// \class DataEncoder 0026 /// 0027 /// An binary data encoding class. 0028 /// 0029 /// DataEncoder is a class that can encode binary data (swapping if needed) to 0030 /// a data buffer. The DataEncoder can be constructed with data that will be 0031 /// copied into the internally owned buffer. This allows data to be modified 0032 /// in the internal buffer. The DataEncoder object can also be constructed with 0033 /// just a byte order and address size and data can be appended to the 0034 /// internally owned buffer. 0035 /// 0036 /// Clients can get a shared pointer to the data buffer when done modifying or 0037 /// creating the data to keep the data around after the lifetime of a 0038 /// DataEncoder object. \see GetDataBuffer 0039 /// 0040 /// Client can get a reference to the object owned data as an array by calling 0041 /// the GetData method. \see GetData 0042 class DataEncoder { 0043 public: 0044 /// Default constructor. 0045 /// 0046 /// Initialize all members to a default empty state and create a empty memory 0047 /// buffer that can be appended to. The ByteOrder and address size will be set 0048 /// to match the current host system. 0049 DataEncoder(); 0050 0051 /// Construct an encoder that copies the specified data into the object owned 0052 /// data buffer. 0053 /// 0054 /// This constructor is designed to be used when you have a data buffer and 0055 /// want to modify values within the buffer. A copy of the data will be made 0056 /// in the internally owned buffer and that data can be fixed up and appended 0057 /// to. 0058 /// 0059 /// \param[in] data 0060 /// A pointer to caller owned data. 0061 /// 0062 /// \param[in] data_length 0063 /// The length in bytes of \a data. 0064 /// 0065 /// \param[in] byte_order 0066 /// A byte order for the data that will be encoded. 0067 /// 0068 /// \param[in] addr_size 0069 /// A size of an address in bytes. \see PutAddress, AppendAddress 0070 DataEncoder(const void *data, uint32_t data_length, 0071 lldb::ByteOrder byte_order, uint8_t addr_size); 0072 0073 /// Construct an encoder that owns a heap based memory buffer. 0074 /// 0075 /// This allows clients to create binary data from scratch by appending values 0076 /// with the methods that start with "Append". 0077 /// 0078 /// \param[in] byte_order 0079 /// A byte order for the data that will be encoded. 0080 /// 0081 /// \param[in] addr_size 0082 /// A size of an address in bytes. \see PutAddress, AppendAddress 0083 DataEncoder(lldb::ByteOrder byte_order, uint8_t addr_size); 0084 0085 ~DataEncoder(); 0086 0087 /// Encode an unsigned integer of size \a byte_size to \a offset. 0088 /// 0089 /// Encode a single integer value at \a offset and return the offset that 0090 /// follows the newly encoded integer when the data is successfully encoded 0091 /// into the existing data. There must be enough room in the existing data, 0092 /// else UINT32_MAX will be returned to indicate that encoding failed. 0093 /// 0094 /// \param[in] offset 0095 /// The offset within the contained data at which to put the encoded 0096 /// integer. 0097 /// 0098 /// \param[in] byte_size 0099 /// The size in byte of the integer to encode. 0100 /// 0101 /// \param[in] value 0102 /// The integer value to write. The least significant bytes of 0103 /// the integer value will be written if the size is less than 0104 /// 8 bytes. 0105 /// 0106 /// \return 0107 /// The next offset in the bytes of this data if the integer 0108 /// was successfully encoded, UINT32_MAX if the encoding failed. 0109 uint32_t PutUnsigned(uint32_t offset, uint32_t byte_size, uint64_t value); 0110 0111 /// Encode an unsigned integer at offset \a offset. 0112 /// 0113 /// Encode a single unsigned integer value at \a offset and return the offset 0114 /// that follows the newly encoded integer when the data is successfully 0115 /// encoded into the existing data. There must be enough room in the data, 0116 /// else UINT32_MAX will be returned to indicate that encoding failed. 0117 /// 0118 /// \param[in] offset 0119 /// The offset within the contained data at which to put the encoded 0120 /// integer. 0121 /// 0122 /// \param[in] value 0123 /// The integer value to write. 0124 /// 0125 /// \return 0126 /// The next offset in the bytes of this data if the integer was 0127 /// successfully encoded, UINT32_MAX if the encoding failed. 0128 uint32_t PutU8(uint32_t offset, uint8_t value); 0129 uint32_t PutU16(uint32_t offset, uint16_t value); 0130 uint32_t PutU32(uint32_t offset, uint32_t value); 0131 uint32_t PutU64(uint32_t offset, uint64_t value); 0132 0133 /// Append a unsigned integer to the end of the owned data. 0134 /// 0135 /// \param value 0136 /// A unsigned integer value to append. 0137 void AppendU8(uint8_t value); 0138 void AppendU16(uint16_t value); 0139 void AppendU32(uint32_t value); 0140 void AppendU64(uint64_t value); 0141 0142 /// Append an address sized integer to the end of the owned data. 0143 /// 0144 /// \param addr 0145 /// A unsigned integer address value to append. The size of the address 0146 /// will be determined by the address size specified in the constructor. 0147 void AppendAddress(lldb::addr_t addr); 0148 0149 /// Append a bytes to the end of the owned data. 0150 /// 0151 /// Append the bytes contained in the string reference. This function will 0152 /// not append a NULL termination character for a C string. Use the 0153 /// AppendCString function for this purpose. 0154 /// 0155 /// \param data 0156 /// A string reference that contains bytes to append. 0157 void AppendData(llvm::StringRef data); 0158 0159 /// Append a bytes to the end of the owned data. 0160 /// 0161 /// Append the bytes contained in the array reference. 0162 /// 0163 /// \param data 0164 /// A array reference that contains bytes to append. 0165 void AppendData(llvm::ArrayRef<uint8_t> data); 0166 0167 /// Append a C string to the end of the owned data. 0168 /// 0169 /// Append the bytes contained in the string reference along with an extra 0170 /// NULL termination character if the StringRef bytes doesn't include one as 0171 /// the last byte. 0172 /// 0173 /// \param data 0174 /// A string reference that contains bytes to append. 0175 void AppendCString(llvm::StringRef data); 0176 0177 /// Encode an arbitrary number of bytes. 0178 /// 0179 /// \param[in] offset 0180 /// The offset in bytes into the contained data at which to 0181 /// start encoding. 0182 /// 0183 /// \param[in] src 0184 /// The buffer that contains the bytes to encode. 0185 /// 0186 /// \param[in] src_len 0187 /// The number of bytes to encode. 0188 /// 0189 /// \return 0190 /// The next valid offset within data if the put operation 0191 /// was successful, else UINT32_MAX to indicate the put failed. 0192 uint32_t PutData(uint32_t offset, const void *src, uint32_t src_len); 0193 0194 /// Encode an address in the existing buffer at \a offset bytes into the 0195 /// buffer. 0196 /// 0197 /// Encode a single address to the data and return the next offset where 0198 /// subsequent data would go. The size of the address comes from the \a 0199 /// m_addr_size member variable and should be set correctly prior to encoding 0200 /// any address values. 0201 /// 0202 /// \param[in] offset 0203 /// The offset where to encode the address. 0204 /// 0205 /// \param[in] addr 0206 /// The address to encode. 0207 /// 0208 /// \return 0209 /// The next valid offset within data if the put operation 0210 /// was successful, else UINT32_MAX to indicate the put failed. 0211 uint32_t PutAddress(uint32_t offset, lldb::addr_t addr); 0212 0213 /// Put a C string to \a offset. 0214 /// 0215 /// Encodes a C string into the existing data including the terminating. If 0216 /// there is not enough room in the buffer to fit the entire C string and the 0217 /// NULL terminator in the existing buffer bounds, then this function will 0218 /// fail. 0219 /// 0220 /// \param[in] offset 0221 /// The offset where to encode the string. 0222 /// 0223 /// \param[in] cstr 0224 /// The string to encode. 0225 /// 0226 /// \return 0227 /// The next valid offset within data if the put operation was successful, 0228 /// else UINT32_MAX to indicate the put failed. 0229 uint32_t PutCString(uint32_t offset, const char *cstr); 0230 0231 /// Get a shared copy of the heap based memory buffer owned by this object. 0232 /// 0233 /// This allows a data encoder to be used to create a data buffer that can 0234 /// be extracted and used elsewhere after this object is destroyed. 0235 /// 0236 /// \return 0237 /// A shared pointer to the DataBufferHeap that contains the data that was 0238 /// encoded into this object. 0239 std::shared_ptr<lldb_private::DataBufferHeap> GetDataBuffer() { 0240 return m_data_sp; 0241 } 0242 0243 /// Get a access to the bytes that this references. 0244 /// 0245 /// This value will always return the data that this object references even if 0246 /// the object was constructed with caller owned data. 0247 /// 0248 /// \return 0249 /// A array reference to the data that this object references. 0250 llvm::ArrayRef<uint8_t> GetData() const; 0251 0252 /// Get the number of bytes contained in this object. 0253 /// 0254 /// \return 0255 /// The total number of bytes of data this object refers to. 0256 size_t GetByteSize() const; 0257 0258 lldb::ByteOrder GetByteOrder() const { return m_byte_order; } 0259 0260 /// The address size to use when encoding pointers or addresses. 0261 uint8_t GetAddressByteSize() const { return m_addr_size; } 0262 0263 private: 0264 uint32_t BytesLeft(uint32_t offset) const { 0265 const uint32_t size = GetByteSize(); 0266 if (size > offset) 0267 return size - offset; 0268 return 0; 0269 } 0270 0271 /// Test the availability of \a length bytes of data from \a offset. 0272 /// 0273 /// \return 0274 /// \b true if \a offset is a valid offset and there are \a 0275 /// length bytes available at that offset, \b false otherwise. 0276 bool ValidOffsetForDataOfSize(uint32_t offset, uint32_t length) const { 0277 return length <= BytesLeft(offset); 0278 } 0279 0280 /// Test the validity of \a offset. 0281 /// 0282 /// \return 0283 /// \b true if \a offset is a valid offset into the data in this 0284 /// object, \b false otherwise. 0285 bool ValidOffset(uint32_t offset) const { return offset < GetByteSize(); } 0286 0287 /// The shared pointer to data that can grow as data is added 0288 std::shared_ptr<lldb_private::DataBufferHeap> m_data_sp; 0289 0290 /// The byte order of the data we are encoding to. 0291 const lldb::ByteOrder m_byte_order; 0292 0293 /// The address size to use when encoding pointers or addresses. 0294 const uint8_t m_addr_size; 0295 0296 DataEncoder(const DataEncoder &) = delete; 0297 const DataEncoder &operator=(const DataEncoder &) = delete; 0298 }; 0299 0300 } // namespace lldb_private 0301 0302 #endif // LLDB_UTILITY_DATAENCODER_H
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|