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
19 struct liveupdate_file_handler;
20 struct liveupdate_flb;
21 struct liveupdate_session;
22 struct 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 */
45 struct 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 */
73 struct 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 */
100 struct 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 */
127 struct 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 */
156 struct 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 */
177 struct 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 */
196 struct 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 */
217 struct 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 */
228 bool liveupdate_enabled(void);
229
230 /* Called during kexec to tell LUO that entered into reboot */
231 int liveupdate_reboot(void);
232
233 int liveupdate_register_file_handler(struct liveupdate_file_handler *fh);
234 void liveupdate_unregister_file_handler(struct liveupdate_file_handler *fh);
235
236 int liveupdate_register_flb(struct liveupdate_file_handler *fh,
237 struct liveupdate_flb *flb);
238 void liveupdate_unregister_flb(struct liveupdate_file_handler *fh,
239 struct liveupdate_flb *flb);
240
241 int liveupdate_flb_get_incoming(struct liveupdate_flb *flb, void **objp);
242 int liveupdate_flb_get_outgoing(struct liveupdate_flb *flb, void **objp);
243
244 #else /* CONFIG_LIVEUPDATE */
245
liveupdate_enabled(void)246 static inline bool liveupdate_enabled(void)
247 {
248 return false;
249 }
250
liveupdate_reboot(void)251 static inline int liveupdate_reboot(void)
252 {
253 return 0;
254 }
255
liveupdate_register_file_handler(struct liveupdate_file_handler * fh)256 static inline int liveupdate_register_file_handler(struct liveupdate_file_handler *fh)
257 {
258 return -EOPNOTSUPP;
259 }
260
liveupdate_unregister_file_handler(struct liveupdate_file_handler * fh)261 static inline void liveupdate_unregister_file_handler(struct liveupdate_file_handler *fh)
262 {
263 }
264
liveupdate_register_flb(struct liveupdate_file_handler * fh,struct liveupdate_flb * flb)265 static inline int liveupdate_register_flb(struct liveupdate_file_handler *fh,
266 struct liveupdate_flb *flb)
267 {
268 return -EOPNOTSUPP;
269 }
270
liveupdate_unregister_flb(struct liveupdate_file_handler * fh,struct liveupdate_flb * flb)271 static inline void liveupdate_unregister_flb(struct liveupdate_file_handler *fh,
272 struct liveupdate_flb *flb)
273 {
274 }
275
liveupdate_flb_get_incoming(struct liveupdate_flb * flb,void ** objp)276 static inline int liveupdate_flb_get_incoming(struct liveupdate_flb *flb,
277 void **objp)
278 {
279 return -EOPNOTSUPP;
280 }
281
liveupdate_flb_get_outgoing(struct liveupdate_flb * flb,void ** objp)282 static 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 */
290