Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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/mutex.h>
15#include <linux/types.h>
16#include <uapi/linux/liveupdate.h>
17
18struct liveupdate_file_handler;
19struct liveupdate_flb;
20struct liveupdate_session;
21struct file;
22
23/**
24 * struct liveupdate_file_op_args - Arguments for file operation callbacks.
25 * @handler: The file handler being called.
26 * @retrieved: The retrieve status for the 'can_finish / finish'
27 * operation.
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 bool retrieved;
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 /* A list of FLB dependencies. */
106 struct list_head __private flb_list;
107};
108
109/**
110 * struct liveupdate_flb_op_args - Arguments for FLB operation callbacks.
111 * @flb: The global FLB instance for which this call is performed.
112 * @data: For .preserve(): [OUT] The callback sets this field.
113 * For .unpreserve(): [IN] The handle from .preserve().
114 * For .retrieve(): [IN] The handle from .preserve().
115 * @obj: For .preserve(): [OUT] Sets this to the live object.
116 * For .retrieve(): [OUT] Sets this to the live object.
117 * For .finish(): [IN] The live object from .retrieve().
118 *
119 * This structure bundles all parameters for the FLB operation callbacks.
120 */
121struct liveupdate_flb_op_args {
122 struct liveupdate_flb *flb;
123 u64 data;
124 void *obj;
125};
126
127/**
128 * struct liveupdate_flb_ops - Callbacks for global File-Lifecycle-Bound data.
129 * @preserve: Called when the first file using this FLB is preserved.
130 * The callback must save its state and return a single,
131 * self-contained u64 handle by setting the 'argp->data'
132 * field and 'argp->obj'.
133 * @unpreserve: Called when the last file using this FLB is unpreserved
134 * (aborted before reboot). Receives the handle via
135 * 'argp->data' and live object via 'argp->obj'.
136 * @retrieve: Called on-demand in the new kernel, the first time a
137 * component requests access to the shared object. It receives
138 * the preserved handle via 'argp->data' and must reconstruct
139 * the live object, returning it by setting the 'argp->obj'
140 * field.
141 * @finish: Called in the new kernel when the last file using this FLB
142 * is finished. Receives the live object via 'argp->obj' for
143 * cleanup.
144 * @owner: Module reference
145 *
146 * Operations that manage global shared data with file bound lifecycle,
147 * triggered by the first file that uses it and concluded by the last file that
148 * uses it, across all sessions.
149 */
150struct liveupdate_flb_ops {
151 int (*preserve)(struct liveupdate_flb_op_args *argp);
152 void (*unpreserve)(struct liveupdate_flb_op_args *argp);
153 int (*retrieve)(struct liveupdate_flb_op_args *argp);
154 void (*finish)(struct liveupdate_flb_op_args *argp);
155 struct module *owner;
156};
157
158/*
159 * struct luo_flb_private_state - Private FLB state structures.
160 * @count: The number of preserved files currently depending on this FLB.
161 * This is used to trigger the preserve/unpreserve/finish ops on the
162 * first/last file.
163 * @data: The opaque u64 handle returned by .preserve() or passed to
164 * .retrieve().
165 * @obj: The live kernel object returned by .preserve() or .retrieve().
166 * @lock: A mutex that protects all fields within this structure, providing
167 * the synchronization service for the FLB's ops.
168 * @finished: True once the FLB's finish() callback has run.
169 * @retrieved: True once the FLB's retrieve() callback has run.
170 */
171struct luo_flb_private_state {
172 long count;
173 u64 data;
174 void *obj;
175 struct mutex lock;
176 bool finished;
177 bool retrieved;
178};
179
180/*
181 * struct luo_flb_private - Keep separate incoming and outgoing states.
182 * @list: A global list of registered FLBs.
183 * @outgoing: The runtime state for the pre-reboot
184 * (preserve/unpreserve) lifecycle.
185 * @incoming: The runtime state for the post-reboot (retrieve/finish)
186 * lifecycle.
187 * @users: With how many File-Handlers this FLB is registered.
188 * @initialized: true when private fields have been initialized.
189 */
190struct luo_flb_private {
191 struct list_head list;
192 struct luo_flb_private_state outgoing;
193 struct luo_flb_private_state incoming;
194 int users;
195 bool initialized;
196};
197
198/**
199 * struct liveupdate_flb - A global definition for a shared data object.
200 * @ops: Callback functions
201 * @compatible: The compatibility string (e.g., "iommu-core-v1"
202 * that uniquely identifies the FLB type this handler
203 * supports. This is matched against the compatible string
204 * associated with individual &struct liveupdate_flb
205 * instances.
206 *
207 * This struct is the "template" that a driver registers to define a shared,
208 * file-lifecycle-bound object. The actual runtime state (the live object,
209 * refcount, etc.) is managed privately by the LUO core.
210 */
211struct liveupdate_flb {
212 const struct liveupdate_flb_ops *ops;
213 const char compatible[LIVEUPDATE_FLB_COMPAT_LENGTH];
214
215 /* private: */
216 struct luo_flb_private __private private;
217};
218
219#ifdef CONFIG_LIVEUPDATE
220
221/* Return true if live update orchestrator is enabled */
222bool liveupdate_enabled(void);
223
224/* Called during kexec to tell LUO that entered into reboot */
225int liveupdate_reboot(void);
226
227int liveupdate_register_file_handler(struct liveupdate_file_handler *fh);
228int liveupdate_unregister_file_handler(struct liveupdate_file_handler *fh);
229
230int liveupdate_register_flb(struct liveupdate_file_handler *fh,
231 struct liveupdate_flb *flb);
232int liveupdate_unregister_flb(struct liveupdate_file_handler *fh,
233 struct liveupdate_flb *flb);
234
235int liveupdate_flb_get_incoming(struct liveupdate_flb *flb, void **objp);
236int liveupdate_flb_get_outgoing(struct liveupdate_flb *flb, void **objp);
237
238#else /* CONFIG_LIVEUPDATE */
239
240static inline bool liveupdate_enabled(void)
241{
242 return false;
243}
244
245static inline int liveupdate_reboot(void)
246{
247 return 0;
248}
249
250static inline int liveupdate_register_file_handler(struct liveupdate_file_handler *fh)
251{
252 return -EOPNOTSUPP;
253}
254
255static inline int liveupdate_unregister_file_handler(struct liveupdate_file_handler *fh)
256{
257 return -EOPNOTSUPP;
258}
259
260static inline int liveupdate_register_flb(struct liveupdate_file_handler *fh,
261 struct liveupdate_flb *flb)
262{
263 return -EOPNOTSUPP;
264}
265
266static inline int liveupdate_unregister_flb(struct liveupdate_file_handler *fh,
267 struct liveupdate_flb *flb)
268{
269 return -EOPNOTSUPP;
270}
271
272static inline int liveupdate_flb_get_incoming(struct liveupdate_flb *flb,
273 void **objp)
274{
275 return -EOPNOTSUPP;
276}
277
278static inline int liveupdate_flb_get_outgoing(struct liveupdate_flb *flb,
279 void **objp)
280{
281 return -EOPNOTSUPP;
282}
283
284#endif /* CONFIG_LIVEUPDATE */
285#endif /* _LINUX_LIVEUPDATE_H */