1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
|
.. _module-pw_allocator:
------------
pw_allocator
------------
This module provides various building blocks
for a dynamic allocator. This is composed of the following parts:
- ``block``: An implementation of a linked list of memory blocks, supporting
splitting and merging of blocks.
- ``freelist``: A freelist, suitable for fast lookups of available memory chunks
(i.e. ``block`` s).
- ``allocator``: An interface for memory allocators. Several concrete
implementations are also provided.
Heap Integrity Check
====================
The ``Block`` class provides two check functions:
.. doxygenclass:: pw::allocator::Block
:members:
FreeList
========
.. doxygenclass:: pw::allocator::FreeList
:members:
Allocator
=========
.. doxygenclass:: pw::allocator::Allocator
:members:
Provided implementations of the ``Allocator`` interface include:
- ``AllocatorMetricProxy``: Wraps another allocator and records its usage.
- ``FallbackAllocator``: Dispatches first to a primary allocator, and, if that
fails, to a secondary alloator.
- ``LibCAllocator``: Uses ``malloc``, ``realloc``, and ``free``. This should
only be used if the ``libc`` in use provides those functions.
- ``NullAllocator``: Always fails. This may be useful if allocations should be
disallowed under specific circumstances.
- ``SplitFreeListAllocator``: Tracks free blocks using a free list, and splits
large and small allocations between the front and back, respectively, of its
memory region in order to reduce fragmentation.
Heap Poisoning
==============
By default, this module disables heap poisoning since it requires extra space.
User can enable heap poisoning by enabling the ``pw_allocator_POISON_HEAP``
build arg.
.. code-block:: sh
$ gn args out
# Modify and save the args file to use heap poison.
pw_allocator_POISON_HEAP = true
When heap poisoning is enabled, ``pw_allocator`` will add ``sizeof(void*)``
bytes before and after the usable space of each ``Block``, and paint the space
with a hard-coded randomized pattern. During each check, ``pw_allocator``
will check if the painted space still remains the pattern, and return ``false``
if the pattern is damaged.
Heap Visualizer
===============
Functionality
-------------
``pw_allocator`` supplies a pw command ``pw heap-viewer`` to help visualize
the state of the heap at the end of a dump file. The heap is represented by
ASCII characters, where each character represents 4 bytes in the heap.
.. image:: doc_resources/pw_allocator_heap_visualizer_demo.png
Usage
-----
The heap visualizer can be launched from a shell using the Pigweed environment.
.. code-block:: sh
$ pw heap-viewer --dump-file <directory of dump file> --heap-low-address
<hex address of heap lower address> --heap-high-address <hex address of heap
lower address> [options]
The required arguments are:
- ``--dump-file`` is the path of a file that contains ``malloc/free``
information. Each line in the dump file represents a ``malloc/free`` call.
``malloc`` is represented as ``m <size> <memory address>`` and ``free`` is
represented as ``f <memory address>``. For example, a dump file should look
like:
.. code-block:: sh
m 20 0x20004450 # malloc 20 bytes, the pointer is 0x20004450
m 8 0x2000447c # malloc 8 bytes, the pointer is 0x2000447c
f 0x2000447c # free the pointer at 0x2000447c
...
Any line not formatted as the above will be ignored.
- ``--heap-low-address`` is the start of the heap. For example:
.. code-block:: sh
--heap-low-address 0x20004440
- ``--heap-high-address`` is the end of the heap. For example:
.. code-block:: sh
--heap-high-address 0x20006040
Options include the following:
- ``--poison-enable``: If heap poisoning is enabled during the
allocation or not. The value is ``False`` if the option is not specified and
``True`` otherwise.
- ``--pointer-size <integer of pointer size>``: The size of a pointer on the
machine where ``malloc/free`` is called. The default value is ``4``.
Note, this module, and its documentation, is currently incomplete and
experimental.
|
