Re: [PATCH v2] Documentation: Update after split of <linux/mod_devicetable.h>

[Randy Dunlap]

Hi,

On 7/6/26 8:01 AM, Uwe Kleine-König (The Capable Hub) wrote:
> Most structs that were defined in <linux/mod_devicetable.h> before were
> moved to a bus specific header. Follow the movement to get the struct's
> documenation back.
> 
> For the list of device ids in basic.rst use an explict list of all the

                                basics.rst

> headers that have kernel-doc annotations and that are not described
> elsewhere (i.e. pci and mei_cl).
> 
> Also repair the referencing in the zh_CN translation of pci.rst and
> don't duplicate `struct mei_cl_device_id`.
> 
> Fixes: ad428f5811bd ("mod_devicetable.h: Split into per subsystem headers")
> Signed-off-by: Uwe Kleine-König (The Capable Hub) <u.kleine-koenig@xxxxxxxxxxxx>
> ---
> Hello,
> 
> the explicit list is a bit ugly, but I don't have a better idea.
> 
> If you're happy with the patch, can Linus and Jonathan please agree on how this
> is applied?
> 
> Best regards
> Uwe
> 
>  Documentation/PCI/pci.rst                     |  2 +-
>  Documentation/driver-api/basics.rst           | 31 +++++++++++++++++--
>  .../driver-api/mei/mei-client-bus.rst         | 12 ++-----
>  Documentation/pcmcia/driver.rst               |  2 +-
>  Documentation/staging/rpmsg.rst               |  2 +-
>  Documentation/translations/zh_CN/PCI/pci.rst  |  8 ++---
>  6 files changed, 39 insertions(+), 18 deletions(-)
> 
> diff --git a/Documentation/PCI/pci.rst b/Documentation/PCI/pci.rst
> index be35e9a1ee75..71c42b0bfa8b 100644
> --- a/Documentation/PCI/pci.rst
> +++ b/Documentation/PCI/pci.rst
> @@ -84,7 +84,7 @@ initialization with a pointer to a structure describing the driver
>  The ID table is an array of ``struct pci_device_id`` entries ending with an
>  all-zero entry.  Definitions with static const are generally preferred.
>  
> -.. kernel-doc:: include/linux/mod_devicetable.h
> +.. kernel-doc:: include/linux/device-id/pci.h
>     :functions: pci_device_id
>  
>  Most drivers only need ``PCI_DEVICE()`` or ``PCI_DEVICE_CLASS()`` to set up
> diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
> index 8b6a5888cb11..647e14254cfb 100644
> --- a/Documentation/driver-api/basics.rst
> +++ b/Documentation/driver-api/basics.rst
> @@ -10,9 +10,36 @@ Driver Entry and Exit points
>  Driver device table
>  -------------------
>  
> -.. kernel-doc:: include/linux/mod_devicetable.h
> +.. kernel-doc:: include/linux/device-id/amba.h
> +   :internal:
> +.. kernel-doc:: include/linux/device-id/cdx.h
> +   :internal:
> +.. kernel-doc:: include/linux/device-id/coreboot.h
> +   :internal:
> +.. kernel-doc:: include/linux/device-id/dfl.h
> +   :internal:
> +.. kernel-doc:: include/linux/device-id/fsl_mc.h
> +   :internal:
> +.. kernel-doc:: include/linux/device-id/ishtp.h
> +   :internal:
> +.. kernel-doc:: include/linux/device-id/mdio.h
> +   :internal:
> +.. kernel-doc:: include/linux/device-id/mhi.h
> +   :internal:
> +.. kernel-doc:: include/linux/device-id/mips_cdmm.h
> +   :internal:
> +.. kernel-doc:: include/linux/device-id/rio.h
> +   :internal:
> +.. kernel-doc:: include/linux/device-id/tb.h
> +   :internal:
> +.. kernel-doc:: include/linux/device-id/tee_client.h
> +   :internal:
> +.. kernel-doc:: include/linux/device-id/typec.h
> +   :internal:
> +.. kernel-doc:: include/linux/device-id/usb.h
> +   :internal:
> +.. kernel-doc:: include/linux/device-id/wmi.h
>     :internal:
> -   :no-identifiers: pci_device_id
>  

LGTM. Thanks.
(see nits below)

>  
>  Delaying and scheduling routines
> diff --git a/Documentation/driver-api/mei/mei-client-bus.rst b/Documentation/driver-api/mei/mei-client-bus.rst
> index f242b3f8d6aa..d46c0d0b3540 100644
> --- a/Documentation/driver-api/mei/mei-client-bus.rst
> +++ b/Documentation/driver-api/mei/mei-client-bus.rst
> @@ -41,17 +41,11 @@ the ``struct mei_cl_driver`` structure defined in :file:`include/linux/mei_cl_bu
>  

Would be nice to add kernel-doc comments in <linux/mei_cl_bus.h>
and then include those here instead of duplicating the struct.
(for mei_cl_driver)
>  
>  
> -The mei_cl_device_id structure defined in :file:`include/linux/mod_devicetable.h` allows a
> +The mei_cl_device_id structure defined in :file:`include/linux/device-id/mei_cl.h` allows a
>  driver to bind itself against a device name.
>  
> -.. code-block:: C
> -
> -        struct mei_cl_device_id {
> -                char name[MEI_CL_NAME_SIZE];
> -                uuid_le uuid;
> -                __u8    version;
> -                kernel_ulong_t driver_info;
> -        };
> +.. kernel-doc:: include/linux/device-id/mei_cl.h
> +   :functions: mei_cl_device_id
>  
>  To actually register a driver on the ME Client bus one must call the :c:func:`mei_cl_add_driver`
>  API. This is typically called at module initialization time.
> diff --git a/Documentation/pcmcia/driver.rst b/Documentation/pcmcia/driver.rst
> index 5c4fe84d51c1..b91e5c14cb87 100644
> --- a/Documentation/pcmcia/driver.rst
> +++ b/Documentation/pcmcia/driver.rst
> @@ -15,7 +15,7 @@ runtime as shown below::
>  All fields are passed in as hexadecimal values (no leading 0x).
>  The meaning is described in the PCMCIA specification, the match_flags is
>  a bitwise or-ed combination from PCMCIA_DEV_ID_MATCH_* constants
> -defined in include/linux/mod_devicetable.h.
> +defined in include/linux/device-id/pcmcia.h.

It would look a little nicer (IMO) and be more consistent to use:
   defined in file:`include/linux/device_id/pcmcia.h`.
>  
>  Once added, the driver probe routine will be invoked for any unclaimed
>  PCMCIA device listed in its (newly updated) pcmcia_device_id list.

Reviewed-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>

-- 
~Randy