Re: [PATCH v3 7/7] Documentation, kstate: Add KSTATE documentation
From: Bagas Sanjaya <hidden>
Date: 2025-09-10 00:53:57
Also in:
kexec, linux-mm, lkml
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
On Tue, Sep 09, 2025 at 10:14:42PM +0200, Andrey Ryabinin wrote:
+There are _V forms of many KSTATE_ macros to load fields for version dependent fields, e.g.
Escape the trailing underscore (i.e. KSTATE\_).
+Addition of new field can be done as version dependent field by using _V form of +KSTATE_ macro:
Ditto.
+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
+ },
+};Sphinx errors out on struct snippets like above: Documentation/core-api/kstate.rst:17: WARNING: Inline emphasis start-string without end-string. [docutils] Documentation/core-api/kstate.rst:17: WARNING: Inline emphasis start-string without end-string. [docutils] Documentation/core-api/kstate.rst:21: WARNING: Definition list ends without a blank line; unexpected unindent. [docutils] Documentation/core-api/kstate.rst:28: ERROR: Unexpected indentation. [docutils] Documentation/core-api/kstate.rst:32: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils] Documentation/core-api/kstate.rst:33: WARNING: Definition list ends without a blank line; unexpected unindent. [docutils] Documentation/core-api/kstate.rst:84: ERROR: Unexpected indentation. [docutils] Documentation/core-api/kstate.rst:100: ERROR: Unexpected indentation. [docutils] Documentation/core-api/kstate.rst:102: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils] Documentation/core-api/kstate.rst:103: WARNING: Definition list ends without a blank line; unexpected unindent. [docutils] Documentation/core-api/kstate.rst:106: CRITICAL: Unexpected section title or transition. ...... [docutils] reStructuredText markup error! I have to wrap them in literal code blocks: ---- >8 ----
diff --git a/Documentation/core-api/kstate.rst b/Documentation/core-api/kstate.rst
index 981ba162109c34..620d7c126c2038 100644
--- a/Documentation/core-api/kstate.rst
+++ b/Documentation/core-api/kstate.rst@@ -11,16 +11,16 @@ kstate_description ------------------ Most kernel's state is in structs and structs could be described by -kstate_description. E.g. +kstate_description. E.g.:: -struct kstate_test_data { + struct kstate_test_data { int i; unsigned long *p_ulong; char s[10]; struct folio *folio; -}; + }; -struct kstate_description test_state = { + struct kstate_description test_state = { .name = "test", .version_id = 1, .id = KSTATE_TEST_ID,
@@ -30,7 +30,7 @@ struct kstate_description test_state = { KSTATE_FOLIO(folio, struct kstate_test_data), KSTATE_END_OF_LIST() }, -}; + }; Changing data structures ------------------------
@@ -55,7 +55,7 @@ There are two version fields: 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. +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),
@@ -67,7 +67,7 @@ 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_*_DEPRECATED macro and bumping ->version_id of kstate_description:: KSTATE_BASE_TYPE_DEPRECATED(k, u16, 1),
@@ -80,7 +80,8 @@ Adding new field ---------------- Addition of new field can be done as version dependent field by using _V form of -KSTATE_ macro: +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'.
@@ -91,24 +92,24 @@ 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: +additional kstate_description which linked to the main one:: -struct kstate_description test_state_v2 = { + 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 = { + 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
Thanks. -- An old man doll... just what I always wanted! - Clara