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