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

[Uwe Kleine-König]

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@xxxxxxxxxxxx>
> > 
> > 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@xxxxxxxxxxxx>
> 
> ...
> 
> > Changes since v2
> >   https://lore.kernel.org/r/ede7ce64f20e10660ebf6bc1b41836dad750ae3b.1783349758.git.ukleinek@xxxxxxxxxx/
> > - 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@xxxxxxxxx/
> > 
> > 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: signature.asc
Description: PGP signature