liveupdate.h

  1/* SPDX-License-Identifier: GPL-2.0 */
  2
  3/*
  4 * Copyright (c) 2025, Google LLC.
  5 * Pasha Tatashin <pasha.tatashin@soleen.com>
  6 */
  7#ifndef _LINUX_LIVEUPDATE_H
  8#define _LINUX_LIVEUPDATE_H
  9
 10#include <linux/bug.h>
 11#include <linux/compiler.h>
 12#include <linux/kho/abi/luo.h>
 13#include <linux/list.h>
 14#include <linux/types.h>
 15#include <uapi/linux/liveupdate.h>
 16
 17struct liveupdate_file_handler;
 18struct file;
 19
 20/**
 21 * struct liveupdate_file_op_args - Arguments for file operation callbacks.
 22 * @handler:          The file handler being called.
 23 * @retrieve_status:  The retrieve status for the 'can_finish / finish'
 24 *                    operation. A value of 0 means the retrieve has not been
 25 *                    attempted, a positive value means the retrieve was
 26 *                    successful, and a negative value means the retrieve failed,
 27 *                    and the value is the error code of the call.
 28 * @file:             The file object. For retrieve: [OUT] The callback sets
 29 *                    this to the new file. For other ops: [IN] The caller sets
 30 *                    this to the file being operated on.
 31 * @serialized_data:  The opaque u64 handle, preserve/prepare/freeze may update
 32 *                    this field.
 33 * @private_data:     Private data for the file used to hold runtime state that
 34 *                    is not preserved. Set by the handler's .preserve()
 35 *                    callback, and must be freed in the handler's
 36 *                    .unpreserve() callback.
 37 *
 38 * This structure bundles all parameters for the file operation callbacks.
 39 * The 'data' and 'file' fields are used for both input and output.
 40 */
 41struct liveupdate_file_op_args {
 42	struct liveupdate_file_handler *handler;
 43	int retrieve_status;
 44	struct file *file;
 45	u64 serialized_data;
 46	void *private_data;
 47};
 48
 49/**
 50 * struct liveupdate_file_ops - Callbacks for live-updatable files.
 51 * @can_preserve: Required. Lightweight check to see if this handler is
 52 *                compatible with the given file.
 53 * @preserve:     Required. Performs state-saving for the file.
 54 * @unpreserve:   Required. Cleans up any resources allocated by @preserve.
 55 * @freeze:       Optional. Final actions just before kernel transition.
 56 * @unfreeze:     Optional. Undo freeze operations.
 57 * @retrieve:     Required. Restores the file in the new kernel.
 58 * @can_finish:   Optional. Check if this FD can finish, i.e. all restoration
 59 *                pre-requirements for this FD are satisfied. Called prior to
 60 *                finish, in order to do successful finish calls for all
 61 *                resources in the session.
 62 * @finish:       Required. Final cleanup in the new kernel.
 63 * @owner:        Module reference
 64 *
 65 * All operations (except can_preserve) receive a pointer to a
 66 * 'struct liveupdate_file_op_args' containing the necessary context.
 67 */
 68struct liveupdate_file_ops {
 69	bool (*can_preserve)(struct liveupdate_file_handler *handler,
 70			     struct file *file);
 71	int (*preserve)(struct liveupdate_file_op_args *args);
 72	void (*unpreserve)(struct liveupdate_file_op_args *args);
 73	int (*freeze)(struct liveupdate_file_op_args *args);
 74	void (*unfreeze)(struct liveupdate_file_op_args *args);
 75	int (*retrieve)(struct liveupdate_file_op_args *args);
 76	bool (*can_finish)(struct liveupdate_file_op_args *args);
 77	void (*finish)(struct liveupdate_file_op_args *args);
 78	struct module *owner;
 79};
 80
 81/**
 82 * struct liveupdate_file_handler - Represents a handler for a live-updatable file type.
 83 * @ops:                Callback functions
 84 * @compatible:         The compatibility string (e.g., "memfd-v1", "vfiofd-v1")
 85 *                      that uniquely identifies the file type this handler
 86 *                      supports. This is matched against the compatible string
 87 *                      associated with individual &struct file instances.
 88 *
 89 * Modules that want to support live update for specific file types should
 90 * register an instance of this structure. LUO uses this registration to
 91 * determine if a given file can be preserved and to find the appropriate
 92 * operations to manage its state across the update.
 93 */
 94struct liveupdate_file_handler {
 95	const struct liveupdate_file_ops *ops;
 96	const char compatible[LIVEUPDATE_HNDL_COMPAT_LENGTH];
 97
 98	/* private: */
 99
100	/*
101	 * Used for linking this handler instance into a global list of
102	 * registered file handlers.
103	 */
104	struct list_head __private list;
105};
106
107#ifdef CONFIG_LIVEUPDATE
108
109/* Return true if live update orchestrator is enabled */
110bool liveupdate_enabled(void);
111
112/* Called during kexec to tell LUO that entered into reboot */
113int liveupdate_reboot(void);
114
115int liveupdate_register_file_handler(struct liveupdate_file_handler *fh);
116int liveupdate_unregister_file_handler(struct liveupdate_file_handler *fh);
117
118#else /* CONFIG_LIVEUPDATE */
119
120static inline bool liveupdate_enabled(void)
121{
122	return false;
123}
124
125static inline int liveupdate_reboot(void)
126{
127	return 0;
128}
129
130static inline int liveupdate_register_file_handler(struct liveupdate_file_handler *fh)
131{
132	return -EOPNOTSUPP;
133}
134
135static inline int liveupdate_unregister_file_handler(struct liveupdate_file_handler *fh)
136{
137	return -EOPNOTSUPP;
138}
139
140#endif /* CONFIG_LIVEUPDATE */
141#endif /* _LINUX_LIVEUPDATE_H */