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) <[email protected]> > > > > 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)
> > <[email protected]>
>
> ...
>
> > Changes since v2
> >
> > https://lore.kernel.org/r/ede7ce64f20e10660ebf6bc1b41836dad750ae3b.1783349758.git.uklei...@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/[email protected]/
> >
> > 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
signature.asc
Description: PGP signature
