AxlShm — Boot-Persistent Shared Memory

<axl/axl-shm.h> is the UEFI analog of POSIX shm_open + mmap (or System V shmget / shmat): a named, fixed-size memory region that outlives the app that created it and is reachable by any later app in the same boot. UEFI is a single flat, identity-mapped address space, so there is no per-process mapping — axl_shm_open returns a pointer that is the region; map/attach collapse to nothing and detach is a no-op.

The region lives in boot-services RAM and is therefore volatile: it is reclaimed at reboot / ExitBootServices. Not NVRAM — no flash wear, and its capacity is system RAM rather than the tiny firmware variable store. The name is hashed to a GUID (axl_guid_v5) and the region published as a UEFI protocol, so it resolves across images with no shared handle. It survives an image unload because it is a data-only pool allocation (no function pointers, which would dangle once the creating image is gone) from EfiBootServicesData, which the firmware does not reclaim on unload — the same mechanism the backend uses to cache the calibrated TSC frequency across processes.

Names are one global namespace (like POSIX /name) — prefix yours. Single-threaded (UEFI): no locking is provided; in the shell apps run one at a time. AxlClipboard and the clip / paste tools are built on it.

Header: <axl/axl-shm.h>

API Reference

Defines

AXL_SHM_CREATE

create the segment if it does not exist

axl-shm.h:

Boot-persistent named shared memory — the UEFI analog of POSIX shm_open + mmap (or System V shmget + shmat).

A named, fixed-size region of memory that outlives the app that created it and is reachable by any later app in the same boot. UEFI is a single flat, identity-mapped address space, so there is no per-process mapping: axl_shm_open returns a pointer that is the region — there is no separate map/attach step (mmap / shmat collapse to nothing), and detach is a no-op. The region lives in boot-services RAM and is therefore volatile: it is reclaimed at reboot / ExitBootServices. Not NVRAM — no flash wear, and capacity is system RAM, not the tiny firmware variable store.

Identity is a name string, hashed to a GUID (axl_guid_v5 under a fixed AXL_SHM namespace) and published as a UEFI protocol, so the same name resolves to the same region across images with no shared handle. Names are a single global namespace (like POSIX “/name”) — prefix yours to avoid collisions.

Mechanism: the region is a data-only pool allocation (it holds bytes, never function pointers — a function pointer would dangle once the creating image unloads) installed under its GUID; pool allocated this way survives image unload. This is the same pattern the backend uses internally to cache the calibrated TSC frequency across processes.

Single-threaded (UEFI): no locking is provided. In the shell, apps run one at a time, so a writer and a later reader never overlap; if you nest access within one image, coordinate it yourself.

AXL_SHM_EXCL

with CREATE, fail if it already exists

Functions

void *axl_shm_open(const char *name, size_t size, uint32_t flags, size_t *out_size)

Open or create a named shared-memory segment.

Without AXL_SHM_CREATE, opens an existing segment (returns NULL if none; size is ignored). With AXL_SHM_CREATE, returns the existing segment if present, otherwise creates a size-byte zero-filled one; adding AXL_SHM_EXCL makes “already exists” an error (NULL) instead. Opening an existing segment ignores size and returns it at the size it was created with (read out_size).

The returned pointer is the region base — directly readable and writable, at least 8-byte aligned, valid until axl_shm_unlink (or reboot). Every open of the same name (in this or any other app) returns the SAME region. Do not free it.

Parameters:

  • name – segment name (UTF-8)

  • size – bytes to create (ignored when opening existing)

  • flags – AXL_SHM_CREATE | AXL_SHM_EXCL

  • out_size – [out, optional] actual segment size

Returns:

region base pointer, or NULL (no segment and no CREATE, an EXCL conflict, allocation failure, or boot services unavailable). out_size (optional) receives the segment’s actual byte size.

Destroy a named segment and free its memory.

Uninstalls the segment’s protocol and frees the region. The name becomes reusable and any base pointer to the segment is now invalid. An absent name is a no-op success.

Parameters:

  • name – segment name (UTF-8)

Returns:

AXL_OK if the segment was removed or already absent, AXL_ERR if a present segment could not be uninstalled.

bool axl_shm_exists(const char *name, size_t *out_size)

Whether a named segment currently exists.

Parameters:

  • name – segment name (UTF-8)

  • out_size – [out, optional] segment size if present

Returns:

true if present; out_size (optional) receives its size.