liveupdate.h

  1/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
  2
  3/*
  4 * Userspace interface for /dev/liveupdate
  5 * Live Update Orchestrator
  6 *
  7 * Copyright (c) 2025, Google LLC.
  8 * Pasha Tatashin <pasha.tatashin@soleen.com>
  9 */
 10
 11#ifndef _UAPI_LIVEUPDATE_H
 12#define _UAPI_LIVEUPDATE_H
 13
 14#include <linux/ioctl.h>
 15#include <linux/types.h>
 16
 17/**
 18 * DOC: General ioctl format
 19 *
 20 * The ioctl interface follows a general format to allow for extensibility. Each
 21 * ioctl is passed in a structure pointer as the argument providing the size of
 22 * the structure in the first u32. The kernel checks that any structure space
 23 * beyond what it understands is 0. This allows userspace to use the backward
 24 * compatible portion while consistently using the newer, larger, structures.
 25 *
 26 * ioctls use a standard meaning for common errnos:
 27 *
 28 *  - ENOTTY: The IOCTL number itself is not supported at all
 29 *  - E2BIG: The IOCTL number is supported, but the provided structure has
 30 *    non-zero in a part the kernel does not understand.
 31 *  - EOPNOTSUPP: The IOCTL number is supported, and the structure is
 32 *    understood, however a known field has a value the kernel does not
 33 *    understand or support.
 34 *  - EINVAL: Everything about the IOCTL was understood, but a field is not
 35 *    correct.
 36 *  - ENOENT: A provided token does not exist.
 37 *  - ENOMEM: Out of memory.
 38 *  - EOVERFLOW: Mathematics overflowed.
 39 *
 40 * As well as additional errnos, within specific ioctls.
 41 */
 42
 43/* The ioctl type, documented in ioctl-number.rst */
 44#define LIVEUPDATE_IOCTL_TYPE		0xBA
 45
 46/* The maximum length of session name including null termination */
 47#define LIVEUPDATE_SESSION_NAME_LENGTH 64
 48
 49/* The /dev/liveupdate ioctl commands */
 50enum {
 51	LIVEUPDATE_CMD_BASE = 0x00,
 52	LIVEUPDATE_CMD_CREATE_SESSION = LIVEUPDATE_CMD_BASE,
 53	LIVEUPDATE_CMD_RETRIEVE_SESSION = 0x01,
 54};
 55
 56/* ioctl commands for session file descriptors */
 57enum {
 58	LIVEUPDATE_CMD_SESSION_BASE = 0x40,
 59	LIVEUPDATE_CMD_SESSION_PRESERVE_FD = LIVEUPDATE_CMD_SESSION_BASE,
 60	LIVEUPDATE_CMD_SESSION_RETRIEVE_FD = 0x41,
 61	LIVEUPDATE_CMD_SESSION_FINISH = 0x42,
 62};
 63
 64/**
 65 * struct liveupdate_ioctl_create_session - ioctl(LIVEUPDATE_IOCTL_CREATE_SESSION)
 66 * @size:	Input; sizeof(struct liveupdate_ioctl_create_session)
 67 * @fd:		Output; The new file descriptor for the created session.
 68 * @name:	Input; A null-terminated string for the session name, max
 69 *		length %LIVEUPDATE_SESSION_NAME_LENGTH including termination
 70 *		character.
 71 *
 72 * Creates a new live update session for managing preserved resources.
 73 * This ioctl can only be called on the main /dev/liveupdate device.
 74 *
 75 * Return: 0 on success, negative error code on failure.
 76 */
 77struct liveupdate_ioctl_create_session {
 78	__u32		size;
 79	__s32		fd;
 80	__u8		name[LIVEUPDATE_SESSION_NAME_LENGTH];
 81};
 82
 83#define LIVEUPDATE_IOCTL_CREATE_SESSION					\
 84	_IO(LIVEUPDATE_IOCTL_TYPE, LIVEUPDATE_CMD_CREATE_SESSION)
 85
 86/**
 87 * struct liveupdate_ioctl_retrieve_session - ioctl(LIVEUPDATE_IOCTL_RETRIEVE_SESSION)
 88 * @size:    Input; sizeof(struct liveupdate_ioctl_retrieve_session)
 89 * @fd:      Output; The new file descriptor for the retrieved session.
 90 * @name:    Input; A null-terminated string identifying the session to retrieve.
 91 *           The name must exactly match the name used when the session was
 92 *           created in the previous kernel.
 93 *
 94 * Retrieves a handle (a new file descriptor) for a preserved session by its
 95 * name. This is the primary mechanism for a userspace agent to regain control
 96 * of its preserved resources after a live update.
 97 *
 98 * The userspace application provides the null-terminated `name` of a session
 99 * it created before the live update. If a preserved session with a matching
100 * name is found, the kernel instantiates it and returns a new file descriptor
101 * in the `fd` field. This new session FD can then be used for all file-specific
102 * operations, such as restoring individual file descriptors with
103 * LIVEUPDATE_SESSION_RETRIEVE_FD.
104 *
105 * It is the responsibility of the userspace application to know the names of
106 * the sessions it needs to retrieve. If no session with the given name is
107 * found, the ioctl will fail with -ENOENT.
108 *
109 * This ioctl can only be called on the main /dev/liveupdate device when the
110 * system is in the LIVEUPDATE_STATE_UPDATED state.
111 */
112struct liveupdate_ioctl_retrieve_session {
113	__u32		size;
114	__s32		fd;
115	__u8		name[LIVEUPDATE_SESSION_NAME_LENGTH];
116};
117
118#define LIVEUPDATE_IOCTL_RETRIEVE_SESSION \
119	_IO(LIVEUPDATE_IOCTL_TYPE, LIVEUPDATE_CMD_RETRIEVE_SESSION)
120
121/* Session specific IOCTLs */
122
123/**
124 * struct liveupdate_session_preserve_fd - ioctl(LIVEUPDATE_SESSION_PRESERVE_FD)
125 * @size:  Input; sizeof(struct liveupdate_session_preserve_fd)
126 * @fd:    Input; The user-space file descriptor to be preserved.
127 * @token: Input; An opaque, unique token for preserved resource.
128 *
129 * Holds parameters for preserving a file descriptor.
130 *
131 * User sets the @fd field identifying the file descriptor to preserve
132 * (e.g., memfd, kvm, iommufd, VFIO). The kernel validates if this FD type
133 * and its dependencies are supported for preservation. If validation passes,
134 * the kernel marks the FD internally and *initiates the process* of preparing
135 * its state for saving. The actual snapshotting of the state typically occurs
136 * during the subsequent %LIVEUPDATE_IOCTL_PREPARE execution phase, though
137 * some finalization might occur during freeze.
138 * On successful validation and initiation, the kernel uses the @token
139 * field with an opaque identifier representing the resource being preserved.
140 * This token confirms the FD is targeted for preservation and is required for
141 * the subsequent %LIVEUPDATE_SESSION_RETRIEVE_FD call after the live update.
142 *
143 * Return: 0 on success (validation passed, preservation initiated), negative
144 * error code on failure (e.g., unsupported FD type, dependency issue,
145 * validation failed).
146 */
147struct liveupdate_session_preserve_fd {
148	__u32		size;
149	__s32		fd;
150	__aligned_u64	token;
151};
152
153#define LIVEUPDATE_SESSION_PRESERVE_FD					\
154	_IO(LIVEUPDATE_IOCTL_TYPE, LIVEUPDATE_CMD_SESSION_PRESERVE_FD)
155
156/**
157 * struct liveupdate_session_retrieve_fd - ioctl(LIVEUPDATE_SESSION_RETRIEVE_FD)
158 * @size:  Input; sizeof(struct liveupdate_session_retrieve_fd)
159 * @fd:    Output; The new file descriptor representing the fully restored
160 *         kernel resource.
161 * @token: Input; An opaque, token that was used to preserve the resource.
162 *
163 * Retrieve a previously preserved file descriptor.
164 *
165 * User sets the @token field to the value obtained from a successful
166 * %LIVEUPDATE_IOCTL_FD_PRESERVE call before the live update. On success,
167 * the kernel restores the state (saved during the PREPARE/FREEZE phases)
168 * associated with the token and populates the @fd field with a new file
169 * descriptor referencing the restored resource in the current (new) kernel.
170 * This operation must be performed *before* signaling completion via
171 * %LIVEUPDATE_IOCTL_FINISH.
172 *
173 * Return: 0 on success, negative error code on failure (e.g., invalid token).
174 */
175struct liveupdate_session_retrieve_fd {
176	__u32		size;
177	__s32		fd;
178	__aligned_u64	token;
179};
180
181#define LIVEUPDATE_SESSION_RETRIEVE_FD					\
182	_IO(LIVEUPDATE_IOCTL_TYPE, LIVEUPDATE_CMD_SESSION_RETRIEVE_FD)
183
184/**
185 * struct liveupdate_session_finish - ioctl(LIVEUPDATE_SESSION_FINISH)
186 * @size:     Input; sizeof(struct liveupdate_session_finish)
187 * @reserved: Input; Must be zero. Reserved for future use.
188 *
189 * Signals the completion of the restoration process for a retrieved session.
190 * This is the final operation that should be performed on a session file
191 * descriptor after a live update.
192 *
193 * This ioctl must be called once all required file descriptors for the session
194 * have been successfully retrieved (using %LIVEUPDATE_SESSION_RETRIEVE_FD) and
195 * are fully restored from the userspace and kernel perspective.
196 *
197 * Upon success, the kernel releases its ownership of the preserved resources
198 * associated with this session. This allows internal resources to be freed,
199 * typically by decrementing reference counts on the underlying preserved
200 * objects.
201 *
202 * If this operation fails, the resources remain preserved in memory. Userspace
203 * may attempt to call finish again. The resources will otherwise be reset
204 * during the next live update cycle.
205 *
206 * Return: 0 on success, negative error code on failure.
207 */
208struct liveupdate_session_finish {
209	__u32		size;
210	__u32		reserved;
211};
212
213#define LIVEUPDATE_SESSION_FINISH					\
214	_IO(LIVEUPDATE_IOCTL_TYPE, LIVEUPDATE_CMD_SESSION_FINISH)
215
216#endif /* _UAPI_LIVEUPDATE_H */