Add KSTATE doc. Describe 'struct kstate_description' and information about versioning fields. Signed-off-by: Andrey Ryabinin --- Documentation/core-api/index.rst | 1 + Documentation/core-api/kstate.rst | 117 ++++++++++++++++++++++++++++++ MAINTAINERS | 1 + 3 files changed, 119 insertions(+) create mode 100644 Documentation/core-api/kstate.rst diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index a8b7d1417f0a..6c0466e0bb35 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -136,6 +136,7 @@ Documents that don't fit elsewhere or which have yet to be categorized. .. toctree:: :maxdepth: 1 + kstate librs liveupdate netlink diff --git a/Documentation/core-api/kstate.rst b/Documentation/core-api/kstate.rst new file mode 100644 index 000000000000..981ba162109c --- /dev/null +++ b/Documentation/core-api/kstate.rst @@ -0,0 +1,117 @@ +.. SPDX-License-Identifier: GPL-2.0 + +KSTATE: Kernel state preservation framework +=========================================== + +KSTATE (kernel state) is framework to migrate some part of the internal +kernel state (device driver, memory, etc) from one kernel to another across +kexec reboot. + +kstate_description +------------------ + +Most kernel's state is in structs and structs could be described by +kstate_description. E.g. + +struct kstate_test_data { + int i; + unsigned long *p_ulong; + char s[10]; + struct folio *folio; +}; + +struct kstate_description test_state = { + .name = "test", + .version_id = 1, + .id = KSTATE_TEST_ID, + .fields = (const struct kstate_field[]) { + KSTATE_BASE_TYPE(s, struct kstate_test_data, char [10]), + KSTATE_POINTER(p_ulong, struct kstate_test_data), + KSTATE_FOLIO(folio, struct kstate_test_data), + KSTATE_END_OF_LIST() + }, +}; + +Changing data structures +------------------------ + +KSTATE saves/restores structs as a series of fields. When the kernel structs +are changed we may need to change the state to store more/different information. + +Versions +-------- + +Version numbers are intended for major incompatible changes, that are not +backward compatible. + +Each version is associated with a series of fields saved. The state is always +saved as the newest version specified by ->version_id. +But loading state sometimes is able to load state from an older version. + +There are two version fields: + + - version_id: the maximum version_id supported by kstate_description. + - min_version_id: the minimum version_id that given kstate_description is able to understand. + +KSTATE is able to read versions from minimum_version_id to version_id. + +There are _V forms of many KSTATE_ macros to load fields for version dependent fields, e.g. + + KSTATE_BASE_TYPE_V(i, struct kstate_test_data, int, 2), + +only loads that field for versions 2 and newer. + +Saving state will always create a section with the ‘version_id’ value and thus can’t +be loaded by any older kernel. + +Removing field +-------------- +If field is no longer needed it could be marked deprecated using +KSTATE_*_DEPRECATED macro and bumping ->version_id of kstate_description: + + KSTATE_BASE_TYPE_DEPRECATED(k, u16, 1), + +The last parameter of the macro is the last version number that have this field. +Old kernel will save such field, but new kernel will skip it on load. Also +the new kernel will not save such field (as there is nothing to save). +Such change is not backward compatible. + +Adding new field +---------------- + +Addition of new field can be done as version dependent field by using _V form of +KSTATE_ macro: + KSTATE_BASE_TYPE_V(i, struct kstate_test_data, int, 2), + +This indicates that 'test_state' only from version 2 and above have field '->i'. +If new kernel sees incoming 'test_state' of version 1 it will skip restoring '->i' +as nothing was saved. This is not backward compatible, as old kernel doesn't +understand the new V2 'test_state'. + +Subsections +----------- +Another option is adding subsection to kstate_description. A subsection is +additional kstate_description which linked to the main one: + +struct kstate_description test_state_v2 = { + .name = "test_v2", + .id = KSTATE_TEST_ID_V2, + .fields = (const struct kstate_field[]) { + KSTATE_BASE_TYPE(i, struct kstate_test_data, int), + KSTATE_END_OF_LIST() + }, +}; + +struct kstate_description test_state = { + ...... + .subsections = (const struct kstate_description *[]){ + &test_state_v2, + NULL + }, +}; + + +Subsection must have a unique ->id. If the receiving side finds a subsection +with unknown id it will be ignored. This make subsections suitable for backward +compatible changes (migrate from N+1 to N kernel) assuming old kernel is ok without +information in subsection. diff --git a/MAINTAINERS b/MAINTAINERS index e96da6d97e75..a9baf49cdbeb 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -13721,6 +13721,7 @@ F: include/linux/ks0108.h KSTATE M: Andrey Ryabinin S: Maintained +F: Documentation/core-api/kstate.rst F: include/linux/kstate.h F: kernel/livupdate/kstate.c F: lib/test_kstate.c -- 2.49.1