luo.h

  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 */
104struct 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 */
119struct 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 */
144struct 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 */
161struct 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 */