linux-stable-mirror/include/linux/kho/abi/luo.h

/* SPDX-License-Identifier: GPL-2.0 */

/*
 * Copyright (c) 2025, Google LLC.
 * Pasha Tatashin <pasha.tatashin@soleen.com>
 */

/**
 * DOC: Live Update Orchestrator ABI
 *
 * Live Update Orchestrator uses the stable Application Binary Interface
 * defined below to pass state from a pre-update kernel to a post-update
 * kernel. The ABI is built upon the Kexec HandOver framework and registers
 * the central `struct luo_ser` via the KHO raw subtree API.
 *
 * This interface is a contract. Any modification to the structure fields,
 * compatible strings, or the layout of the `__packed` serialization
 * structures defined here constitutes a breaking change. Such changes require
 * incrementing the version number in the relevant `_COMPATIBLE` string to
 * prevent a new kernel from misinterpreting data from an old kernel.
 *
 * Changes are allowed provided the compatibility version is incremented;
 * however, backward/forward compatibility is only guaranteed for kernels
 * supporting the same ABI version.
 *
 * KHO Structure Overview:
 *   The entire LUO state is encapsulated within a single KHO entry named "LUO".
 *   This entry contains the `struct luo_ser` structure.
 *
 * Serialization Structures:
 *   - struct luo_ser:
 *     The central ABI structure that contains the overall state of the LUO.
 *     It includes the compatibility string, the liveupdate-number, and pointers
 *     to sessions and FLBs.
 *
 *   - struct luo_session_ser:
 *     Metadata for a single session, including its name and a physical pointer
 *     to the first `struct kho_block_header_ser` for all files in that session.
 *     Multiple blocks are linked via the `next` field in the header.
 *
 *   - struct luo_file_ser:
 *     Metadata for a single preserved file. Contains the `compatible` string to
 *     find the correct handler in the new kernel, a user-provided `token` for
 *     identification, and an opaque `data` handle for the handler to use.
 *
 *   - struct luo_flb_header_ser:
 *     Header for the FLB array. Contains the total page count of the
 *     preserved memory block and the number of `struct luo_flb_ser` entries
 *     that follow.
 *
 *   - struct luo_flb_ser:
 *     Metadata for a single preserved global object. Contains its `name`
 *     (compatible string), an opaque `data` handle, and the `count`
 *     number of files depending on it.
 */

#ifndef _LINUX_KHO_ABI_LUO_H
#define _LINUX_KHO_ABI_LUO_H

#include <linux/align.h>
#include <linux/kho/abi/block.h>
#include <uapi/linux/liveupdate.h>

/*
 * The LUO state is registered under this KHO entry name.
 */
#define LUO_KHO_ENTRY_NAME	"LUO"
#define LUO_ABI_COMPATIBLE	"luo-v5"
#define LUO_ABI_COMPAT_LEN	ALIGN(sizeof(LUO_ABI_COMPATIBLE), 8)

/**
 * struct luo_ser - Centralized LUO ABI header.
 * @compatible:     Compatibility string identifying the LUO ABI version.
 * @liveupdate_num: A counter tracking the number of successful live updates.
 * @sessions_pa:    Physical address of the first session block header.
 * @flbs_pa:        Physical address of the FLB header.
 *
 * This structure is the root of all preserved LUO state.
 */
struct luo_ser {
	char compatible[LUO_ABI_COMPAT_LEN];
	u64 liveupdate_num;
	u64 sessions_pa;
	u64 flbs_pa;
} __packed;

#define LIVEUPDATE_HNDL_COMPAT_LENGTH	48

/**
 * struct luo_file_ser - Represents the serialized preserves files.
 * @compatible:  File handler compatible string.
 * @data:        Private data
 * @token:       User provided token for this file
 *
 * If this structure is modified, `LUO_ABI_COMPATIBLE` must be updated.
 */
struct luo_file_ser {
	char compatible[LIVEUPDATE_HNDL_COMPAT_LENGTH];
	u64 data;
	u64 token;
} __packed;

/**
 * struct luo_file_set_ser - Represents the serialized metadata for file set
 * @files:   The physical address of the first `struct kho_block_header_ser`.
 *           This structure is the header for a block of memory containing
 *           an array of `struct luo_file_ser` entries. Multiple blocks are
 *           linked via the `next` field in the header.
 * @count:   The total number of files that were part of this session during
 *           serialization. Used for iteration and validation during
 *           restoration.
 */
struct luo_file_set_ser {
	u64 files;
	u64 count;
} __packed;

/**
 * struct luo_session_ser - Represents the serialized metadata for a LUO session.
 * @name:         The unique name of the session, provided by the userspace at
 *                the time of session creation.
 * @file_set_ser: Serialized files belonging to this session,
 *
 * This structure is used to package session-specific metadata for transfer
 * between kernels via Kexec Handover. An array of these structures (one per
 * session) is created and passed to the new kernel, allowing it to reconstruct
 * the session context.
 *
 * If this structure is modified, `LUO_ABI_COMPATIBLE` must be updated.
 */
struct luo_session_ser {
	char name[LIVEUPDATE_SESSION_NAME_LENGTH];
	struct luo_file_set_ser file_set_ser;
} __packed;

/* The max size is set so it can be reliably used during in serialization */
#define LIVEUPDATE_FLB_COMPAT_LENGTH	48

/**
 * struct luo_flb_header_ser - Header for the serialized FLB data block.
 * @pgcnt: The total number of pages occupied by the entire preserved memory
 *         region, including this header and the subsequent array of
 *         &struct luo_flb_ser entries.
 * @count: The number of &struct luo_flb_ser entries that follow this header
 *         in the memory block.
 *
 * This structure is located at the physical address specified by the
 * flbs_pa in luo_ser.
 *
 * If this structure is modified, `LUO_ABI_COMPATIBLE` must be updated.
 */
struct luo_flb_header_ser {
	u64 pgcnt;
	u64 count;
} __packed;

/**
 * struct luo_flb_ser - Represents the serialized state of a single FLB object.
 * @name:    The unique compatibility string of the FLB object, used to find the
 *           corresponding &struct liveupdate_flb handler in the new kernel.
 * @data:    The opaque u64 handle returned by the FLB's .preserve() operation
 *           in the old kernel. This handle encapsulates the entire state needed
 *           for restoration.
 * @count:   The reference count at the time of serialization; i.e., the number
 *           of preserved files that depended on this FLB. This is used by the
 *           new kernel to correctly manage the FLB's lifecycle.
 *
 * An array of these structures is created in a preserved memory region and
 * passed to the new kernel. Each entry allows the LUO core to restore one
 * global, shared object.
 *
 * If this structure is modified, `LUO_ABI_COMPATIBLE` must be updated.
 */
struct luo_flb_ser {
	char name[LIVEUPDATE_FLB_COMPAT_LENGTH];
	u64 data;
	u64 count;
} __packed;

/* Kernel Live Update Test ABI */
#ifdef CONFIG_LIVEUPDATE_TEST
#define LIVEUPDATE_TEST_FLB_COMPATIBLE(i)	"liveupdate-test-flb-v" #i
#endif

#endif /* _LINUX_KHO_ABI_LUO_H */