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