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/rwsem.h>
16#include <linux/types.h>
17#include <uapi/linux/liveupdate.h>
18
19struct liveupdate_file_handler;
20struct liveupdate_flb;
21struct liveupdate_session;
22struct file;
23
24/**
25 * struct liveupdate_file_op_args - Arguments for file operation callbacks.
26 * @handler: The file handler being called.
27 * @retrieve_status: The retrieve status for the 'can_finish / finish'
28 * operation. A value of 0 means the retrieve has not been
29 * attempted, a positive value means the retrieve was
30 * successful, and a negative value means the retrieve failed,
31 * and the value is the error code of the call.
32 * @file: The file object. For retrieve: [OUT] The callback sets
33 * this to the new file. For other ops: [IN] The caller sets
34 * this to the file being operated on.
35 * @serialized_data: The opaque u64 handle, preserve/prepare/freeze may update
36 * this field.
37 * @private_data: Private data for the file used to hold runtime state that
38 * is not preserved. Set by the handler's .preserve()
39 * callback, and must be freed in the handler's
40 * .unpreserve() callback.
41 *
42 * This structure bundles all parameters for the file operation callbacks.
43 * The 'data' and 'file' fields are used for both input and output.
44 */
45struct liveupdate_file_op_args {
46 struct liveupdate_file_handler *handler;
47 int retrieve_status;
48 struct file *file;
49 u64 serialized_data;
50 void *private_data;
51};
52
53/**
54 * struct liveupdate_file_ops - Callbacks for live-updatable files.
55 * @can_preserve: Required. Lightweight check to see if this handler is
56 * compatible with the given file.
57 * @preserve: Required. Performs state-saving for the file.
58 * @unpreserve: Required. Cleans up any resources allocated by @preserve.
59 * @freeze: Optional. Final actions just before kernel transition.
60 * @unfreeze: Optional. Undo freeze operations.
61 * @retrieve: Required. Restores the file in the new kernel.
62 * @can_finish: Optional. Check if this FD can finish, i.e. all restoration
63 * pre-requirements for this FD are satisfied. Called prior to
64 * finish, in order to do successful finish calls for all
65 * resources in the session.
66 * @finish: Required. Final cleanup in the new kernel.
67 * @get_id: Optional. Returns a unique identifier for the file.
68 * @owner: Module reference
69 *
70 * All operations (except can_preserve) receive a pointer to a
71 * 'struct liveupdate_file_op_args' containing the necessary context.
72 */
73struct liveupdate_file_ops {
74 bool (*can_preserve)(struct liveupdate_file_handler *handler,
75 struct file *file);
76 int (*preserve)(struct liveupdate_file_op_args *args);
77 void (*unpreserve)(struct liveupdate_file_op_args *args);
78 int (*freeze)(struct liveupdate_file_op_args *args);
79 void (*unfreeze)(struct liveupdate_file_op_args *args);
80 int (*retrieve)(struct liveupdate_file_op_args *args);
81 bool (*can_finish)(struct liveupdate_file_op_args *args);
82 void (*finish)(struct liveupdate_file_op_args *args);
83 unsigned long (*get_id)(struct file *file);
84 struct module *owner;
85};
86
87/**
88 * struct liveupdate_file_handler - Represents a handler for a live-updatable file type.
89 * @ops: Callback functions
90 * @compatible: The compatibility string (e.g., "memfd-v1", "vfiofd-v1")
91 * that uniquely identifies the file type this handler
92 * supports. This is matched against the compatible string
93 * associated with individual &struct file instances.
94 *
95 * Modules that want to support live update for specific file types should
96 * register an instance of this structure. LUO uses this registration to
97 * determine if a given file can be preserved and to find the appropriate
98 * operations to manage its state across the update.
99 */
100struct liveupdate_file_handler {
101 const struct liveupdate_file_ops *ops;
102 const char compatible[LIVEUPDATE_HNDL_COMPAT_LENGTH];
103
104 /* private: */
105
106 /*
107 * Used for linking this handler instance into a global list of
108 * registered file handlers.
109 */
110 struct list_head __private list;
111 /* A list of FLB dependencies. */
112 struct list_head __private flb_list;
113};
114
115/**
116 * struct liveupdate_flb_op_args - Arguments for FLB operation callbacks.
117 * @flb: The global FLB instance for which this call is performed.
118 * @data: For .preserve(): [OUT] The callback sets this field.
119 * For .unpreserve(): [IN] The handle from .preserve().
120 * For .retrieve(): [IN] The handle from .preserve().
121 * @obj: For .preserve(): [OUT] Sets this to the live object.
122 * For .retrieve(): [OUT] Sets this to the live object.
123 * For .finish(): [IN] The live object from .retrieve().
124 *
125 * This structure bundles all parameters for the FLB operation callbacks.
126 */
127struct liveupdate_flb_op_args {
128 struct liveupdate_flb *flb;
129 u64 data;
130 void *obj;
131};
132
133/**
134 * struct liveupdate_flb_ops - Callbacks for global File-Lifecycle-Bound data.
135 * @preserve: Called when the first file using this FLB is preserved.
136 * The callback must save its state and return a single,
137 * self-contained u64 handle by setting the 'argp->data'
138 * field and 'argp->obj'.
139 * @unpreserve: Called when the last file using this FLB is unpreserved
140 * (aborted before reboot). Receives the handle via
141 * 'argp->data' and live object via 'argp->obj'.
142 * @retrieve: Called on-demand in the new kernel, the first time a
143 * component requests access to the shared object. It receives
144 * the preserved handle via 'argp->data' and must reconstruct
145 * the live object, returning it by setting the 'argp->obj'
146 * field.
147 * @finish: Called in the new kernel when the last file using this FLB
148 * is finished. Receives the live object via 'argp->obj' for
149 * cleanup.
150 * @owner: Module reference
151 *
152 * Operations that manage global shared data with file bound lifecycle,
153 * triggered by the first file that uses it and concluded by the last file that
154 * uses it, across all sessions.
155 */
156struct liveupdate_flb_ops {
157 int (*preserve)(struct liveupdate_flb_op_args *argp);
158 void (*unpreserve)(struct liveupdate_flb_op_args *argp);
159 int (*retrieve)(struct liveupdate_flb_op_args *argp);
160 void (*finish)(struct liveupdate_flb_op_args *argp);
161 struct module *owner;
162};
163
164/*
165 * struct luo_flb_private_state - Private FLB state structures.
166 * @count: The number of preserved files currently depending on this FLB.
167 * This is used to trigger the preserve/unpreserve/finish ops on the
168 * first/last file.
169 * @data: The opaque u64 handle returned by .preserve() or passed to
170 * .retrieve().
171 * @obj: The live kernel object returned by .preserve() or .retrieve().
172 * @lock: A mutex that protects all fields within this structure, providing
173 * the synchronization service for the FLB's ops.
174 * @finished: True once the FLB's finish() callback has run.
175 * @retrieved: True once the FLB's retrieve() callback has run.
176 */
177struct luo_flb_private_state {
178 long count;
179 u64 data;
180 void *obj;
181 struct mutex lock;
182 bool finished;
183 bool retrieved;
184};
185
186/*
187 * struct luo_flb_private - Keep separate incoming and outgoing states.
188 * @list: A global list of registered FLBs.
189 * @outgoing: The runtime state for the pre-reboot
190 * (preserve/unpreserve) lifecycle.
191 * @incoming: The runtime state for the post-reboot (retrieve/finish)
192 * lifecycle.
193 * @users: With how many File-Handlers this FLB is registered.
194 * @initialized: true when private fields have been initialized.
195 */
196struct luo_flb_private {
197 struct list_head list;
198 struct luo_flb_private_state outgoing;
199 struct luo_flb_private_state incoming;
200 int users;
201 bool initialized;
202};
203
204/**
205 * struct liveupdate_flb - A global definition for a shared data object.
206 * @ops: Callback functions
207 * @compatible: The compatibility string (e.g., "iommu-core-v1"
208 * that uniquely identifies the FLB type this handler
209 * supports. This is matched against the compatible string
210 * associated with individual &struct liveupdate_flb
211 * instances.
212 *
213 * This struct is the "template" that a driver registers to define a shared,
214 * file-lifecycle-bound object. The actual runtime state (the live object,
215 * refcount, etc.) is managed privately by the LUO core.
216 */
217struct liveupdate_flb {
218 const struct liveupdate_flb_ops *ops;
219 const char compatible[LIVEUPDATE_FLB_COMPAT_LENGTH];
220
221 /* private: */
222 struct luo_flb_private __private private;
223};
224
225#ifdef CONFIG_LIVEUPDATE
226
227/* Return true if live update orchestrator is enabled */
228bool liveupdate_enabled(void);
229
230/* Called during kexec to tell LUO that entered into reboot */
231int liveupdate_reboot(void);
232
233int liveupdate_register_file_handler(struct liveupdate_file_handler *fh);
234void liveupdate_unregister_file_handler(struct liveupdate_file_handler *fh);
235
236int liveupdate_register_flb(struct liveupdate_file_handler *fh,
237 struct liveupdate_flb *flb);
238void liveupdate_unregister_flb(struct liveupdate_file_handler *fh,
239 struct liveupdate_flb *flb);
240
241int liveupdate_flb_get_incoming(struct liveupdate_flb *flb, void **objp);
242int liveupdate_flb_get_outgoing(struct liveupdate_flb *flb, void **objp);
243
244#else /* CONFIG_LIVEUPDATE */
245
246static inline bool liveupdate_enabled(void)
247{
248 return false;
249}
250
251static inline int liveupdate_reboot(void)
252{
253 return 0;
254}
255
256static inline int liveupdate_register_file_handler(struct liveupdate_file_handler *fh)
257{
258 return -EOPNOTSUPP;
259}
260
261static inline void liveupdate_unregister_file_handler(struct liveupdate_file_handler *fh)
262{
263}
264
265static inline int liveupdate_register_flb(struct liveupdate_file_handler *fh,
266 struct liveupdate_flb *flb)
267{
268 return -EOPNOTSUPP;
269}
270
271static inline void liveupdate_unregister_flb(struct liveupdate_file_handler *fh,
272 struct liveupdate_flb *flb)
273{
274}
275
276static inline int liveupdate_flb_get_incoming(struct liveupdate_flb *flb,
277 void **objp)
278{
279 return -EOPNOTSUPP;
280}
281
282static inline int liveupdate_flb_get_outgoing(struct liveupdate_flb *flb,
283 void **objp)
284{
285 return -EOPNOTSUPP;
286}
287
288#endif /* CONFIG_LIVEUPDATE */
289#endif /* _LINUX_LIVEUPDATE_H */