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