third_party/pigweed/repo/pw_allocator/docs.rst

   1 .. _module-pw_allocator:
   2
   3 ------------
   4 pw_allocator
   5 ------------
   6
   7 This module provides various building blocks
   8 for a dynamic allocator. This is composed of the following parts:
   9
  10  - ``block``: An implementation of a linked list of memory blocks, supporting
  11    splitting and merging of blocks.
  12  - ``freelist``: A freelist, suitable for fast lookups of available memory
  13    chunks (i.e. ``block`` s).
  14
  15 Heap Integrity Check
  16 ====================
  17 The ``Block`` class provides two sanity check functions:
  18
  19   - ``bool Block::IsValid()``: Returns ``true`` is the given block is valid
  20     and ``false`` otherwise.
  21   - ``void Block::CrashIfInvalid()``: Crash the program and output the reason
  22     why sanity check fails using ``PW_DCHECK``.
  23
  24 Heap Poisoning
  25 ==============
  26
  27 By default, this module disables heap poisoning since it requires extra space.
  28 User can enable heap poisoning by enabling the ``pw_allocator_POISON_HEAP``
  29 build arg.
  30
  31 .. code:: sh
  32
  33   $ gn args out
  34   # Modify and save the args file to use heap poison.
  35   pw_allocator_POISON_HEAP = true
  36
  37 When heap poisoning is enabled, ``pw_allocator`` will add ``sizeof(void*)``
  38 bytes before and after the usable space of each ``Block``, and paint the space
  39 with a hard-coded randomized pattern. During each sanity check, ``pw_allocator``
  40 will check if the painted space still remains the pattern, and return ``false``
  41 if the pattern is damaged.
  42
  43 Heap Visualizer
  44 ===============
  45
  46 Functionality
  47 -------------
  48
  49 ``pw_allocator`` supplies a pw command ``pw heap-viewer`` to help visualize
  50 the state of the heap at the end of a dump file. The heap is represented by
  51 ASCII characters, where each character represents 4 bytes in the heap.
  52
  53 .. image:: doc_resources/pw_allocator_heap_visualizer_demo.png
  54
  55 Usage
  56 -----
  57
  58 The heap visualizer can be launched from a shell using the Pigweed environment.
  59
  60 .. code:: sh
  61
  62   $ pw heap-viewer --dump-file <directory of dump file> --heap-low-address
  63   <hex address of heap lower address> --heap-high-address <hex address of heap
  64   lower address> [options]
  65
  66 The required arguments are:
  67
  68   - ``--dump-file`` is the path of a file that contains ``malloc/free``
  69     information. Each line in the dump file represents a ``malloc/free`` call.
  70     ``malloc`` is represented as ``m <size> <memory address>`` and ``free`` is
  71     represented as ``f <memory address>``. For example, a dump file should look
  72     like:
  73
  74       .. code:: sh
  75
  76         m 20 0x20004450  # malloc 20 bytes, the pointer is 0x20004450
  77         m 8 0x2000447c   # malloc 8 bytes, the pointer is 0x2000447c
  78         f 0x2000447c     # free the pointer at 0x2000447c
  79         ...
  80
  81       Any line not formatted as the above will be ignored.
  82
  83   - ``--heap-low-address`` is the start of the heap. For example:
  84
  85       .. code:: sh
  86
  87         --heap-low-address 0x20004440
  88
  89   - ``--heap-high-address`` is the end of the heap. For example:
  90
  91       .. code:: sh
  92
  93         --heap-high-address 0x20006040
  94
  95 Options include the following:
  96
  97   - ``--poison-enable``: If heap poisoning is enabled during the
  98     allocation or not. The value is ``False`` if the option is not specified and
  99     ``True`` otherwise.
 100
 101   - ``--pointer-size <integer of pointer size>``: The size of a pointer on the
 102     machine where ``malloc/free`` is called. The default value is ``4``.
 103
 104 Note, this module, and its documentation, is currently incomplete and
 105 experimental.