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

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

[Karl Mehltretter]

From: Uwe Kleine-König (The Capable Hub) <u.kleine-koenig@baylibre.com>

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
documentation back.

For the list of device ids in basics.rst use an explicit list of all the
headers that have kernel-doc annotations and that are not described
elsewhere (i.e. pci and mei_cl). <linux/device-id/acpi.h> is left out on
purpose, ACPI_DEVICE_CLASS() is not a device id struct.

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@baylibre.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
[Karl Mehltretter: use the :file: role in pcmcia/driver.rst, say why
 acpi.h is left out]
Assisted-by: LLM
Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>
---
Changes since v2
  https://lore.kernel.org/r/ede7ce64f20e10660ebf6bc1b41836dad750ae3b.1783349758.git.ukleinek@kernel.org/
- use the :file: role for the header path in pcmcia/driver.rst (Randy)
- say in the commit message that <linux/device-id/acpi.h> is left out on
  purpose (question raised by the Sashiko review)
- carried Randy's Reviewed-by and Tested-by from v2, the diff changed in
  one line of markup only
- Uwe asked me to take over the patch:
  https://lore.kernel.org/r/apv6yQ1U-HhNglyV@monoceros/
  It supersedes my PCI-only patch
  https://lore.kernel.org/r/20260905084916.40196-1-kmehltretter@gmail.com/

Randy's suggestion to add kernel-doc comments to <linux/mei_cl_bus.h> for
struct mei_cl_driver and include those instead of the duplicated struct is
left for a separate patch, it touches a header outside Documentation/.

 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 3b182cfdf135..84f701b84e4f 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
 
 
 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
 
 
 
-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..0b6370c1d525 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 :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.
diff --git a/Documentation/staging/rpmsg.rst b/Documentation/staging/rpmsg.rst
index 63612b7ee120..ea0eb1981124 100644
--- a/Documentation/staging/rpmsg.rst
+++ b/Documentation/staging/rpmsg.rst
@@ -224,7 +224,7 @@ content to the console.
 ::
 
   #include <linux/dev_printk.h>
-  #include <linux/mod_devicetable.h>
+  #include <linux/device-id/rpmsg.h>
   #include <linux/module.h>
   #include <linux/printk.h>
   #include <linux/rpmsg.h>
diff --git a/Documentation/translations/zh_CN/PCI/pci.rst b/Documentation/translations/zh_CN/PCI/pci.rst
index 347f5c3f5ce9..64372a16caf6 100644
--- a/Documentation/translations/zh_CN/PCI/pci.rst
+++ b/Documentation/translations/zh_CN/PCI/pci.rst
@@ -84,16 +84,16 @@ PCI设备驱动程序在初始化过程中调用 ``pci_register_driver()`` ，
 
 该API在以下内核代码中:
 
-include/linux/pci.h
-pci_driver
+.. kernel-doc:: include/linux/pci.h
+   :functions: pci_driver
 
 ID表是一个由 ``struct pci_device_id`` 结构体成员组成的数组，以一个全零的成员
 结束。一般来说，带有静态常数的定义是首选。
 
 该API在以下内核代码中:
 
-include/linux/mod_devicetable.h
-pci_device_id
+.. kernel-doc:: include/linux/device-id/pci.h
+   :functions: pci_device_id
 
 大多数驱动程序只需要 ``PCI_DEVICE()`` 或 ``PCI_DEVICE_CLASS()`` 来设置一个
 pci_device_id表。

base-commit: 986c24e0fe44f844b44d365b71ce831947f50298
-- 
2.53.0

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

[Andy Shevchenko]

On Tue, Sep 08, 2026 at 09:00:31AM +0200, Karl Mehltretter wrote:
> From: Uwe Kleine-König (The Capable Hub) <u.kleine-koenig@baylibre.com>
> 
> 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
> documentation back.
> 
> For the list of device ids in basics.rst use an explicit list of all the
> headers that have kernel-doc annotations and that are not described
> elsewhere (i.e. pci and mei_cl). <linux/device-id/acpi.h> is left out on
> purpose, ACPI_DEVICE_CLASS() is not a device id struct.

Huh?! The device-id/acpi.h provides the ACPI device ID definition.

> 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@baylibre.com>

...

> Changes since v2
>   https://lore.kernel.org/r/ede7ce64f20e10660ebf6bc1b41836dad750ae3b.1783349758.git.ukleinek@kernel.org/
> - use the :file: role for the header path in pcmcia/driver.rst (Randy)
> - say in the commit message that <linux/device-id/acpi.h> is left out on
>   purpose (question raised by the Sashiko review)

I am unsatisfied with how the ACPI division was handled in the above mentioned
split. Id est the include/device-id/acpi.h is *the* header that has to be used
for the IDs, not the respective "include all" linux/acpi.h.
Hence the documentation has to allow the use of the device-id/*.h directly in
the drivers (most of the cases for ACPI).

Alternatively the OF ID *and* ACPI ID must be included to the upper lever bus
headers. So, spi.h, i2c.h, platform_device.h and so on has to *always* provide
both.

> - carried Randy's Reviewed-by and Tested-by from v2, the diff changed in
>   one line of markup only
> - Uwe asked me to take over the patch:
>   https://lore.kernel.org/r/apv6yQ1U-HhNglyV@monoceros/
>   It supersedes my PCI-only patch
>   https://lore.kernel.org/r/20260905084916.40196-1-kmehltretter@gmail.com/
> 
> Randy's suggestion to add kernel-doc comments to <linux/mei_cl_bus.h> for
> struct mei_cl_driver and include those instead of the duplicated struct is
> left for a separate patch, it touches a header outside Documentation/.

Uwe, can you fix that?

-- 
With Best Regards,
Andy Shevchenko

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

[Uwe Kleine-König]

[-- Attachment #1: Type: text/plain, Size: 1258 bytes --]

Hello Karl,

On Tue, Sep 08, 2026 at 09:00:31AM +0200, Karl Mehltretter wrote:
> From: Uwe Kleine-König (The Capable Hub) <u.kleine-koenig@baylibre.com>
> 
> 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
> documentation back.
> 
> For the list of device ids in basics.rst use an explicit list of all the
> headers that have kernel-doc annotations and that are not described
> elsewhere (i.e. pci and mei_cl). <linux/device-id/acpi.h> is left out on
> purpose, ACPI_DEVICE_CLASS() is not a device id struct.
> 
> 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@baylibre.com>
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> Tested-by: Randy Dunlap <rdunlap@infradead.org>
> [Karl Mehltretter: use the :file: role in pcmcia/driver.rst, say why
>  acpi.h is left out]
> Assisted-by: LLM
> Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>

Thanks for picking that up, very appreciated!

Best regards
Uwe

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

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

[Uwe Kleine-König]

[-- Attachment #1: Type: text/plain, Size: 3522 bytes --]

Hello Andy,

On Tue, Sep 08, 2026 at 11:29:23AM +0300, Andy Shevchenko wrote:
> On Tue, Sep 08, 2026 at 09:00:31AM +0200, Karl Mehltretter wrote:
> > From: Uwe Kleine-König (The Capable Hub) <u.kleine-koenig@baylibre.com>
> > 
> > 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
> > documentation back.
> > 
> > For the list of device ids in basics.rst use an explicit list of all the
> > headers that have kernel-doc annotations and that are not described
> > elsewhere (i.e. pci and mei_cl). <linux/device-id/acpi.h> is left out on
> > purpose, ACPI_DEVICE_CLASS() is not a device id struct.
> 
> Huh?! The device-id/acpi.h provides the ACPI device ID definition.

<linux/device-id/acpi.h> provides both, struct acpi_device_id and the
macro ACPI_DEVICE_CLASS. The latter has a kdoc comment, the former
doesn't. So including <linux/device-id/acpi.h> in the patch makes
ACPI_DEVICE_CLASS appear in the list of device-id structs, but
acpi_device_id not.

So while this patch doesn't implement the optimum to get acpi_device_id
explicitly documented, but the purpose of the patch is to restore the
from before ad428f5811bd, which is accomplished.

> 
> > 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@baylibre.com>
> 
> ...
> 
> > Changes since v2
> >   https://lore.kernel.org/r/ede7ce64f20e10660ebf6bc1b41836dad750ae3b.1783349758.git.ukleinek@kernel.org/
> > - use the :file: role for the header path in pcmcia/driver.rst (Randy)
> > - say in the commit message that <linux/device-id/acpi.h> is left out on
> >   purpose (question raised by the Sashiko review)
> 
> I am unsatisfied with how the ACPI division was handled in the above mentioned
> split. Id est the include/device-id/acpi.h is *the* header that has to be used
> for the IDs, not the respective "include all" linux/acpi.h.
> Hence the documentation has to allow the use of the device-id/*.h directly in
> the drivers (most of the cases for ACPI).

I don't care much if drivers include <linux/device-id/acpi.h>
transitively via <linux/acpi.h> (or another header) or explicitly. My
preference is the former, but I won't argue if it's done differently.

> Alternatively the OF ID *and* ACPI ID must be included to the upper lever bus
> headers. So, spi.h, i2c.h, platform_device.h and so on has to *always* provide
> both.

That is the case today and it's sensible. So without giving a guarantee
for the next 20 years, I'd say keeping it as is is fine.
 
> > - carried Randy's Reviewed-by and Tested-by from v2, the diff changed in
> >   one line of markup only
> > - Uwe asked me to take over the patch:
> >   https://lore.kernel.org/r/apv6yQ1U-HhNglyV@monoceros/
> >   It supersedes my PCI-only patch
> >   https://lore.kernel.org/r/20260905084916.40196-1-kmehltretter@gmail.com/
> > 
> > Randy's suggestion to add kernel-doc comments to <linux/mei_cl_bus.h> for
> > struct mei_cl_driver and include those instead of the duplicated struct is
> > left for a separate patch, it touches a header outside Documentation/.
> 
> Uwe, can you fix that?

It's on my idle-todo-list. So unless someone beats me to it, I will
addresss that eventually.

Best regards
Uwe

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]