Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 1 | .. _module-pw_hex_dump: |
Armando Montanez | 593d0d5 | 2020-07-08 19:55:01 -0700 | [diff] [blame] | 2 | |
| 3 | ----------- |
| 4 | pw_hex_dump |
| 5 | ----------- |
| 6 | Sometimes on embedded systems there's a desire to view memory contents when |
| 7 | debugging various issues. While in some cases this can be done by attaching an |
| 8 | in-circuit debugger of some kind, form-factor hardware might not have this as an |
| 9 | option due to size constraints. Additionally, there's often quite a bit more |
| 10 | setup involved than simply adding a print statement. |
| 11 | |
| 12 | A common practice to address this is setting up print statements that dump data |
| 13 | as logs when a certain event occurs. There's often value to formatting these |
| 14 | dumps as human readable key-value pairs, but sometimes there's a need to see the |
| 15 | raw binary data in different ways. This can help validate in memory/on flash |
| 16 | binary structure of stored data, among other things. |
| 17 | |
| 18 | ``pw_hex_dump`` is a handy toolbox that provides utilities to help dump data as |
| 19 | hex to debug issues. Unless otherwise specified, avoid depending directly on the |
| 20 | formatting of the output as it may change (unless otherwise specified). With |
| 21 | that said, the ``FormattedHexDumper`` strives to be xxd compatible by default. |
| 22 | |
| 23 | DumpAddr() |
| 24 | ========== |
| 25 | Dumps the value of a pointer (or size_t) as a hex string to a provided |
| 26 | destination buffer. While this sounds redundant to printf's %p or %zx, those |
| 27 | format specifiers are not universally available in all embedded libc |
| 28 | implementations. The goal is for this to be as portable as possible. |
| 29 | |
| 30 | The output format for this function is expected to be stable. |
| 31 | |
| 32 | FormattedHexDumper |
| 33 | ================== |
| 34 | The formatted hex dumper is a configurable class that can dump hex in various |
| 35 | formats. The default produced output is xxd compatible, though there are options |
| 36 | to further adjust the output. One example is address prefixing, where base |
| 37 | memory address of each line is used instead of an offset. |
| 38 | |
| 39 | Examples |
| 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 | |
| 83 | Usage |
| 84 | ----- |
| 85 | Here'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 | |
| 97 | Which 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 | |
| 106 | Dependencies |
| 107 | ============ |
| 108 | * pw_bytes |
| 109 | * pw_span |
Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 110 | * pw_status |