Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
tjh.dev
kernel
os
linux
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 */