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)
> <[email protected]>
> ---
> 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 <[email protected]>
Tested-by: Randy Dunlap <[email protected]>
--
~Randy
