[Linux-kernel-mentees] Investigating ./scripts/kernel-doc for third phase of mentorship

Lukas Bulwahn lukas.bulwahn at gmail.com
Thu Feb 11 10:43:36 UTC 2021


On Thu, Feb 11, 2021 at 9:02 AM Aditya <yashsri421 at gmail.com> wrote:
>
> On 9/2/21 10:31 pm, Aditya wrote:
> > On 9/2/21 9:43 am, Lukas Bulwahn wrote:
> >> Hi Aditya,
> >>
> >>
> >> I have been using ./scripts/kernel-doc lately and noticed a few issues
> >> with this script.
> >> For the third phase, I expect you to investigate the issues on
> >> ./scripts/kernel-doc below, describe the issue to the kernel-doc
> >> maintainer, and work on proper support for this parser in kernel-doc.
> >>
> >> When running kernel-doc on these files below, you should observe these errors:
> >>
> >> ./scripts/kernel-doc -none kernel/gcov/gcc_4_7.c
> >>
> >> Use of uninitialized value $param in regexp compilation at
> >> ./scripts/kernel-doc line 1559, <IN_FILE> line 95.
> >> Use of uninitialized value $actual in substitution (s///) at
> >> ./scripts/kernel-doc line 1523, <IN_FILE> line 95.
> >> Use of uninitialized value $actual in substitution (s///) at
> >> ./scripts/kernel-doc line 1523, <IN_FILE> line 95.
> >> Use of uninitialized value $param in substitution (s///) at
> >> ./scripts/kernel-doc line 1617, <IN_FILE> line 95.
> >> Use of uninitialized value $param in hash element at
> >> ./scripts/kernel-doc line 1651, <IN_FILE> line 95.
> >> Use of uninitialized value $param in pattern match (m//) at
> >> ./scripts/kernel-doc line 1651, <IN_FILE> line 95.
> >> Use of uninitialized value $param in hash element at
> >> ./scripts/kernel-doc line 1652, <IN_FILE> line 95.
> >> Use of uninitialized value $param in pattern match (m//) at
> >> ./scripts/kernel-doc line 1654, <IN_FILE> line 95.
> >> Use of uninitialized value $param in concatenation (.) or string at
> >> ./scripts/kernel-doc line 1655, <IN_FILE> line 95.
> >> Use of uninitialized value $param in hash element at
> >> ./scripts/kernel-doc line 1672, <IN_FILE> line 95.
> >>
> >>
> >> ./scripts/kernel-doc -none include/linux/zstd.h
> >>
> >> include/linux/zstd.h:153: error: Cannot parse struct or union!
> >> include/linux/zstd.h:170: error: Cannot parse struct or union!
> >> include/linux/zstd.h:180: error: Cannot parse struct or union!
> >> include/linux/zstd.h:230: error: Cannot parse struct or union!
> >> include/linux/zstd.h:273: error: Cannot parse struct or union!
> >> include/linux/zstd.h:365: error: Cannot parse struct or union!
> >>
> >> include/linux/zstd.h:421: error: Cannot parse struct or union!
> >>
> >> include/linux/zstd.h:537: error: Cannot parse struct or union!
> >> include/linux/zstd.h:682: error: Cannot parse struct or union!
> >>
> >> include/linux/zstd.h:935: error: Cannot parse struct or union!
> >>
> >> Can you reproduce these issues?
> >>>>
> >> Further, I would see that you can create two new features for kernel-doc:
> >>
> >> - Support for warning types and configuration of build warning flags,
> >> i.e., with -W command-line arguments and output as known for compilers
> >> - Support of default arguments
> >>
> >> Let us start with investigation of those issues in the files, though.
> >> Then, we see how complicated it is to resolve those and discuss that
> >> with the maintainer.
> >>
> >>
> >
> > Alright Lukas. Sounds interesting. I'll get back to you with my findings.
> >
>
> Hi Lukas
>
> I was able to reproduce the issues. In my investigation I found the
> following to be the cause of this:
>
> - For scripts/kernel-doc -none kernel/gcov/gcc_4_7.c :-
> Cause:
> struct gcov_info is a structure in this file, which has a parameter:
> void (*merge[GCOV_COUNTERS])(gcov_type *, unsigned int)
>
> This argument goes to the elsif condition for argument parsing "elsif
> ($arg =~ m/\(.+\)\s*\(/)"
> But the regex match at Line 1556 ($arg =~
> m/[^\(]+\(\*?\s*([\w\.]*)\s*\)/;) is not able to capture the $param.
>
> In my investigation, I found that it was expected to capture
> "*merge[GCOV_COUNTERS]" as $param. But the regex does not take into
> account the presence of square brackets("["."]"). As a result, the
> $param capture does not happen as expected.
> As $param remains undefined in this case, it causes the above error to
> occur.
>
> - For scripts/kernel-doc -none include/linux/zstd.h :-
> Cause: Certain struct definitions present in the file do not follow
> the expected format for parsing.
> For eg. for "struct ZSTD_compressionParameters", it is defined with
> the help of typedef syntax, ie
> typedef struct {
>         unsigned int windowLog;
>         unsigned int chainLog;
>         unsigned int hashLog;
>         unsigned int searchLog;
>         unsigned int searchLength;
>         unsigned int targetLength;
>         ZSTD_strategy strategy;
> } ZSTD_compressionParameters;
>
> Here, the definition might be compiler error free, but for kernel-doc
> parsing, the definition was probably supposed to go like:
>
> typedef struct ZSTD_compressionParameters {
>         unsigned int windowLog;
>         unsigned int chainLog;
>         unsigned int hashLog;
>         unsigned int searchLog;
>         unsigned int searchLength;
>         unsigned int targetLength;
>         ZSTD_strategy strategy;
> } ZSTD_compressionParameters;
>
> OR
>
> struct ZSTD_compressionParameters {
>         unsigned int windowLog;
>         unsigned int chainLog;
>         unsigned int hashLog;
>         unsigned int searchLog;
>         unsigned int searchLength;
>         unsigned int targetLength;
>         ZSTD_strategy strategy;
> };
>
> The parser probably expects struct struct_name to occur together,
> causing the above error.
>

Good initial analysis. Do you want to extend those patterns, such that
these definitions are properly parsed as well?

Then, we should check if we observe any other difference (caused any
regression) running kernel-doc on the complete tree.

Lukas


More information about the Linux-kernel-mentees mailing list