Coverage Report

Created: 2022-01-18 06:27

/Users/buildslave/jenkins/workspace/coverage/llvm-project/lldb/include/lldb/Utility/DataEncoder.h
Line
Count
Source
1
//===-- DataEncoder.h -------------------------------------------*- C++ -*-===//
2
//
3
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4
// See https://llvm.org/LICENSE.txt for license information.
5
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6
//
7
//===----------------------------------------------------------------------===//
8
9
#ifndef LLDB_UTILITY_DATAENCODER_H
10
#define LLDB_UTILITY_DATAENCODER_H
11
12
#if defined(__cplusplus)
13
14
#include "lldb/lldb-defines.h"
15
#include "lldb/lldb-enumerations.h"
16
#include "lldb/lldb-forward.h"
17
#include "lldb/lldb-types.h"
18
19
#include "llvm/ADT/ArrayRef.h"
20
#include "llvm/ADT/StringRef.h"
21
22
#include <cstddef>
23
#include <cstdint>
24
25
namespace lldb_private {
26
27
/// \class DataEncoder
28
///
29
/// An binary data encoding class.
30
///
31
/// DataEncoder is a class that can encode binary data (swapping if needed) to
32
/// a data buffer. The DataEncoder can be constructed with data that will be
33
/// copied into the internally owned buffer. This allows data to be modified
34
/// in the internal buffer. The DataEncoder object can also be constructed with
35
/// just a byte order and address size and data can be appended to the
36
/// internally owned buffer.
37
///
38
/// Clients can get a shared pointer to the data buffer when done modifying or
39
/// creating the data to keep the data around after the lifetime of a
40
/// DataEncoder object. \see GetDataBuffer
41
///
42
/// Client can get a reference to the object owned data as an array by calling
43
/// the GetData method. \see GetData
44
class DataEncoder {
45
public:
46
  /// Default constructor.
47
  ///
48
  /// Initialize all members to a default empty state and create a empty memory
49
  /// buffer that can be appended to. The ByteOrder and address size will be set
50
  /// to match the current host system.
51
  DataEncoder();
52
53
  /// Construct an encoder that copies the specified data into the object owned
54
  /// data buffer.
55
  ///
56
  /// This constructor is designed to be used when you have a data buffer and
57
  /// want to modify values within the buffer. A copy of the data will be made
58
  /// in the internally owned buffer and that data can be fixed up and appended
59
  /// to.
60
  ///
61
  /// \param[in] data
62
  ///     A pointer to caller owned data.
63
  ///
64
  /// \param[in] data_length
65
  ///     The length in bytes of \a data.
66
  ///
67
  /// \param[in] byte_order
68
  ///     A byte order for the data that will be encoded.
69
  ///
70
  /// \param[in] addr_size
71
  ///     A size of an address in bytes. \see PutAddress, AppendAddress
72
  DataEncoder(const void *data, uint32_t data_length,
73
              lldb::ByteOrder byte_order, uint8_t addr_size);
74
75
  /// Construct an encoder that owns a heap based memory buffer.
76
  ///
77
  /// This allows clients to create binary data from scratch by appending values
78
  /// with the methods that start with "Append".
79
  ///
80
  /// \param[in] byte_order
81
  ///     A byte order for the data that will be encoded.
82
  ///
83
  /// \param[in] addr_size
84
  ///     A size of an address in bytes. \see PutAddress, AppendAddress
85
  DataEncoder(lldb::ByteOrder byte_order, uint8_t addr_size);
86
87
  ~DataEncoder();
88
89
  /// Encode an unsigned integer of size \a byte_size to \a offset.
90
  ///
91
  /// Encode a single integer value at \a offset and return the offset that
92
  /// follows the newly encoded integer when the data is successfully encoded
93
  /// into the existing data. There must be enough room in the existing data,
94
  /// else UINT32_MAX will be returned to indicate that encoding failed.
95
  ///
96
  /// \param[in] offset
97
  ///     The offset within the contained data at which to put the encoded
98
  ///     integer.
99
  ///
100
  /// \param[in] byte_size
101
  ///     The size in byte of the integer to encode.
102
  ///
103
  /// \param[in] value
104
  ///     The integer value to write. The least significant bytes of
105
  ///     the integer value will be written if the size is less than
106
  ///     8 bytes.
107
  ///
108
  /// \return
109
  ///     The next offset in the bytes of this data if the integer
110
  ///     was successfully encoded, UINT32_MAX if the encoding failed.
111
  uint32_t PutUnsigned(uint32_t offset, uint32_t byte_size, uint64_t value);
112
113
  /// Encode an unsigned integer at offset \a offset.
114
  ///
115
  /// Encode a single unsigned integer value at \a offset and return the offset
116
  /// that follows the newly encoded integer when the data is successfully
117
  /// encoded into the existing data. There must be enough room in the data,
118
  /// else UINT32_MAX will be returned to indicate that encoding failed.
119
  ///
120
  /// \param[in] offset
121
  ///     The offset within the contained data at which to put the encoded
122
  ///     integer.
123
  ///
124
  /// \param[in] value
125
  ///     The integer value to write.
126
  ///
127
  /// \return
128
  ///     The next offset in the bytes of this data if the integer was
129
  ///     successfully encoded, UINT32_MAX if the encoding failed.
130
  uint32_t PutU8(uint32_t offset, uint8_t value);
131
  uint32_t PutU16(uint32_t offset, uint16_t value);
132
  uint32_t PutU32(uint32_t offset, uint32_t value);
133
  uint32_t PutU64(uint32_t offset, uint64_t value);
134
135
  /// Append a unsigned integer to the end of the owned data.
136
  ///
137
  /// \param value
138
  ///   A unsigned integer value to append.
139
  void AppendU8(uint8_t value);
140
  void AppendU16(uint16_t value);
141
  void AppendU32(uint32_t value);
142
  void AppendU64(uint64_t value);
143
144
  /// Append an address sized integer to the end of the owned data.
145
  ///
146
  /// \param addr
147
  ///    A unsigned integer address value to append. The size of the address
148
  ///    will be determined by the address size specified in the constructor.
149
  void AppendAddress(lldb::addr_t addr);
150
151
  /// Append a bytes to the end of the owned data.
152
  ///
153
  /// Append the bytes contained in the string reference. This function will
154
  /// not append a NULL termination character for a C string. Use the
155
  /// AppendCString function for this purpose.
156
  ///
157
  /// \param data
158
  ///     A string reference that contains bytes to append.
159
  void AppendData(llvm::StringRef data);
160
161
  /// Append a bytes to the end of the owned data.
162
  ///
163
  /// Append the bytes contained in the array reference.
164
  ///
165
  /// \param data
166
  ///     A array reference that contains bytes to append.
167
  void AppendData(llvm::ArrayRef<uint8_t> data);
168
169
  /// Append a C string to the end of the owned data.
170
  ///
171
  /// Append the bytes contained in the string reference along with an extra
172
  /// NULL termination character if the StringRef bytes doesn't include one as
173
  /// the last byte.
174
  ///
175
  /// \param data
176
  ///     A string reference that contains bytes to append.
177
  void AppendCString(llvm::StringRef data);
178
179
  /// Encode an arbitrary number of bytes.
180
  ///
181
  /// \param[in] offset
182
  ///     The offset in bytes into the contained data at which to
183
  ///     start encoding.
184
  ///
185
  /// \param[in] src
186
  ///     The buffer that contains the bytes to encode.
187
  ///
188
  /// \param[in] src_len
189
  ///     The number of bytes to encode.
190
  ///
191
  /// \return
192
  ///     The next valid offset within data if the put operation
193
  ///     was successful, else UINT32_MAX to indicate the put failed.
194
  uint32_t PutData(uint32_t offset, const void *src, uint32_t src_len);
195
196
  /// Encode an address in the existing buffer at \a offset bytes into the
197
  /// buffer.
198
  ///
199
  /// Encode a single address to the data and return the next offset where
200
  /// subsequent data would go. The size of the address comes from the \a
201
  /// m_addr_size member variable and should be set correctly prior to encoding
202
  /// any address values.
203
  ///
204
  /// \param[in] offset
205
  ///     The offset where to encode the address.
206
  ///
207
  /// \param[in] addr
208
  ///     The address to encode.
209
  ///
210
  /// \return
211
  ///     The next valid offset within data if the put operation
212
  ///     was successful, else UINT32_MAX to indicate the put failed.
213
  uint32_t PutAddress(uint32_t offset, lldb::addr_t addr);
214
215
  /// Put a C string to \a offset.
216
  ///
217
  /// Encodes a C string into the existing data including the terminating. If
218
  /// there is not enough room in the buffer to fit the entire C string and the
219
  /// NULL terminator in the existing buffer bounds, then this function will
220
  /// fail.
221
  ///
222
  /// \param[in] offset
223
  ///     The offset where to encode the string.
224
  ///
225
  /// \param[in] cstr
226
  ///     The string to encode.
227
  ///
228
  /// \return
229
  ///     The next valid offset within data if the put operation was successful,
230
  ///     else UINT32_MAX to indicate the put failed.
231
  uint32_t PutCString(uint32_t offset, const char *cstr);
232
233
  /// Get a shared copy of the heap based memory buffer owned by this object.
234
  ///
235
  /// This allows a data encoder to be used to create a data buffer that can
236
  /// be extracted and used elsewhere after this object is destroyed.
237
  ///
238
  /// \return
239
  ///     A shared pointer to the DataBufferHeap that contains the data that was
240
  ///     encoded into this object.
241
755
  std::shared_ptr<lldb_private::DataBufferHeap> GetDataBuffer() {
242
755
    return m_data_sp;
243
755
  }
244
245
  /// Get a access to the bytes that this references.
246
  ///
247
  /// This value will always return the data that this object references even if
248
  /// the object was constructed with caller owned data.
249
  ///
250
  /// \return
251
  ///     A array reference to the data that this object references.
252
  llvm::ArrayRef<uint8_t> GetData() const;
253
254
  /// Get the number of bytes contained in this object.
255
  ///
256
  /// \return
257
  ///     The total number of bytes of data this object refers to.
258
  size_t GetByteSize() const;
259
260
34
  lldb::ByteOrder GetByteOrder() const { return m_byte_order; }
261
262
  /// The address size to use when encoding pointers or addresses.
263
34
  uint8_t GetAddressByteSize() const { return m_addr_size; }
264
265
private:
266
1.90k
  uint32_t BytesLeft(uint32_t offset) const {
267
1.90k
    const uint32_t size = GetByteSize();
268
1.90k
    if (size > offset)
269
1.89k
      return size - offset;
270
10
    return 0;
271
1.90k
  }
272
273
  /// Test the availability of \a length bytes of data from \a offset.
274
  ///
275
  /// \return
276
  ///     \b true if \a offset is a valid offset and there are \a
277
  ///     length bytes available at that offset, \b false otherwise.
278
1.90k
  bool ValidOffsetForDataOfSize(uint32_t offset, uint32_t length) const {
279
1.90k
    return length <= BytesLeft(offset);
280
1.90k
  }
281
282
  /// Test the validity of \a offset.
283
  ///
284
  /// \return
285
  ///     \b true if \a offset is a valid offset into the data in this
286
  ///     object, \b false otherwise.
287
17
  bool ValidOffset(uint32_t offset) const { return offset < GetByteSize(); }
288
289
  /// The shared pointer to data that can grow as data is added
290
  std::shared_ptr<lldb_private::DataBufferHeap> m_data_sp;
291
292
  /// The byte order of the data we are encoding to.
293
  const lldb::ByteOrder m_byte_order;
294
295
  /// The address size to use when encoding pointers or addresses.
296
  const uint8_t m_addr_size;
297
298
  DataEncoder(const DataEncoder &) = delete;
299
  const DataEncoder &operator=(const DataEncoder &) = delete;
300
};
301
302
} // namespace lldb_private
303
304
#endif // #if defined (__cplusplus)
305
#endif // LLDB_UTILITY_DATAENCODER_H