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>
123  * struct luo_file - Represents a single preserved file instance.
125  *                 this type of file.
126  * @file:          Pointer to the kernel's &struct file that is being preserved.
127  *                 This is NULL in the new kernel until the file is successfully
129  * @serialized_data: The opaque u64 handle to the serialized state of the file.
133  * @private_data:  Pointer to the private data for the file used to hold runtime
138  *                 successfully called retrieve() on this file. This prevents
141  *                 (e.g., @retrieved, @file), ensuring that operations like
142  *                 retrieving or finishing a file are atomic.
145  * @token:         The user-provided unique token used to identify this file.
147  * This structure is the core in-kernel representation of a single file being
149  * to link a 'struct file' to its corresponding handler, a user-provided token,
154  * field, which holds a handle to the file's serialized state, may be updated
161 	struct file *file;  member
216  * luo_preserve_file - Initiate the preservation of a file descriptor.
217  * @file_set: The file_set to which the preserved file will be added.
218  * @token:    A unique, user-provided identifier for the file.
219  * @fd:       The file descriptor to be preserved.
221  * This function orchestrates the first phase of preserving a file. Upon entry,
222  * it takes a reference to the 'struct file' via fget(), effectively making LUO
223  * a co-owner of the file. This reference is held until the file is either
224  * unpreserved or successfully finished in the next kernel, preventing the file
227  * This function orchestrates the first phase of preserving a file. It performs
235  * 4. Calls the handler's .preserve() operation, which saves the file's state
239  * On success, LUO takes a reference to the 'struct file' and considers it
242  * In case of any failure, all intermediate allocations (file reference, memory
248  *         -EBADF if the file descriptor is invalid.
259 	struct file *file;  in luo_preserve_file()  local
268 	file = fget(fd);  in luo_preserve_file()
269 	if (!file)  in luo_preserve_file()
278 		if (fh->ops->can_preserve(fh, file)) {  in luo_preserve_file()
298 	luo_file->file = file;  in luo_preserve_file()
305 	args.file = file;  in luo_preserve_file()
324 	fput(file);  in luo_preserve_file()
334  * invoked when the userspace agent closes the file_set's file descriptor.
336  * For each file, it performs the following cleanup actions:
339  *   2. Removes the file from the file_set's internal tracking list.
340  *   3. Releases the reference to the 'struct file' that was taken by
358 		args.file = luo_file->file;  in luo_file_unpreserve_files()
367 		fput(luo_file->file);  in luo_file_unpreserve_files()
386 		args.file = luo_file->file;  in luo_file_freeze_one()
407 		args.file = luo_file->file;  in luo_file_unfreeze_one()
440  * It iterates through each preserved file in FIFO order (the order of
443  * 1. Freezes the File: It calls the handler's .freeze() callback for each
444  *    file. This gives the handler a final opportunity to quiesce the device or
448  * 2. Serializes Metadata: After a successful freeze, it copies the final file
534  * luo_retrieve_file - Restores a preserved file from a file_set by its token.
535  * @file_set: The file_set from which to retrieve the file.
536  * @token:    The unique token identifying the file to be restored.
538  *            to the newly retrieved 'struct file'.
540  * This function is the primary mechanism for recreating a file in the new
544  * The operation is idempotent: if a file has already been successfully
546  * 'struct file' and report success without re-executing the retrieve
549  * File retrieval can happen in any order; it is not bound by the order of
555  *         -ENOENT if no file with the matching token is found.
559 		      struct file **filep)  in luo_retrieve_file()
582 		 * Someone is asking for this file again, so get a reference  in luo_retrieve_file()
585 		get_file(luo_file->file);  in luo_retrieve_file()
586 		*filep = luo_file->file;  in luo_retrieve_file()
594 		luo_file->file = args.file;  in luo_retrieve_file()
596 		/* Get reference so we can keep this file in LUO until finish */  in luo_retrieve_file()
597 		get_file(luo_file->file);  in luo_retrieve_file()
598 		*filep = luo_file->file;  in luo_retrieve_file()
616 		args.file = luo_file->file;  in luo_file_can_finish_one()
633 	args.file = luo_file->file;  in luo_file_finish_one()
649  * The function iterates through all tracked files. For each file, it performs
652  * 1. If file is not yet retrieved, retrieves it, and calls can_finish() on
653  *    every file in the file_set. If all can_finish return true, continue to
657  * 3. Releases LUO's ownership reference on the 'struct file' via fput(). This
694 		if (luo_file->file)  in luo_file_finish()
695 			fput(luo_file->file);  in luo_file_finish()
722  *   2. Searches the global list of registered file handlers for one that
726  *      data handle) and links it to the found handler. The 'file' pointer is
727  *      initialized to NULL, as the file has not been retrieved yet.
731  * luo_retrieve_file() to restore the actual file descriptors.
788 		luo_file->file = NULL;  in luo_file_deserialize()
811  * liveupdate_register_file_handler - Register a file handler with LUO.
815  * handler to the global list of supported file handlers.
817  * Context: Typically called during module initialization for file types that
847 			pr_err("File handler registration failed: Compatible string '%s' already registered.\n",  in liveupdate_register_file_handler()
875  * liveupdate_unregister_file_handler - Unregister a liveupdate file handler
876  * @fh: The file handler to unregister
878  * Unregisters the file handler from the liveupdate core. This function
883  * No FLB registered with this file handler.
889  * this file handler.