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

Aditya yashsri421 at gmail.com
Thu Feb 11 11:16:47 UTC 2021


On 11/2/21 4:13 pm, Lukas Bulwahn wrote:
> 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.
> 

Sounds good. I'll be back with the report.

Thanks
Aditya


More information about the Linux-kernel-mentees mailing list