1//===-- Stream.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_STREAM_H
10#define LLDB_UTILITY_STREAM_H
11
12#include "lldb/Utility/Flags.h"
13#include "lldb/lldb-defines.h"
14#include "lldb/lldb-enumerations.h"
15#include "llvm/ADT/StringRef.h"
16#include "llvm/Support/FormatVariadic.h"
17#include "llvm/Support/raw_ostream.h"
18
19#include <stdarg.h>
20#include <stddef.h>
21#include <stdint.h>
22#include <type_traits>
23
24namespace lldb_private {
25
26/// \class Stream Stream.h "lldb/Utility/Stream.h"
27/// A stream class that can stream formatted output to a file.
28class Stream {
29public:
30 /// \a m_flags bit values.
31 enum {
32 eBinary = (1 << 0) ///< Get and put data as binary instead of as the default
33 /// string mode.
34 };
35
36 /// Utility class for counting the bytes that were written to a stream in a
37 /// certain time span.
38 ///
39 /// \example
40 /// ByteDelta delta(*this);
41 /// WriteDataToStream("foo");
42 /// return *delta;
43 class ByteDelta {
44 Stream *m_stream;
45 /// Bytes we have written so far when ByteDelta was created.
46 size_t m_start;
47
48 public:
49 ByteDelta(Stream &s) : m_stream(&s), m_start(s.GetWrittenBytes()) {}
50 /// Returns the number of bytes written to the given Stream since this
51 /// ByteDelta object was created.
52 size_t operator*() const { return m_stream->GetWrittenBytes() - m_start; }
53 };
54
55 /// Construct with flags and address size and byte order.
56 ///
57 /// Construct with dump flags \a flags and the default address size. \a
58 /// flags can be any of the above enumeration logical OR'ed together.
59 Stream(uint32_t flags, uint32_t addr_size, lldb::ByteOrder byte_order,
60 bool colors = false);
61
62 /// Construct a default Stream, not binary, host byte order and host addr
63 /// size.
64 ///
65 Stream(bool colors = false);
66
67 // FIXME: Streams should not be copyable.
68 Stream(const Stream &other) : m_forwarder(*this) { (*this) = other; }
69
70 Stream &operator=(const Stream &rhs) {
71 m_flags = rhs.m_flags;
72 m_addr_size = rhs.m_addr_size;
73 m_byte_order = rhs.m_byte_order;
74 m_indent_level = rhs.m_indent_level;
75 return *this;
76 }
77
78 /// Destructor
79 virtual ~Stream();
80
81 // Subclasses must override these methods
82
83 /// Flush the stream.
84 ///
85 /// Subclasses should flush the stream to make any output appear if the
86 /// stream has any buffering.
87 virtual void Flush() = 0;
88
89 /// Output character bytes to the stream.
90 ///
91 /// Appends \a src_len characters from the buffer \a src to the stream.
92 ///
93 /// \param[in] src
94 /// A buffer containing at least \a src_len bytes of data.
95 ///
96 /// \param[in] src_len
97 /// A number of bytes to append to the stream.
98 ///
99 /// \return
100 /// The number of bytes that were appended to the stream.
101 size_t Write(const void *src, size_t src_len) {
102 size_t appended_byte_count = WriteImpl(src, src_len);
103 m_bytes_written += appended_byte_count;
104 return appended_byte_count;
105 }
106
107 size_t GetWrittenBytes() const { return m_bytes_written; }
108
109 // Member functions
110 size_t PutChar(char ch);
111
112 /// Set the byte_order value.
113 ///
114 /// Sets the byte order of the data to extract. Extracted values will be
115 /// swapped if necessary when decoding.
116 ///
117 /// \param[in] byte_order
118 /// The byte order value to use when extracting data.
119 ///
120 /// \return
121 /// The old byte order value.
122 lldb::ByteOrder SetByteOrder(lldb::ByteOrder byte_order);
123
124 /// Format a C string from a printf style format and variable arguments and
125 /// encode and append the resulting C string as hex bytes.
126 ///
127 /// \param[in] format
128 /// A printf style format string.
129 ///
130 /// \param[in] ...
131 /// Any additional arguments needed for the printf format string.
132 ///
133 /// \return
134 /// The number of bytes that were appended to the stream.
135 size_t PrintfAsRawHex8(const char *format, ...)
136 __attribute__((__format__(__printf__, 2, 3)));
137
138 /// Append an uint8_t value in the hexadecimal format to the stream.
139 ///
140 /// \param[in] uvalue
141 /// The value to append.
142 ///
143 /// \return
144 /// The number of bytes that were appended to the stream.
145 size_t PutHex8(uint8_t uvalue);
146
147 size_t PutNHex8(size_t n, uint8_t uvalue);
148
149 size_t PutHex16(uint16_t uvalue,
150 lldb::ByteOrder byte_order = lldb::eByteOrderInvalid);
151
152 size_t PutHex32(uint32_t uvalue,
153 lldb::ByteOrder byte_order = lldb::eByteOrderInvalid);
154
155 size_t PutHex64(uint64_t uvalue,
156 lldb::ByteOrder byte_order = lldb::eByteOrderInvalid);
157
158 size_t PutMaxHex64(uint64_t uvalue, size_t byte_size,
159 lldb::ByteOrder byte_order = lldb::eByteOrderInvalid);
160 size_t PutFloat(float f,
161 lldb::ByteOrder byte_order = lldb::eByteOrderInvalid);
162
163 size_t PutDouble(double d,
164 lldb::ByteOrder byte_order = lldb::eByteOrderInvalid);
165
166 size_t PutLongDouble(long double ld,
167 lldb::ByteOrder byte_order = lldb::eByteOrderInvalid);
168
169 size_t PutPointer(void *ptr);
170
171 // Append \a src_len bytes from \a src to the stream as hex characters (two
172 // ascii characters per byte of input data)
173 size_t
174 PutBytesAsRawHex8(const void *src, size_t src_len,
175 lldb::ByteOrder src_byte_order = lldb::eByteOrderInvalid,
176 lldb::ByteOrder dst_byte_order = lldb::eByteOrderInvalid);
177
178 // Append \a src_len bytes from \a s to the stream as binary data.
179 size_t PutRawBytes(const void *s, size_t src_len,
180 lldb::ByteOrder src_byte_order = lldb::eByteOrderInvalid,
181 lldb::ByteOrder dst_byte_order = lldb::eByteOrderInvalid);
182
183 size_t PutStringAsRawHex8(llvm::StringRef s);
184
185 /// Output a NULL terminated C string \a cstr to the stream \a s.
186 ///
187 /// \param[in] cstr
188 /// A NULL terminated C string.
189 ///
190 /// \return
191 /// A reference to this class so multiple things can be streamed
192 /// in one statement.
193 Stream &operator<<(const char *cstr);
194
195 Stream &operator<<(llvm::StringRef str);
196
197 /// Output a pointer value \a p to the stream \a s.
198 ///
199 /// \param[in] p
200 /// A void pointer.
201 ///
202 /// \return
203 /// A reference to this class so multiple things can be streamed
204 /// in one statement.
205 Stream &operator<<(const void *p);
206
207 /// Output a character \a ch to the stream \a s.
208 ///
209 /// \param[in] ch
210 /// A printable character value.
211 ///
212 /// \return
213 /// A reference to this class so multiple things can be streamed
214 /// in one statement.
215 Stream &operator<<(char ch);
216
217 Stream &operator<<(uint8_t uval) = delete;
218 Stream &operator<<(uint16_t uval) = delete;
219 Stream &operator<<(uint32_t uval) = delete;
220 Stream &operator<<(uint64_t uval) = delete;
221 Stream &operator<<(int8_t sval) = delete;
222 Stream &operator<<(int16_t sval) = delete;
223 Stream &operator<<(int32_t sval) = delete;
224 Stream &operator<<(int64_t sval) = delete;
225
226 /// Output a C string to the stream.
227 ///
228 /// Print a C string \a cstr to the stream.
229 ///
230 /// \param[in] cstr
231 /// The string to be output to the stream.
232 size_t PutCString(llvm::StringRef cstr);
233
234 /// Output and End of Line character to the stream.
235 size_t EOL();
236
237 /// Get the address size in bytes.
238 ///
239 /// \return
240 /// The size of an address in bytes that is used when outputting
241 /// address and pointer values to the stream.
242 uint32_t GetAddressByteSize() const;
243
244 /// The flags accessor.
245 ///
246 /// \return
247 /// A reference to the Flags member variable.
248 Flags &GetFlags();
249
250 /// The flags const accessor.
251 ///
252 /// \return
253 /// A const reference to the Flags member variable.
254 const Flags &GetFlags() const;
255
256 //// The byte order accessor.
257 ////
258 //// \return
259 //// The byte order.
260 lldb::ByteOrder GetByteOrder() const;
261
262 /// Get the current indentation level.
263 ///
264 /// \return
265 /// The current indentation level.
266 unsigned GetIndentLevel() const;
267
268 /// Indent the current line in the stream.
269 ///
270 /// Indent the current line using the current indentation level and print an
271 /// optional string following the indentation spaces.
272 ///
273 /// \param[in] s
274 /// A string to print following the indentation.
275 size_t Indent(llvm::StringRef s = "");
276
277 /// Decrement the current indentation level.
278 void IndentLess(unsigned amount = 2);
279
280 /// Increment the current indentation level.
281 void IndentMore(unsigned amount = 2);
282
283 /// Output an offset value.
284 ///
285 /// Put an offset \a uval out to the stream using the printf format in \a
286 /// format.
287 ///
288 /// \param[in] offset
289 /// The offset value.
290 ///
291 /// \param[in] format
292 /// The printf style format to use when outputting the offset.
293 void Offset(uint32_t offset, const char *format = "0x%8.8x: ");
294
295 /// Output printf formatted output to the stream.
296 ///
297 /// Print some formatted output to the stream.
298 ///
299 /// \param[in] format
300 /// A printf style format string.
301 ///
302 /// \param[in] ...
303 /// Variable arguments that are needed for the printf style
304 /// format string \a format.
305 size_t Printf(const char *format, ...) __attribute__((format(printf, 2, 3)));
306
307 size_t PrintfVarArg(const char *format, va_list args);
308
309 template <typename... Args> void Format(const char *format, Args &&... args) {
310 PutCString(llvm::formatv(format, std::forward<Args>(args)...).str());
311 }
312
313 /// Output a quoted C string value to the stream.
314 ///
315 /// Print a double quoted NULL terminated C string to the stream using the
316 /// printf format in \a format.
317 ///
318 /// \param[in] cstr
319 /// A NULL terminated C string value.
320 ///
321 /// \param[in] format
322 /// The optional C string format that can be overridden.
323 void QuotedCString(const char *cstr, const char *format = "\"%s\"");
324
325 /// Set the address size in bytes.
326 ///
327 /// \param[in] addr_size
328 /// The new size in bytes of an address to use when outputting
329 /// address and pointer values.
330 void SetAddressByteSize(uint32_t addr_size);
331
332 /// Set the current indentation level.
333 ///
334 /// \param[in] level
335 /// The new indentation level.
336 void SetIndentLevel(unsigned level);
337
338 /// Output a SLEB128 number to the stream.
339 ///
340 /// Put an SLEB128 \a uval out to the stream using the printf format in \a
341 /// format.
342 ///
343 /// \param[in] uval
344 /// A uint64_t value that was extracted as a SLEB128 value.
345 size_t PutSLEB128(int64_t uval);
346
347 /// Output a ULEB128 number to the stream.
348 ///
349 /// Put an ULEB128 \a uval out to the stream using the printf format in \a
350 /// format.
351 ///
352 /// \param[in] uval
353 /// A uint64_t value that was extracted as a ULEB128 value.
354 size_t PutULEB128(uint64_t uval);
355
356 /// Returns a raw_ostream that forwards the data to this Stream object.
357 llvm::raw_ostream &AsRawOstream() {
358 return m_forwarder;
359 }
360
361protected:
362 // Member variables
363 Flags m_flags; ///< Dump flags.
364 uint32_t m_addr_size; ///< Size of an address in bytes.
365 lldb::ByteOrder
366 m_byte_order; ///< Byte order to use when encoding scalar types.
367 unsigned m_indent_level; ///< Indention level.
368 std::size_t m_bytes_written = 0; ///< Number of bytes written so far.
369
370 void _PutHex8(uint8_t uvalue, bool add_prefix);
371
372 /// Output character bytes to the stream.
373 ///
374 /// Appends \a src_len characters from the buffer \a src to the stream.
375 ///
376 /// \param[in] src
377 /// A buffer containing at least \a src_len bytes of data.
378 ///
379 /// \param[in] src_len
380 /// A number of bytes to append to the stream.
381 ///
382 /// \return
383 /// The number of bytes that were appended to the stream.
384 virtual size_t WriteImpl(const void *src, size_t src_len) = 0;
385
386 /// \class RawOstreamForward Stream.h "lldb/Utility/Stream.h"
387 /// This is a wrapper class that exposes a raw_ostream interface that just
388 /// forwards to an LLDB stream, allowing to reuse LLVM algorithms that take
389 /// a raw_ostream within the LLDB code base.
390 class RawOstreamForward : public llvm::raw_ostream {
391 // Note: This stream must *not* maintain its own buffer, but instead
392 // directly write everything to the internal Stream class. Without this,
393 // we would run into the problem that the Stream written byte count would
394 // differ from the actually written bytes by the size of the internal
395 // raw_ostream buffer.
396
397 Stream &m_target;
398 void write_impl(const char *Ptr, size_t Size) override {
399 m_target.Write(Ptr, Size);
400 }
401
402 uint64_t current_pos() const override {
403 return m_target.GetWrittenBytes();
404 }
405
406 public:
407 RawOstreamForward(Stream &target, bool colors = false)
408 : llvm::raw_ostream(/*unbuffered*/ true), m_target(target) {
409 enable_colors(colors);
410 }
411 };
412 RawOstreamForward m_forwarder;
413};
414
415/// Output an address value to this stream.
416///
417/// Put an address \a addr out to the stream with optional \a prefix and \a
418/// suffix strings.
419///
420/// \param[in] s
421/// The output stream.
422///
423/// \param[in] addr
424/// An address value.
425///
426/// \param[in] addr_size
427/// Size in bytes of the address, used for formatting.
428///
429/// \param[in] prefix
430/// A prefix C string. If nullptr, no prefix will be output.
431///
432/// \param[in] suffix
433/// A suffix C string. If nullptr, no suffix will be output.
434void DumpAddress(llvm::raw_ostream &s, uint64_t addr, uint32_t addr_size,
435 const char *prefix = nullptr, const char *suffix = nullptr);
436
437/// Output an address range to this stream.
438///
439/// Put an address range \a lo_addr - \a hi_addr out to the stream with
440/// optional \a prefix and \a suffix strings.
441///
442/// \param[in] s
443/// The output stream.
444///
445/// \param[in] lo_addr
446/// The start address of the address range.
447///
448/// \param[in] hi_addr
449/// The end address of the address range.
450///
451/// \param[in] addr_size
452/// Size in bytes of the address, used for formatting.
453///
454/// \param[in] prefix
455/// A prefix C string. If nullptr, no prefix will be output.
456///
457/// \param[in] suffix
458/// A suffix C string. If nullptr, no suffix will be output.
459void DumpAddressRange(llvm::raw_ostream &s, uint64_t lo_addr, uint64_t hi_addr,
460 uint32_t addr_size, const char *prefix = nullptr,
461 const char *suffix = nullptr);
462
463} // namespace lldb_private
464
465#endif // LLDB_UTILITY_STREAM_H
466