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