AxlMem -- Memory Allocation
===========================

Memory allocation with dmalloc-inspired debug features. Size-tracking headers
enable ``axl_realloc`` without passing the old size. Debug builds add
fence-post guards, alloc/free fill patterns, file/line tracking, and leak
reporting.

Header: ``<axl/axl-mem.h>``

Overview
--------

AXL provides its own allocator on top of UEFI's pool memory. All allocated
memory is tracked with a small header that stores the block size, enabling
``axl_realloc`` and debug features without requiring the caller to pass the
old size.

**Do not mix** ``axl_malloc`` with UEFI's ``FreePool``, or ``AllocatePool``
with ``axl_free`` -- they use different headers.

Debug vs. Release
~~~~~~~~~~~~~~~~~

In debug builds (``-DAXL_MEM_DEBUG``, the default for ``make``):

- **Fill patterns**: newly allocated memory is filled with ``0xDA``;
  freed memory is filled with ``0xDD``. Use-after-free often manifests
  as reads of ``0xDD``.
- **Fence-post guards**: 8 bytes of ``0xFD`` are placed before and after
  each allocation. ``axl_mem_check(ptr)`` verifies these guards.
- **File/line tracking**: each allocation records ``__FILE__`` and
  ``__LINE__`` for leak reports.
- **Leak reporting**: ``axl_mem_dump_leaks()`` prints all outstanding
  allocations with their sizes and source locations.

In release builds (``make BUILD=RELEASE``), these features are disabled
and the allocator has minimal overhead.

RAII Auto-Cleanup
~~~~~~~~~~~~~~~~~

AXL provides GLib-style auto-cleanup macros using
``__attribute__((cleanup))``:

.. code-block:: c

   // Automatically freed when 's' goes out of scope
   AXL_AUTO_FREE char *s = axl_strdup("hello");

   // Automatically freed when 'h' goes out of scope
   AXL_AUTOPTR(AxlHashTable) h = axl_hash_table_new();

   if (error_condition) {
       return -1;  // both 's' and 'h' are freed automatically
   }

**Important**: Always initialize at declaration. Never use with ``goto``
that jumps over the declaration. See the
`GLib g_autoptr documentation <https://docs.gtk.org/glib/auto-cleanup.html>`_
for detailed rules.

Quick Reference
~~~~~~~~~~~~~~~

.. code-block:: c

   #include <axl.h>

   // Basic allocation
   char *buf = axl_malloc(256);
   void *copy = axl_memdup(original, size);
   char *str = axl_strdup("hello");

   // Typed allocation (zero-initialized)
   MyStruct *s = axl_new(MyStruct);
   int *arr = axl_new_array(int, 100);

   // Free (NULL-safe)
   axl_free(buf);

   // Debug: check for leaks before exit
   axl_mem_dump_leaks();

API Reference
-------------

.. doxygenfile:: axl-mem.h