1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
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 */
|
