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
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
.. Sources:

    `<https://info.ravenbrook.com/project/mps/master/design/object-debug/>`_

.. index::
   single: debugging; pool
   single: pool; debugging

.. _topic-debugging:

Debugging pools
===============

Several :term:`pool classes` have debugging counterparts:

=================  ==============================
Pool class         Debugging counterpart
=================  ==============================
:ref:`pool-ams`    :c:func:`mps_class_ams_debug`
:ref:`pool-mv`     :c:func:`mps_class_mv_debug`
:ref:`pool-mvff`   :c:func:`mps_class_mvff_debug`
=================  ==============================

These debugging pool classes provide two features that are useful for
debugging:

* .. index::
     single: debugging; fencepost
     single: fencepost

  :dfn:`fenceposts` are patterns of data that are written before and
  after each allocated block. In :term:`manually managed <manual
  memory management>` pools, fenceposts are checked when the block is
  deallocated, to see that they are unchanged. This helps detect
  underwriting and :term:`overwriting errors`. Fenceposts for all
  objects in a pool are checked when the pool is destroyed, and can be
  checked at any time by calling :c:func:`mps_pool_check_fenceposts`.

* .. index::
     single: debugging; free space splatting
     single: free space splatting

  :dfn:`free space splatting` overwrites recycled space with a pattern
  of data. If the pattern is designed so that it does not resemble a
  live object (and if code checks the consistency of its data
  structues), then this helps to detect :term:`dangling pointer`
  dereferences. The pattern is checked just before allocation, and
  when a block of memory is released from the pool to the arena, to
  see that it is unchanged. All free space in a pool can be checked
  for the pattern at any time by calling
  :c:func:`mps_pool_check_free_space`.

The :term:`client program` specifies templates for both of these
features via the :c:type:`mps_pool_debug_option_s` structure. This
allows it to specify patterns:

* that mimic illegal data values;

* that cause bus errors if wrongly interpreted as pointers;

* that cause assertions to fire if wrongly interpreted as data values;

* that contain an instruction sequence that wold cause the program to
  signal an error or stop if wrongly interpreted as executable code.

For example::

    mps_pool_debug_option_s debug_options = {
       (void *)"postpost", 8,
       (void *)"freefree", 8,
    };
    mps_pool_t pool;
    mps_res_t res;
    MPS_ARGS_BEGIN(args) {
        MPS_ARGS_ADD(args, MPS_KEY_POOL_DEBUG_OPTIONS, &debug_options);
        MPS_ARGS_ADD(args, MPS_KEY_FORMAT, &fmt);
        MPS_ARGS_ADD(args, MPS_KEY_CHAIN, &chain);
        MPS_ARGS_DONE(args);
        res = mps_pool_create_k(&pool, arena, mps_class_ams_debug(), args);
    } MPS_ARGS_END(args);
    if (res != MPS_RES_OK) error("can't create debug pool");


.. c:type:: mps_pool_debug_option_s

    The type of the structure passed as the
    :c:macro:`MPS_KEY_POOL_DEBUG_OPTIONS` keyword argument to
    :c:func:`mps_pool_create_k` when creating a debugging :term:`pool
    class`. ::

        typedef struct mps_pool_debug_option_s {
            void  *fence_template;
            size_t fence_size;
            void  *free_template;
            size_t free_size;
        } mps_pool_debug_option_s;

    ``fence_template`` points to a template for :term:`fenceposts`.

    ``fence_size`` is the :term:`size` of ``fence_template`` in
    :term:`bytes (1)`, or zero if the debugging pool should not use
    fenceposts.

    ``free_template`` points to a template for splatting free space.

    ``free_size`` is the :term:`size` of ``free_template`` in bytes, or
    zero if the debugging pool should not splat free space.

    Both ``fence_size`` and ``free_size`` must be a multiple of the
    :term:`alignment` of the :term:`pool`, and also a multiple of the
    alignment of the pool's :term:`object format` if it has one.

    The debugging pool will copy the ``fence_size`` bytes pointed to by
    ``fence_template`` in a repeating pattern onto each fencepost during
    allocation, and it will copy the bytes pointed to by
    ``free_template`` in a repeating pattern over free space after the
    space is reclaimed.

    The MPS may not always use the whole of a template: it may use
    pieces smaller than the given size, for example to pad out part of
    a block that was left unused because of alignment requirements.


.. c:function:: void mps_pool_check_fenceposts(mps_pool_t pool)

    Check all the :term:`fenceposts` in a :term:`pool`.

    ``pool`` is the pool whose fenceposts are to be checked.

    If a corrupted fencepost is found, the MPS will :term:`assert
    <assertion>`. It is only useful to call this on a :term:`debugging
    pool` that has fenceposts turned on. It does nothing on
    non-debugging pools.


.. c:function:: void mps_pool_check_free_space(mps_pool_t pool)

    Check all the free space in a :term:`pool` for :term:`overwriting
    errors`.

    ``pool`` is the pool whose free space is to be checked.

    If corrupted free space is found, the MPS will :term:`assert
    <assertion>`. It is only useful to call this on a :term:`debugging
    pool` that has free space splatting turned on. It does nothing on
    non-debugging pools.