1.. _module-pw_allocator: 2 3------------ 4pw_allocator 5------------ 6 7This module provides various building blocks 8for 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 chunks 13 (i.e. ``block`` s). 14 15Heap Integrity Check 16==================== 17The ``Block`` class provides two check functions: 18 19- ``bool Block::IsValid()``: Returns ``true`` is the given block is valid and 20 ``false`` otherwise. 21- ``void Block::CrashIfInvalid()``: Crash the program and output the reason why 22 the check fails using ``PW_DCHECK``. 23 24Heap Poisoning 25============== 26 27By default, this module disables heap poisoning since it requires extra space. 28User can enable heap poisoning by enabling the ``pw_allocator_POISON_HEAP`` 29build 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 37When heap poisoning is enabled, ``pw_allocator`` will add ``sizeof(void*)`` 38bytes before and after the usable space of each ``Block``, and paint the space 39with a hard-coded randomized pattern. During each check, ``pw_allocator`` 40will check if the painted space still remains the pattern, and return ``false`` 41if the pattern is damaged. 42 43Heap Visualizer 44=============== 45 46Functionality 47------------- 48 49``pw_allocator`` supplies a pw command ``pw heap-viewer`` to help visualize 50the state of the heap at the end of a dump file. The heap is represented by 51ASCII characters, where each character represents 4 bytes in the heap. 52 53.. image:: doc_resources/pw_allocator_heap_visualizer_demo.png 54 55Usage 56----- 57 58The 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 66The 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 95Options 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 104Note, this module, and its documentation, is currently incomplete and 105experimental. 106
