pw_hex_dump#

Pigweed AI summary: The article discusses the use of print statements to view memory contents on embedded systems when debugging issues. The article introduces pw_hex_dump, a toolbox that provides utilities to dump data as hex to debug issues. The article explains the two main components of pw_hex_dump: DumpAddr() and FormattedHexDumper. The article provides examples of how to use FormattedHexDumper to dump hex in various formats. The article also lists the dependencies of pw_hex_dump.

Sometimes on embedded systems there’s a desire to view memory contents when debugging various issues. While in some cases this can be done by attaching an in-circuit debugger of some kind, form-factor hardware might not have this as an option due to size constraints. Additionally, there’s often quite a bit more setup involved than simply adding a print statement.

A common practice to address this is setting up print statements that dump data as logs when a certain event occurs. There’s often value to formatting these dumps as human readable key-value pairs, but sometimes there’s a need to see the raw binary data in different ways. This can help validate in memory/on flash binary structure of stored data, among other things.

pw_hex_dump is a handy toolbox that provides utilities to help dump data as hex to debug issues. Unless otherwise specified, avoid depending directly on the formatting of the output as it may change (unless otherwise specified). With that said, the FormattedHexDumper strives to be xxd compatible by default.

DumpAddr()#

Pigweed AI summary: The DumpAddr() function dumps the value of a pointer or size_t as a hex string to a provided destination buffer. This is necessary because printf's %p or %zx format specifiers are not universally available in all embedded libc implementations. The function aims to be as portable as possible and the output format is expected to be stable.

Dumps the value of a pointer (or size_t) as a hex string to a provided destination buffer. While this sounds redundant to printf’s %p or %zx, those format specifiers are not universally available in all embedded libc implementations. The goal is for this to be as portable as possible.

The output format for this function is expected to be stable.

FormattedHexDumper#

Pigweed AI summary: The FormattedHexDumper is a configurable class that can dump hex in various formats, with the default output being xxd compatible. There are options to adjust the output, such as address prefixing where the base memory address of each line is used instead of an offset. The article provides examples of different output formats, including groupings and prefix modes. The usage of the class is also demonstrated with a code example that prints the output.

The formatted hex dumper is a configurable class that can dump hex in various formats. The default produced output is xxd compatible, though there are options to further adjust the output. One example is address prefixing, where base memory address of each line is used instead of an offset.

Examples#

Pigweed AI summary: This is a technical document that provides examples of different ways to display hexadecimal data. The examples include different groupings of bytes, prefix modes, and bytes per line. The document includes three examples with corresponding hexadecimal data and their respective displays.

Default:

Offs.  0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F  Text
0000: A4 CC 32 62 9B 46 38 1A 23 1A 2A 7A BC E2 40 A0  ..2b.F8.#.*z..@.
0010: FF 33 E5 2B 9E 9F 6B 3C BE 9B 89 3C 7E 4A 7A 48  .3.+..k<...<~JzH
0020: 18                                               .

Example 1: (32-bit machine, group_every=4, prefix_mode=kAbsolute, bytes_per_line = 8)

Address      0        4        Text
0x20000000: A4CC3262 9B46381A  ..2b.F8.
0x20000008: 231A2A7A BCE240A0  #.*z..@.
0x20000010: FF33E52B 9E9F6B3C  .3.+..k<
0x20000018: BE9B893C 7E4A7A48  ...<~JzH
0x20000020: 18                 .

Example 2: (group_every=1, bytes_per_line = 16)

Offs.  0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
0000: A4 CC 32 62 9B 46 38 1A 23 1A 2A 7A BC E2 40 A0
0010: FF 33 E5 2B 9E 9F 6B 3C BE 9B 89 3C 7E 4A 7A 48
0020: 18

Example 3: (group_every=0, prefix_mode=kNone, show_header=false, show_ascii=false)

A4CC32629B46381A231A2A7ABCE240A0
FF33E52B9E9F6B3CBE9B893C7E4A7A48
18

Usage#

Pigweed AI summary: This section provides an example of how to use a class called FormattedHexDumper in C++. The example shows how to initialize the class, hide ASCII characters, begin the dumping process, and print the output. The output is a formatted hexadecimal dump of data.

Here’s an example of how this class might be used:

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

Which prints:

Offs.  0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
0000: A4 CC 32 62 9B 46 38 1A 23 1A 2A 7A BC E2 40 A0
0010: FF 33 E5 2B 9E 9F 6B 3C BE 9B 89 3C 7E 4A 7A 48
0020: 18

Dependencies#

Pigweed AI summary: This section lists the dependencies of the project, which include pw_bytes, pw_span, and pw_status.

  • pw_bytes

  • pw_span

  • pw_status