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 _LIVEUPDATE_H
12#define _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 LIVEUPDATE_CMD_SESSION_GET_NAME = 0x43,
63};
64
65/**
66 * struct liveupdate_ioctl_create_session - ioctl(LIVEUPDATE_IOCTL_CREATE_SESSION)
67 * @size: Input; sizeof(struct liveupdate_ioctl_create_session)
68 * @fd: Output; The new file descriptor for the created session.
69 * @name: Input; A null-terminated string for the session name, max
70 * length %LIVEUPDATE_SESSION_NAME_LENGTH including termination
71 * character.
72 *
73 * Creates a new live update session for managing preserved resources.
74 * This ioctl can only be called on the main /dev/liveupdate device.
75 *
76 * Return: 0 on success, negative error code on failure.
77 */
78struct liveupdate_ioctl_create_session {
79 __u32 size;
80 __s32 fd;
81 __u8 name[LIVEUPDATE_SESSION_NAME_LENGTH];
82};
83
84#define LIVEUPDATE_IOCTL_CREATE_SESSION \
85 _IO(LIVEUPDATE_IOCTL_TYPE, LIVEUPDATE_CMD_CREATE_SESSION)
86
87/**
88 * struct liveupdate_ioctl_retrieve_session - ioctl(LIVEUPDATE_IOCTL_RETRIEVE_SESSION)
89 * @size: Input; sizeof(struct liveupdate_ioctl_retrieve_session)
90 * @fd: Output; The new file descriptor for the retrieved session.
91 * @name: Input; A null-terminated string identifying the session to retrieve.
92 * The name must exactly match the name used when the session was
93 * created in the previous kernel.
94 *
95 * Retrieves a handle (a new file descriptor) for a preserved session by its
96 * name. This is the primary mechanism for a userspace agent to regain control
97 * of its preserved resources after a live update.
98 *
99 * The userspace application provides the null-terminated `name` of a session
100 * it created before the live update. If a preserved session with a matching
101 * name is found, the kernel instantiates it and returns a new file descriptor
102 * in the `fd` field. This new session FD can then be used for all file-specific
103 * operations, such as restoring individual file descriptors with
104 * LIVEUPDATE_SESSION_RETRIEVE_FD.
105 *
106 * It is the responsibility of the userspace application to know the names of
107 * the sessions it needs to retrieve. If no session with the given name is
108 * found, the ioctl will fail with -ENOENT.
109 *
110 * This ioctl can only be called on the main /dev/liveupdate device when the
111 * system is in the LIVEUPDATE_STATE_UPDATED state.
112 */
113struct liveupdate_ioctl_retrieve_session {
114 __u32 size;
115 __s32 fd;
116 __u8 name[LIVEUPDATE_SESSION_NAME_LENGTH];
117};
118
119#define LIVEUPDATE_IOCTL_RETRIEVE_SESSION \
120 _IO(LIVEUPDATE_IOCTL_TYPE, LIVEUPDATE_CMD_RETRIEVE_SESSION)
121
122/* Session specific IOCTLs */
123
124/**
125 * struct liveupdate_session_preserve_fd - ioctl(LIVEUPDATE_SESSION_PRESERVE_FD)
126 * @size: Input; sizeof(struct liveupdate_session_preserve_fd)
127 * @fd: Input; The user-space file descriptor to be preserved.
128 * @token: Input; An opaque, unique token for preserved resource.
129 *
130 * Holds parameters for preserving a file descriptor.
131 *
132 * User sets the @fd field identifying the file descriptor to preserve
133 * (e.g., memfd, kvm, iommufd, VFIO). The kernel validates if this FD type
134 * and its dependencies are supported for preservation. If validation passes,
135 * the kernel marks the FD internally and *initiates the process* of preparing
136 * its state for saving. The actual snapshotting of the state typically occurs
137 * during the subsequent %LIVEUPDATE_IOCTL_PREPARE execution phase, though
138 * some finalization might occur during freeze.
139 * On successful validation and initiation, the kernel uses the @token
140 * field with an opaque identifier representing the resource being preserved.
141 * This token confirms the FD is targeted for preservation and is required for
142 * the subsequent %LIVEUPDATE_SESSION_RETRIEVE_FD call after the live update.
143 *
144 * Return: 0 on success (validation passed, preservation initiated), negative
145 * error code on failure (e.g., unsupported FD type, dependency issue,
146 * validation failed).
147 */
148struct liveupdate_session_preserve_fd {
149 __u32 size;
150 __s32 fd;
151 __aligned_u64 token;
152};
153
154#define LIVEUPDATE_SESSION_PRESERVE_FD \
155 _IO(LIVEUPDATE_IOCTL_TYPE, LIVEUPDATE_CMD_SESSION_PRESERVE_FD)
156
157/**
158 * struct liveupdate_session_retrieve_fd - ioctl(LIVEUPDATE_SESSION_RETRIEVE_FD)
159 * @size: Input; sizeof(struct liveupdate_session_retrieve_fd)
160 * @fd: Output; The new file descriptor representing the fully restored
161 * kernel resource.
162 * @token: Input; An opaque, token that was used to preserve the resource.
163 *
164 * Retrieve a previously preserved file descriptor.
165 *
166 * User sets the @token field to the value obtained from a successful
167 * %LIVEUPDATE_IOCTL_FD_PRESERVE call before the live update. On success,
168 * the kernel restores the state (saved during the PREPARE/FREEZE phases)
169 * associated with the token and populates the @fd field with a new file
170 * descriptor referencing the restored resource in the current (new) kernel.
171 * This operation must be performed *before* signaling completion via
172 * %LIVEUPDATE_IOCTL_FINISH. If a retrieve of a token fails, subsequent
173 * attempts to retrieve the token fail with the same error code. Failed
174 * retrieves are not retried.
175 *
176 * Return: 0 on success, negative error code on failure (e.g., invalid token).
177 */
178struct liveupdate_session_retrieve_fd {
179 __u32 size;
180 __s32 fd;
181 __aligned_u64 token;
182};
183
184#define LIVEUPDATE_SESSION_RETRIEVE_FD \
185 _IO(LIVEUPDATE_IOCTL_TYPE, LIVEUPDATE_CMD_SESSION_RETRIEVE_FD)
186
187/**
188 * struct liveupdate_session_finish - ioctl(LIVEUPDATE_SESSION_FINISH)
189 * @size: Input; sizeof(struct liveupdate_session_finish)
190 * @reserved: Input; Must be zero. Reserved for future use.
191 *
192 * Signals the completion of the restoration process for a retrieved session.
193 * This is the final operation that should be performed on a session file
194 * descriptor after a live update.
195 *
196 * This ioctl must be called once all required file descriptors for the session
197 * have been successfully retrieved (using %LIVEUPDATE_SESSION_RETRIEVE_FD) and
198 * are fully restored from the userspace and kernel perspective.
199 *
200 * Upon success, the kernel releases its ownership of the preserved resources
201 * associated with this session. This allows internal resources to be freed,
202 * typically by decrementing reference counts on the underlying preserved
203 * objects.
204 *
205 * If this operation fails, the resources remain preserved in memory. Userspace
206 * may attempt to call finish again. The resources will otherwise be reset
207 * during the next live update cycle.
208 *
209 * Return: 0 on success, negative error code on failure.
210 */
211struct liveupdate_session_finish {
212 __u32 size;
213 __u32 reserved;
214};
215
216#define LIVEUPDATE_SESSION_FINISH \
217 _IO(LIVEUPDATE_IOCTL_TYPE, LIVEUPDATE_CMD_SESSION_FINISH)
218
219/**
220 * struct liveupdate_session_get_name - ioctl(LIVEUPDATE_SESSION_GET_NAME)
221 * @size: Input; sizeof(struct liveupdate_session_get_name)
222 * @reserved: Input; Must be zero. Reserved for future use.
223 * @name: Output; A null-terminated string with the full session name.
224 *
225 * Retrieves the full name of the session associated with this file descriptor.
226 * This is useful because the kernel may truncate the name shown in /proc.
227 *
228 * Return: 0 on success, negative error code on failure.
229 */
230struct liveupdate_session_get_name {
231 __u32 size;
232 __u32 reserved;
233 __u8 name[LIVEUPDATE_SESSION_NAME_LENGTH];
234};
235
236#define LIVEUPDATE_SESSION_GET_NAME \
237 _IO(LIVEUPDATE_IOCTL_TYPE, LIVEUPDATE_CMD_SESSION_GET_NAME)
238
239#endif /* _LIVEUPDATE_H */