Re: [PATCH v2] ACPI: device-id: document struct acpi_device_id

[Rafael J. Wysocki (Intel)]

On Fri, Oct 2, 2026 at 4:47 PM Miguel Garcia via B4 Relay
<devnull+miguelgarciaroman8.gmail.com@xxxxxxxxxx> wrote:
>
> From: Miguel Garcia <miguelgarciaroman8@xxxxxxxxx>
>
> struct acpi_device_id lacks kernel-doc, so extracting documentation from
> its header describes ACPI_DEVICE_CLASS() but not the matching table entry.
>
> Document the four members, ID and class-code matching, and the table
> terminator. This complements the documentation header-split work
> without changing its include directives.
>
> Link: https://lore.kernel.org/all/aqEWUBf1pewPP_K2@monoceros/
> Assisted-by: LLM
> Signed-off-by: Miguel Garcia <miguelgarciaroman8@xxxxxxxxx>
> ---
> Changes in v2:
> - Use ACPI_DEVICE_CLASS() in the commit message, as requested by Andy.
> - Move the drafting and validation notes below the commit message.
> - Describe the related header-split work without assuming its status.
> - No change to the source diff.
>
> v1: https://lore.kernel.org/r/20260913095111.2543502-1-miguelgarciaroman8@xxxxxxxxx/
>
> An LLM drafted this comment and changelog after being asked to address
> the missing documentation noted in the header-split discussion. The
> field descriptions were checked against the ACPI matching code. The
> extracted documentation passes kernel-doc and a focused Sphinx HTML
> build with warnings treated as errors; checkpatch reports no warnings.
>
>  include/linux/device-id/acpi.h | 10 ++++++++++
>  1 file changed, 10 insertions(+)
>
> diff --git a/include/linux/device-id/acpi.h b/include/linux/device-id/acpi.h
> index 65800cefd..8c3b30ebf 100644
> --- a/include/linux/device-id/acpi.h
> +++ b/include/linux/device-id/acpi.h
> @@ -9,6 +9,16 @@ typedef unsigned long kernel_ulong_t;
>
>  #define ACPI_ID_LEN    16
>
> +/**
> + * struct acpi_device_id - ACPI device matching table entry
> + * @id: NUL-terminated hardware ID (_HID) or compatible ID (_CID) to match.

This should be

+ * @id: NUL-terminated ACPI or PNP device ID (as defined by the ACPI
specification) to match.

> + * @driver_data: Data private to the driver.
> + * @cls: PCI-defined class, subclass and programming interface code (_CLS).
> + * @cls_msk: Mask selecting the class-code fields to match.
> + *
> + * Use @id for ID matching or ACPI_DEVICE_CLASS() for class-code matching.

I would say here

"Either @id is used for device ID matching, or @cls along with
@cls_mask is used for class-code matching via ACPI_DEVICE_CLASS()."

> + * Terminate the table with an entry whose @id is empty and @cls is zero.

s/is empty/represents an empty string/

> + */
>  struct acpi_device_id {
>         __u8 id[ACPI_ID_LEN];
>         kernel_ulong_t driver_data;
> --