Import linux/liveupdate.h UAPI header
From kernel 7.0
This commit is contained in:
Luca Boccassi
@@ -0,0 +1,216 @@
|
||||
/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
|
||||
|
||||
/*
|
||||
* Userspace interface for /dev/liveupdate
|
||||
* Live Update Orchestrator
|
||||
*
|
||||
* Copyright (c) 2025, Google LLC.
|
||||
* Pasha Tatashin <pasha.tatashin@soleen.com>
|
||||
*/
|
||||
|
||||
#ifndef _UAPI_LIVEUPDATE_H
|
||||
#define _UAPI_LIVEUPDATE_H
|
||||
|
||||
#include <linux/ioctl.h>
|
||||
#include <linux/types.h>
|
||||
|
||||
/**
|
||||
* DOC: General ioctl format
|
||||
*
|
||||
* The ioctl interface follows a general format to allow for extensibility. Each
|
||||
* ioctl is passed in a structure pointer as the argument providing the size of
|
||||
* the structure in the first u32. The kernel checks that any structure space
|
||||
* beyond what it understands is 0. This allows userspace to use the backward
|
||||
* compatible 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 has
|
||||
* non-zero in a part the kernel does not understand.
|
||||
* - EOPNOTSUPP: The IOCTL number is supported, and the structure is
|
||||
* understood, however a known field has a value the kernel does not
|
||||
* understand or support.
|
||||
* - EINVAL: Everything about the IOCTL was understood, but a field is not
|
||||
* correct.
|
||||
* - ENOENT: A provided token does not exist.
|
||||
* - ENOMEM: Out of memory.
|
||||
* - EOVERFLOW: Mathematics overflowed.
|
||||
*
|
||||
* As well as additional errnos, within specific ioctls.
|
||||
*/
|
||||
|
||||
/* The ioctl type, documented in ioctl-number.rst */
|
||||
#define LIVEUPDATE_IOCTL_TYPE 0xBA
|
||||
|
||||
/* The maximum length of session name including null termination */
|
||||
#define LIVEUPDATE_SESSION_NAME_LENGTH 64
|
||||
|
||||
/* The /dev/liveupdate ioctl commands */
|
||||
enum {
|
||||
LIVEUPDATE_CMD_BASE = 0x00,
|
||||
LIVEUPDATE_CMD_CREATE_SESSION = LIVEUPDATE_CMD_BASE,
|
||||
LIVEUPDATE_CMD_RETRIEVE_SESSION = 0x01,
|
||||
};
|
||||
|
||||
/* ioctl commands for session file descriptors */
|
||||
enum {
|
||||
LIVEUPDATE_CMD_SESSION_BASE = 0x40,
|
||||
LIVEUPDATE_CMD_SESSION_PRESERVE_FD = LIVEUPDATE_CMD_SESSION_BASE,
|
||||
LIVEUPDATE_CMD_SESSION_RETRIEVE_FD = 0x41,
|
||||
LIVEUPDATE_CMD_SESSION_FINISH = 0x42,
|
||||
};
|
||||
|
||||
/**
|
||||
* struct liveupdate_ioctl_create_session - ioctl(LIVEUPDATE_IOCTL_CREATE_SESSION)
|
||||
* @size: Input; sizeof(struct liveupdate_ioctl_create_session)
|
||||
* @fd: Output; The new file descriptor for the created session.
|
||||
* @name: Input; A null-terminated string for the session name, max
|
||||
* length %LIVEUPDATE_SESSION_NAME_LENGTH including termination
|
||||
* character.
|
||||
*
|
||||
* 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.
|
||||
*/
|
||||
struct liveupdate_ioctl_create_session {
|
||||
__u32 size;
|
||||
__s32 fd;
|
||||
__u8 name[LIVEUPDATE_SESSION_NAME_LENGTH];
|
||||
};
|
||||
|
||||
#define LIVEUPDATE_IOCTL_CREATE_SESSION \
|
||||
_IO(LIVEUPDATE_IOCTL_TYPE, LIVEUPDATE_CMD_CREATE_SESSION)
|
||||
|
||||
/**
|
||||
* struct liveupdate_ioctl_retrieve_session - ioctl(LIVEUPDATE_IOCTL_RETRIEVE_SESSION)
|
||||
* @size: Input; sizeof(struct liveupdate_ioctl_retrieve_session)
|
||||
* @fd: Output; The new file descriptor for the retrieved session.
|
||||
* @name: Input; A null-terminated string identifying the session to retrieve.
|
||||
* The name must exactly match the name used when the session was
|
||||
* created in the previous kernel.
|
||||
*
|
||||
* Retrieves a handle (a new file descriptor) for a preserved session by its
|
||||
* name. This is the primary mechanism for a userspace agent to regain control
|
||||
* of its preserved resources after a live update.
|
||||
*
|
||||
* The userspace application provides the null-terminated `name` of a session
|
||||
* it created before the live update. If a preserved session with a matching
|
||||
* name is found, the kernel instantiates it and returns a new file descriptor
|
||||
* in the `fd` field. This new session FD can then be used for all file-specific
|
||||
* operations, such as restoring individual file descriptors with
|
||||
* LIVEUPDATE_SESSION_RETRIEVE_FD.
|
||||
*
|
||||
* It is the responsibility of the userspace application to know the names of
|
||||
* the sessions it needs to retrieve. If no session with the given name is
|
||||
* found, the ioctl will fail with -ENOENT.
|
||||
*
|
||||
* This ioctl can only be called on the main /dev/liveupdate device when the
|
||||
* system is in the LIVEUPDATE_STATE_UPDATED state.
|
||||
*/
|
||||
struct liveupdate_ioctl_retrieve_session {
|
||||
__u32 size;
|
||||
__s32 fd;
|
||||
__u8 name[LIVEUPDATE_SESSION_NAME_LENGTH];
|
||||
};
|
||||
|
||||
#define LIVEUPDATE_IOCTL_RETRIEVE_SESSION \
|
||||
_IO(LIVEUPDATE_IOCTL_TYPE, LIVEUPDATE_CMD_RETRIEVE_SESSION)
|
||||
|
||||
/* Session specific IOCTLs */
|
||||
|
||||
/**
|
||||
* struct liveupdate_session_preserve_fd - ioctl(LIVEUPDATE_SESSION_PRESERVE_FD)
|
||||
* @size: Input; sizeof(struct liveupdate_session_preserve_fd)
|
||||
* @fd: Input; The user-space file descriptor to be preserved.
|
||||
* @token: Input; An opaque, unique token for preserved resource.
|
||||
*
|
||||
* Holds parameters for preserving a file descriptor.
|
||||
*
|
||||
* User sets the @fd field identifying the file descriptor to preserve
|
||||
* (e.g., memfd, kvm, iommufd, VFIO). The kernel validates if this FD type
|
||||
* and its dependencies are supported for preservation. If validation passes,
|
||||
* the kernel marks the FD internally and *initiates the process* of preparing
|
||||
* its state for saving. The actual snapshotting of the state typically occurs
|
||||
* during the subsequent %LIVEUPDATE_IOCTL_PREPARE execution phase, though
|
||||
* some finalization might occur during freeze.
|
||||
* On successful validation and initiation, the kernel uses the @token
|
||||
* field with an opaque identifier representing the resource being preserved.
|
||||
* This token confirms the FD is targeted for preservation and is required for
|
||||
* the subsequent %LIVEUPDATE_SESSION_RETRIEVE_FD call after the live update.
|
||||
*
|
||||
* Return: 0 on success (validation passed, preservation initiated), negative
|
||||
* error code on failure (e.g., unsupported FD type, dependency issue,
|
||||
* validation failed).
|
||||
*/
|
||||
struct liveupdate_session_preserve_fd {
|
||||
__u32 size;
|
||||
__s32 fd;
|
||||
__aligned_u64 token;
|
||||
};
|
||||
|
||||
#define LIVEUPDATE_SESSION_PRESERVE_FD \
|
||||
_IO(LIVEUPDATE_IOCTL_TYPE, LIVEUPDATE_CMD_SESSION_PRESERVE_FD)
|
||||
|
||||
/**
|
||||
* struct liveupdate_session_retrieve_fd - ioctl(LIVEUPDATE_SESSION_RETRIEVE_FD)
|
||||
* @size: Input; sizeof(struct liveupdate_session_retrieve_fd)
|
||||
* @fd: Output; The new file descriptor representing the fully restored
|
||||
* kernel resource.
|
||||
* @token: Input; An opaque, token that was used to preserve the resource.
|
||||
*
|
||||
* Retrieve a previously preserved file descriptor.
|
||||
*
|
||||
* User sets the @token field to the value obtained from a successful
|
||||
* %LIVEUPDATE_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 the @fd field with a new file
|
||||
* descriptor referencing the restored resource in the current (new) kernel.
|
||||
* This operation must be performed *before* signaling completion via
|
||||
* %LIVEUPDATE_IOCTL_FINISH.
|
||||
*
|
||||
* Return: 0 on success, negative error code on failure (e.g., invalid token).
|
||||
*/
|
||||
struct liveupdate_session_retrieve_fd {
|
||||
__u32 size;
|
||||
__s32 fd;
|
||||
__aligned_u64 token;
|
||||
};
|
||||
|
||||
#define LIVEUPDATE_SESSION_RETRIEVE_FD \
|
||||
_IO(LIVEUPDATE_IOCTL_TYPE, LIVEUPDATE_CMD_SESSION_RETRIEVE_FD)
|
||||
|
||||
/**
|
||||
* struct liveupdate_session_finish - ioctl(LIVEUPDATE_SESSION_FINISH)
|
||||
* @size: Input; sizeof(struct liveupdate_session_finish)
|
||||
* @reserved: Input; Must be zero. Reserved for future use.
|
||||
*
|
||||
* Signals the completion of the restoration process for a retrieved session.
|
||||
* This is the final operation that should be performed on a session file
|
||||
* descriptor after a live update.
|
||||
*
|
||||
* This ioctl must be called once all required file descriptors for the session
|
||||
* have been successfully retrieved (using %LIVEUPDATE_SESSION_RETRIEVE_FD) and
|
||||
* are fully restored from the userspace and kernel perspective.
|
||||
*
|
||||
* Upon success, the kernel releases its ownership of the preserved resources
|
||||
* associated with this session. This allows internal resources to be freed,
|
||||
* typically by decrementing reference counts on the underlying preserved
|
||||
* objects.
|
||||
*
|
||||
* If this operation fails, the resources remain preserved in memory. Userspace
|
||||
* may attempt to call finish again. The resources will otherwise be reset
|
||||
* during the next live update cycle.
|
||||
*
|
||||
* Return: 0 on success, negative error code on failure.
|
||||
*/
|
||||
struct liveupdate_session_finish {
|
||||
__u32 size;
|
||||
__u32 reserved;
|
||||
};
|
||||
|
||||
#define LIVEUPDATE_SESSION_FINISH \
|
||||
_IO(LIVEUPDATE_IOCTL_TYPE, LIVEUPDATE_CMD_SESSION_FINISH)
|
||||
|
||||
#endif /* _UAPI_LIVEUPDATE_H */
|
||||
Reference in New Issue
Block a user