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 */ 50 enum { 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 */ 57 enum { 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 */ 77 struct 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 */ 112 struct 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 */ 147 struct 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 */ 175 struct 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 */ 208 struct 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 */ 217