liveupdate: luo_file: implement file systems callbacks

+38 -1

include/linux/kho/abi/luo.h

··· 69 69 * Metadata for a single session, including its name and a physical pointer 70 70 * to another preserved memory block containing an array of 71 71 * `struct luo_file_ser` for all files in that session. 72 + * 73 + * - struct luo_file_ser: 74 + * Metadata for a single preserved file. Contains the `compatible` string to 75 + * find the correct handler in the new kernel, a user-provided `token` for 76 + * identification, and an opaque `data` handle for the handler to use. 72 77 */ 73 78 74 79 #ifndef _LINUX_KHO_ABI_LUO_H ··· 91 86 #define LUO_FDT_COMPATIBLE "luo-v1" 92 87 #define LUO_FDT_LIVEUPDATE_NUM "liveupdate-number" 93 88 89 + #define LIVEUPDATE_HNDL_COMPAT_LENGTH 48 90 + 91 + /** 92 + * struct luo_file_ser - Represents the serialized preserves files. 93 + * @compatible: File handler compatible string. 94 + * @data: Private data 95 + * @token: User provided token for this file 96 + * 97 + * If this structure is modified, LUO_SESSION_COMPATIBLE must be updated. 98 + */ 99 + struct luo_file_ser { 100 + char compatible[LIVEUPDATE_HNDL_COMPAT_LENGTH]; 101 + u64 data; 102 + u64 token; 103 + } __packed; 104 + 105 + /** 106 + * struct luo_file_set_ser - Represents the serialized metadata for file set 107 + * @files: The physical address of a contiguous memory block that holds 108 + * the serialized state of files (array of luo_file_ser) in this file 109 + * set. 110 + * @count: The total number of files that were part of this session during 111 + * serialization. Used for iteration and validation during 112 + * restoration. 113 + */ 114 + struct luo_file_set_ser { 115 + u64 files; 116 + u64 count; 117 + } __packed; 118 + 94 119 /* 95 120 * LUO FDT session node 96 121 * LUO_FDT_SESSION_HEADER: is a u64 physical address of struct 97 122 * luo_session_header_ser 98 123 */ 99 124 #define LUO_FDT_SESSION_NODE_NAME "luo-session" 100 - #define LUO_FDT_SESSION_COMPATIBLE "luo-session-v1" 125 + #define LUO_FDT_SESSION_COMPATIBLE "luo-session-v2" 101 126 #define LUO_FDT_SESSION_HEADER "luo-session-header" 102 127 103 128 /** ··· 149 114 * struct luo_session_ser - Represents the serialized metadata for a LUO session. 150 115 * @name: The unique name of the session, provided by the userspace at 151 116 * the time of session creation. 117 + * @file_set_ser: Serialized files belonging to this session, 152 118 * 153 119 * This structure is used to package session-specific metadata for transfer 154 120 * between kernels via Kexec Handover. An array of these structures (one per ··· 160 124 */ 161 125 struct luo_session_ser { 162 126 char name[LIVEUPDATE_SESSION_NAME_LENGTH]; 127 + struct luo_file_set_ser file_set_ser; 163 128 } __packed; 164 129 165 130 #endif /* _LINUX_KHO_ABI_LUO_H */

+98

include/linux/liveupdate.h

··· 8 8 #define _LINUX_LIVEUPDATE_H 9 9 10 10 #include <linux/bug.h> 11 + #include <linux/compiler.h> 12 + #include <linux/kho/abi/luo.h> 11 13 #include <linux/list.h> 12 14 #include <linux/types.h> 15 + #include <uapi/linux/liveupdate.h> 16 + 17 + struct liveupdate_file_handler; 18 + struct file; 19 + 20 + /** 21 + * struct liveupdate_file_op_args - Arguments for file operation callbacks. 22 + * @handler: The file handler being called. 23 + * @retrieved: The retrieve status for the 'can_finish / finish' 24 + * operation. 25 + * @file: The file object. For retrieve: [OUT] The callback sets 26 + * this to the new file. For other ops: [IN] The caller sets 27 + * this to the file being operated on. 28 + * @serialized_data: The opaque u64 handle, preserve/prepare/freeze may update 29 + * this field. 30 + * 31 + * This structure bundles all parameters for the file operation callbacks. 32 + * The 'data' and 'file' fields are used for both input and output. 33 + */ 34 + struct liveupdate_file_op_args { 35 + struct liveupdate_file_handler *handler; 36 + bool retrieved; 37 + struct file *file; 38 + u64 serialized_data; 39 + }; 40 + 41 + /** 42 + * struct liveupdate_file_ops - Callbacks for live-updatable files. 43 + * @can_preserve: Required. Lightweight check to see if this handler is 44 + * compatible with the given file. 45 + * @preserve: Required. Performs state-saving for the file. 46 + * @unpreserve: Required. Cleans up any resources allocated by @preserve. 47 + * @freeze: Optional. Final actions just before kernel transition. 48 + * @unfreeze: Optional. Undo freeze operations. 49 + * @retrieve: Required. Restores the file in the new kernel. 50 + * @can_finish: Optional. Check if this FD can finish, i.e. all restoration 51 + * pre-requirements for this FD are satisfied. Called prior to 52 + * finish, in order to do successful finish calls for all 53 + * resources in the session. 54 + * @finish: Required. Final cleanup in the new kernel. 55 + * @owner: Module reference 56 + * 57 + * All operations (except can_preserve) receive a pointer to a 58 + * 'struct liveupdate_file_op_args' containing the necessary context. 59 + */ 60 + struct liveupdate_file_ops { 61 + bool (*can_preserve)(struct liveupdate_file_handler *handler, 62 + struct file *file); 63 + int (*preserve)(struct liveupdate_file_op_args *args); 64 + void (*unpreserve)(struct liveupdate_file_op_args *args); 65 + int (*freeze)(struct liveupdate_file_op_args *args); 66 + void (*unfreeze)(struct liveupdate_file_op_args *args); 67 + int (*retrieve)(struct liveupdate_file_op_args *args); 68 + bool (*can_finish)(struct liveupdate_file_op_args *args); 69 + void (*finish)(struct liveupdate_file_op_args *args); 70 + struct module *owner; 71 + }; 72 + 73 + /** 74 + * struct liveupdate_file_handler - Represents a handler for a live-updatable file type. 75 + * @ops: Callback functions 76 + * @compatible: The compatibility string (e.g., "memfd-v1", "vfiofd-v1") 77 + * that uniquely identifies the file type this handler 78 + * supports. This is matched against the compatible string 79 + * associated with individual &struct file instances. 80 + * 81 + * Modules that want to support live update for specific file types should 82 + * register an instance of this structure. LUO uses this registration to 83 + * determine if a given file can be preserved and to find the appropriate 84 + * operations to manage its state across the update. 85 + */ 86 + struct liveupdate_file_handler { 87 + const struct liveupdate_file_ops *ops; 88 + const char compatible[LIVEUPDATE_HNDL_COMPAT_LENGTH]; 89 + 90 + /* private: */ 91 + 92 + /* 93 + * Used for linking this handler instance into a global list of 94 + * registered file handlers. 95 + */ 96 + struct list_head __private list; 97 + }; 13 98 14 99 #ifdef CONFIG_LIVEUPDATE 15 100 ··· 103 18 104 19 /* Called during kexec to tell LUO that entered into reboot */ 105 20 int liveupdate_reboot(void); 21 + 22 + int liveupdate_register_file_handler(struct liveupdate_file_handler *fh); 23 + int liveupdate_unregister_file_handler(struct liveupdate_file_handler *fh); 106 24 107 25 #else /* CONFIG_LIVEUPDATE */ 108 26 ··· 117 29 static inline int liveupdate_reboot(void) 118 30 { 119 31 return 0; 32 + } 33 + 34 + static inline int liveupdate_register_file_handler(struct liveupdate_file_handler *fh) 35 + { 36 + return -EOPNOTSUPP; 37 + } 38 + 39 + static inline int liveupdate_unregister_file_handler(struct liveupdate_file_handler *fh) 40 + { 41 + return -EOPNOTSUPP; 120 42 } 121 43 122 44 #endif /* CONFIG_LIVEUPDATE */

+1

kernel/liveupdate/Makefile

··· 2 2 3 3 luo-y := \ 4 4 luo_core.o \ 5 + luo_file.o \ 5 6 luo_session.o 6 7 7 8 obj-$(CONFIG_KEXEC_HANDOVER) += kexec_handover.o

+880

kernel/liveupdate/luo_file.c

··· 1 + // SPDX-License-Identifier: GPL-2.0 2 + 3 + /* 4 + * Copyright (c) 2025, Google LLC. 5 + * Pasha Tatashin <pasha.tatashin@soleen.com> 6 + */ 7 + 8 + /** 9 + * DOC: LUO File Descriptors 10 + * 11 + * LUO provides the infrastructure to preserve specific, stateful file 12 + * descriptors across a kexec-based live update. The primary goal is to allow 13 + * workloads, such as virtual machines using vfio, memfd, or iommufd, to 14 + * retain access to their essential resources without interruption. 15 + * 16 + * The framework is built around a callback-based handler model and a well- 17 + * defined lifecycle for each preserved file. 18 + * 19 + * Handler Registration: 20 + * Kernel modules responsible for a specific file type (e.g., memfd, vfio) 21 + * register a &struct liveupdate_file_handler. This handler provides a set of 22 + * callbacks that LUO invokes at different stages of the update process, most 23 + * notably: 24 + * 25 + * - can_preserve(): A lightweight check to determine if the handler is 26 + * compatible with a given 'struct file'. 27 + * - preserve(): The heavyweight operation that saves the file's state and 28 + * returns an opaque u64 handle. This is typically performed while the 29 + * workload is still active to minimize the downtime during the 30 + * actual reboot transition. 31 + * - unpreserve(): Cleans up any resources allocated by .preserve(), called 32 + * if the preservation process is aborted before the reboot (i.e. session is 33 + * closed). 34 + * - freeze(): A final pre-reboot opportunity to prepare the state for kexec. 35 + * We are already in reboot syscall, and therefore userspace cannot mutate 36 + * the file anymore. 37 + * - unfreeze(): Undoes the actions of .freeze(), called if the live update 38 + * is aborted after the freeze phase. 39 + * - retrieve(): Reconstructs the file in the new kernel from the preserved 40 + * handle. 41 + * - finish(): Performs final check and cleanup in the new kernel. After 42 + * succesul finish call, LUO gives up ownership to this file. 43 + * 44 + * File Preservation Lifecycle happy path: 45 + * 46 + * 1. Preserve (Normal Operation): A userspace agent preserves files one by one 47 + * via an ioctl. For each file, luo_preserve_file() finds a compatible 48 + * handler, calls its .preserve() operation, and creates an internal &struct 49 + * luo_file to track the live state. 50 + * 51 + * 2. Freeze (Pre-Reboot): Just before the kexec, luo_file_freeze() is called. 52 + * It iterates through all preserved files, calls their respective .freeze() 53 + * operation, and serializes their final metadata (compatible string, token, 54 + * and data handle) into a contiguous memory block for KHO. 55 + * 56 + * 3. Deserialize: After kexec, luo_file_deserialize() runs when session gets 57 + * deserialized (which is when /dev/liveupdate is first opened). It reads the 58 + * serialized data from the KHO memory region and reconstructs the in-memory 59 + * list of &struct luo_file instances for the new kernel, linking them to 60 + * their corresponding handlers. 61 + * 62 + * 4. Retrieve (New Kernel - Userspace Ready): The userspace agent can now 63 + * restore file descriptors by providing a token. luo_retrieve_file() 64 + * searches for the matching token, calls the handler's .retrieve() op to 65 + * re-create the 'struct file', and returns a new FD. Files can be 66 + * retrieved in ANY order. 67 + * 68 + * 5. Finish (New Kernel - Cleanup): Once a session retrival is complete, 69 + * luo_file_finish() is called. It iterates through all files, invokes their 70 + * .finish() operations for final cleanup, and releases all associated kernel 71 + * resources. 72 + * 73 + * File Preservation Lifecycle unhappy paths: 74 + * 75 + * 1. Abort Before Reboot: If the userspace agent aborts the live update 76 + * process before calling reboot (e.g., by closing the session file 77 + * descriptor), the session's release handler calls 78 + * luo_file_unpreserve_files(). This invokes the .unpreserve() callback on 79 + * all preserved files, ensuring all allocated resources are cleaned up and 80 + * returning the system to a clean state. 81 + * 82 + * 2. Freeze Failure: During the reboot() syscall, if any handler's .freeze() 83 + * op fails, the .unfreeze() op is invoked on all previously *successful* 84 + * freezes to roll back their state. The reboot() syscall then returns an 85 + * error to userspace, canceling the live update. 86 + * 87 + * 3. Finish Failure: In the new kernel, if a handler's .finish() op fails, 88 + * the luo_file_finish() operation is aborted. LUO retains ownership of 89 + * all files within that session, including those that were not yet 90 + * processed. The userspace agent can attempt to call the finish operation 91 + * again later. If the issue cannot be resolved, these resources will be held 92 + * by LUO until the next live update cycle, at which point they will be 93 + * discarded. 94 + */ 95 + 96 + #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt 97 + 98 + #include <linux/cleanup.h> 99 + #include <linux/compiler.h> 100 + #include <linux/err.h> 101 + #include <linux/errno.h> 102 + #include <linux/file.h> 103 + #include <linux/fs.h> 104 + #include <linux/io.h> 105 + #include <linux/kexec_handover.h> 106 + #include <linux/kho/abi/luo.h> 107 + #include <linux/liveupdate.h> 108 + #include <linux/module.h> 109 + #include <linux/sizes.h> 110 + #include <linux/slab.h> 111 + #include <linux/string.h> 112 + #include "luo_internal.h" 113 + 114 + static LIST_HEAD(luo_file_handler_list); 115 + 116 + /* 2 4K pages, give space for 128 files per file_set */ 117 + #define LUO_FILE_PGCNT 2ul 118 + #define LUO_FILE_MAX \ 119 + ((LUO_FILE_PGCNT << PAGE_SHIFT) / sizeof(struct luo_file_ser)) 120 + 121 + /** 122 + * struct luo_file - Represents a single preserved file instance. 123 + * @fh: Pointer to the &struct liveupdate_file_handler that manages 124 + * this type of file. 125 + * @file: Pointer to the kernel's &struct file that is being preserved. 126 + * This is NULL in the new kernel until the file is successfully 127 + * retrieved. 128 + * @serialized_data: The opaque u64 handle to the serialized state of the file. 129 + * This handle is passed back to the handler's .freeze(), 130 + * .retrieve(), and .finish() callbacks, allowing it to track 131 + * and update its serialized state across phases. 132 + * @retrieved: A flag indicating whether a user/kernel in the new kernel has 133 + * successfully called retrieve() on this file. This prevents 134 + * multiple retrieval attempts. 135 + * @mutex: A mutex that protects the fields of this specific instance 136 + * (e.g., @retrieved, @file), ensuring that operations like 137 + * retrieving or finishing a file are atomic. 138 + * @list: The list_head linking this instance into its parent 139 + * file_set's list of preserved files. 140 + * @token: The user-provided unique token used to identify this file. 141 + * 142 + * This structure is the core in-kernel representation of a single file being 143 + * managed through a live update. An instance is created by luo_preserve_file() 144 + * to link a 'struct file' to its corresponding handler, a user-provided token, 145 + * and the serialized state handle returned by the handler's .preserve() 146 + * operation. 147 + * 148 + * These instances are tracked in a per-file_set list. The @serialized_data 149 + * field, which holds a handle to the file's serialized state, may be updated 150 + * during the .freeze() callback before being serialized for the next kernel. 151 + * After reboot, these structures are recreated by luo_file_deserialize() and 152 + * are finally cleaned up by luo_file_finish(). 153 + */ 154 + struct luo_file { 155 + struct liveupdate_file_handler *fh; 156 + struct file *file; 157 + u64 serialized_data; 158 + bool retrieved; 159 + struct mutex mutex; 160 + struct list_head list; 161 + u64 token; 162 + }; 163 + 164 + static int luo_alloc_files_mem(struct luo_file_set *file_set) 165 + { 166 + size_t size; 167 + void *mem; 168 + 169 + if (file_set->files) 170 + return 0; 171 + 172 + WARN_ON_ONCE(file_set->count); 173 + 174 + size = LUO_FILE_PGCNT << PAGE_SHIFT; 175 + mem = kho_alloc_preserve(size); 176 + if (IS_ERR(mem)) 177 + return PTR_ERR(mem); 178 + 179 + file_set->files = mem; 180 + 181 + return 0; 182 + } 183 + 184 + static void luo_free_files_mem(struct luo_file_set *file_set) 185 + { 186 + /* If file_set has files, no need to free preservation memory */ 187 + if (file_set->count) 188 + return; 189 + 190 + if (!file_set->files) 191 + return; 192 + 193 + kho_unpreserve_free(file_set->files); 194 + file_set->files = NULL; 195 + } 196 + 197 + static bool luo_token_is_used(struct luo_file_set *file_set, u64 token) 198 + { 199 + struct luo_file *iter; 200 + 201 + list_for_each_entry(iter, &file_set->files_list, list) { 202 + if (iter->token == token) 203 + return true; 204 + } 205 + 206 + return false; 207 + } 208 + 209 + /** 210 + * luo_preserve_file - Initiate the preservation of a file descriptor. 211 + * @file_set: The file_set to which the preserved file will be added. 212 + * @token: A unique, user-provided identifier for the file. 213 + * @fd: The file descriptor to be preserved. 214 + * 215 + * This function orchestrates the first phase of preserving a file. Upon entry, 216 + * it takes a reference to the 'struct file' via fget(), effectively making LUO 217 + * a co-owner of the file. This reference is held until the file is either 218 + * unpreserved or successfully finished in the next kernel, preventing the file 219 + * from being prematurely destroyed. 220 + * 221 + * This function orchestrates the first phase of preserving a file. It performs 222 + * the following steps: 223 + * 224 + * 1. Validates that the @token is not already in use within the file_set. 225 + * 2. Ensures the file_set's memory for files serialization is allocated 226 + * (allocates if needed). 227 + * 3. Iterates through registered handlers, calling can_preserve() to find one 228 + * compatible with the given @fd. 229 + * 4. Calls the handler's .preserve() operation, which saves the file's state 230 + * and returns an opaque private data handle. 231 + * 5. Adds the new instance to the file_set's internal list. 232 + * 233 + * On success, LUO takes a reference to the 'struct file' and considers it 234 + * under its management until it is unpreserved or finished. 235 + * 236 + * In case of any failure, all intermediate allocations (file reference, memory 237 + * for the 'luo_file' struct, etc.) are cleaned up before returning an error. 238 + * 239 + * Context: Can be called from an ioctl handler during normal system operation. 240 + * Return: 0 on success. Returns a negative errno on failure: 241 + * -EEXIST if the token is already used. 242 + * -EBADF if the file descriptor is invalid. 243 + * -ENOSPC if the file_set is full. 244 + * -ENOENT if no compatible handler is found. 245 + * -ENOMEM on memory allocation failure. 246 + * Other erros might be returned by .preserve(). 247 + */ 248 + int luo_preserve_file(struct luo_file_set *file_set, u64 token, int fd) 249 + { 250 + struct liveupdate_file_op_args args = {0}; 251 + struct liveupdate_file_handler *fh; 252 + struct luo_file *luo_file; 253 + struct file *file; 254 + int err; 255 + 256 + if (luo_token_is_used(file_set, token)) 257 + return -EEXIST; 258 + 259 + if (file_set->count == LUO_FILE_MAX) 260 + return -ENOSPC; 261 + 262 + file = fget(fd); 263 + if (!file) 264 + return -EBADF; 265 + 266 + err = luo_alloc_files_mem(file_set); 267 + if (err) 268 + goto err_fput; 269 + 270 + err = -ENOENT; 271 + luo_list_for_each_private(fh, &luo_file_handler_list, list) { 272 + if (fh->ops->can_preserve(fh, file)) { 273 + err = 0; 274 + break; 275 + } 276 + } 277 + 278 + /* err is still -ENOENT if no handler was found */ 279 + if (err) 280 + goto err_free_files_mem; 281 + 282 + luo_file = kzalloc(sizeof(*luo_file), GFP_KERNEL); 283 + if (!luo_file) { 284 + err = -ENOMEM; 285 + goto err_free_files_mem; 286 + } 287 + 288 + luo_file->file = file; 289 + luo_file->fh = fh; 290 + luo_file->token = token; 291 + luo_file->retrieved = false; 292 + mutex_init(&luo_file->mutex); 293 + 294 + args.handler = fh; 295 + args.file = file; 296 + err = fh->ops->preserve(&args); 297 + if (err) 298 + goto err_kfree; 299 + 300 + luo_file->serialized_data = args.serialized_data; 301 + list_add_tail(&luo_file->list, &file_set->files_list); 302 + file_set->count++; 303 + 304 + return 0; 305 + 306 + err_kfree: 307 + kfree(luo_file); 308 + err_free_files_mem: 309 + luo_free_files_mem(file_set); 310 + err_fput: 311 + fput(file); 312 + 313 + return err; 314 + } 315 + 316 + /** 317 + * luo_file_unpreserve_files - Unpreserves all files from a file_set. 318 + * @file_set: The files to be cleaned up. 319 + * 320 + * This function serves as the primary cleanup path for a file_set. It is 321 + * invoked when the userspace agent closes the file_set's file descriptor. 322 + * 323 + * For each file, it performs the following cleanup actions: 324 + * 1. Calls the handler's .unpreserve() callback to allow the handler to 325 + * release any resources it allocated. 326 + * 2. Removes the file from the file_set's internal tracking list. 327 + * 3. Releases the reference to the 'struct file' that was taken by 328 + * luo_preserve_file() via fput(), returning ownership. 329 + * 4. Frees the memory associated with the internal 'struct luo_file'. 330 + * 331 + * After all individual files are unpreserved, it frees the contiguous memory 332 + * block that was allocated to hold their serialization data. 333 + */ 334 + void luo_file_unpreserve_files(struct luo_file_set *file_set) 335 + { 336 + struct luo_file *luo_file; 337 + 338 + while (!list_empty(&file_set->files_list)) { 339 + struct liveupdate_file_op_args args = {0}; 340 + 341 + luo_file = list_last_entry(&file_set->files_list, 342 + struct luo_file, list); 343 + 344 + args.handler = luo_file->fh; 345 + args.file = luo_file->file; 346 + args.serialized_data = luo_file->serialized_data; 347 + luo_file->fh->ops->unpreserve(&args); 348 + 349 + list_del(&luo_file->list); 350 + file_set->count--; 351 + 352 + fput(luo_file->file); 353 + mutex_destroy(&luo_file->mutex); 354 + kfree(luo_file); 355 + } 356 + 357 + luo_free_files_mem(file_set); 358 + } 359 + 360 + static int luo_file_freeze_one(struct luo_file_set *file_set, 361 + struct luo_file *luo_file) 362 + { 363 + int err = 0; 364 + 365 + guard(mutex)(&luo_file->mutex); 366 + 367 + if (luo_file->fh->ops->freeze) { 368 + struct liveupdate_file_op_args args = {0}; 369 + 370 + args.handler = luo_file->fh; 371 + args.file = luo_file->file; 372 + args.serialized_data = luo_file->serialized_data; 373 + 374 + err = luo_file->fh->ops->freeze(&args); 375 + if (!err) 376 + luo_file->serialized_data = args.serialized_data; 377 + } 378 + 379 + return err; 380 + } 381 + 382 + static void luo_file_unfreeze_one(struct luo_file_set *file_set, 383 + struct luo_file *luo_file) 384 + { 385 + guard(mutex)(&luo_file->mutex); 386 + 387 + if (luo_file->fh->ops->unfreeze) { 388 + struct liveupdate_file_op_args args = {0}; 389 + 390 + args.handler = luo_file->fh; 391 + args.file = luo_file->file; 392 + args.serialized_data = luo_file->serialized_data; 393 + 394 + luo_file->fh->ops->unfreeze(&args); 395 + } 396 + 397 + luo_file->serialized_data = 0; 398 + } 399 + 400 + static void __luo_file_unfreeze(struct luo_file_set *file_set, 401 + struct luo_file *failed_entry) 402 + { 403 + struct list_head *files_list = &file_set->files_list; 404 + struct luo_file *luo_file; 405 + 406 + list_for_each_entry(luo_file, files_list, list) { 407 + if (luo_file == failed_entry) 408 + break; 409 + 410 + luo_file_unfreeze_one(file_set, luo_file); 411 + } 412 + 413 + memset(file_set->files, 0, LUO_FILE_PGCNT << PAGE_SHIFT); 414 + } 415 + 416 + /** 417 + * luo_file_freeze - Freezes all preserved files and serializes their metadata. 418 + * @file_set: The file_set whose files are to be frozen. 419 + * @file_set_ser: Where to put the serialized file_set. 420 + * 421 + * This function is called from the reboot() syscall path, just before the 422 + * kernel transitions to the new image via kexec. Its purpose is to perform the 423 + * final preparation and serialization of all preserved files in the file_set. 424 + * 425 + * It iterates through each preserved file in FIFO order (the order of 426 + * preservation) and performs two main actions: 427 + * 428 + * 1. Freezes the File: It calls the handler's .freeze() callback for each 429 + * file. This gives the handler a final opportunity to quiesce the device or 430 + * prepare its state for the upcoming reboot. The handler may update its 431 + * private data handle during this step. 432 + * 433 + * 2. Serializes Metadata: After a successful freeze, it copies the final file 434 + * metadata—the handler's compatible string, the user token, and the final 435 + * private data handle—into the pre-allocated contiguous memory buffer 436 + * (file_set->files) that will be handed over to the next kernel via KHO. 437 + * 438 + * Error Handling (Rollback): 439 + * This function is atomic. If any handler's .freeze() operation fails, the 440 + * entire live update is aborted. The __luo_file_unfreeze() helper is 441 + * immediately called to invoke the .unfreeze() op on all files that were 442 + * successfully frozen before the point of failure, rolling them back to a 443 + * running state. The function then returns an error, causing the reboot() 444 + * syscall to fail. 445 + * 446 + * Context: Called only from the liveupdate_reboot() path. 447 + * Return: 0 on success, or a negative errno on failure. 448 + */ 449 + int luo_file_freeze(struct luo_file_set *file_set, 450 + struct luo_file_set_ser *file_set_ser) 451 + { 452 + struct luo_file_ser *file_ser = file_set->files; 453 + struct luo_file *luo_file; 454 + int err; 455 + int i; 456 + 457 + if (!file_set->count) 458 + return 0; 459 + 460 + if (WARN_ON(!file_ser)) 461 + return -EINVAL; 462 + 463 + i = 0; 464 + list_for_each_entry(luo_file, &file_set->files_list, list) { 465 + err = luo_file_freeze_one(file_set, luo_file); 466 + if (err < 0) { 467 + pr_warn("Freeze failed for token[%#0llx] handler[%s] err[%pe]\n", 468 + luo_file->token, luo_file->fh->compatible, 469 + ERR_PTR(err)); 470 + goto err_unfreeze; 471 + } 472 + 473 + strscpy(file_ser[i].compatible, luo_file->fh->compatible, 474 + sizeof(file_ser[i].compatible)); 475 + file_ser[i].data = luo_file->serialized_data; 476 + file_ser[i].token = luo_file->token; 477 + i++; 478 + } 479 + 480 + file_set_ser->count = file_set->count; 481 + if (file_set->files) 482 + file_set_ser->files = virt_to_phys(file_set->files); 483 + 484 + return 0; 485 + 486 + err_unfreeze: 487 + __luo_file_unfreeze(file_set, luo_file); 488 + 489 + return err; 490 + } 491 + 492 + /** 493 + * luo_file_unfreeze - Unfreezes all files in a file_set and clear serialization 494 + * @file_set: The file_set whose files are to be unfrozen. 495 + * @file_set_ser: Serialized file_set. 496 + * 497 + * This function rolls back the state of all files in a file_set after the 498 + * freeze phase has begun but must be aborted. It is the counterpart to 499 + * luo_file_freeze(). 500 + * 501 + * It invokes the __luo_file_unfreeze() helper with a NULL argument, which 502 + * signals the helper to iterate through all files in the file_set and call 503 + * their respective .unfreeze() handler callbacks. 504 + * 505 + * Context: This is called when the live update is aborted during 506 + * the reboot() syscall, after luo_file_freeze() has been called. 507 + */ 508 + void luo_file_unfreeze(struct luo_file_set *file_set, 509 + struct luo_file_set_ser *file_set_ser) 510 + { 511 + if (!file_set->count) 512 + return; 513 + 514 + __luo_file_unfreeze(file_set, NULL); 515 + memset(file_set_ser, 0, sizeof(*file_set_ser)); 516 + } 517 + 518 + /** 519 + * luo_retrieve_file - Restores a preserved file from a file_set by its token. 520 + * @file_set: The file_set from which to retrieve the file. 521 + * @token: The unique token identifying the file to be restored. 522 + * @filep: Output parameter; on success, this is populated with a pointer 523 + * to the newly retrieved 'struct file'. 524 + * 525 + * This function is the primary mechanism for recreating a file in the new 526 + * kernel after a live update. It searches the file_set's list of deserialized 527 + * files for an entry matching the provided @token. 528 + * 529 + * The operation is idempotent: if a file has already been successfully 530 + * retrieved, this function will simply return a pointer to the existing 531 + * 'struct file' and report success without re-executing the retrieve 532 + * operation. This is handled by checking the 'retrieved' flag under a lock. 533 + * 534 + * File retrieval can happen in any order; it is not bound by the order of 535 + * preservation. 536 + * 537 + * Context: Can be called from an ioctl or other in-kernel code in the new 538 + * kernel. 539 + * Return: 0 on success. Returns a negative errno on failure: 540 + * -ENOENT if no file with the matching token is found. 541 + * Any error code returned by the handler's .retrieve() op. 542 + */ 543 + int luo_retrieve_file(struct luo_file_set *file_set, u64 token, 544 + struct file **filep) 545 + { 546 + struct liveupdate_file_op_args args = {0}; 547 + struct luo_file *luo_file; 548 + int err; 549 + 550 + if (list_empty(&file_set->files_list)) 551 + return -ENOENT; 552 + 553 + list_for_each_entry(luo_file, &file_set->files_list, list) { 554 + if (luo_file->token == token) 555 + break; 556 + } 557 + 558 + if (luo_file->token != token) 559 + return -ENOENT; 560 + 561 + guard(mutex)(&luo_file->mutex); 562 + if (luo_file->retrieved) { 563 + /* 564 + * Someone is asking for this file again, so get a reference 565 + * for them. 566 + */ 567 + get_file(luo_file->file); 568 + *filep = luo_file->file; 569 + return 0; 570 + } 571 + 572 + args.handler = luo_file->fh; 573 + args.serialized_data = luo_file->serialized_data; 574 + err = luo_file->fh->ops->retrieve(&args); 575 + if (!err) { 576 + luo_file->file = args.file; 577 + 578 + /* Get reference so we can keep this file in LUO until finish */ 579 + get_file(luo_file->file); 580 + *filep = luo_file->file; 581 + luo_file->retrieved = true; 582 + } 583 + 584 + return err; 585 + } 586 + 587 + static int luo_file_can_finish_one(struct luo_file_set *file_set, 588 + struct luo_file *luo_file) 589 + { 590 + bool can_finish = true; 591 + 592 + guard(mutex)(&luo_file->mutex); 593 + 594 + if (luo_file->fh->ops->can_finish) { 595 + struct liveupdate_file_op_args args = {0}; 596 + 597 + args.handler = luo_file->fh; 598 + args.file = luo_file->file; 599 + args.serialized_data = luo_file->serialized_data; 600 + args.retrieved = luo_file->retrieved; 601 + can_finish = luo_file->fh->ops->can_finish(&args); 602 + } 603 + 604 + return can_finish ? 0 : -EBUSY; 605 + } 606 + 607 + static void luo_file_finish_one(struct luo_file_set *file_set, 608 + struct luo_file *luo_file) 609 + { 610 + struct liveupdate_file_op_args args = {0}; 611 + 612 + guard(mutex)(&luo_file->mutex); 613 + 614 + args.handler = luo_file->fh; 615 + args.file = luo_file->file; 616 + args.serialized_data = luo_file->serialized_data; 617 + args.retrieved = luo_file->retrieved; 618 + 619 + luo_file->fh->ops->finish(&args); 620 + } 621 + 622 + /** 623 + * luo_file_finish - Completes the lifecycle for all files in a file_set. 624 + * @file_set: The file_set to be finalized. 625 + * 626 + * This function orchestrates the final teardown of a live update file_set in 627 + * the new kernel. It should be called after all necessary files have been 628 + * retrieved and the userspace agent is ready to release the preserved state. 629 + * 630 + * The function iterates through all tracked files. For each file, it performs 631 + * the following sequence of cleanup actions: 632 + * 633 + * 1. If file is not yet retrieved, retrieves it, and calls can_finish() on 634 + * every file in the file_set. If all can_finish return true, continue to 635 + * finish. 636 + * 2. Calls the handler's .finish() callback (via luo_file_finish_one) to 637 + * allow for final resource cleanup within the handler. 638 + * 3. Releases LUO's ownership reference on the 'struct file' via fput(). This 639 + * is the counterpart to the get_file() call in luo_retrieve_file(). 640 + * 4. Removes the 'struct luo_file' from the file_set's internal list. 641 + * 5. Frees the memory for the 'struct luo_file' instance itself. 642 + * 643 + * After successfully finishing all individual files, it frees the 644 + * contiguous memory block that was used to transfer the serialized metadata 645 + * from the previous kernel. 646 + * 647 + * Error Handling (Atomic Failure): 648 + * This operation is atomic. If any handler's .can_finish() op fails, the entire 649 + * function aborts immediately and returns an error. 650 + * 651 + * Context: Can be called from an ioctl handler in the new kernel. 652 + * Return: 0 on success, or a negative errno on failure. 653 + */ 654 + int luo_file_finish(struct luo_file_set *file_set) 655 + { 656 + struct list_head *files_list = &file_set->files_list; 657 + struct luo_file *luo_file; 658 + int err; 659 + 660 + if (!file_set->count) 661 + return 0; 662 + 663 + list_for_each_entry(luo_file, files_list, list) { 664 + err = luo_file_can_finish_one(file_set, luo_file); 665 + if (err) 666 + return err; 667 + } 668 + 669 + while (!list_empty(&file_set->files_list)) { 670 + luo_file = list_last_entry(&file_set->files_list, 671 + struct luo_file, list); 672 + 673 + luo_file_finish_one(file_set, luo_file); 674 + 675 + if (luo_file->file) 676 + fput(luo_file->file); 677 + list_del(&luo_file->list); 678 + file_set->count--; 679 + mutex_destroy(&luo_file->mutex); 680 + kfree(luo_file); 681 + } 682 + 683 + if (file_set->files) { 684 + kho_restore_free(file_set->files); 685 + file_set->files = NULL; 686 + } 687 + 688 + return 0; 689 + } 690 + 691 + /** 692 + * luo_file_deserialize - Reconstructs the list of preserved files in the new kernel. 693 + * @file_set: The incoming file_set to fill with deserialized data. 694 + * @file_set_ser: Serialized KHO file_set data from the previous kernel. 695 + * 696 + * This function is called during the early boot process of the new kernel. It 697 + * takes the raw, contiguous memory block of 'struct luo_file_ser' entries, 698 + * provided by the previous kernel, and transforms it back into a live, 699 + * in-memory linked list of 'struct luo_file' instances. 700 + * 701 + * For each serialized entry, it performs the following steps: 702 + * 1. Reads the 'compatible' string. 703 + * 2. Searches the global list of registered file handlers for one that 704 + * matches the compatible string. 705 + * 3. Allocates a new 'struct luo_file'. 706 + * 4. Populates the new structure with the deserialized data (token, private 707 + * data handle) and links it to the found handler. The 'file' pointer is 708 + * initialized to NULL, as the file has not been retrieved yet. 709 + * 5. Adds the new 'struct luo_file' to the file_set's files_list. 710 + * 711 + * This prepares the file_set for userspace, which can later call 712 + * luo_retrieve_file() to restore the actual file descriptors. 713 + * 714 + * Context: Called from session deserialization. 715 + */ 716 + int luo_file_deserialize(struct luo_file_set *file_set, 717 + struct luo_file_set_ser *file_set_ser) 718 + { 719 + struct luo_file_ser *file_ser; 720 + u64 i; 721 + 722 + if (!file_set_ser->files) { 723 + WARN_ON(file_set_ser->count); 724 + return 0; 725 + } 726 + 727 + file_set->count = file_set_ser->count; 728 + file_set->files = phys_to_virt(file_set_ser->files); 729 + 730 + /* 731 + * Note on error handling: 732 + * 733 + * If deserialization fails (e.g., allocation failure or corrupt data), 734 + * we intentionally skip cleanup of files that were already restored. 735 + * 736 + * A partial failure leaves the preserved state inconsistent. 737 + * Implementing a safe "undo" to unwind complex dependencies (sessions, 738 + * files, hardware state) is error-prone and provides little value, as 739 + * the system is effectively in a broken state. 740 + * 741 + * We treat these resources as leaked. The expected recovery path is for 742 + * userspace to detect the failure and trigger a reboot, which will 743 + * reliably reset devices and reclaim memory. 744 + */ 745 + file_ser = file_set->files; 746 + for (i = 0; i < file_set->count; i++) { 747 + struct liveupdate_file_handler *fh; 748 + bool handler_found = false; 749 + struct luo_file *luo_file; 750 + 751 + luo_list_for_each_private(fh, &luo_file_handler_list, list) { 752 + if (!strcmp(fh->compatible, file_ser[i].compatible)) { 753 + handler_found = true; 754 + break; 755 + } 756 + } 757 + 758 + if (!handler_found) { 759 + pr_warn("No registered handler for compatible '%s'\n", 760 + file_ser[i].compatible); 761 + return -ENOENT; 762 + } 763 + 764 + luo_file = kzalloc(sizeof(*luo_file), GFP_KERNEL); 765 + if (!luo_file) 766 + return -ENOMEM; 767 + 768 + luo_file->fh = fh; 769 + luo_file->file = NULL; 770 + luo_file->serialized_data = file_ser[i].data; 771 + luo_file->token = file_ser[i].token; 772 + luo_file->retrieved = false; 773 + mutex_init(&luo_file->mutex); 774 + list_add_tail(&luo_file->list, &file_set->files_list); 775 + } 776 + 777 + return 0; 778 + } 779 + 780 + void luo_file_set_init(struct luo_file_set *file_set) 781 + { 782 + INIT_LIST_HEAD(&file_set->files_list); 783 + } 784 + 785 + void luo_file_set_destroy(struct luo_file_set *file_set) 786 + { 787 + WARN_ON(file_set->count); 788 + WARN_ON(!list_empty(&file_set->files_list)); 789 + } 790 + 791 + /** 792 + * liveupdate_register_file_handler - Register a file handler with LUO. 793 + * @fh: Pointer to a caller-allocated &struct liveupdate_file_handler. 794 + * The caller must initialize this structure, including a unique 795 + * 'compatible' string and a valid 'fh' callbacks. This function adds the 796 + * handler to the global list of supported file handlers. 797 + * 798 + * Context: Typically called during module initialization for file types that 799 + * support live update preservation. 800 + * 801 + * Return: 0 on success. Negative errno on failure. 802 + */ 803 + int liveupdate_register_file_handler(struct liveupdate_file_handler *fh) 804 + { 805 + struct liveupdate_file_handler *fh_iter; 806 + int err; 807 + 808 + if (!liveupdate_enabled()) 809 + return -EOPNOTSUPP; 810 + 811 + /* Sanity check that all required callbacks are set */ 812 + if (!fh->ops->preserve || !fh->ops->unpreserve || !fh->ops->retrieve || 813 + !fh->ops->finish || !fh->ops->can_preserve) { 814 + return -EINVAL; 815 + } 816 + 817 + /* 818 + * Ensure the system is quiescent (no active sessions). 819 + * This prevents registering new handlers while sessions are active or 820 + * while deserialization is in progress. 821 + */ 822 + if (!luo_session_quiesce()) 823 + return -EBUSY; 824 + 825 + /* Check for duplicate compatible strings */ 826 + luo_list_for_each_private(fh_iter, &luo_file_handler_list, list) { 827 + if (!strcmp(fh_iter->compatible, fh->compatible)) { 828 + pr_err("File handler registration failed: Compatible string '%s' already registered.\n", 829 + fh->compatible); 830 + err = -EEXIST; 831 + goto err_resume; 832 + } 833 + } 834 + 835 + /* Pin the module implementing the handler */ 836 + if (!try_module_get(fh->ops->owner)) { 837 + err = -EAGAIN; 838 + goto err_resume; 839 + } 840 + 841 + INIT_LIST_HEAD(&ACCESS_PRIVATE(fh, list)); 842 + list_add_tail(&ACCESS_PRIVATE(fh, list), &luo_file_handler_list); 843 + luo_session_resume(); 844 + 845 + return 0; 846 + 847 + err_resume: 848 + luo_session_resume(); 849 + return err; 850 + } 851 + 852 + /** 853 + * liveupdate_unregister_file_handler - Unregister a liveupdate file handler 854 + * @fh: The file handler to unregister 855 + * 856 + * Unregisters the file handler from the liveupdate core. This function 857 + * reverses the operations of liveupdate_register_file_handler(). 858 + * 859 + * It ensures safe removal by checking that: 860 + * No live update session is currently in progress. 861 + * 862 + * If the unregistration fails, the internal test state is reverted. 863 + * 864 + * Return: 0 Success. -EOPNOTSUPP when live update is not enabled. -EBUSY A live 865 + * update is in progress, can't quiesce live update. 866 + */ 867 + int liveupdate_unregister_file_handler(struct liveupdate_file_handler *fh) 868 + { 869 + if (!liveupdate_enabled()) 870 + return -EOPNOTSUPP; 871 + 872 + if (!luo_session_quiesce()) 873 + return -EBUSY; 874 + 875 + list_del(&ACCESS_PRIVATE(fh, list)); 876 + module_put(fh->ops->owner); 877 + luo_session_resume(); 878 + 879 + return 0; 880 + }

+38

kernel/liveupdate/luo_internal.h

··· 40 40 */ 41 41 #define luo_restore_fail(__fmt, ...) panic(__fmt, ##__VA_ARGS__) 42 42 43 + /* Mimics list_for_each_entry() but for private list head entries */ 44 + #define luo_list_for_each_private(pos, head, member) \ 45 + for (struct list_head *__iter = (head)->next; \ 46 + __iter != (head) && \ 47 + ({ pos = container_of(__iter, typeof(*(pos)), member); 1; }); \ 48 + __iter = __iter->next) 49 + 50 + /** 51 + * struct luo_file_set - A set of files that belong to the same sessions. 52 + * @files_list: An ordered list of files associated with this session, it is 53 + * ordered by preservation time. 54 + * @files: The physically contiguous memory block that holds the serialized 55 + * state of files. 56 + * @count: A counter tracking the number of files currently stored in the 57 + * @files_list for this session. 58 + */ 59 + struct luo_file_set { 60 + struct list_head files_list; 61 + struct luo_file_ser *files; 62 + long count; 63 + }; 64 + 43 65 /** 44 66 * struct luo_session - Represents an active or incoming Live Update session. 45 67 * @name: A unique name for this session, used for identification and ··· 72 50 * previous kernel) sessions. 73 51 * @retrieved: A boolean flag indicating whether this session has been 74 52 * retrieved by a consumer in the new kernel. 53 + * @file_set: A set of files that belong to this session. 75 54 * @mutex: protects fields in the luo_session. 76 55 */ 77 56 struct luo_session { ··· 80 57 struct luo_session_ser *ser; 81 58 struct list_head list; 82 59 bool retrieved; 60 + struct luo_file_set file_set; 83 61 struct mutex mutex; 84 62 }; 85 63 ··· 92 68 int luo_session_deserialize(void); 93 69 bool luo_session_quiesce(void); 94 70 void luo_session_resume(void); 71 + 72 + int luo_preserve_file(struct luo_file_set *file_set, u64 token, int fd); 73 + void luo_file_unpreserve_files(struct luo_file_set *file_set); 74 + int luo_file_freeze(struct luo_file_set *file_set, 75 + struct luo_file_set_ser *file_set_ser); 76 + void luo_file_unfreeze(struct luo_file_set *file_set, 77 + struct luo_file_set_ser *file_set_ser); 78 + int luo_retrieve_file(struct luo_file_set *file_set, u64 token, 79 + struct file **filep); 80 + int luo_file_finish(struct luo_file_set *file_set); 81 + int luo_file_deserialize(struct luo_file_set *file_set, 82 + struct luo_file_set_ser *file_set_ser); 83 + void luo_file_set_init(struct luo_file_set *file_set); 84 + void luo_file_set_destroy(struct luo_file_set *file_set); 95 85 96 86 #endif /* _LINUX_LUO_INTERNAL_H */

Configure Feed

Configure Feed