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

Aditya yashsri421 at gmail.com
Thu Feb 11 08:02:20 UTC 2021


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.

Thanks
Aditya


More information about the Linux-kernel-mentees mailing list