Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
tjh.dev
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
8/**
9 * DOC: Live Update Orchestrator ABI
10 *
11 * Live Update Orchestrator uses the stable Application Binary Interface
12 * defined below to pass state from a pre-update kernel to a post-update
13 * kernel. The ABI is built upon the Kexec HandOver framework and uses a
14 * Flattened Device Tree to describe the preserved data.
15 *
16 * This interface is a contract. Any modification to the FDT structure, node
17 * properties, compatible strings, or the layout of the `__packed` serialization
18 * structures defined here constitutes a breaking change. Such changes require
19 * incrementing the version number in the relevant `_COMPATIBLE` string to
20 * prevent a new kernel from misinterpreting data from an old kernel.
21 *
22 * Changes are allowed provided the compatibility version is incremented;
23 * however, backward/forward compatibility is only guaranteed for kernels
24 * supporting the same ABI version.
25 *
26 * FDT Structure Overview:
27 * The entire LUO state is encapsulated within a single KHO entry named "LUO".
28 * This entry contains an FDT with the following layout:
29 *
30 * .. code-block:: none
31 *
32 * / {
33 * compatible = "luo-v1";
34 * liveupdate-number = <...>;
35 *
36 * luo-session {
37 * compatible = "luo-session-v1";
38 * luo-session-header = <phys_addr_of_session_header_ser>;
39 * };
40 *
41 * luo-flb {
42 * compatible = "luo-flb-v1";
43 * luo-flb-header = <phys_addr_of_flb_header_ser>;
44 * };
45 * };
46 *
47 * Main LUO Node (/):
48 *
49 * - compatible: "luo-v1"
50 * Identifies the overall LUO ABI version.
51 * - liveupdate-number: u64
52 * A counter tracking the number of successful live updates performed.
53 *
54 * Session Node (luo-session):
55 * This node describes all preserved user-space sessions.
56 *
57 * - compatible: "luo-session-v1"
58 * Identifies the session ABI version.
59 * - luo-session-header: u64
60 * The physical address of a `struct luo_session_header_ser`. This structure
61 * is the header for a contiguous block of memory containing an array of
62 * `struct luo_session_ser`, one for each preserved session.
63 *
64 * File-Lifecycle-Bound Node (luo-flb):
65 * This node describes all preserved global objects whose lifecycle is bound
66 * to that of the preserved files (e.g., shared IOMMU state).
67 *
68 * - compatible: "luo-flb-v1"
69 * Identifies the FLB ABI version.
70 * - luo-flb-header: u64
71 * The physical address of a `struct luo_flb_header_ser`. This structure is
72 * the header for a contiguous block of memory containing an array of
73 * `struct luo_flb_ser`, one for each preserved global object.
74 *
75 * Serialization Structures:
76 * The FDT properties point to memory regions containing arrays of simple,
77 * `__packed` structures. These structures contain the actual preserved state.
78 *
79 * - struct luo_session_header_ser:
80 * Header for the session array. Contains the total page count of the
81 * preserved memory block and the number of `struct luo_session_ser`
82 * entries that follow.
83 *
84 * - struct luo_session_ser:
85 * Metadata for a single session, including its name and a physical pointer
86 * to another preserved memory block containing an array of
87 * `struct luo_file_ser` for all files in that session.
88 *
89 * - struct luo_file_ser:
90 * Metadata for a single preserved file. Contains the `compatible` string to
91 * find the correct handler in the new kernel, a user-provided `token` for
92 * identification, and an opaque `data` handle for the handler to use.
93 *
94 * - struct luo_flb_header_ser:
95 * Header for the FLB array. Contains the total page count of the
96 * preserved memory block and the number of `struct luo_flb_ser` entries
97 * that follow.
98 *
99 * - struct luo_flb_ser:
100 * Metadata for a single preserved global object. Contains its `name`
101 * (compatible string), an opaque `data` handle, and the `count`
102 * number of files depending on it.
103 */
104
105#ifndef _LINUX_KHO_ABI_LUO_H
106#define _LINUX_KHO_ABI_LUO_H
107
108#include <uapi/linux/liveupdate.h>
109
110/*
111 * The LUO FDT hooks all LUO state for sessions, fds, etc.
112 * In the root it also carries "liveupdate-number" 64-bit property that
113 * corresponds to the number of live-updates performed on this machine.
114 */
115#define LUO_FDT_SIZE PAGE_SIZE
116#define LUO_FDT_KHO_ENTRY_NAME "LUO"
117#define LUO_FDT_COMPATIBLE "luo-v1"
118#define LUO_FDT_LIVEUPDATE_NUM "liveupdate-number"
119
120#define LIVEUPDATE_HNDL_COMPAT_LENGTH 48
121
122/**
123 * struct luo_file_ser - Represents the serialized preserves files.
124 * @compatible: File handler compatible string.
125 * @data: Private data
126 * @token: User provided token for this file
127 *
128 * If this structure is modified, LUO_SESSION_COMPATIBLE must be updated.
129 */
130struct luo_file_ser {
131 char compatible[LIVEUPDATE_HNDL_COMPAT_LENGTH];
132 u64 data;
133 u64 token;
134} __packed;
135
136/**
137 * struct luo_file_set_ser - Represents the serialized metadata for file set
138 * @files: The physical address of a contiguous memory block that holds
139 * the serialized state of files (array of luo_file_ser) in this file
140 * set.
141 * @count: The total number of files that were part of this session during
142 * serialization. Used for iteration and validation during
143 * restoration.
144 */
145struct luo_file_set_ser {
146 u64 files;
147 u64 count;
148} __packed;
149
150/*
151 * LUO FDT session node
152 * LUO_FDT_SESSION_HEADER: is a u64 physical address of struct
153 * luo_session_header_ser
154 */
155#define LUO_FDT_SESSION_NODE_NAME "luo-session"
156#define LUO_FDT_SESSION_COMPATIBLE "luo-session-v2"
157#define LUO_FDT_SESSION_HEADER "luo-session-header"
158
159/**
160 * struct luo_session_header_ser - Header for the serialized session data block.
161 * @count: The number of `struct luo_session_ser` entries that immediately
162 * follow this header in the memory block.
163 *
164 * This structure is located at the beginning of a contiguous block of
165 * physical memory preserved across the kexec. It provides the necessary
166 * metadata to interpret the array of session entries that follow.
167 *
168 * If this structure is modified, `LUO_FDT_SESSION_COMPATIBLE` must be updated.
169 */
170struct luo_session_header_ser {
171 u64 count;
172} __packed;
173
174/**
175 * struct luo_session_ser - Represents the serialized metadata for a LUO session.
176 * @name: The unique name of the session, provided by the userspace at
177 * the time of session creation.
178 * @file_set_ser: Serialized files belonging to this session,
179 *
180 * This structure is used to package session-specific metadata for transfer
181 * between kernels via Kexec Handover. An array of these structures (one per
182 * session) is created and passed to the new kernel, allowing it to reconstruct
183 * the session context.
184 *
185 * If this structure is modified, `LUO_FDT_SESSION_COMPATIBLE` must be updated.
186 */
187struct luo_session_ser {
188 char name[LIVEUPDATE_SESSION_NAME_LENGTH];
189 struct luo_file_set_ser file_set_ser;
190} __packed;
191
192/* The max size is set so it can be reliably used during in serialization */
193#define LIVEUPDATE_FLB_COMPAT_LENGTH 48
194
195#define LUO_FDT_FLB_NODE_NAME "luo-flb"
196#define LUO_FDT_FLB_COMPATIBLE "luo-flb-v1"
197#define LUO_FDT_FLB_HEADER "luo-flb-header"
198
199/**
200 * struct luo_flb_header_ser - Header for the serialized FLB data block.
201 * @pgcnt: The total number of pages occupied by the entire preserved memory
202 * region, including this header and the subsequent array of
203 * &struct luo_flb_ser entries.
204 * @count: The number of &struct luo_flb_ser entries that follow this header
205 * in the memory block.
206 *
207 * This structure is located at the physical address specified by the
208 * `LUO_FDT_FLB_HEADER` FDT property. It provides the new kernel with the
209 * necessary information to find and iterate over the array of preserved
210 * File-Lifecycle-Bound objects and to manage the underlying memory.
211 *
212 * If this structure is modified, LUO_FDT_FLB_COMPATIBLE must be updated.
213 */
214struct luo_flb_header_ser {
215 u64 pgcnt;
216 u64 count;
217} __packed;
218
219/**
220 * struct luo_flb_ser - Represents the serialized state of a single FLB object.
221 * @name: The unique compatibility string of the FLB object, used to find the
222 * corresponding &struct liveupdate_flb handler in the new kernel.
223 * @data: The opaque u64 handle returned by the FLB's .preserve() operation
224 * in the old kernel. This handle encapsulates the entire state needed
225 * for restoration.
226 * @count: The reference count at the time of serialization; i.e., the number
227 * of preserved files that depended on this FLB. This is used by the
228 * new kernel to correctly manage the FLB's lifecycle.
229 *
230 * An array of these structures is created in a preserved memory region and
231 * passed to the new kernel. Each entry allows the LUO core to restore one
232 * global, shared object.
233 *
234 * If this structure is modified, LUO_FDT_FLB_COMPATIBLE must be updated.
235 */
236struct luo_flb_ser {
237 char name[LIVEUPDATE_FLB_COMPAT_LENGTH];
238 u64 data;
239 u64 count;
240} __packed;
241
242/* Kernel Live Update Test ABI */
243#ifdef CONFIG_LIVEUPDATE_TEST
244#define LIVEUPDATE_TEST_FLB_COMPATIBLE(i) "liveupdate-test-flb-v" #i
245#endif
246
247#endif /* _LINUX_KHO_ABI_LUO_H */