[PATCH v4 0/2] Documentation: Restore device-ID documentation

[PATCH v4 0/2] Documentation: Restore device-ID documentation

[Karl Mehltretter]

This v4 addresses the duplicate PCI declaration warnings Jonathan
reported on v3.

Patch 1 retains Uwe's device-ID documentation restoration. Patch 2
corrects the Chinese PCI header path and preserves its existing plain
references. The kernel-doc blocks added in v3 are dropped, with generated
API documentation deferred to a separate change.

A focused Sphinx 8.2.3 build with -W includes the complete English and
Chinese PCI pages together. It reproduces both warnings with v3 and
passes without warnings after each v4 patch.

Changes since v3:
  https://lore.kernel.org/r/20260908070031.32833-1-kmehltretter@gmail.com/
- Move the Chinese PCI changes to patch 2. The five files in patch 1 are
  unchanged from v3.
- Clarify the ACPI exclusion in patch 1's commit message using Uwe's
  explanation to Andy. Only ACPI_DEVICE_CLASS() has kernel-doc in that
  header.
- Retain Randy's review and test tags from v2 on patch 1.

Changes since v2:
  https://lore.kernel.org/r/ede7ce64f20e10660ebf6bc1b41836dad750ae3b.1783349758.git.ukleinek@kernel.org/
- Use the :file: role in pcmcia/driver.rst (Randy) and explain why acpi.h
  is excluded.

Documenting struct mei_cl_driver in include/linux/mei_cl_bus.h remains
a separate follow-up.

Report: https://lore.kernel.org/r/87h5jq8gia.fsf@trenco.lwn.net/

Karl Mehltretter (1):
  docs/zh_CN: PCI: Update the pci_device_id header reference

Uwe Kleine-König (The Capable Hub) (1):
  Documentation: Update after split of <linux/mod_devicetable.h>

 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  |  2 +-
 6 files changed, 36 insertions(+), 15 deletions(-)

base-commit: 5b0764a53235d3c77e1ed674e836e1b3fe1a4b1f

[PATCH v4 1/2] 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). Leave <linux/device-id/acpi.h> out:
only ACPI_DEVICE_CLASS() has kernel-doc there, so including it would
document that macro rather than struct acpi_device_id.

Generate mei_cl_device_id from its header instead of keeping a copy in
the MEI client bus documentation.

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, explain why
 acpi.h is left out]
Assisted-by: LLM
Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>
---
 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 +-
 5 files changed, 35 insertions(+), 14 deletions(-)

diff --git a/Documentation/PCI/pci.rst b/Documentation/PCI/pci.rst
index be35e9a1ee75f7038539a5f162f621086cc3f495..71c42b0bfa8b3b30b63935b7f4d96e56e9bfb302 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 3b182cfdf13509f1ee8306cffaaf8c99c337270f..84f701b84e4fc517ed12fcb7001fd1f90252784b 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 f242b3f8d6aa5754b6064411be360442bf443678..d46c0d0b3540afd6fb85baf0ee51ae5032b6e5f7 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 5c4fe84d51c14caed1fba614934b37bdc51b4420..0b6370c1d52573c5b48eb8d7d577a6f363997e4d 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 63612b7ee120ad230e6f38983758a5a35ece3b0d..ea0eb19811248132f9a221dd49f421f80fcbba06 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>

base-commit: 5b0764a53235d3c77e1ed674e836e1b3fe1a4b1f

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

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] Documentation: basics.rst omits kernel-doc for arm_smccc.h
--

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

Documentation: Update after split of <linux/mod_devicetable.h>

This patch updates documentation references after struct definitions in
include/linux/mod_devicetable.h were split into bus-specific headers under
include/linux/device-id/.

> diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
> index 3b182cfdf1350..84f701b84e4fc 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:

[Severity: Low]
Should include/linux/device-id/arm_smccc.h also be included here in the
Driver device table section of Documentation/driver-api/basics.rst?

The commit message notes that basics.rst lists all headers that have
kernel-doc annotations and are not described elsewhere (with acpi.h left
out). However, include/linux/device-id/arm_smccc.h (which is included by
include/linux/mod_devicetable.h) defines struct arm_smccc_device_id with a
kernel-doc comment:

/**
 * struct arm_smccc_device_id - Arm SMCCC bus device identifier
 * @func_id: SMCCC function identifier
 */
struct arm_smccc_device_id {
	__u32 func_id;
};

Since arm_smccc.h is not referenced elsewhere under Documentation/ and is
skipped between amba.h and cdx.h, struct arm_smccc_device_id is omitted when
generating the documentation.

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/cover.1793221199.git.kmehltretter@gmail.com?part=1

[PATCH v4 2/2] docs/zh_CN: PCI: Update the pci_device_id header reference

[Karl Mehltretter]

struct pci_device_id moved from <linux/mod_devicetable.h> to
<linux/device-id/pci.h>. Update the header reference in the Chinese PCI
guide to match its new location.

Fixes: ad428f5811bd ("mod_devicetable.h: Split into per subsystem headers")
Assisted-by: LLM
Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>
---
 Documentation/translations/zh_CN/PCI/pci.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/translations/zh_CN/PCI/pci.rst b/Documentation/translations/zh_CN/PCI/pci.rst
index 347f5c3f5ce99bade1221f083b208972baf102ec..452e073b8c067ce16c76d9a5a5883532ebce3296 100644
--- a/Documentation/translations/zh_CN/PCI/pci.rst
+++ b/Documentation/translations/zh_CN/PCI/pci.rst
@@ -92,7 +92,7 @@ ID表是一个由 ``struct pci_device_id`` 结构体成员组成的数组，以
 
 该API在以下内核代码中:
 
-include/linux/mod_devicetable.h
+include/linux/device-id/pci.h
 pci_device_id
 
 大多数驱动程序只需要 ``PCI_DEVICE()`` 或 ``PCI_DEVICE_CLASS()`` 来设置一个

Re: [PATCH v4 2/2] docs/zh_CN: PCI: Update the pci_device_id header reference

[sashiko-bot]

> struct pci_device_id moved from <linux/mod_devicetable.h> to
> <linux/device-id/pci.h>. Update the header reference in the Chinese PCI
> guide to match its new location.
> 
> Fixes: ad428f5811bd ("mod_devicetable.h: Split into per subsystem headers")
> Assisted-by: LLM
> Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>

Sashiko has reviewed this patch and found no issues.

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/cover.1793221199.git.kmehltretter@gmail.com?part=2