third_party/pigweed/repo/pw_hex_dump/docs.rst

   1 .. _module-pw_hex_dump:
   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
 110 * pw_status