1.. _module-pw_hex_dump:
2
3-----------
4pw_hex_dump
5-----------
6Sometimes on embedded systems there's a desire to view memory contents when
7debugging various issues. While in some cases this can be done by attaching an
8in-circuit debugger of some kind, form-factor hardware might not have this as an
9option due to size constraints. Additionally, there's often quite a bit more
10setup involved than simply adding a print statement.
11
12A common practice to address this is setting up print statements that dump data
13as logs when a certain event occurs. There's often value to formatting these
14dumps as human readable key-value pairs, but sometimes there's a need to see the
15raw binary data in different ways. This can help validate in memory/on flash
16binary structure of stored data, among other things.
17
18``pw_hex_dump`` is a handy toolbox that provides utilities to help dump data as
19hex to debug issues. Unless otherwise specified, avoid depending directly on the
20formatting of the output as it may change (unless otherwise specified). With
21that said, the ``FormattedHexDumper`` strives to be xxd compatible by default.
22
23DumpAddr()
24==========
25Dumps the value of a pointer (or size_t) as a hex string to a provided
26destination buffer. While this sounds redundant to printf's %p or %zx, those
27format specifiers are not universally available in all embedded libc
28implementations. The goal is for this to be as portable as possible.
29
30The output format for this function is expected to be stable.
31
32FormattedHexDumper
33==================
34The formatted hex dumper is a configurable class that can dump hex in various
35formats. The default produced output is xxd compatible, though there are options
36to further adjust the output. One example is address prefixing, where base
37memory address of each line is used instead of an offset.
38
39Examples
40--------
41
42**Default:**
43
44.. code-block:: none
45
46  Offs.  0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F  Text
47  0000: A4 CC 32 62 9B 46 38 1A 23 1A 2A 7A BC E2 40 A0  ..2b.F8.#.*z..@.
48  0010: FF 33 E5 2B 9E 9F 6B 3C BE 9B 89 3C 7E 4A 7A 48  .3.+..k<...<~JzH
49  0020: 18                                               .
50
51**Example 1:**
52(32-bit machine, group_every=4, prefix_mode=kAbsolute, bytes_per_line = 8)
53
54.. code-block:: none
55
56  Address      0        4        Text
57  0x20000000: A4CC3262 9B46381A  ..2b.F8.
58  0x20000008: 231A2A7A BCE240A0  #.*z..@.
59  0x20000010: FF33E52B 9E9F6B3C  .3.+..k<
60  0x20000018: BE9B893C 7E4A7A48  ...<~JzH
61  0x20000020: 18                 .
62
63**Example 2:**
64(group_every=1, bytes_per_line = 16)
65
66.. code-block:: none
67
68  Offs.  0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
69  0000: A4 CC 32 62 9B 46 38 1A 23 1A 2A 7A BC E2 40 A0
70  0010: FF 33 E5 2B 9E 9F 6B 3C BE 9B 89 3C 7E 4A 7A 48
71  0020: 18
72
73**Example 3:**
74(group_every=0, prefix_mode=kNone, show_header=false, show_ascii=false)
75
76.. code-block:: none
77
78  A4CC32629B46381A231A2A7ABCE240A0
79  FF33E52B9E9F6B3CBE9B893C7E4A7A48
80  18
81
82
83Usage
84-----
85Here's an example of how this class might be used:
86
87.. code-block:: cpp
88
89  std::array<char, 80> temp;
90  FormattedHexDumper hex_dumper(temp);
91  hex_dumper.HideAscii();
92  hex_dumper.BeginDump(my_data);
93  while(hex_dumper.DumpLine().ok()) {
94    LOG_INFO("%s", temp.data());
95  }
96
97Which prints:
98
99.. code-block:: none
100
101  Offs.  0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
102  0000: A4 CC 32 62 9B 46 38 1A 23 1A 2A 7A BC E2 40 A0
103  0010: FF 33 E5 2B 9E 9F 6B 3C BE 9B 89 3C 7E 4A 7A 48
104  0020: 18
105
106Dependencies
107============
108* pw_bytes
109* pw_span
110* pw_status
111