liveupdate: Add feature header for fine-grained ABI compatibility
Subsystems (4)
v3 cover liveupdate: Add feature header for fine-grained ABI compatibility
Changes since RFC v2 [1]:
- Dropped the file handler compatible rename and per-FD handler selection patches.
- Replaced the fixed 128-byte header with an expandable struct luo_ser_hdr (size, nr_features, flags[]), kept separate from the payload structure. The header is 8 bytes with no features and 16 bytes for 1 to 32 features.
- Each subsystem declares its wrapper once with DECLARE_LUO_SER_WRAP(), passing its feature enum MAX; the macro sizes the flags entries and generates name##_wrap_init(), so callers never pass sizes or counts. The target kernel reaches the payload with luo_ser_payload().
- Feature bits describe only what each preserved object uses. The target kernel checks them against its own boolean supported table, and the header is trusted as the source of truth: validation only rejects a required feature the target kernel does not support. 0b10 is reserved.
- Moved the __packed removal into its own patch (1/4) and added a KUnit test (4/4).
Changes since RFC v1 [2]:
- Replaced the 3-mask (supp, req, active) design with a header of 2-bit feature states.
[1] https://lore.kernel.org/all/[email protected]/
[2] https://lore.kernel.org/all/[email protected]/
==========COVER LETTER==============
LUO and its file handlers rely only on coarse-grained compatibility strings (such as luo-v5 and memfd-v2) to validate handed-over state across kexec. Any change to a serialized structure, even an optional additive field, requires bumping the string and breaks live update between adjacent kernels.
This series adds a feature header (struct luo_ser_hdr) ahead of serialized LUO structures so subsystems can evolve their serialized state per feature. Each subsystem groups its serialized fields under feature indices, with index 0 for the base fields. New capabilities append fields at the end of the payload under a new feature index, and retired fields stay in place so offsets never shift. Only a change that feature flags cannot express needs a new handler with a bumped compatibility string.
Each feature has a 2-bit state set by the source kernel:
- LUO_FEAT_ABSENT (0b00): not in the payload; a target kernel that supports it can use default values.
- LUO_FEAT_OPTIONAL (0b01): in the payload; a target kernel that does not support it ignores the data.
- LUO_FEAT_REQUIRED (0b11): in the payload; a target kernel that does not support it rejects the state with -EOPNOTSUPP.
- LUO_FEAT_RESERVED (0b10): reserved, not checked by the target kernel.
The target kernel checks the header against its own boolean supported table:
Source hdr Target supported[i] Action ---------- ------------------- ---------------------------------- 00 0 or 1 Accept: feature absent in payload 01 0 Accept: ignore the feature data 01 1 Accept: use the feature data 11 0 Reject: -EOPNOTSUPP 11 1 Accept: use the feature data 10 0 or 1 Reserved: not checked by target
struct luo_ser_hdr holds the total size of the serialized structure (u32), the number of features (u32 nr_features), and 64-bit flags entries with 32 features each. With no features the header is 8 bytes; with 1 to 32 features it is 16 bytes.
On the source side, a subsystem declares its wrapper once with DECLARE_LUO_SER_WRAP(name, expected_size, nr_features), passing its feature enum MAX, then calls name##_wrap_init(), marks the features the preserved object uses with luo_ser_set_feat(), and fills wrap->ser. On the target side, incoming state is never cast to the wrapper, since the source kernel may use a different number of flags entries. The target kernel calls luo_ser_hdr_validate(), finds the payload with luo_ser_payload(), and reads the fields of a feature only after luo_ser_get_feat() shows it present.
Patch 1 removes __packed from the LUO and memfd ABI structures. Patch 2 adds the header and converts struct luo_ser. Patch 3 converts memfd and bumps its compatibility string to memfd-v3. Patch 4 adds KUnit tests.
Tarun Sahu (4):
liveupdate: Remove __packed from LUO and memfd ABI structures
liveupdate: Add feature header for fine-grained ABI compatibility
mm: memfd_luo: Add the feature header
liveupdate: Add KUnit test for the feature header helpers
MAINTAINERS | 1 + include/linux/kho/abi/luo.h | 359 ++++++++++++++++++++++++--- include/linux/kho/abi/memfd.h | 43 +++- kernel/liveupdate/luo_core.c | 62 +++-- lib/Kconfig.debug | 16 ++ lib/tests/Makefile | 1 + lib/tests/liveupdate_feature_kunit.c | 118 +++++++++ mm/memfd_luo.c | 68 +++-- 8 files changed, 577 insertions(+), 91 deletions(-) create mode 100644 lib/tests/liveupdate_feature_kunit.c
Signature · 1 line
2.56.0.307.g5fe7bd680c-goog
RFC PATCH v3 1/4 liveupdate: Remove __packed from LUO and memfd ABI structures
All structures in include/linux/kho/abi/luo.h (struct luo_ser, struct luo_file_ser, struct luo_file_set_ser, struct luo_session_ser, struct luo_flb_header_ser, struct luo_flb_ser) and include/linux/kho/abi/memfd.h (struct memfd_luo_folio_ser, struct memfd_luo_ser) have naturally aligned fields on 64-bit architectures, with no padding holes between fields or tail padding. Any future unaligned field addition should come with reserved field to keep the structure aligned.
--- include/linux/kho/abi/luo.h | 25 +++++++++++++++++++------ include/linux/kho/abi/memfd.h | 11 ++++++++--- 2 files changed, 27 insertions(+), 9 deletions(-)
include/linux/kho/abi/luo.h +19 -6
@@ -58,6 +58,7 @@#define _LINUX_KHO_ABI_LUO_H#include <linux/align.h> +#include <linux/build_bug.h> #include <linux/kho/abi/block.h> #include <uapi/linux/liveupdate.h>
@@ -82,7 +83,9 @@ struct luo_ser {u64 liveupdate_num;u64 sessions_pa;u64 flbs_pa; -} __packed; +}; + +static_assert (sizeof (struct luo_ser ) ==32 );#define LIVEUPDATE_HNDL_COMPAT_LENGTH 48
@@ -98,7 +101,9 @@ struct luo_file_ser {char compatible[LIVEUPDATE_HNDL_COMPAT_LENGTH ];u64 data;u64 token; -} __packed; +}; + +static_assert (sizeof (struct luo_file_ser ) ==64 );/** * struct luo_file_set_ser - Represents the serialized metadata for file set
@@ -113,7 +118,9 @@ struct luo_file_ser {struct luo_file_set_ser {u64 files;u64 count; -} __packed; +}; + +static_assert (sizeof (struct luo_file_set_ser ) ==16 );/** * struct luo_session_ser - Represents the serialized metadata for a LUO session.
@@ -131,7 +138,9 @@ struct luo_file_set_ser {struct luo_session_ser {char name[LIVEUPDATE_SESSION_NAME_LENGTH ];struct luo_file_set_ser file_set_ser; -} __packed; +}; + +static_assert (sizeof (struct luo_session_ser ) ==80 );/* The max size is set so it can be reliably used during in serialization */ #define LIVEUPDATE_FLB_COMPAT_LENGTH 48
@@ -152,7 +161,9 @@ struct luo_session_ser {struct luo_flb_header_ser {u64 pgcnt;u64 count; -} __packed; +}; + +static_assert (sizeof (struct luo_flb_header_ser ) ==16 );/** * struct luo_flb_ser - Represents the serialized state of a single FLB object.
@@ -175,7 +186,9 @@ struct luo_flb_ser {char name[LIVEUPDATE_FLB_COMPAT_LENGTH ];u64 data;u64 count; -} __packed; +}; + +static_assert (sizeof (struct luo_flb_ser ) ==64 );/* Kernel Live Update Test ABI */ #ifdef CONFIG_LIVEUPDATE_TEST
include/linux/kho/abi/memfd.h +8 -3
@@ -11,6 +11,7 @@#ifndef _LINUX_KHO_ABI_MEMFD_H#define _LINUX_KHO_ABI_MEMFD_H +#include <linux/build_bug.h> #include <linux/types.h> #include <linux/kho/abi/kexec_handover.h>
@@ -20,7 +21,7 @@* memfd uses the ABI defined below for preserving its state across a kexec * reboot using the LUO. * -* The state is serialized into a packed structure `struct memfd_luo_ser` +* The state is serialized into `struct memfd_luo_ser` * which is handed over to the next kernel via the KHO mechanism. * * This interface is a contract. Any modification to the structure layout
@@ -54,7 +55,9 @@ struct memfd_luo_folio_ser { u64 pfn:52; u64 flags:12;u64 index; -} __packed; +}; + +static_assert (sizeof (struct memfd_luo_folio_ser ) ==16 );/* * The set of seals this version supports preserving. If support for any new
@@ -85,7 +88,9 @@ struct memfd_luo_ser {u32 flags;u64 nr_folios;struct kho_vmalloc folios; -} __packed; +}; + +static_assert (sizeof (struct memfd_luo_ser ) ==48 );/* The compatibility string for memfd file handler */ #define MEMFD_LUO_FH_COMPATIBLE "memfd-v2"
Signature · 1 line
2.56.0.307.g5fe7bd680c-goog
[email protected]
AI reviewRe: [RFC PATCH v3 1/4] liveupdate: Remove __packed from LUO and memfd ABI structures
Sashiko has reviewed this patch and found no issues.
Quoted 9 lines
All structures in
include/linux/kho/abi/luo.h(structluo_ser, structluo_file_ser, structluo_file_set_ser, structluo_session_ser, structluo_flb_header_ser, structluo_flb_ser) andinclude/linux/kho/abi/memfd.h(structmemfd_luo_folio_ser, structmemfd_luo_ser) have naturally aligned fields on 64-bit architectures, with no padding holes between fields or tail padding. Any future unaligned field addition should come with reserved field to keep the structure aligned.Signed-off-by Tarun Sahu <[email protected]>
Sashiko has reviewed this patch and found no issues.
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=1
RFC PATCH v3 2/4 liveupdate: Add feature header for fine-grained ABI compatibility
In reply to Tarun SahuLUO and its file handlers currently rely solely on coarse-grained compatibility strings (such as luo-v5 and memfd-v2) to validate handed-over state across kexec. Because compatibility is checked only at the whole-structure level, any change to a serialized structure, even an optional additive field, requires bumping the compatibility string and breaks live update between adjacent kernels.
Introduce a feature header (struct luo_ser_hdr) ahead of serialized LUO structures so subsystems can evolve their serialized state at per-feature granularity. Each subsystem groups the fields of its serialized structure under feature indices, starting with index 0 for the base fields. When a subsystem adds a new capability, it appends any new fields to the end of its payload structure under a new feature index. Retired fields are kept in place so existing field offsets never shift; if the type or format of a field needs to change, the existing field and feature are kept intact until retired and a new feature index with an appended field of the new type is added. Only when a change requires a complete break in the serialized layout or semantics that feature flags cannot handle, a new handler can be introduced with an incremented version number in its compatibility string.
Each feature in the header has a 2-bit state (enum luo_feat_state):
- LUO_FEAT_ABSENT (0b00): Feature is absent in the serialized payload. Target kernel can initialize the feature with the default values if it supports it.
- LUO_FEAT_OPTIONAL (0b01): Feature is present in the payload and optional; a target kernel that does not support it ignores the feature data.
- LUO_FEAT_REQUIRED (0b11): Feature is present in the payload and required; a target kernel that does not support it rejects the state with -EOPNOTSUPP.
- LUO_FEAT_RESERVED (0b10): Reserved encoding, not checked by target.
During deserialization, the target kernel validates the incoming header against its per feature supported information stored as a simple boolean array. The truth table for the deserialization:
Source hdr Target supported[i] Action ---------- ------------------- ---------------------------------- 00 0 or 1 Accept: feature absent in payload 01 0 Accept: ignore the feature data 01 1 Accept: use the feature data 11 0 Reject: -EOPNOTSUPP 11 1 Accept: use the feature data 10 0 or 1 Reserved: not checked by target
Source hdr is the 2-bit state of feature i written by the source kernel. Target supported[i] is the boolean entry for feature i in the target kernel supported features table passed to luo_ser_hdr_validate() (1 = supported, 0 = not supported; an index at or beyond the table size, or a NULL table, is read as 0).
The preserved data from the source kernel includes hdr and payload (ABI for serialized data).
Each subsystem declares a wrapper structure using
DECLARE_LUO_SER_WRAP(name, expected_size, nr_features)
This Wrapper wraps the hdr and serialized ABI payload in one structure. Which will be preserved and passed to target kernel. Target kernel will deserialized the hdr and based on each feature it will deserialize the payload.
For deserialization in the target kernel, incoming state is never cast to struct name##_wrap because a source kernel with a different feature count may have a different number of flags entries. Instead, the target kernel validates the header with luo_ser_hdr_validate(), locates the payload with ser = luo_ser_payload(hdr), and checks whether a feature is present before reading its fields:
if (luo_ser_get_feat(hdr, FEAT_X) != LUO_FEAT_ABSENT)
val = ser->x_field;Also, introduce the LUO_CORE_FEAT_CORE for LUO for the existing mechanism which is also a required feature.
--- include/linux/kho/abi/luo.h | 336 +++++++++++++++++++++++++++++++---- kernel/liveupdate/luo_core.c | 62 ++++--- 2 files changed, 338 insertions(+), 60 deletions(-)
include/linux/kho/abi/luo.h +300 -36
@@ -9,29 +9,81 @@* 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. +* defined below to pass state from a source kernel to a target 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. +* This interface is a contract. `struct luo_ser`, and the serialized state +* of each file handler that uses it, start with an 8-byte base feature +* header (`struct luo_ser_hdr`) holding the combined structure `size` +* (`__u32`) and `nr_features` (`__u32`), followed by an array of 64-bit +* `flags` entries (`__u64 flags[]`) before the payload structure. +* When `nr_features == 0`, `flags` has zero entries and the header is exactly +* 8 bytes. For `1 <= nr_features <= 32`, `flags` has 1 entry and the header +* is 16 bytes. * -* Changes are allowed provided the compatibility version is incremented; -* however, backward/forward compatibility is only guaranteed for kernels -* supporting the same ABI version. +* Feature state encoding (2 bits per feature): +* `LUO_FEAT_ABSENT` = 0b00: Feature absent in serialized payload +* `LUO_FEAT_OPTIONAL` = 0b01: Feature present in serialized payload (optional) +* `LUO_FEAT_RESERVED` = 0b10: Reserved encoding (not validated) +* `LUO_FEAT_REQUIRED` = 0b11: Feature present in serialized payload (required) +* +* Feature flags mapping: +* - Each 64-bit `flags` entry encodes 32 features (2 bits per feature). +* - Feature N is encoded in `flags[N / 32]` at bits +* `[2 * (N % 32) + 1 : 2 * (N % 32)]`. +* +* Truth table:: +* +* Source hdr Target supported[i] Action +* ---------- ------------------- ---------------------------------- +* 00 0 or 1 Accept: feature absent in payload +* 01 0 Accept: ignore the feature data +* 01 1 Accept: use the feature data +* 11 0 Reject: -EOPNOTSUPP +* 11 1 Accept: use the feature data +* 10 0 or 1 Reserved: not checked by target +* +* Source hdr is the 2-bit state (enum luo_feat_state) of feature i in the +* header written by the source kernel. Target supported[i] is the boolean entry +* for feature i in the target kernel's supported feature table passed to +* luo_ser_hdr_validate() (1 = supported, 0 = not supported; an index at or +* beyond @nr_supported, or a NULL table, is 0). +* +* The relative order and offsets of fields in serialized structures must +* remain unchanged as features are added or retired. New fields are always +* appended at the end of the structure under a new feature flag, and +* retired fields are kept in place so that the offsets of subsequent +* fields never shift. If a field's type or format needs to change, the +* existing field and feature are kept intact (and retired when no longer +* needed) and a new feature flag with a new appended field of the new type +* is added. +* +* Apart from missing required features (-EOPNOTSUPP), `luo_ser_hdr_validate()` +* rejects a header only when the source kernel marks a feature `LUO_FEAT_REQUIRED` +* that the target kernel does not support. A feature the source kernel did +* not send reads as `LUO_FEAT_ABSENT`, so the target kernel reads the fields +* of a feature only after checking it:: +* +* if (luo_ser_get_feat(hdr, FEAT_X) != LUO_FEAT_ABSENT) +* val = ser->x_field; +* +* The source kernel is responsible for marking a feature it relies on as +* `LUO_FEAT_REQUIRED`. The target kernel handles each feature in its own +* retrieve code, for example by falling back to default behavior when a +* feature is absent; it does not guard against a source kernel that sets +* the wrong states. * * KHO Structure Overview: * The entire LUO state is encapsulated within a single KHO entry named "LUO". -* This entry contains the `struct luo_ser` structure. +* This entry contains a `struct luo_ser_hdr` followed by the +* `struct luo_ser` payload. * * 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. +* The central ABI payload structure that contains the overall state of +* the LUO (`LUO_CORE_FEAT_CORE`: the liveupdate-number and physical +* pointers to sessions and FLBs), preceded by `struct luo_ser_hdr`. * * - struct luo_session_ser: * Metadata for a single session, including its name and a physical pointer
@@ -40,7 +92,7 @@* * - 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 +* find the correct handler in the target kernel, a user-provided `token` for * identification, and an opaque `data` handle for the handler to use. * * - struct luo_flb_header_ser:
@@ -57,35 +109,247 @@#ifndef _LINUX_KHO_ABI_LUO_H#define _LINUX_KHO_ABI_LUO_H -#include <linux/align.h> +#include <linux/bits.h> +#include <linux/bug.h> #include <linux/build_bug.h> +#include <linux/errno.h> #include <linux/kho/abi/block.h> +#include <linux/math.h> +#include <linux/string.h> +#include <linux/types.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) + +#define LUO_FEAT_PER_FLAGS 32 +#define LUO_FEAT_STATE_MASK 0b11ULL + +/** +* enum luo_feat_state - 2-bit state of a feature in the serialized payload. +* @LUO_FEAT_ABSENT: Feature is absent in the serialized payload (`0b00`). +* @LUO_FEAT_OPTIONAL: Feature is present and optional (`0b01`). +* @LUO_FEAT_RESERVED: Reserved encoding (`0b10`). +* @LUO_FEAT_REQUIRED: Feature is present and required (`0b11`). +*/ +enum luo_feat_state { +LUO_FEAT_ABSENT =0b00 , +LUO_FEAT_OPTIONAL =0b01 , +LUO_FEAT_RESERVED =0b10 , +LUO_FEAT_REQUIRED =0b11 , +}; + +/** +* struct luo_ser_hdr - Base 8-byte header for serialized LUO ABI structures. +* @size: Total size of the serialized structure in bytes (header + +* `flags` + payload). +* @nr_features: Number of features encoded in @flags. +* @flags: 64-bit feature flags entries (`DIV_ROUND_UP(@nr_features, 32)` +* entries). Each entry encodes 32 features (2 bits per feature: +* feature `N` is in `flags[N / 32]` bits +* `[2*(N % 32) + 1 : 2*(N % 32)]`). +*/ +struct luo_ser_hdr { +__u32 size; +__u32 nr_features; +__u64 flags[]; +}; + +static_assert (sizeof (struct luo_ser_hdr ) ==8 ); + +/* +* Each subsystem declares a wrapper structure with DECLARE_LUO_SER_WRAP() (for +* example `struct memfd_luo_ser_wrap` or `struct luo_ser_wrap`) holding the +* header, any 64-bit `flags` entries and its payload, allocates it with +* sizeof() and initializes the header with the generated wrapper initializer +* (e.g. luo_ser_wrap_init()). The structure matches only the layout this kernel +* writes, so incoming state is never cast to it; the target kernel uses +* luo_ser_hdr_validate() and luo_ser_payload() instead. +*/ + +#define LUO_SER_NR_FLAGS (nr_features) DIV_ROUND_UP_POW2(nr_features, LUO_FEAT_PER_FLAGS) + +/** +* DECLARE_LUO_SER_WRAP - Declare an outgoing LUO header + payload wrapper structure. +* @name: Name of the payload structure (`struct @name`). +* @expected_size: Expected total size in bytes of `struct @name_wrap`. +* @nr_features: Number of features defined for `struct @name`. +* +* Declares `struct @name_wrap` and inline initializer `@name_wrap_init()` +* for the source kernel to allocate and populate when preserving state. +* It matches only the layout written by this kernel; incoming state from +* another kernel must be validated with luo_ser_hdr_validate() and its +* payload reached via luo_ser_payload(). +*/ +#define DECLARE_LUO_SER_WRAP (name, expected_size, nr_features) \ + struct name##_wrap { \ + union { \ + struct luo_ser_hdr hdr; \ + struct { \ + __u32 __size; \ + __u32 __nr_features; \ + __u64 flags[LUO_SER_NR_FLAGS(nr_features)];\ + struct name ser; \ + }; \ + }; \ + }; \ + static_assert(sizeof(struct name##_wrap) == (expected_size), \ + "LUO struct " #name " size mismatch!"); \ + static inline void name##_wrap_init(struct name##_wrap *wrap) \ + { \ + luo_ser_hdr_init(&wrap->hdr, sizeof(*wrap), (nr_features));\ + } + +/** +* luo_ser_hdr_size - Header size of a serialized header. +* @hdr: Pointer to the serialized &struct luo_ser_hdr. +* +* Return: Size of @hdr in bytes, including its 64-bit `flags` entries. +*/ +static inline size_t luo_ser_hdr_size (const struct luo_ser_hdr *hdr) +{ +return struct_size (hdr, flags,LUO_SER_NR_FLAGS (hdr->nr_features)); +} + +/** +* luo_ser_hdr_init - Initialize a feature header. +* @hdr: Pointer to the &struct luo_ser_hdr to initialize. +* @size: Total size of the serialized structure (header, `flags` entries +* and payload), normally sizeof() of the wrapper structure. +* @nr_features: Number of features to accommodate. +* +* Sets @hdr->size and @hdr->nr_features, and clears the 64-bit `flags` entries. +* Touches only the header. +*/ +static inline void +luo_ser_hdr_init (struct luo_ser_hdr *hdr,size_t size,u32 nr_features) +{ + hdr->size = size; + hdr->nr_features = nr_features; +memset (hdr->flags,0 ,LUO_SER_NR_FLAGS (nr_features) *sizeof (hdr->flags[0 ])); +} + +/* +* These helpers operate on any well-formed header: one initialized on the +* outgoing path or validated by luo_ser_hdr_validate() on the incoming path. +*/ + +/** +* luo_ser_payload - Get pointer to the payload immediately following @hdr. +* @hdr: Pointer to the serialized &struct luo_ser_hdr. +* +* @hdr must be initialized or validated. +* +* Return: Pointer to the payload structure. +*/ +static inline void *luo_ser_payload (const struct luo_ser_hdr *hdr) +{ +return (void *)((const char *)hdr +luo_ser_hdr_size (hdr)); +} + +/** +* luo_ser_set_feat - Set the 2-bit state of feature @feat in @hdr. +* @hdr: Pointer to &struct luo_ser_hdr. +* @feat: Feature index. +* @state: Feature state (&enum luo_feat_state). +* +* @hdr must be initialized or validated. +*/ +static inline void +luo_ser_set_feat (struct luo_ser_hdr *hdr,u32 feat,enum luo_feat_state state) +{ +u32 idx, slot; + +if (WARN_ON_ONCE (feat >= hdr->nr_features)) +return ; + + idx = feat /LUO_FEAT_PER_FLAGS ; + slot = feat %LUO_FEAT_PER_FLAGS ; + hdr->flags[idx] &= ~(LUO_FEAT_STATE_MASK << (2 * slot)); + hdr->flags[idx] |= (u64)(state &LUO_FEAT_STATE_MASK ) << (2 * slot); +} + +/** +* luo_ser_get_feat - Query the 2-bit state of feature @feat in @hdr. +* @hdr: Pointer to &struct luo_ser_hdr. +* @feat: Feature index. +* +* @hdr must be initialized or validated. +* +* Return: &enum luo_feat_state (returns %LUO_FEAT_ABSENT if @feat is beyond +* @hdr->nr_features). +*/ +static inline enum luo_feat_state +luo_ser_get_feat (const struct luo_ser_hdr *hdr,u32 feat) +{ +u32 idx, slot; + +if (feat >= hdr->nr_features) +return LUO_FEAT_ABSENT ; + + idx = feat /LUO_FEAT_PER_FLAGS ; + slot = feat %LUO_FEAT_PER_FLAGS ; + +return (hdr->flags[idx] >> (2 * slot)) &LUO_FEAT_STATE_MASK ; +}/** -* struct luo_ser - Centralized LUO ABI header. -* @compatible: Compatibility string identifying the LUO ABI version. +* luo_ser_hdr_validate - Validate source kernel's feature header. +* @hdr: Pointer to the feature header from the source kernel. +* @supported: Target kernel's supported features table, indexed by feature. +* @nr_supported: Number of entries in @supported. +* +* Checks each source feature state in @hdr against @supported[i] using the +* truth table in the DOC section above. +* +* Return: 0 if compatible, or -EOPNOTSUPP on required feature mismatch. +*/ +static inline int +luo_ser_hdr_validate (const struct luo_ser_hdr *hdr, +const bool *supported,u32 nr_supported) +{ +u32 feat; + +for (feat =0 ; feat < hdr->nr_features; feat++) +if (luo_ser_get_feat (hdr, feat) ==LUO_FEAT_REQUIRED && + (feat >= nr_supported || !supported[feat])) +return -EOPNOTSUPP ; + +return 0 ; +} + +/** +* enum luo_core_feature - Feature indices for &struct luo_ser. +* @LUO_CORE_FEAT_CORE: Core feature covering `liveupdate_num`, `sessions_pa` +* and `flbs_pa`. +* @LUO_CORE_FEAT_MAX: Number of defined &enum luo_core_feature features. +*/ +enum luo_core_feature { +LUO_CORE_FEAT_CORE =0 , +LUO_CORE_FEAT_MAX , +}; + +/** +* struct luo_ser - Centralized LUO ABI payload. * @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. +* This structure is the root payload of all preserved LUO state, preceded by +* &struct luo_ser_hdr. */ struct luo_ser { -char compatible[LUO_ABI_COMPAT_LEN ];u64 liveupdate_num;u64 sessions_pa;u64 flbs_pa; }; -static_assert (sizeof (struct luo_ser ) ==32 ); +static_assert (sizeof (struct luo_ser ) ==24 ); + +/* LUO state written by this kernel. Never cast incoming state to it. */ +DECLARE_LUO_SER_WRAP (luo_ser,40 ,LUO_CORE_FEAT_MAX );#define LIVEUPDATE_HNDL_COMPAT_LENGTH 48
@@ -95,7 +359,7 @@ static_assert(sizeof(struct luo_ser) == 32);* @data: Private data * @token: User provided token for this file * -* If this structure is modified, `LUO_ABI_COMPATIBLE` must be updated. +* Layout changes must be gated by a feature in &enum luo_core_feature. */ struct luo_file_ser {char compatible[LIVEUPDATE_HNDL_COMPAT_LENGTH ];
@@ -130,10 +394,10 @@ static_assert(sizeof(struct luo_file_set_ser) == 16);* * 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. +* session) is created and passed to the target kernel, allowing it to +* reconstruct the session context. * -* If this structure is modified, `LUO_ABI_COMPATIBLE` must be updated. +* Layout changes must be gated by a feature in &enum luo_core_feature. */ struct luo_session_ser {char name[LIVEUPDATE_SESSION_NAME_LENGTH ];
@@ -156,7 +420,7 @@ static_assert(sizeof(struct luo_session_ser) == 80);* 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. +* Layout changes must be gated by a feature in &enum luo_core_feature. */ struct luo_flb_header_ser {u64 pgcnt;
@@ -168,19 +432,19 @@ static_assert(sizeof(struct luo_flb_header_ser) == 16);/** * 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. +* corresponding &struct liveupdate_flb in the target 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. +* in the source 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. +* target 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. +* passed to the target kernel. Each entry allows the LUO core to restore +* one global, shared object. * -* If this structure is modified, `LUO_ABI_COMPATIBLE` must be updated. +* Layout changes must be gated by a feature in &enum luo_core_feature. */ struct luo_flb_ser {char name[LIVEUPDATE_FLB_COMPAT_LENGTH ];
kernel/liveupdate/luo_core.c +38 -24
120 lines not on this page · raw message
Signature · 1 line
2.56.0.307.g5fe7bd680c-goog
[email protected]
AI reviewSashiko has reviewed this patch and found no issues.
Quoted 19 lines
LUO and its file handlers currently rely solely on coarse-grained compatibility strings (such as luo-v5 and memfd-v2) to validate handed-over state across kexec. Because compatibility is checked only at the whole-structure level, any change to a serialized structure, even an optional additive field, requires bumping the compatibility string and breaks live update between adjacent kernels.
Introduce a feature header (struct
luo_ser_hdr) ahead of serialized LUO structures so subsystems can evolve their serialized state at per-feature granularity. Each subsystem groups the fields of its serialized structure under feature indices, starting with index 0 for the base fields. When a subsystem adds a new capability, it appends any new fields to the end of its payload structure under a new feature index. Retired fields are kept in place so existing field offsets never shift; if the type or format of a field needs to change, the existing field and [ ... ]
Also, introduce theLUO_CORE_FEAT_COREfor LUO for the existing mechanism which is also a required feature.
Quoted 2 lines
Signed-off-by Logan Odell <[email protected]>Signed-off-by Tarun Sahu <[email protected]>
Sashiko has reviewed this patch and found no issues.
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=2
RFC PATCH v3 3/4 mm: memfd_luo: Add the feature header
In reply to Tarun SahuPrecede struct memfd_luo_ser with the 8-byte struct luo_ser_hdr for memfd preservation. The source kernel writes the state through struct memfd_luo_ser_wrap, declared with DECLARE_LUO_SER_WRAP():
DECLARE_LUO_SER_WRAP(memfd_luo_ser, 64, MEMFD_LUO_FEAT_MAX);
This consists of hdr + memfd_luo_ser (payload).
The existing struct memfd_luo_ser fields (pos, size, seals, flags, nr_folios, folios, and MEMFD_LUO_ALL_SEALS) form MEMFD_LUO_FEAT_CORE (index 0 of enum memfd_luo_feature). The source kernel marks it as LUO_FEAT_REQUIRED when preserving state, and the target kernel marks it as supported (true) in its memfd_luo_supported_feats table passed to luo_ser_hdr_validate(). Future changes append any new fields to the end of struct memfd_luo_ser under a new feature index so existing field offsets never shift.
memfd_luo_retrieve() and memfd_luo_finish() validate the incoming header against memfd_luo_supported_feats with luo_ser_hdr_validate() before accessing any payload field; finish warns and skips discarding the folios when the header is invalid.
Prepending the header shifts every field of the serialized memfd state, so bump MEMFD_LUO_FH_COMPATIBLE from memfd-v2 to memfd-v3.
--- include/linux/kho/abi/memfd.h | 32 +++++++++++++++-- mm/memfd_luo.c | 68 ++++++++++++++++++++++++----------- 2 files changed, 77 insertions(+), 23 deletions(-)
include/linux/kho/abi/memfd.h +29 -3
@@ -14,6 +14,7 @@#include <linux/build_bug.h> #include <linux/types.h> #include <linux/kho/abi/kexec_handover.h> +#include <linux/kho/abi/luo.h> /** * DOC: memfd Live Update ABI
@@ -22,9 +23,18 @@* reboot using the LUO. * * The state is serialized into `struct memfd_luo_ser` -* which is handed over to the next kernel via the KHO mechanism. +* which is handed over to the target kernel via the KHO mechanism. * -* This interface is a contract. Any modification to the structure layout +* This interface is a contract. The serialized state starts with an +* 8-byte `struct luo_ser_hdr` followed by `struct memfd_luo_ser`. +* The relative order and offsets of fields must remain unchanged as +* features are added or retired: new fields are appended at the end of +* `struct memfd_luo_ser` under a new feature flag, and retired fields are +* kept in place so subsequent offsets never shift. In the target kernel, +* the fields of a feature are read only after `luo_ser_get_feat()` shows +* the feature present. +* +* Any modification to the structure layout beyond feature extensions * constitutes a breaking change. Such changes require incrementing the * version number in the MEMFD_LUO_FH_COMPATIBLE string. */
@@ -70,6 +80,17 @@ static_assert(sizeof(struct memfd_luo_folio_ser) == 16); F_SEAL_FUTURE_WRITE | \ F_SEAL_EXEC) +/** +* enum memfd_luo_feature - Feature indices for &struct memfd_luo_ser. +* @MEMFD_LUO_FEAT_CORE: Core feature covering `pos`, `size`, `seals`, `flags`, +* `nr_folios`, `folios`, and %MEMFD_LUO_ALL_SEALS. +* @MEMFD_LUO_FEAT_MAX: Number of defined &enum memfd_luo_feature features. +*/ +enum memfd_luo_feature { +MEMFD_LUO_FEAT_CORE =0 , +MEMFD_LUO_FEAT_MAX , +}; +/** * struct memfd_luo_ser - Main serialization structure for a memfd. * @pos: The file's current position (f_pos).
@@ -80,6 +101,8 @@ static_assert(sizeof(struct memfd_luo_folio_ser) == 16);* @nr_folios: Number of folios in the folios array. * @folios: KHO vmalloc descriptor pointing to the array of * struct memfd_luo_folio_ser. +* +* Preceded by &struct luo_ser_hdr. */ struct memfd_luo_ser {u64 pos;
@@ -92,7 +115,10 @@ struct memfd_luo_ser {static_assert (sizeof (struct memfd_luo_ser ) ==48 ); +/* memfd state written by this kernel. Never cast incoming state to it. */ +DECLARE_LUO_SER_WRAP (memfd_luo_ser,64 ,MEMFD_LUO_FEAT_MAX ); +/* The compatibility string for memfd file handler */ -#define MEMFD_LUO_FH_COMPATIBLE "memfd-v2" +#define MEMFD_LUO_FH_COMPATIBLE "memfd-v3"#endif /* _LINUX_KHO_ABI_MEMFD_H */
mm/memfd_luo.c +48 -20
176 lines not on this page · raw message
Signature · 1 line
2.56.0.307.g5fe7bd680c-goog
[email protected]
AI reviewRe: [RFC PATCH v3 3/4] mm: memfd_luo: Add the feature header
Sashiko has reviewed this patch and found no issues.
Quoted 22 lines
Precede struct
memfd_luo_serwith the 8-byte structluo_ser_hdrfor memfd preservation. The source kernel writes the state through structmemfd_luo_ser_wrap, declared withDECLARE_LUO_SER_WRAP():DECLARE_LUO_SER_WRAP(memfd_luo_ser, 64, MEMFD_LUO_FEAT_MAX);This consists of hdr +
memfd_luo_ser(payload).The existing struct
memfd_luo_serfields (pos, size, seals, flags,nr_folios, folios, andMEMFD_LUO_ALL_SEALS) formMEMFD_LUO_FEAT_CORE(index 0 of enummemfd_luo_feature). The source kernel marks it asLUO_FEAT_REQUIREDwhen preserving state, and the target kernel marks it as supported (true) in itsmemfd_luo_supported_featstable passed toluo_ser_hdr_validate(). Future changes append any new fields to the end of structmemfd_luo_serunder a new feature index so existing field offsets never shift.
memfd_luo_retrieve()andmemfd_luo_finish()validate the incoming header againstmemfd_luo_supported_featswithluo_ser_hdr_validate()before accessing any payload field; finish warns and skips discarding the folios when the header is invalid.
Quoted 5 lines
Prepending the header shifts every field of the serialized memfd state, so bump
MEMFD_LUO_FH_COMPATIBLEfrom memfd-v2 to memfd-v3.Signed-off-by Logan Odell <[email protected]>Signed-off-by Tarun Sahu <[email protected]>
Sashiko has reviewed this patch and found no issues.
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=3
RFC PATCH v3 4/4 liveupdate: Add KUnit test for the feature header helpers
In reply to Tarun SahuAdd a KUnit test suite in lib/tests/liveupdate_feature_kunit.c covering the Live Update feature header declared in include/linux/kho/abi/luo.h.
The suite contains two focused test cases:
- luo_ser_hdr_set_get_test: verifies DECLARE_LUO_SER_WRAP structure sizing, header initialization, payload pointer resolution, and 2-bit feature flag setting and retrieval across flags entry boundaries, including out-of-range queries.
- luo_ser_hdr_truth_table_test: verifies luo_ser_hdr_validate against all rows of the feature state truth table (absent, optional, required, and reserved 0b10 encodings), as well as empty supported tables.
--- MAINTAINERS | 1 + lib/Kconfig.debug | 16 ++++ lib/tests/Makefile | 1 + lib/tests/liveupdate_feature_kunit.c | 118 +++++++++++++++++++++++++++ 4 files changed, 136 insertions(+) create mode 100644 lib/tests/liveupdate_feature_kunit.c
MAINTAINERS +1 -0
@@ -15191,6 +15191,7 @@ F: include/linux/liveupdate.h F: include/uapi/linux/liveupdate.h F: kernel/liveupdate/ F: lib/tests/liveupdate.c +F: lib/tests/liveupdate_feature_kunit.c F: mm/memfd_luo.c F: tools/testing/selftests/liveupdate/
lib/Kconfig.debug +16 -0
@@ -2906,6 +2906,22 @@ config LIVEUPDATE_TEST If unsure, say N +config LIVEUPDATE_FEATURE_KUNIT_TEST + tristate "KUnit test for the Live Update feature header helpers" if !KUNIT_ALL_TESTS + depends on KUNIT + default KUNIT_ALL_TESTS + help + This option enables the KUnit test suite for the Live Update + Orchestrator feature header helpers defined in + include/linux/kho/abi/luo.h. It checks the feature flag encoding, + the flags array sizing, the source/target kernel validation + truth table, header initialization and the payload size checks. + + The helpers are self-contained, so the test does not depend on + CONFIG_LIVEUPDATE and can also run under UML. + + If unsure, say N. + config CMDLINE_KUNIT_TEST tristate "KUnit test for cmdline API" if !KUNIT_ALL_TESTS depends on KUNIT
lib/tests/Makefile +1 -0
@@ -33,6 +33,7 @@ obj-$(CONFIG_KFIFO_KUNIT_TEST) += kfifo_kunit.o obj-$(CONFIG_TEST_LIST_SORT) += test_list_sort.o obj-$(CONFIG_LINEAR_RANGES_TEST) += test_linear_ranges.o obj-$(CONFIG_LIVEUPDATE_TEST) += liveupdate.o +obj-$(CONFIG_LIVEUPDATE_FEATURE_KUNIT_TEST) += liveupdate_feature_kunit.o CFLAGS_longest_symbol_kunit.o += $(call cc-disable-warning, missing-prototypes) obj-$(CONFIG_LONGEST_SYM_KUNIT_TEST) += longest_symbol_kunit.o
lib/tests/liveupdate_feature_kunit.c new file +118 -0
118 lines not on this page · raw message
Signature · 1 line
2.56.0.307.g5fe7bd680c-goog
[email protected]
AI reviewRe: [RFC PATCH v3 4/4] liveupdate: Add KUnit test for the feature header helpers
Sashiko has reviewed this patch and found no issues.
Quoted 13 lines
Add a KUnit test suite in
lib/tests/liveupdate_feature_kunit.ccovering the Live Update feature header declared ininclude/linux/kho/abi/luo.h.The suite contains two focused test cases:
-luo_ser_hdr_set_get_test: verifiesDECLARE_LUO_SER_WRAPstructure sizing, header initialization, payload pointer resolution, and 2-bit feature flag setting and retrieval across flags entry boundaries, including out-of-range queries.
-luo_ser_hdr_truth_table_test: verifiesluo_ser_hdr_validateagainst all rows of the feature state truth table (absent, optional, required, and reserved 0b10 encodings), as well as empty supported tables.
Quoted 1 line
Signed-off-by Tarun Sahu <[email protected]>
Sashiko has reviewed this patch and found no issues.
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=4
Withdrawing this version because of the following reasons.
1. KHO also has versioning which can also share the same concept of the feature flags, And the header can be shared amongst KHO and LUO. In next version, I will include this.
2. If there are any open threads in the V2, Can be settled based on this V3 reference. This V3 has included the suggestion from V2, like updated truth table, nr_features based flags array, ABI wrapper MACRO etc.
~Tarun
Quoted 100 lines · Tarun Sahu
Changes since RFC v2 [1]:
- Dropped the file handler compatible rename and per-FD handler selection patches.
- Replaced the fixed 128-byte header with an expandable structluo_ser_hdr(size,nr_features, flags[]), kept separate from the payload structure. The header is 8 bytes with no features and 16 bytes for 1 to 32 features.
- Each subsystem declares its wrapper once withDECLARE_LUO_SER_WRAP(), passing its feature enum MAX; the macro sizes the flags entries and generates name##_wrap_init(), so callers never pass sizes or counts. The target kernel reaches the payload withluo_ser_payload().
- Feature bits describe only what each preserved object uses. The target kernel checks them against its own boolean supported table, and the header is trusted as the source of truth: validation only rejects a required feature the target kernel does not support. 0b10 is reserved.
- Moved the__packedremoval into its own patch (1/4) and added a KUnit test (4/4).Changes since RFC v1 [2]:
- Replaced the 3-mask (supp, req, active) design with a header of 2-bit feature states.[1] https://lore.kernel.org/all/[email protected]/
[2] https://lore.kernel.org/all/[email protected]/==========COVER LETTER==============
LUO and its file handlers rely only on coarse-grained compatibility strings (such as luo-v5 and memfd-v2) to validate handed-over state across kexec. Any change to a serialized structure, even an optional additive field, requires bumping the string and breaks live update between adjacent kernels.
This series adds a feature header (struct
luo_ser_hdr) ahead of serialized LUO structures so subsystems can evolve their serialized state per feature. Each subsystem groups its serialized fields under feature indices, with index 0 for the base fields. New capabilities append fields at the end of the payload under a new feature index, and retired fields stay in place so offsets never shift. Only a change that feature flags cannot express needs a new handler with a bumped compatibility string.Each feature has a 2-bit state set by the source kernel:
-LUO_FEAT_ABSENT(0b00): not in the payload; a target kernel that supports it can use default values.
-LUO_FEAT_OPTIONAL(0b01): in the payload; a target kernel that does not support it ignores the data.
-LUO_FEAT_REQUIRED(0b11): in the payload; a target kernel that does not support it rejects the state with-EOPNOTSUPP.
-LUO_FEAT_RESERVED(0b10): reserved, not checked by the target kernel.The target kernel checks the header against its own boolean supported table:
Source hdr Target supported[i] Action ---------- ------------------- ---------------------------------- 00 0 or 1 Accept: feature absent in payload 01 0 Accept: ignore the feature data 01 1 Accept: use the feature data 11 0 Reject: -EOPNOTSUPP 11 1 Accept: use the feature data 10 0 or 1 Reserved: not checked by targetstruct
luo_ser_hdrholds the total size of the serialized structure (u32), the number of features (u32nr_features), and 64-bit flags entries with 32 features each. With no features the header is 8 bytes; with 1 to 32 features it is 16 bytes.On the source side, a subsystem declares its wrapper once with
DECLARE_LUO_SER_WRAP(name, expected_size, nr_features), passing its feature enum MAX, then calls name##_wrap_init(), marks the features the preserved object uses withluo_ser_set_feat(), and fillswrap->ser. On the target side, incoming state is never cast to the wrapper, since the source kernel may use a different number of flags entries. The target kernel callsluo_ser_hdr_validate(), finds the payload withluo_ser_payload(), and reads the fields of a feature only afterluo_ser_get_feat()shows it present.Patch 1 removes
__packedfrom the LUO and memfd ABI structures. Patch 2 adds the header and converts structluo_ser. Patch 3 converts memfd and bumps its compatibility string to memfd-v3. Patch 4 adds KUnit tests.Tarun Sahu (4):
liveupdate: Remove__packedfrom LUO and memfd ABI structures
liveupdate: Add feature header for fine-grained ABI compatibility
mm:memfd_luo: Add the feature header
liveupdate: Add KUnit test for the feature header helpersMAINTAINERS | 1 + include/linux/kho/abi/luo.h | 359 ++++++++++++++++++++++++--- include/linux/kho/abi/memfd.h | 43 +++- kernel/liveupdate/luo_core.c | 62 +++-- lib/Kconfig.debug | 16 ++ lib/tests/Makefile | 1 + lib/tests/liveupdate_feature_kunit.c | 118 +++++++++ mm/memfd_luo.c | 68 +++-- 8 files changed, 577 insertions(+), 91 deletions(-) create mode 100644 lib/tests/liveupdate_feature_kunit.cSignature · 1 line
2.56.0.307.g5fe7bd680c-goog