[Linux-kernel-mentees] Investigating parsing error for struct/union

Randy Dunlap rdunlap at infradead.org
Mon Feb 22 21:37:16 UTC 2021


On 2/22/21 9:27 AM, Aditya wrote:
> Hi Jonathan, Lukas
> 
> While investigating "error: Cannot parse struct or union!", I
> discovered few more patterns causing this error:
> 1) A large part of this error(~80%) occurs due to the presence of one
> or more lines(such as '#define' lines) between commented code and
> struct declaration.
> 
> For e.g., in include/linux/platform_data/apds990x.h:
> 
> /**
>  * struct apds990x_chip_factors - defines effect of the cover window
>  * @ga: Total glass attenuation
>  * @cf1: clear channel factor 1 for raw to lux conversion
>  * @irf1: IR channel factor 1 for raw to lux conversion
>  * @cf2: clear channel factor 2 for raw to lux conversion
>  * @irf2: IR channel factor 2 for raw to lux conversion
>  * @df: device factor for conversion formulas
>  *
>  * Structure for tuning ALS calculation to match with environment.
>  * Values depend on the material above the sensor and the sensor
>  * itself. If the GA is zero, driver will use uncovered sensor default
> values
>  * format: decimal value * APDS_PARAM_SCALE except df which is plain
> integer.
>  */
> #define APDS_PARAM_SCALE 4096
> struct apds990x_chip_factors {
> 	int ga;
> 	int cf1;
> 	int irf1;
> 	int cf2;
> 	int irf2;
> 	int df;
> };

I have been known to move a few of macros such as this one.
OTOH, if you can coax kernel-doc to skip macros and find a
struct/union/function, that would be OK IMO.

> 
> 
> 2) If struct does not contain any members, for e.g., in
> include/linux/xz.h:
> 
> /**
>  * struct xz_dec - Opaque type to hold the XZ decoder state
>  */
> struct xz_dec;
> 
> Here, it causes error as the curly braces and members expected by the
> regex, are absent.

I.e., there is no kernel-doc description there at all.

Then in lib/xz/xz_dec_stream.c, the struct is defined with no
kernel-doc at all.

IMO the struct in lib/xz/xz_dec_stream.c should be marked as
kernel-doc and then all of the fields in it marked as
  /* private: */
since the author(s) seem to want this struct to be private/opaque.

> This kind of use has also been made in include/linux/zstd.h:
> 
> /**
>  * struct ZSTD_DDict - a digested dictionary to be used for decompression
>  */
> typedef struct ZSTD_DDict_s ZSTD_DDict;
> 
> 
> 3) Different Syntax than expected. For e.g.:
>     a) struct xyz struct_name {} syntax. This syntax has been used in
> arch/arm/mach-omap2/omap_hwmod_common_data.c file
>     b) "static __maybe_unused const struct st_sensors_platform_data
> default_press_pdata = {" in drivers/iio/pressure/st_pressure.h.
> This kind of syntax has also been used in
> drivers/iio/accel/st_accel.h, and drivers/iio/gyro/st_gyro.h

kernel-doc should just ignore/skip/drop __maybe_unused.

> 
> I wanted to take your opinion if we should extend support for any of
> these syntax, causing the error. If not, perhaps we can make the
> documentation a bit clear, atleast for (1), which causes most of these
> errors; so as to not include any lines between comment and struct
> declaration.
> 
> What do you think?


-- 
~Randy



More information about the Linux-kernel-mentees mailing list