pw_hex_dump

Oveview

Handy hexdump utilities. Main docs: https://pigweed.dev/pw_hex_dump.

Classes
class	pw::dump::FormattedHexDumper
struct	pw::dump::FormattedHexDumper::Flags

Enumerations
enum	AddressMode { kDisabled = 0 , kOffset = 1 , kAbsolute = 2 }

Functions
	pw::dump::FormattedHexDumper::FormattedHexDumper (span< char > dest)
	pw::dump::FormattedHexDumper::FormattedHexDumper (span< char > dest, Flags config_flags)
Status	pw::dump::FormattedHexDumper::SetLineBuffer (span< char > dest)
Status	pw::dump::FormattedHexDumper::BeginDump (ConstByteSpan data)
Status	pw::dump::FormattedHexDumper::DumpLine ()
Status	pw::dump::DumpAddr (span< char > dest, uintptr_t addr)
Status	pw::dump::DumpAddr (span< char > dest, const void *ptr)
template<std::size_t kBytesPerLine = 16>
void	pw::dump::LogBytes (int log_level, pw::ConstByteSpan bytes)

Variables
constexpr const size_t	pw::dump::kHexAddrStringSize = sizeof(uintptr_t) * 2 + 2
uint8_t	pw::dump::FormattedHexDumper::Flags::bytes_per_line: 8
	Sets the number of source data bytes to print in each formatted line.
uint8_t	pw::dump::FormattedHexDumper::Flags::group_every: 8
bool	pw::dump::FormattedHexDumper::Flags::show_ascii: 1
	Show or hide ascii interpretation of binary data.
bool	pw::dump::FormattedHexDumper::Flags::show_header: 1
	Show descriptive column headers.
AddressMode	pw::dump::FormattedHexDumper::Flags::prefix_mode: 2
	Prefix each line of the dump with an offset or absolute address.
Flags	pw::dump::FormattedHexDumper::flags

Function Documentation

BeginDump()

Status pw::dump::FormattedHexDumper::BeginDump

(

ConstByteSpan

data

)

Begin dumping the provided data. Does NOT populate the line buffer with a string, simply resets the statefulness to track this buffer.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*    OK: Ready to begin dump.
* 
*    INVALID_ARGUMENT: The source data starts at null, but has been set.
* 
*    FAILED_PRECONDITION: Line buffer too small to hold current formatting
*    settings.
* 
*  

DumpAddr()

Status pw::dump::DumpAddr	(	span< char >	dest,
		uintptr_t	addr
	)

Dumps a uintptr_t to a character buffer as a hex address. This may be useful to print out an address in a generalized way when z and p aren't supported by a standard library implementation. The destination buffer MUST be large enough to hold kHexAddrStringSize + 1 (null terminator) bytes.

Example (64-bit):

0x000000000022b698

Example (32-bit):

0x70000000

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*    OK: Address has been written to the buffer.
* 
*    INVALID_ARGUMENT: The destination buffer is invalid (nullptr).
* 
*    RESOURCE_EXHAUSTED: The destination buffer is too small. No data written.
* 
*  

DumpLine()

Status pw::dump::FormattedHexDumper::DumpLine

(

)

Dumps a single line to the line buffer.

Example usage:

std::array<char, 80> temp;
FormattedHexDumper hex_dumper(temp);
hex_dumper.BeginDump(my_data);
while(hex_dumper.DumpLine().ok()) {
  LOG_INFO("%s", temp.data());
}

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*    OK:  A line has been written to the line buffer.
* 
*    RESOURCE_EXHAUSTED:  All the data has been dumped.
* 
*    FAILED_PRECONDITION:  Destination line buffer is too small to fit
*    current formatting configuration.
* 
*  

LogBytes()

template<std::size_t kBytesPerLine = 16>

void pw::dump::LogBytes ( int  log_level, pw::ConstByteSpan  bytes  )

inline

Helper to log human-readable hex dumps to console.

Example:

std::array<const std::byte, 9> my_data = {
  std::byte('h'),
  std::byte('e'),
  std::byte('l'),
  std::byte('l'),
  std::byte('o'),
  std::byte(0xde),
  std::byte(0xad),
  std::byte(0xbe),
  std::byte(0xef),
};
 
LogBytes(PW_LOG_LEVEL_DEBUG, my_data);

DBG  0000: 68 65 6c 6c 6f de ad be ef                       hello....

To print other data types, obtain a ConstByteSpan view first:

LogBytes(PW_LOG_LEVEL_DEBUG, pw::as_bytes(pw::span("world!")));

DBG  0000: 77 6f 72 6c 64 21 00                             world!.

Use template arguments to modify the number of bytes printed per line:

LogBytes<8>(PW_LOG_LEVEL_DEBUG, pw::as_bytes(pw::span("hello world!")));

DBG  0000: 68 65 6c 6c 6f 20 77 6f  hello wo
DBG  0008: 72 6c 64 21 00           rld!.

Template Parameters

kBytesPerLine

The number of input bytes to display per line. Defaults to 16.

Parameters

[in]	log_level	The PW_LOG_LEVEL to log at.
[in]	bytes	The data to log.

SetLineBuffer()

Status pw::dump::FormattedHexDumper::SetLineBuffer

(

span< char >

dest

)

Set the destination buffer that the hex dumper will write to line-by-line.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*    RESOURCE_EXHAUSTED: The buffer was set, but is too small to fit the
*    current formatting configuration.
* 
*    INVALID_ARGUMENT: The destination buffer is invalid (nullptr or zero-
*    length).
* 
*  

Variable Documentation

flags

Flags pw::dump::FormattedHexDumper::flags

Initial value:

= {.bytes_per_line = 16,
                 .group_every = 1,
                 .show_ascii = true,
                 .show_header = true,
                 .prefix_mode = AddressMode::kOffset}

group_every

uint8_t pw::dump::FormattedHexDumper::Flags::group_every

Inserts a space every N bytes for readability. Note that this is in number of bytes converted to characters. Set to zero to disable.

i.e. a value of 2 results in:

0x00000000: 0102 0304 0506 0708

kHexAddrStringSize

constexpr const size_t pw::dump::kHexAddrStringSize = sizeof(uintptr_t) * 2 + 2

inlineconstexpr

Size, in bytes, of the resulting string after converting an address to a UTF-8 encoded hex representation. This constant depends on the size a of a pointer.

Example (32-bit): 0x0000F00D

Note: the +2 accounts for the "0x" prefix.