On Thu, Feb 12, 2026 at 4:23 PM Greg KH <[email protected]> wrote: > > On Thu, Feb 12, 2026 at 03:00:01PM +0100, Gabriele Paoloni wrote: > > On Thu, Feb 12, 2026 at 1:59 PM Greg KH <[email protected]> wrote: > > > > > > On Thu, Feb 12, 2026 at 01:49:18PM +0100, Gabriele Paoloni wrote: > > > > Extend the longer description section of a function kernel-doc > > > > header with an itemised list of function's behaviors and > > > > constraints of use. > > > > These are useful to link and trace test cases (e.g. KUnit) to > > > > the different behavior IDs and define the constraints to be > > > > met by the function's caller. > > > > > > > > Signed-off-by: Gabriele Paoloni <[email protected]> > > > > --- > > > > Documentation/doc-guide/kernel-doc.rst | 19 +++++++++++++++++++ > > > > 1 file changed, 19 insertions(+) > > > > > > > > diff --git a/Documentation/doc-guide/kernel-doc.rst > > > > b/Documentation/doc-guide/kernel-doc.rst > > > > index 8d2c09fb36e4..23e6c4b45b14 100644 > > > > --- a/Documentation/doc-guide/kernel-doc.rst > > > > +++ b/Documentation/doc-guide/kernel-doc.rst > > > > @@ -83,6 +83,25 @@ The general format of a function and function-like > > > > macro kernel-doc comment is:: > > > > * > > > > * The longer description may have multiple paragraphs. > > > > * > > > > + * When specifying testable code behaviour the longer description > > > > must contain > > > > + * a paragraph formatted as follows: > > > > + * > > > > + * function_name behavior: > > > > + * [ID1] - [expected behavior] > > > > + * > > > > + * [ID2] - [expected behavior] > > > > + * > > > > + * [...] > > > > + * > > > > + * [IDn] - [expected behavior] > > > > + * > > > > + * function_name constraints of use: > > > > + * [ID1] - [constraint to be met by the caller] > > > > + * > > > > + * [ID2] - [constraint to be met by the caller] > > > > + * > > > > + * [IDn] - [constraint to be met by the caller] > > > > > > So the same "id" is used for a behavior, AND a constraint? > > > > The idea is to have a specific behaviour or constraint of use > > identified by the tuple [function_name behavior][ID]. > > So I think we could have a problem for duplicated symbols (but > > it is a sort of corner case...) > > I am trying to say that you have ID1 listed in two places above. So > that's not unique with a [function_name][ID] pair, where does the > "behavior" part come in?
Maybe it is not clear from the patch above (and I can find a better way to describe it), however if we take one example from patch 2 we have: [...] + * read_mem behavior: + * 1. it checks if the requested physical memory range [ppos, ppos + count - 1] + * is valid; + * 2. for each page in the requested range, it checks if user space access is + * allowed; [...] So in the end a unique identifier is "[read_mem behavior] [1]" and if the same IDx is used for both behavior and constraint there would be no issues since the tuple is the actual unique identifier. So for example in partch 2 we have: [...] + * memory_open behavior: + * 1. This function retrieves the minor number associated with the input inode + * and the memory device corresponding to such a minor number; [...] + * memory_open constraints of use: + * 1. The input inode and filp are expected to be valid. [...] In this case while 1 is used as IDx for both the behavior and a constraint of use the is no ambiguity since the unique identifiers are "[memory_open behavior][1]" and "[memory_open constraints of use][1]" > > What is now parsing these comments to ensure that they are unique, in > correct order, and are used elsewhere? What is the text for such a > behavior and constraint? Right now I have not implemented any check to make sure the identifiers (in terms of tuples as explained above) are correct and unique, however maybe a check can be added in kdoc_parser.py to make sure no duplicate tuples exist in the same file (I guess that we do not need to check tuples uniqueness across multiple files) > > Heck, what does a "constraint" mean? A constraint to be met by the caller of the function (e.g. passing a valid pointer when the function is missing checks on the validity of it, invoking a function with a certain mutex locked, avoiding certain ranges of input parameters ) > > > > And what defines an "id"? I see in your example you use number.number, > > > but is that specified? > > > > I thought that there is no need to specify an ID format as long as the ID is > > unique and referenced by the kunit tests testing the symbol. > > Basically I thought that in some cases it is easier to enumerate 1, 2, 3, > > whereas in others a, b, c can be used or even a mix 1a, 1b, 2a, 2b etc. > > So I wanted to leave such freedom to the programmer. > > Ok, so be aware that people will then put whatever they want in there, > making it impossible for you to parse :( Once we have a check on the uniqueness of the tuples within a single file, we can add another check when building kunit tests that look-up identifiers documented in the test headers to match the tuples from the source code being tested. So for example in patch 5 we have: [...] +/** + * read_mem_zero_count_test - Verify behavior when @count is 0 + * @test: KUnit test context. + * + * Confirms that read_mem() correctly handles a zero-length read. + * Per POSIX semantics, this may either return 0 or return an error + * if parameter validation is performed. + * + * Expected test behavior: + * - the input @buf user space buffer is not written; + * - @ppos is not modified; + * - 0 or -EFAULT is returned. + * + * Tested behavior: + * [read_mem.1] + */ [...] This means that this test is testing "[read_mem behavior] [1]". Having said that, technically this policy allows for very human unfriendly itemized lists, but I hope developers' common sense and the maintainers' judgement to be sufficient for this not to happen. > > > > And how is a id going to stay in sync across different files? That > > > feels impossible to maintain for any length of time, and puts a burden > > > on the developer who wishes to add/remove a test or "id", AND a > > > maintainer who has to remember to go and look in multiple places for > > > such an id sync up. > > > > Well given that the tested ids are defined by the tuples mentioned above, > > the relation between a kunit test and the tested tuples should be not > > ambiguous. > > How do I "know" that there is a test that matches the tuple at all? As mentioned above the test cases descriptors define the tuples that are tested. So using a tool like BASIL or StrictDoc it is possible to generate a graph tracing tests to the corresponding tuples > Your patch series proves this, it adds the tuple in one, and then the > test in another. If you add another patch that adds another comment, > how do I as a maintainer know if this refers to an existing test, or a > new one somewhere else? I would say - If the patch is modifying the text of an existing tuple the maintainer would directly see it and, by using a traceability tool, he would know the impacted tests - if the patch is adding a new tuple by definition it is a new behavior or constraints (so the gap will be identified by the lack of tests tracing to it) - if the patch adds a comment that is outside the list of tuples, such a change must be reviewed by the maintainer to figure out if the comment is appropriate as an informative note or if instead should be part of either lists (probably if there is also a code change it is more likely that the behaviors and constraints of use must be updated) > > > Also I thought that, when writing a kunit test, the tester should know which > > behavior is being tested and hence it should be easy to define the tested > > tuples in the kunit header. > > So I do not see much of a burden, but maybe I am missing something here... > > if there is no automatic way of linking a comment to a test, the ids > WILL get out of sync. We have 20+ years of history for "simple" things > like enums and strings getting out of sync in the same exact file. > Whenever you are going to allow a free-form structure like this, and yet > expect a maintainer and developer to always know how to keep it in sync, > that's just an impossible task, please do not do that. Got it, so I wonder if the extra checks I mentioned above WRT kdoc_parser.py and the kunit build process together with the traceability tool (BASIL or StrictDoc or others) would help to address this issue... > > And let's go back to the root issue, why have an id at all? Who > benefits from this? Who requires it? Who wants it? Who will do the > work to add/maintain/update them all? Ok, here I assume that we agree on the value of having function specifications and kunit tests. So I guess that the key question is why adding traceability provides value. To this point traceability makes it easier to understand the test cases against specifications, allows to spot specifications that are lacking tests and allows to easily spot tests that require modifications following a specifications' update. If you do not see value in traceability for /dev/mem I can drop patch 1 and just re-submit using simple bullets and removing the tuples references from the kunit tests, otherwise I could work on the implementation of the checkers mentioned above when building kernel-doc and kunits so that it would be easier for a maintainer to manage such a traceability.... Thanks and regards Gab > > thanks, > > greg k-h > On Thu, Feb 12, 2026 at 4:23 PM Greg KH <[email protected]> wrote: > > On Thu, Feb 12, 2026 at 03:00:01PM +0100, Gabriele Paoloni wrote: > > On Thu, Feb 12, 2026 at 1:59 PM Greg KH <[email protected]> wrote: > > > > > > On Thu, Feb 12, 2026 at 01:49:18PM +0100, Gabriele Paoloni wrote: > > > > Extend the longer description section of a function kernel-doc > > > > header with an itemised list of function's behaviors and > > > > constraints of use. > > > > These are useful to link and trace test cases (e.g. KUnit) to > > > > the different behavior IDs and define the constraints to be > > > > met by the function's caller. > > > > > > > > Signed-off-by: Gabriele Paoloni <[email protected]> > > > > --- > > > > Documentation/doc-guide/kernel-doc.rst | 19 +++++++++++++++++++ > > > > 1 file changed, 19 insertions(+) > > > > > > > > diff --git a/Documentation/doc-guide/kernel-doc.rst > > > > b/Documentation/doc-guide/kernel-doc.rst > > > > index 8d2c09fb36e4..23e6c4b45b14 100644 > > > > --- a/Documentation/doc-guide/kernel-doc.rst > > > > +++ b/Documentation/doc-guide/kernel-doc.rst > > > > @@ -83,6 +83,25 @@ The general format of a function and function-like > > > > macro kernel-doc comment is:: > > > > * > > > > * The longer description may have multiple paragraphs. > > > > * > > > > + * When specifying testable code behaviour the longer description > > > > must contain > > > > + * a paragraph formatted as follows: > > > > + * > > > > + * function_name behavior: > > > > + * [ID1] - [expected behavior] > > > > + * > > > > + * [ID2] - [expected behavior] > > > > + * > > > > + * [...] > > > > + * > > > > + * [IDn] - [expected behavior] > > > > + * > > > > + * function_name constraints of use: > > > > + * [ID1] - [constraint to be met by the caller] > > > > + * > > > > + * [ID2] - [constraint to be met by the caller] > > > > + * > > > > + * [IDn] - [constraint to be met by the caller] > > > > > > So the same "id" is used for a behavior, AND a constraint? > > > > The idea is to have a specific behaviour or constraint of use > > identified by the tuple [function_name behavior][ID]. > > So I think we could have a problem for duplicated symbols (but > > it is a sort of corner case...) > > I am trying to say that you have ID1 listed in two places above. So > that's not unique with a [function_name][ID] pair, where does the > "behavior" part come in? > > What is now parsing these comments to ensure that they are unique, in > correct order, and are used elsewhere? What is the text for such a > behavior and constraint? > > Heck, what does a "constraint" mean? > > > > And what defines an "id"? I see in your example you use number.number, > > > but is that specified? > > > > I thought that there is no need to specify an ID format as long as the ID is > > unique and referenced by the kunit tests testing the symbol. > > Basically I thought that in some cases it is easier to enumerate 1, 2, 3, > > whereas in others a, b, c can be used or even a mix 1a, 1b, 2a, 2b etc. > > So I wanted to leave such freedom to the programmer. > > Ok, so be aware that people will then put whatever they want in there, > making it impossible for you to parse :( > > > > And how is a id going to stay in sync across different files? That > > > feels impossible to maintain for any length of time, and puts a burden > > > on the developer who wishes to add/remove a test or "id", AND a > > > maintainer who has to remember to go and look in multiple places for > > > such an id sync up. > > > > Well given that the tested ids are defined by the tuples mentioned above, > > the relation between a kunit test and the tested tuples should be not > > ambiguous. > > How do I "know" that there is a test that matches the tuple at all? > Your patch series proves this, it adds the tuple in one, and then the > test in another. If you add another patch that adds another comment, > how do I as a maintainer know if this refers to an existing test, or a > new one somewhere else? > > > Also I thought that, when writing a kunit test, the tester should know which > > behavior is being tested and hence it should be easy to define the tested > > tuples in the kunit header. > > So I do not see much of a burden, but maybe I am missing something here... > > if there is no automatic way of linking a comment to a test, the ids > WILL get out of sync. We have 20+ years of history for "simple" things > like enums and strings getting out of sync in the same exact file. > Whenever you are going to allow a free-form structure like this, and yet > expect a maintainer and developer to always know how to keep it in sync, > that's just an impossible task, please do not do that. > > And let's go back to the root issue, why have an id at all? Who > benefits from this? Who requires it? Who wants it? Who will do the > work to add/maintain/update them all? > > thanks, > > greg k-h >
