• Memfd Preservation via LUO

Definition:

struct liveupdate_file_op_args {    struct liveupdate_file_handler *handler;    bool retrieved;    struct file *file;    u64 serialized_data;    void *private_data;};

Members

handler

The file handler being called.

retrieved

The retrieve status for the ‘can_finish / finish’operation.

file

The file object. For retrieve: [OUT] The callback setsthis to the new file. For other ops: [IN] The caller setsthis to the file being operated on.

serialized_data

The opaque u64 handle, preserve/prepare/freeze may updatethis field.

private_data

Private data for the file used to hold runtime state thatis not preserved. Set by the handler’s .preserve()callback, and must be freed in the handler’s.unpreserve() callback.

Definition:

struct liveupdate_file_ops {    bool (*can_preserve)(struct liveupdate_file_handler *handler, struct file *file);    int (*preserve)(struct liveupdate_file_op_args *args);    void (*unpreserve)(struct liveupdate_file_op_args *args);    int (*freeze)(struct liveupdate_file_op_args *args);    void (*unfreeze)(struct liveupdate_file_op_args *args);    int (*retrieve)(struct liveupdate_file_op_args *args);    bool (*can_finish)(struct liveupdate_file_op_args *args);    void (*finish)(struct liveupdate_file_op_args *args);    struct module *owner;};

Members

can_preserve

Required. Lightweight check to see if this handler iscompatible with the given file.

preserve

Required. Performs state-saving for the file.

unpreserve

Required. Cleans up any resources allocated bypreserve.

freeze

Optional. Final actions just before kernel transition.

unfreeze

Optional. Undo freeze operations.

retrieve

Required. Restores the file in the new kernel.

can_finish

Optional. Check if this FD can finish, i.e. all restorationpre-requirements for this FD are satisfied. Called prior tofinish, in order to do successful finish calls for allresources in the session.

finish

Required. Final cleanup in the new kernel.

owner

Module reference

Definition:

struct liveupdate_file_handler {    const struct liveupdate_file_ops *ops;    const char compatible[LIVEUPDATE_HNDL_COMPAT_LENGTH];};

Members

ops

Callback functions

compatible

The compatibility string (e.g., “memfd-v1”, “vfiofd-v1”)that uniquely identifies the file type this handlersupports. This is matched against the compatible stringassociated with individualstructfile instances.

Definition:

struct luo_file_ser {    char compatible[LIVEUPDATE_HNDL_COMPAT_LENGTH];    u64 data;    u64 token;};

Members

compatible

File handler compatible string.

data

Private data

token

User provided token for this file

Definition:

struct luo_file_set_ser {    u64 files;    u64 count;};

Members

files

The physical address of a contiguous memory block that holdsthe serialized state of files (array of luo_file_ser) in this fileset.

count

The total number of files that were part of this session duringserialization. Used for iteration and validation duringrestoration.

Definition:

struct luo_session_header_ser {    u64 count;};

Members

count

The number ofstructluo_session_ser entries that immediatelyfollow this header in the memory block.

Definition:

struct luo_session_ser {    char name[LIVEUPDATE_SESSION_NAME_LENGTH];    struct luo_file_set_ser file_set_ser;};

Members

name

The unique name of the session, provided by the userspace atthe time of session creation.

file_set_ser

Serialized files belonging to this session,

Parameters

void

no arguments

Description

This function is invoked directly from thereboot() syscall pathwayif kexec is in progress.

If any callback fails, this function aborts KHO, undoes thefreeze()callbacks, and returns an error.

Parameters

void

no arguments

Description

This function returns the state of the live update feature flag, whichcan be controlled via theliveupdate kernel command-line parameter.

return true if live update is enabled, false otherwise.

Definition:

struct luo_session_header {    long count;    struct list_head list;    struct rw_semaphore rwsem;    struct luo_session_header_ser *header_ser;    struct luo_session_ser *ser;    bool active;};

Members

count

The number of sessions currently tracked in thelist.

list

The head of the linked list ofstructluo_session instances.

rwsem

A read-write semaphore providing synchronized access to thesession list and other fields in this structure.

header_ser

The header data of serialization array.

ser

The serialized session data (an array ofstructluo_session_ser).

active

Set to true when first initialized. If previous kernel did notsend session data, active stays false for incoming.

Definition:

struct luo_session_global {    struct luo_session_header incoming;    struct luo_session_header outgoing;};

Members

incoming

The sessions passed from the previous kernel.

outgoing

The sessions that are going to be passed to the next kernel.

Parameters

void

no arguments

Description

Acquires exclusive write locks on both incoming and outgoing session lists.It then validates no sessions exist in either list.

This mechanism is used during file handler un/registration to ensure that nosessions are currently using the handler, and no new sessions can be createdwhile un/registration is in progress.

This prevents registering new handlers while sessions are active orwhile deserialization is in progress.

Return

true - System is quiescent (0 sessions) and locked.false - Active sessions exist. The locks are released internally.

Parameters

void

no arguments

Description

Releases the exclusive locks acquired by a successful call toluo_session_quiesce().

Definition:

struct luo_file {    struct liveupdate_file_handler *fh;    struct file *file;    u64 serialized_data;    void *private_data;    bool retrieved;    struct mutex mutex;    struct list_head list;    u64 token;};

Members

fh

Pointer to thestructliveupdate_file_handler that managesthis type of file.

file

Pointer to the kernel’sstructfile that is being preserved.This is NULL in the new kernel until the file is successfullyretrieved.

serialized_data

The opaque u64 handle to the serialized state of the file.This handle is passed back to the handler’s .freeze(),.retrieve(), and .finish() callbacks, allowing it to trackand update its serialized state across phases.

private_data

Pointer to the private data for the file used to hold runtimestate that is not preserved. Set by the handler’s .preserve()callback, and must be freed in the handler’s .unpreserve()callback.

retrieved

A flag indicating whether a user/kernel in the new kernel hassuccessfully calledretrieve() on this file. This preventsmultiple retrieval attempts.

mutex

A mutex that protects the fields of this specific instance(e.g.,retrieved,file), ensuring that operations likeretrieving or finishing a file are atomic.

list

The list_head linking this instance into its parentfile_set’s list of preserved files.

token

The user-provided unique token used to identify this file.

Parameters

structluo_file_set*file_set

The file_set to which the preserved file will be added.

u64token

A unique, user-provided identifier for the file.

intfd

The file descriptor to be preserved.

Description

This function orchestrates the first phase of preserving a file. Upon entry,it takes a reference to the ‘structfile’ viafget(), effectively making LUOa co-owner of the file. This reference is held until the file is eitherunpreserved or successfully finished in the next kernel, preventing the filefrom being prematurely destroyed.

This function orchestrates the first phase of preserving a file. It performsthe following steps:

1. Validates that thetoken is not already in use within the file_set.

2. Ensures the file_set’s memory for files serialization is allocated(allocates if needed).

3. Iterates through registered handlers, callingcan_preserve() to find onecompatible with the givenfd.

4. Calls the handler’s .preserve() operation, which saves the file’s stateand returns an opaque private data handle.

5. Adds the new instance to the file_set’s internal list.

On success, LUO takes a reference to the ‘structfile’ and considers itunder its management until it is unpreserved or finished.

In case of any failure, all intermediate allocations (file reference, memoryfor the ‘luo_file’ struct, etc.) are cleaned up before returning an error.

Context

Can be called from an ioctl handler during normal system operation.

Return

0 on success. Returns a negative errno on failure:-EEXIST if the token is already used.-EBADF if the file descriptor is invalid.-ENOSPC if the file_set is full.-ENOENT if no compatible handler is found.-ENOMEM on memory allocation failure.Other erros might be returned by .preserve().

Parameters

structluo_file_set*file_set

The files to be cleaned up.

Description

This function serves as the primary cleanup path for a file_set. It isinvoked when the userspace agent closes the file_set’s file descriptor.

For each file, it performs the following cleanup actions:

1. Calls the handler’s .unpreserve() callback to allow the handler torelease any resources it allocated.

2. Removes the file from the file_set’s internal tracking list.

3. Releases the reference to the ‘structfile’ that was taken byluo_preserve_file() viafput(), returning ownership.

4. Frees the memory associated with the internal ‘structluo_file’.

After all individual files are unpreserved, it frees the contiguous memoryblock that was allocated to hold their serialization data.

Parameters

structluo_file_set*file_set

The file_set whose files are to be frozen.

structluo_file_set_ser*file_set_ser

Where to put the serialized file_set.

Description

This function is called from thereboot() syscall path, just before thekernel transitions to the new image via kexec. Its purpose is to perform thefinal preparation and serialization of all preserved files in the file_set.

It iterates through each preserved file in FIFO order (the order ofpreservation) and performs two main actions:

1. Freezes the File: It calls the handler’s .freeze() callback for eachfile. This gives the handler a final opportunity to quiesce the device orprepare its state for the upcoming reboot. The handler may update itsprivate data handle during this step.

2. Serializes Metadata: After a successful freeze, it copies the final filemetadata—the handler’s compatible string, the user token, and the finalprivate data handle—into the pre-allocated contiguous memory buffer(file_set->files) that will be handed over to the next kernel via KHO.

Error Handling (Rollback):This function is atomic. If any handler’s .freeze() operation fails, theentire live update is aborted. The__luo_file_unfreeze() helper isimmediately called to invoke the .unfreeze() op on all files that weresuccessfully frozen before the point of failure, rolling them back to arunning state. The function then returns an error, causing thereboot()syscall to fail.

Context

Called only from theliveupdate_reboot() path.

Return

0 on success, or a negative errno on failure.

Parameters

structluo_file_set*file_set

The file_set whose files are to be unfrozen.

structluo_file_set_ser*file_set_ser

Serialized file_set.

Description

This function rolls back the state of all files in a file_set after thefreeze phase has begun but must be aborted. It is the counterpart toluo_file_freeze().

It invokes the__luo_file_unfreeze() helper with a NULL argument, whichsignals the helper to iterate through all files in the file_set and calltheir respective .unfreeze() handler callbacks.

Context

This is called when the live update is aborted duringthereboot() syscall, afterluo_file_freeze() has been called.

Parameters

structluo_file_set*file_set

The file_set from which to retrieve the file.

u64token

The unique token identifying the file to be restored.

structfile**filep

Output parameter; on success, this is populated with a pointerto the newly retrieved ‘structfile’.

Description

This function is the primary mechanism for recreating a file in the newkernel after a live update. It searches the file_set’s list of deserializedfiles for an entry matching the providedtoken.

The operation is idempotent: if a file has already been successfullyretrieved, this function will simply return a pointer to the existing‘structfile’ and report success without re-executing the retrieveoperation. This is handled by checking the ‘retrieved’ flag under a lock.

File retrieval can happen in any order; it is not bound by the order ofpreservation.

Context

Can be called from an ioctl or other in-kernel code in the newkernel.

Return

0 on success. Returns a negative errno on failure:-ENOENT if no file with the matching token is found.Any error code returned by the handler’s .retrieve() op.

Parameters

structluo_file_set*file_set

The file_set to be finalized.

Description

This function orchestrates the final teardown of a live update file_set inthe new kernel. It should be called after all necessary files have beenretrieved and the userspace agent is ready to release the preserved state.

The function iterates through all tracked files. For each file, it performsthe following sequence of cleanup actions:

1. If file is not yet retrieved, retrieves it, and callscan_finish() onevery file in the file_set. If all can_finish return true, continue tofinish.

2. Calls the handler’s .finish() callback (via luo_file_finish_one) toallow for final resource cleanup within the handler.

3. Releases LUO’s ownership reference on the ‘structfile’ viafput(). Thisis the counterpart to theget_file() call inluo_retrieve_file().

4. Removes the ‘structluo_file’ from the file_set’s internal list.

5. Frees the memory for the ‘structluo_file’ instance itself.

After successfully finishing all individual files, it frees thecontiguous memory block that was used to transfer the serialized metadatafrom the previous kernel.

Error Handling (Atomic Failure):This operation is atomic. If any handler’s .can_finish() op fails, the entirefunction aborts immediately and returns an error.

Context

Can be called from an ioctl handler in the new kernel.

Return

0 on success, or a negative errno on failure.

Parameters

structluo_file_set*file_set

The incoming file_set to fill with deserialized data.

structluo_file_set_ser*file_set_ser

Serialized KHO file_set data from the previous kernel.

Description

This function is called during the early boot process of the new kernel. Ittakes the raw, contiguous memory block of ‘structluo_file_ser’ entries,provided by the previous kernel, and transforms it back into a live,in-memory linked list of ‘structluo_file’ instances.

For each serialized entry, it performs the following steps:

1. Reads the ‘compatible’ string.

2. Searches the global list of registered file handlers for one thatmatches the compatible string.

3. Allocates a new ‘structluo_file’.

4. Populates the new structure with the deserialized data (token, privatedata handle) and links it to the found handler. The ‘file’ pointer isinitialized to NULL, as the file has not been retrieved yet.

5. Adds the new ‘structluo_file’ to the file_set’s files_list.

This prepares the file_set for userspace, which can later callluo_retrieve_file() to restore the actual file descriptors.

Context

Called from session deserialization.

Parameters

structliveupdate_file_handler*fh

Pointer to a caller-allocatedstructliveupdate_file_handler.The caller must initialize this structure, including a unique‘compatible’ string and a valid ‘fh’ callbacks. This function adds thehandler to the global list of supported file handlers.

Context

Typically called during module initialization for file types thatsupport live update preservation.

Return

0 on success. Negative errno on failure.

Parameters

structliveupdate_file_handler*fh

The file handler to unregister

Description

Unregisters the file handler from the liveupdate core. This functionreverses the operations ofliveupdate_register_file_handler().

It ensures safe removal by checking that:No live update session is currently in progress.

If the unregistration fails, the internal test state is reverted.

Return

0 Success. -EOPNOTSUPP when live update is not enabled. -EBUSY A liveupdate is in progress, can’t quiesce live update.