Add KSTATE doc. Describe 'struct kstate_description' and information
about versioning fields.
Signed-off-by: Andrey Ryabinin <a...@yandex-team.com>
---
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 <ryabinin....@gmail.com>
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
