AxlBoot — boot-option management

Typed wrappers over the Boot#### / BootOrder / BootNext / BootCurrent firmware-variable family. The EFI_LOAD_OPTION wire codec is internal — consumers operate on AxlBootOption structs, never on raw bytes.

See AxlSys — System Utilities for the underlying axl_nvstore_* namespace machinery.

API Reference

Boot-option management.

Backend-neutral interface for the firmware boot manager. On UEFI this is backed by the spec EFI_LOAD_OPTION wire format under Boot####/BootOrder/BootNext/BootCurrent variables; the binary codec is internal to the implementation. Consumers operate on typed AxlBootOption structs only — raw LOAD_OPTION bytes never cross this boundary.

Boot-option indices are 16-bit numbers (0x0000..0xFFFF) named Boot0000..BootFFFF in firmware-variable storage. BootOrder is the active boot ordering; BootNext is a one-shot override (consumed and cleared on next boot); BootCurrent is the index the system actually booted from this run.

AxlBootOption opt;
if (axl_boot_option_get(0x0001, &opt) == 0) {
    axl_printf("Boot0001: %s\n", opt.description);
    axl_boot_option_free(&opt);
}

uint16_t *order;
size_t    n;
if (axl_boot_order_get(&order, &n) == 0) {
    for (size_t i = 0; i < n; i++) {
        axl_printf("  %zu: Boot%04x\n", i, order[i]);
    }
    axl_free(order);
}

Defines

AXL_BOOT_ATTR_ACTIVE

Boot option is enabled for selection by the boot manager.

AXL_BOOT_ATTR_FORCE_RECONNECT

Boot manager should reconnect all controllers before loading.

AXL_BOOT_ATTR_HIDDEN

Boot option is hidden from interactive boot menus.

AXL_BOOT_ATTR_CATEGORY_MASK

Mask covering the option-category field (boot vs application).

AXL_BOOT_ATTR_CATEGORY_BOOT

Standard boot entry (default for OS-loader entries).

AXL_BOOT_ATTR_CATEGORY_APP

Application entry (boot-time utility, not a normal OS boot path).

Functions

void axl_boot_option_free(AxlBootOption *opt)

Free heap-owned fields inside an AxlBootOption.

Resets the struct to zeroed state. NULL-safe. Doesn’t free the struct itself — callers stack-allocate it.

Parameters:

  • opt – option to free, or NULL

int axl_boot_option_get(uint16_t index, AxlBootOption *out)

Read a single Boot#### option from firmware.

Populates out with description, device-path text (if obtainable) and any opt_data. The caller frees with axl_boot_option_free().

Parameters:

  • index – Boot#### index

  • out – [out] populated on success

Returns:

0 on success, -1 if the variable is missing or malformed.

int axl_boot_option_set(uint16_t index, const AxlBootOption *opt)

Write a Boot#### option to firmware.

Encodes opt as the firmware’s wire format and stores it under Boot####. Requires the firmware to expose a text→device-path service (DevicePathFromText on UEFI); on backends without one, returns -1.

Parameters:

  • index – Boot#### index

  • opt – option to encode and write

Returns:

0 on success, -1 on encode or write failure.

int axl_boot_option_delete(uint16_t index)

Delete a Boot#### option.

Parameters:

  • index – Boot#### index

Returns:

0 on success (or if the variable already absent), -1 on error.

int axl_boot_order_get(uint16_t **out, size_t *count)

Read the BootOrder variable.

Allocates an array of Boot#### indices in firmware order. Caller frees *out with axl_free().

Parameters:

  • out – [out] caller-freed array of indices

  • count – [out] number of entries in *out

Returns:

0 on success, -1 if BootOrder is absent or malformed.

int axl_boot_order_set(const uint16_t *order, size_t count)

Write the BootOrder variable.

Parameters:

  • order – new boot order

  • count – entry count (0 deletes BootOrder)

Returns:

0 on success, -1 on write failure.

int axl_boot_next_get(uint16_t *out)

Read the BootNext one-shot override.

Parameters:

  • out – [out] receives the Boot#### index

Returns:

0 on success, -1 if BootNext is unset.

int axl_boot_next_set(uint16_t index)

Set the BootNext one-shot override.

Firmware will boot index on the next reboot, then automatically delete BootNext.

Parameters:

  • index – Boot#### index to boot next

Returns:

0 on success, -1 on write failure.

int axl_boot_next_clear(void)

Clear the BootNext one-shot override.

Returns:

0 on success (or if BootNext already absent), -1 on error.

int axl_boot_current_get(uint16_t *out)

Read the BootCurrent variable.

BootCurrent is set by firmware to the Boot#### index that the current boot used. Useful for “which entry got us here” reporting.

Parameters:

  • out – [out] receives the Boot#### index

Returns:

0 on success, -1 if BootCurrent is absent.

struct AxlBootOption
#include <axl-boot.h>

Decoded boot option.

Heap-allocated string fields are owned by the struct after a successful axl_boot_option_get and freed by axl_boot_option_free. Pass a struct that’s been zero-initialised if you populate it manually for _set; the encoder accepts NULL fields and writes empty equivalents to the variable.

Public Members

uint16_t index

Boot#### index (0..0xFFFF)

uint32_t attrs

AXL_BOOT_ATTR_* flags.

char *description

UTF-8 description, NULL allowed.

char *device_path

UTF-8 device-path text, NULL if firmware lacks DevicePathToText.

void *opt_data

OS-loader options (opaque to AXL), NULL allowed.

size_t opt_data_len

bytes in opt_data (0 if no opt data)