Re: [PATCH v4 11/19] liveupdate: Add feature header to struct luo_file_set_ser

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 1 potential
issue to consider:
- [Low] liveupdate: DECLARE_KHO_SER_HDR() mangles kernel-doc in
  luo_file.c
--

commit 56a2b87048122363acff436905ac6fad2da6e4c3
Author: Tarun Sahu <tarunsahu@google.com>

liveupdate: Add feature header to struct luo_file_set_ser

This commit precedes struct luo_file_set_ser with struct kho_ser_hdr via
DECLARE_KHO_SER and updates the file-set freeze, unfreeze, and
deserialization routines to initialize and validate the feature header.

> diff --git a/kernel/liveupdate/luo_file.c b/kernel/liveupdate/luo_file.c
> index a39992da504fb..02d09a80d7852 100644
> --- a/kernel/liveupdate/luo_file.c
> +++ b/kernel/liveupdate/luo_file.c
> @@ -440,8 +440,8 @@ static void __luo_file_unfreeze(struct luo_file_set *file_set,
>  
>  /**
>   * luo_file_freeze - Freezes all preserved files and serializes their metadata.
> - * @file_set:     The file_set whose files are to be frozen.
> - * @file_set_ser: Where to put the serialized file_set.
> + * @file_set:      The file_set whose files are to be frozen.
> + * @file_set_fhdr: Where to put the serialized file_set.
>   *
>   * This function is called from the reboot() syscall path, just before the
>   * kernel transitions to the new image via kexec. Its purpose is to perform the
> @@ -472,12 +472,14 @@ static void __luo_file_unfreeze(struct luo_file_set *file_set,
>   * Return: 0 on success, or a negative errno on failure.
>   */
>  int luo_file_freeze(struct luo_file_set *file_set,
> -		    struct luo_file_set_ser *file_set_ser)
> +		    DECLARE_KHO_SER_HDR(luo_file_set_ser, *file_set_fhdr))

[Severity: Low]
Does using DECLARE_KHO_SER_HDR() in documented function prototypes break
kernel-doc output when building htmldocs?

Documentation/core-api/liveupdate.rst includes kernel/liveupdate/luo_file.c
with :internal:, which processes luo_file_freeze(), luo_file_unfreeze(), and
luo_file_deserialize().  Unlike DECLARE_KHOSER_PTR(), DECLARE_KHO_SER_HDR()
has no CMatch transform in tools/lib/python/kdoc/xforms_lists.py.  When
create_parameter_list() in tools/lib/python/kdoc/kdoc_parser.py splits the
parameter list, it replaces the comma inside the macro with '#' and never
restores it, emitting invalid C syntax in Sphinx:

  .. c:function:: int luo_file_freeze (struct luo_file_set *file_set, DECLARE_KHO_SER_HDR(luo_file_set_ser# *file_set_fhdr))

Adding a CMatch("DECLARE_KHO_SER_HDR") rule in
tools/lib/python/kdoc/xforms_lists.py alongside DECLARE_KHOSER_PTR would
let kernel-doc expand the macro cleanly.

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261110050202.529473-1-tarunsahu@google.com?part=11