9  * DOC: LUO File Descriptors
11  * LUO provides the infrastructure to preserve specific, stateful file
17  * defined lifecycle for each preserved file.
20  * Kernel modules responsible for a specific file type (e.g., memfd, vfio)
26  *     compatible with a given 'struct file'.
27  *   - preserve(): The heavyweight operation that saves the file's state and
36  *     the file anymore.
39  *   - retrieve(): Reconstructs the file in the new kernel from the preserved
42  *     succesul finish call, LUO gives up ownership to this file.
44  * File Preservation Lifecycle happy path:
47  *    via an ioctl. For each file, luo_preserve_file() finds a compatible
63  *    restore file descriptors by providing a token. luo_retrieve_file()
65  *    re-create the 'struct file', and returns a new FD. Files can be
73  * File Preservation Lifecycle unhappy paths:
76  *    process before calling reboot (e.g., by closing the session file
102 #include <linux/file.h>
122  * struct luo_file - Represents a single preserved file instance.
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
128  * @serialized_data: The opaque u64 handle to the serialized state of the file.
132  * @private_data:  Pointer to the private data for the file used to hold runtime
137  *                 successfully called retrieve() on this file. This prevents
140  *                 (e.g., @retrieved, @file), ensuring that operations like
141  *                 retrieving or finishing a file are atomic.
144  * @token:         The user-provided unique token used to identify this file.
146  * This structure is the core in-kernel representation of a single file being
148  * to link a 'struct file' to its corresponding handler, a user-provided token,
153  * field, which holds a handle to the file's serialized state, may be updated
160 	struct file *file;  member
215  * luo_preserve_file - Initiate the preservation of a file descriptor.
216  * @file_set: The file_set to which the preserved file will be added.
217  * @token:    A unique, user-provided identifier for the file.
218  * @fd:       The file descriptor to be preserved.
220  * This function orchestrates the first phase of preserving a file. Upon entry,
221  * it takes a reference to the 'struct file' via fget(), effectively making LUO
222  * a co-owner of the file. This reference is held until the file is either
223  * unpreserved or successfully finished in the next kernel, preventing the file
226  * This function orchestrates the first phase of preserving a file. It performs
234  * 4. Calls the handler's .preserve() operation, which saves the file's state
238  * On success, LUO takes a reference to the 'struct file' and considers it
241  * In case of any failure, all intermediate allocations (file reference, memory
247  *         -EBADF if the file descriptor is invalid.
258 	struct file *file;  in luo_preserve_file()  local
267 	file = fget(fd);  in luo_preserve_file()
268 	if (!file)  in luo_preserve_file()
277 		if (fh->ops->can_preserve(fh, file)) {  in luo_preserve_file()
293 	luo_file->file = file;  in luo_preserve_file()
300 	args.file = file;  in luo_preserve_file()
317 	fput(file);  in luo_preserve_file()
327  * invoked when the userspace agent closes the file_set's file descriptor.
329  * For each file, it performs the following cleanup actions:
332  *   2. Removes the file from the file_set's internal tracking list.
333  *   3. Releases the reference to the 'struct file' that was taken by
351 		args.file = luo_file->file;  in luo_file_unpreserve_files()
359 		fput(luo_file->file);  in luo_file_unpreserve_files()
378 		args.file = luo_file->file;  in luo_file_freeze_one()
399 		args.file = luo_file->file;  in luo_file_unfreeze_one()
434  * It iterates through each preserved file in FIFO order (the order of
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
442  * 2. Serializes Metadata: After a successful freeze, it copies the final file
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.
532  *            to the newly retrieved 'struct file'.
534  * This function is the primary mechanism for recreating a file in the new
538  * The operation is idempotent: if a file has already been successfully
540  * 'struct file' and report success without re-executing the retrieve
543  * File retrieval can happen in any order; it is not bound by the order of
549  *         -ENOENT if no file with the matching token is found.
553 		      struct file **filep)  in luo_retrieve_file()
576 		 * Someone is asking for this file again, so get a reference  in luo_retrieve_file()
579 		get_file(luo_file->file);  in luo_retrieve_file()
580 		*filep = luo_file->file;  in luo_retrieve_file()
588 		luo_file->file = args.file;  in luo_retrieve_file()
590 		/* Get reference so we can keep this file in LUO until finish */  in luo_retrieve_file()
591 		get_file(luo_file->file);  in luo_retrieve_file()
592 		*filep = luo_file->file;  in luo_retrieve_file()
610 		args.file = luo_file->file;  in luo_file_can_finish_one()
627 	args.file = luo_file->file;  in luo_file_finish_one()
642  * The function iterates through all tracked files. For each file, it performs
645  * 1. If file is not yet retrieved, retrieves it, and calls can_finish() on
646  *    every file in the file_set. If all can_finish return true, continue to
650  * 3. Releases LUO's ownership reference on the 'struct file' via fput(). This
687 		if (luo_file->file)  in luo_file_finish()
688 			fput(luo_file->file);  in luo_file_finish()
715  *   2. Searches the global list of registered file handlers for one that
719  *      data handle) and links it to the found handler. The 'file' pointer is
720  *      initialized to NULL, as the file has not been retrieved yet.
724  * luo_retrieve_file() to restore the actual file descriptors.
781 		luo_file->file = NULL;  in luo_file_deserialize()
804  * liveupdate_register_file_handler - Register a file handler with LUO.
808  * handler to the global list of supported file handlers.
810  * Context: Typically called during module initialization for file types that
840 			pr_err("File handler registration failed: Compatible string '%s' already registered.\n",  in liveupdate_register_file_handler()
865  * liveupdate_unregister_file_handler - Unregister a liveupdate file handler
866  * @fh: The file handler to unregister
868  * Unregisters the file handler from the liveupdate core. This function