| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <aMDMHx1spjeETKK4@archie.me>
Date: Wed, 10 Sep 2025 07:53:51 +0700
From: Bagas Sanjaya <bagasdotme@...il.com>
To: Andrey Ryabinin <arbn@...dex-team.com>, linux-kernel@...r.kernel.org
Cc: Alexander Graf <graf@...zon.com>, Mike Rapoport <rppt@...nel.org>,
James Gowans <jgowans@...zon.com>,
Andrew Morton <akpm@...ux-foundation.org>, linux-mm@...ck.org,
Thomas Gleixner <tglx@...utronix.de>,
Ingo Molnar <mingo@...hat.com>, Borislav Petkov <bp@...en8.de>,
Dave Hansen <dave.hansen@...ux.intel.com>, x86@...nel.org,
"H. Peter Anvin" <hpa@...or.com>, Baoquan He <bhe@...hat.com>,
kexec@...ts.infradead.org, Pratyush Yadav <ptyadav@...zon.de>,
Jason Gunthorpe <jgg@...dia.com>,
Pasha Tatashin <pasha.tatashin@...een.com>,
David Rientjes <rientjes@...gle.com>,
Pratyush Yadav <pratyush@...nel.org>,
Changyuan Lyu <changyuanl@...gle.com>,
Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org,
Andrey Ryabinin <ryabinin.a.a@...il.com>,
Chris Li <chrisl@...nel.org>, Ashish.Kalra@....com,
William Tu <witu@...dia.com>, David Matlack <dmatlack@...gle.com>
Subject: Re: [PATCH v3 7/7] Documentation, kstate: Add KSTATE documentation
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
Powered by blists - more mailing lists