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