ioctl interface¶

The IOCTL user-space control interface for the LUO subsystem.It registers a character device, typically found at/dev/liveupdate,which allows a userspace agent to manage the LUO state machine and itsassociated resources, such as preservable file descriptors.

To ensure that the state machine is controlled by a single entity, accessto this device is exclusive: only one process is permitted to have/dev/liveupdate open at any given time. Subsequent open attempts willfail with -EBUSY until the first process closes its file descriptor.This singleton model simplifies state management by preventing conflictingcommands from multiple userspace agents.

ioctl uAPI¶

General ioctl format

The ioctl interface follows a general format to allow for extensibility. Eachioctl is passed in a structure pointer as the argument providing the size ofthe structure in the first u32. The kernel checks that any structure spacebeyond what it understands is 0. This allows userspace to use the backwardcompatible portion while consistently using the newer, larger, structures.

ioctls use a standard meaning for common errnos:

• ENOTTY: The IOCTL number itself is not supported at all

• E2BIG: The IOCTL number is supported, but the provided structure hasnon-zero in a part the kernel does not understand.

• EOPNOTSUPP: The IOCTL number is supported, and the structure isunderstood, however a known field has a value the kernel does notunderstand or support.

• EINVAL: Everything about the IOCTL was understood, but a field is notcorrect.

• ENOENT: A provided token does not exist.

• ENOMEM: Out of memory.

• EOVERFLOW: Mathematics overflowed.

As well as additional errnos, within specific ioctls.

structliveupdate_ioctl_create_session¶

ioctl(LIVEUPDATE_IOCTL_CREATE_SESSION)

struct liveupdate_ioctl_create_session {    __u32 size;    __s32 fd;    __u8 name[LIVEUPDATE_SESSION_NAME_LENGTH];};

Description

Creates a new live update session for managing preserved resources.This ioctl can only be called on the main /dev/liveupdate device.

Return

0 on success, negative error code on failure.

structliveupdate_ioctl_retrieve_session¶

ioctl(LIVEUPDATE_IOCTL_RETRIEVE_SESSION)

struct liveupdate_ioctl_retrieve_session {    __u32 size;    __s32 fd;    __u8 name[LIVEUPDATE_SESSION_NAME_LENGTH];};

Description

Retrieves a handle (a new file descriptor) for a preserved session by itsname. This is the primary mechanism for a userspace agent to regain controlof its preserved resources after a live update.

The userspace application provides the null-terminatedname of a sessionit created before the live update. If a preserved session with a matchingname is found, the kernel instantiates it and returns a new file descriptorin thefd field. This new session FD can then be used for all file-specificoperations, such as restoring individual file descriptors withLIVEUPDATE_SESSION_RETRIEVE_FD.

It is the responsibility of the userspace application to know the names ofthe sessions it needs to retrieve. If no session with the given name isfound, the ioctl will fail with -ENOENT.

This ioctl can only be called on the main /dev/liveupdate device when thesystem is in the LIVEUPDATE_STATE_UPDATED state.

structliveupdate_session_preserve_fd¶

ioctl(LIVEUPDATE_SESSION_PRESERVE_FD)

struct liveupdate_session_preserve_fd {    __u32 size;    __s32 fd;    __aligned_u64 token;};

Description

Holds parameters for preserving a file descriptor.

User sets thefd field identifying the file descriptor to preserve(e.g., memfd, kvm, iommufd, VFIO). The kernel validates if this FD typeand its dependencies are supported for preservation. If validation passes,the kernel marks the FD internally andinitiates the process of preparingits state for saving. The actual snapshotting of the state typically occursduring the subsequentLIVEUPDATE_IOCTL_PREPARE execution phase, thoughsome finalization might occur during freeze.On successful validation and initiation, the kernel uses thetokenfield with an opaque identifier representing the resource being preserved.This token confirms the FD is targeted for preservation and is required forthe subsequentLIVEUPDATE_SESSION_RETRIEVE_FD call after the live update.

Return

0 on success (validation passed, preservation initiated), negativeerror code on failure (e.g., unsupported FD type, dependency issue,validation failed).

structliveupdate_session_retrieve_fd¶

ioctl(LIVEUPDATE_SESSION_RETRIEVE_FD)

struct liveupdate_session_retrieve_fd {    __u32 size;    __s32 fd;    __aligned_u64 token;};

Description

Retrieve a previously preserved file descriptor.

User sets thetoken field to the value obtained from a successfulLIVEUPDATE_IOCTL_FD_PRESERVE call before the live update. On success,the kernel restores the state (saved during the PREPARE/FREEZE phases)associated with the token and populates thefd field with a new filedescriptor referencing the restored resource in the current (new) kernel.This operation must be performedbefore signaling completion viaLIVEUPDATE_IOCTL_FINISH.

Return

0 on success, negative error code on failure (e.g., invalid token).

structliveupdate_session_finish¶

ioctl(LIVEUPDATE_SESSION_FINISH)

struct liveupdate_session_finish {    __u32 size;    __u32 reserved;};

Description

Signals the completion of the restoration process for a retrieved session.This is the final operation that should be performed on a session filedescriptor after a live update.

This ioctl must be called once all required file descriptors for the sessionhave been successfully retrieved (usingLIVEUPDATE_SESSION_RETRIEVE_FD) andare fully restored from the userspace and kernel perspective.

Upon success, the kernel releases its ownership of the preserved resourcesassociated with this session. This allows internal resources to be freed,typically by decrementing reference counts on the underlying preservedobjects.

If this operation fails, the resources remain preserved in memory. Userspacemay attempt to call finish again. The resources will otherwise be resetduring the next live update cycle.

Return

0 on success, negative error code on failure.

See Also¶

• Live Update Orchestrator