Re: [PATCH v4 07/19] kho: vmalloc: Add the feature header

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 1 potential
issue to consider:
- [Low] kho: missing DECLARE_KHO_SER_HDR() kdoc transform breaks
  kernel-doc
--

commit 5eeff1f169bf967112c6cc25130cc4d0e9b8a838
Author: Tarun Sahu <tarunsahu@google.com>

kho: vmalloc: Add the feature header

This commit registers struct kho_vmalloc with the KHO serialization feature
header mechanism and updates kho_preserve_vmalloc(), kho_unpreserve_vmalloc(),
kho_restore_vmalloc(), and their callers to pass typed feature header
pointers.

> diff --git a/include/linux/kho/abi/memfd.h b/include/linux/kho/abi/memfd.h
> index 7b49dd6d7e2af..b0597c4389732 100644
> --- a/include/linux/kho/abi/memfd.h
> +++ b/include/linux/kho/abi/memfd.h
> @@ -80,9 +80,9 @@ static_assert(!IS_ENABLED(CONFIG_64BIT) ||
>   * @seals:     The seals present on the memfd. The seals are uABI so it is safe
>   *             to directly use them in the ABI.
>   * @flags:     Flags for the file. Unused flag bits must be set to 0.
> - * @nr_folios: Number of folios in the folios array.
> - * @folios:    Pointer to KHO vmalloc descriptor for the array of
> - *             struct memfd_luo_folio_ser.
> + * @nr_folios:   Number of folios in the folios array.
> + * @folios_fhdr: Pointer to KHO vmalloc descriptor for the array of
> + *               struct memfd_luo_folio_ser.
>   */
>  struct memfd_luo_ser {
>  	u64 pos;
> @@ -90,7 +90,7 @@ struct memfd_luo_ser {
>  	u32 seals;
>  	u32 flags;
>  	u64 nr_folios;
> -	DECLARE_KHOSER_PTR(folios, struct kho_vmalloc *);
> +	DECLARE_KHOSER_PTR(folios_fhdr, DECLARE_KHO_SER_HDR(kho_vmalloc, *));
>  };
>  
>  static_assert(sizeof(struct memfd_luo_ser) == 40);
> diff --git a/kernel/liveupdate/kexec_handover.c b/kernel/liveupdate/kexec_handover.c
> index 369ce411928d3..919210d7a91ab 100644
> --- a/kernel/liveupdate/kexec_handover.c
> +++ b/kernel/liveupdate/kexec_handover.c
> @@ -1382,20 +1382,20 @@ static void kho_vmalloc_unpreserve_chunk(struct kho_vmalloc_chunk *chunk,
>  /**
>   * kho_preserve_vmalloc - preserve memory allocated with vmalloc() across kexec
>   * @ptr: pointer to the area in vmalloc address space
> - * @preservation: placeholder for preservation metadata
> + * @fhdr:         placeholder for preservation metadata
>   *
>   * Instructs KHO to preserve the area in vmalloc address space at @ptr. The
>   * physical pages mapped at @ptr will be preserved and on successful return
> - * @preservation will hold the physical address of a structure that describes
> - * the preservation.
> + * @fhdr will hold the preservation metadata.
>   *
>   * NOTE: The memory allocated with vmalloc_node() variants cannot be reliably
>   * restored on the same node
>   *
>   * Return: 0 on success, error code on failure
>   */
> -int kho_preserve_vmalloc(void *ptr, struct kho_vmalloc *preservation)
> +int kho_preserve_vmalloc(void *ptr, DECLARE_KHO_SER_HDR(kho_vmalloc, *fhdr))

[Severity: Low]
Does using DECLARE_KHO_SER_HDR() here and in kho_unpreserve_vmalloc(),
kho_restore_vmalloc(), and struct memfd_luo_ser break kernel-doc without a
matching CTransforms rule in tools/lib/python/kdoc/xforms_lists.py?

In kernel/liveupdate/kexec_handover.c, KernelDoc.create_parameter_list()
replaces the comma inside DECLARE_KHO_SER_HDR(kho_vmalloc, *fhdr) with '#'
and parses the parameter name as "fhdr)", causing W=1 builds and make
htmldocs to warn about undescribed parameter "fhdr)" and excess parameter
"fhdr" while emitting malformed ReST c:function directives.  In
include/linux/kho/abi/memfd.h, CTokenArgs.groups() splits the outer
DECLARE_KHOSER_PTR() on the inner comma of DECLARE_KHO_SER_HDR(), truncating
the struct member in the generated documentation to
"DECLARE_KHO_SER_HDR(kho_vmalloc folios_fhdr;".

Adding (CMatch("DECLARE_KHO_SER_HDR"), r"struct kho_ser_hdr \2") to
CTransforms.struct_xforms (before DECLARE_KHOSER_PTR) and
CTransforms.function_xforms in tools/lib/python/kdoc/xforms_lists.py would
avoid both issues.

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