AxlSys -- System Utilities
==========================

System operations, environment variables, time, NVRAM storage, driver
lifecycle, and hex dump.

Headers:

- ``<axl/axl-sys.h>`` -- System operations (reset, GUID, device map refresh)
- ``<axl/axl-env.h>`` -- Environment variables and working directory
- ``<axl/axl-time.h>`` -- Wall-clock time and monotonic timestamps
- ``<axl/axl-nvstore.h>`` -- UEFI NVRAM variable access
- ``<axl/axl-driver.h>`` -- Driver binding and lifecycle
- ``<axl/axl-hexdump.h>`` -- Hex/ASCII dump formatting

Overview
--------

GUIDs
~~~~~

UEFI identifies protocols, variables, and services by 128-bit GUIDs.
AXL provides ``AxlGuid`` (standard C types, no UEFI headers needed)
and the ``AXL_GUID`` macro for initialization:

.. code-block:: c

   AxlGuid my_guid = AXL_GUID(0x12345678, 0xabcd, 0xef01,
       0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x01);

   if (axl_guid_cmp(&a, &b) == 0) {
       // GUIDs are equal
   }

Firmware Globals
~~~~~~~~~~~~~~~~

After ``AXL_APP`` or ``axl_driver_init``, these globals are available
(typed when ``<uefi/axl-uefi.h>`` is included):

- ``gST`` -- :term:`System Table` (``EFI_SYSTEM_TABLE *``)
- ``gBS`` -- :term:`Boot Services` (``EFI_BOOT_SERVICES *``)
- ``gRT`` -- :term:`Runtime Services` (``EFI_RUNTIME_SERVICES *``)
- ``gImageHandle`` -- handle of the running application or driver

NVRAM Variables
~~~~~~~~~~~~~~~

Read and write persistent UEFI variables (survive reboot):

.. code-block:: c

   // Read
   uint8_t secure_boot;
   size_t sz = sizeof(secure_boot);
   if (axl_nvstore_get("global", "SecureBoot", &secure_boot, &sz) == 0) {
       axl_printf("SecureBoot: %s\n", secure_boot ? "on" : "off");
   }

   // Write
   axl_nvstore_set("app", "last-run", timestamp, timestamp_len,
                   AXL_NVSTORE_BOOT | AXL_NVSTORE_NV);

Driver Lifecycle
~~~~~~~~~~~~~~~~

Build DXE drivers with ``axl-cc --type driver``. The driver entry point
is ``DriverEntry`` (not ``main``). Call ``axl_driver_init`` to set up
the AXL runtime:

.. code-block:: c

   EFI_STATUS EFIAPI DriverEntry(EFI_HANDLE ImageHandle,
                                  EFI_SYSTEM_TABLE *SystemTable) {
       axl_driver_init(ImageHandle, SystemTable);
       axl_printf("Driver loaded\n");
       // ...
   }

See ``sdk/examples/driver.c`` for a complete example.

AxlSys
------

.. doxygenfile:: axl-sys.h

AxlEnv
------

.. doxygenfile:: axl-env.h

AxlTime
-------

.. doxygenfile:: axl-time.h

AxlNvStore
----------

.. doxygenfile:: axl-nvstore.h

AxlDriver
---------

.. doxygenfile:: axl-driver.h

AxlHexdump
----------

.. doxygenfile:: axl-hexdump.h