xref: /linux/include/linux/kho/abi/luo.h (revision 509d3f45847627f4c5cdce004c3ec79262b5239c) 
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  * This header defines the stable Application Binary Interface used by the
12  * Live Update Orchestrator to pass state from a pre-update kernel to a
13  * post-update kernel. The ABI is built upon the Kexec HandOver framework
14  * and uses a 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  *
42  * Main LUO Node (/):
43  *
44  *   - compatible: "luo-v1"
45  *     Identifies the overall LUO ABI version.
46  *   - liveupdate-number: u64
47  *     A counter tracking the number of successful live updates performed.
48  *
49  * Session Node (luo-session):
50  *   This node describes all preserved user-space sessions.
51  *
52  *   - compatible: "luo-session-v1"
53  *     Identifies the session ABI version.
54  *   - luo-session-header: u64
55  *     The physical address of a `struct luo_session_header_ser`. This structure
56  *     is the header for a contiguous block of memory containing an array of
57  *     `struct luo_session_ser`, one for each preserved session.
58  *
59  * Serialization Structures:
60  *   The FDT properties point to memory regions containing arrays of simple,
61  *   `__packed` structures. These structures contain the actual preserved state.
62  *
63  *   - struct luo_session_header_ser:
64  *     Header for the session array. Contains the total page count of the
65  *     preserved memory block and the number of `struct luo_session_ser`
66  *     entries that follow.
67  *
68  *   - struct luo_session_ser:
69  *     Metadata for a single session, including its name and a physical pointer
70  *     to another preserved memory block containing an array of
71  *     `struct luo_file_ser` for all files in that session.
72  *
73  *   - struct luo_file_ser:
74  *     Metadata for a single preserved file. Contains the `compatible` string to
75  *     find the correct handler in the new kernel, a user-provided `token` for
76  *     identification, and an opaque `data` handle for the handler to use.
77  */
78 
79 #ifndef _LINUX_KHO_ABI_LUO_H
80 #define _LINUX_KHO_ABI_LUO_H
81 
82 #include <uapi/linux/liveupdate.h>
83 
84 /*
85  * The LUO FDT hooks all LUO state for sessions, fds, etc.
86  * In the root it also carries "liveupdate-number" 64-bit property that
87  * corresponds to the number of live-updates performed on this machine.
88  */
89 #define LUO_FDT_SIZE		PAGE_SIZE
90 #define LUO_FDT_KHO_ENTRY_NAME	"LUO"
91 #define LUO_FDT_COMPATIBLE	"luo-v1"
92 #define LUO_FDT_LIVEUPDATE_NUM	"liveupdate-number"
93 
94 #define LIVEUPDATE_HNDL_COMPAT_LENGTH	48
95 
96 /**
97  * struct luo_file_ser - Represents the serialized preserves files.
98  * @compatible:  File handler compatible string.
99  * @data:        Private data
100  * @token:       User provided token for this file
101  *
102  * If this structure is modified, LUO_SESSION_COMPATIBLE must be updated.
103  */
104 struct luo_file_ser {
105 	char compatible[LIVEUPDATE_HNDL_COMPAT_LENGTH];
106 	u64 data;
107 	u64 token;
108 } __packed;
109 
110 /**
111  * struct luo_file_set_ser - Represents the serialized metadata for file set
112  * @files:   The physical address of a contiguous memory block that holds
113  *           the serialized state of files (array of luo_file_ser) in this file
114  *           set.
115  * @count:   The total number of files that were part of this session during
116  *           serialization. Used for iteration and validation during
117  *           restoration.
118  */
119 struct luo_file_set_ser {
120 	u64 files;
121 	u64 count;
122 } __packed;
123 
124 /*
125  * LUO FDT session node
126  * LUO_FDT_SESSION_HEADER:  is a u64 physical address of struct
127  *                          luo_session_header_ser
128  */
129 #define LUO_FDT_SESSION_NODE_NAME	"luo-session"
130 #define LUO_FDT_SESSION_COMPATIBLE	"luo-session-v2"
131 #define LUO_FDT_SESSION_HEADER		"luo-session-header"
132 
133 /**
134  * struct luo_session_header_ser - Header for the serialized session data block.
135  * @count: The number of `struct luo_session_ser` entries that immediately
136  *         follow this header in the memory block.
137  *
138  * This structure is located at the beginning of a contiguous block of
139  * physical memory preserved across the kexec. It provides the necessary
140  * metadata to interpret the array of session entries that follow.
141  *
142  * If this structure is modified, `LUO_FDT_SESSION_COMPATIBLE` must be updated.
143  */
144 struct luo_session_header_ser {
145 	u64 count;
146 } __packed;
147 
148 /**
149  * struct luo_session_ser - Represents the serialized metadata for a LUO session.
150  * @name:         The unique name of the session, provided by the userspace at
151  *                the time of session creation.
152  * @file_set_ser: Serialized files belonging to this session,
153  *
154  * This structure is used to package session-specific metadata for transfer
155  * between kernels via Kexec Handover. An array of these structures (one per
156  * session) is created and passed to the new kernel, allowing it to reconstruct
157  * the session context.
158  *
159  * If this structure is modified, `LUO_FDT_SESSION_COMPATIBLE` must be updated.
160  */
161 struct luo_session_ser {
162 	char name[LIVEUPDATE_SESSION_NAME_LENGTH];
163 	struct luo_file_set_ser file_set_ser;
164 } __packed;
165 
166 #endif /* _LINUX_KHO_ABI_LUO_H */
167