.../bindings/incomplete-devices.yaml | 139 ++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 Documentation/devicetree/bindings/incomplete-devices.yaml
There are devices in the wild with non-updatable firmware coming with
ACPI tables with rejected compatibles, e.g. "ltr,ltrf216a". Linux
kernel still supports this device via ACPI PRP0001, however the
compatible was never accepted to bindings.
There are also several early PowerPC or SPARC platforms using
compatibles for their OpenFirmware, but without in-tree DTS. Often the
compatible is not correct in terms of Devicetree specification,
e.g. missing vendor prefix.
Finally there are also Linux-specific tools and test code with
compatibles.
Add a schema covering above cases purely to satisfy the DT schema and
scripts/checkpatch.pl checks for undocumented compatibles. For
ltr,ltrf216a this also documents the consensus: compatible is allowed
only via ACPI PRP0001, but not bindings.
Link: https://lore.kernel.org/all/20240705095047.90558-1-marex@denx.de/
Link: https://lore.kernel.org/lkml/20220731173446.7400bfa8@jic23-huawei/T/#me55be502302d70424a85368c2645c89f860b7b40
Cc: Marek Vasut <marex@denx.de>
Cc: Jonathan Cameron <jic23@kernel.org>
Cc: Sebastian Reichel <sebastian.reichel@collabora.com>
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
---
Changes in v2:
1. Rename to incomplete-devices.yaml
2. Add many compatibles based on Rob's feedback, rewrite descriptions in
the schema.
---
.../bindings/incomplete-devices.yaml | 139 ++++++++++++++++++
1 file changed, 139 insertions(+)
create mode 100644 Documentation/devicetree/bindings/incomplete-devices.yaml
diff --git a/Documentation/devicetree/bindings/incomplete-devices.yaml b/Documentation/devicetree/bindings/incomplete-devices.yaml
new file mode 100644
index 000000000000..d690d44560fd
--- /dev/null
+++ b/Documentation/devicetree/bindings/incomplete-devices.yaml
@@ -0,0 +1,139 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/incomplete-devices.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Rejected or Incomplete Devices
+
+maintainers:
+ - Rob Herring <robh@kernel.org>
+
+description:
+ Some devices will not or should not get a proper Devicetree bindings, but
+ their compatibles are present in Linux drivers for various reasons.
+
+ Examples are devices using ACPI PRP0001 with non-updatable firmware/ACPI
+ tables or old PowerPC platforms without in-tree DTS.
+
+ Following list of devices is an incomplete schema with a goal to pass DT schema
+ checks on undocumented compatibles but also reject any DTS file using such
+ un-approved compatible.
+
+ Usage of any of following compatibles is not allowed in Devicetree sources,
+ even if they come from immutable firmware.
+
+properties:
+ compatible:
+ oneOf:
+ - description:
+ Rejected compatibles in Devicetree, but used in ACPI-based devices
+ with non-updatable firmware/ACPI tables (via ACPI PRP0001)
+ enum:
+ - broadcom,bcm5241
+ - ltr,ltrf216a
+
+ - description: Incorrect compatibles used on Macintosh devices
+ enum:
+ - adm1030
+ - bmac+
+ - heathrow-media-bay
+ - keylargo-media-bay
+ - lm87cimt
+ - MAC,adm1030
+ - MAC,ds1775
+ - max6690
+ - ohare-media-bay
+ - ohare-swim3
+ - smu-sat
+ - swim3
+
+ - description: Incorrect compatibles used on other PowerPC devices
+ enum:
+ - 1682m-rng
+ - IBM,lhca
+ - IBM,lhea
+ - IBM,lhea-ethernet
+ - mpc5200b-fec-phy
+ - mpc5200-serial
+ - mpc5200-sram
+ - ohci-bigendian
+ - ohci-le
+ - ohci-littledian
+
+ - description: Incorrect compatibles used on SPARC devices
+ enum:
+ - bq4802
+ - ds1287
+ - isa-m5819p
+ - isa-m5823p
+ - m5819
+ - sab82532
+ - SUNW,bbc-beep
+ - SUNW,bbc-i2c
+ - SUNW,CS4231
+ - SUNW,ebus-pic16f747-env
+ - SUNW,kt-cwq
+ - SUNW,kt-mau
+ - SUNW,n2-cwq
+ - SUNW,n2-mau
+ - SUNW,niusl
+ - SUNW,smbus-beep
+ - SUNW,sun4v-console
+ - SUNW,sun4v-pci
+ - SUNW,vf-cwq
+ - SUNW,vf-mau
+
+ - description: Incomplete and incorrect compatibles for unknown devices
+ enum:
+ - electra-cf
+ - i2cpcf,8584
+ - virtio,uml
+
+ - description: Linux kernel unit tests and sample code
+ enum:
+ - audio-graph-card2-custom-sample
+ - compat1
+ - compat2
+ - compat3
+ - linux,spi-loopback-test
+ - mailbox-test
+ - regulator-virtual-consumer
+ - unittest-gpio
+ - unittest-pci
+
+ - description:
+ Devices on MIPS platform, without any DTS users. These are
+ unlikely to get converted to DT schema.
+ enum:
+ - mti,ranchu
+
+ - description:
+ Devices on PowerPC platform, without any DTS users. These are
+ unlikely to get converted to DT schema.
+ enum:
+ - fujitsu,coral
+ - fujitsu,lime
+ - fujitsu,MB86276
+ - fujitsu,MB86277
+ - fujitsu,MB86293
+ - fujitsu,MB86294
+ - fujitsu,mint
+ - ibm,axon-msic
+ - ibm,pmemory
+ - ibm,pmemory-v2
+ - ibm,power-rng
+ - ibm,ppc4xx-spi
+ - ibm,sdram-4xx-ddr2
+ - ibm,secureboot
+ - ibm,secureboot-v1
+ - ibm,secureboot-v2
+ - ibm,secvar-backend
+ - sgy,gpio-halt
+ - wrs,epld-localbus
+
+required:
+ - compatible
+ - broken-usage-of-incorrect-compatible
+
+additionalProperties: false
--
2.43.0On Thu, Jul 11, 2024 at 2:59 AM Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> wrote: > > There are devices in the wild with non-updatable firmware coming with > ACPI tables with rejected compatibles, e.g. "ltr,ltrf216a". Linux > kernel still supports this device via ACPI PRP0001, however the > compatible was never accepted to bindings. > > There are also several early PowerPC or SPARC platforms using > compatibles for their OpenFirmware, but without in-tree DTS. Often the > compatible is not correct in terms of Devicetree specification, > e.g. missing vendor prefix. > > Finally there are also Linux-specific tools and test code with > compatibles. > > Add a schema covering above cases purely to satisfy the DT schema and > scripts/checkpatch.pl checks for undocumented compatibles. For > ltr,ltrf216a this also documents the consensus: compatible is allowed > only via ACPI PRP0001, but not bindings. > > Link: https://lore.kernel.org/all/20240705095047.90558-1-marex@denx.de/ > Link: https://lore.kernel.org/lkml/20220731173446.7400bfa8@jic23-huawei/T/#me55be502302d70424a85368c2645c89f860b7b40 > Cc: Marek Vasut <marex@denx.de> > Cc: Jonathan Cameron <jic23@kernel.org> > Cc: Sebastian Reichel <sebastian.reichel@collabora.com> > Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> > > --- > > Changes in v2: > 1. Rename to incomplete-devices.yaml > 2. Add many compatibles based on Rob's feedback, rewrite descriptions in > the schema. > --- > .../bindings/incomplete-devices.yaml | 139 ++++++++++++++++++ > 1 file changed, 139 insertions(+) > create mode 100644 Documentation/devicetree/bindings/incomplete-devices.yaml > > diff --git a/Documentation/devicetree/bindings/incomplete-devices.yaml b/Documentation/devicetree/bindings/incomplete-devices.yaml > new file mode 100644 > index 000000000000..d690d44560fd > --- /dev/null > +++ b/Documentation/devicetree/bindings/incomplete-devices.yaml > @@ -0,0 +1,139 @@ > +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause > +%YAML 1.2 > +--- > +$id: http://devicetree.org/schemas/incomplete-devices.yaml# > +$schema: http://devicetree.org/meta-schemas/core.yaml# > + > +title: Rejected or Incomplete Devices > + > +maintainers: > + - Rob Herring <robh@kernel.org> > + > +description: > + Some devices will not or should not get a proper Devicetree bindings, but > + their compatibles are present in Linux drivers for various reasons. > + > + Examples are devices using ACPI PRP0001 with non-updatable firmware/ACPI > + tables or old PowerPC platforms without in-tree DTS. > + > + Following list of devices is an incomplete schema with a goal to pass DT schema > + checks on undocumented compatibles but also reject any DTS file using such > + un-approved compatible. > + > + Usage of any of following compatibles is not allowed in Devicetree sources, > + even if they come from immutable firmware. > + > +properties: > + compatible: > + oneOf: > + - description: > + Rejected compatibles in Devicetree, but used in ACPI-based devices > + with non-updatable firmware/ACPI tables (via ACPI PRP0001) > + enum: > + - broadcom,bcm5241 > + - ltr,ltrf216a > + > + - description: Incorrect compatibles used on Macintosh devices They were correct at the time. Rules/standards evolve though. I would just say 'Legacy" rather than "Incorrect". > + enum: > + - adm1030 > + - bmac+ > + - heathrow-media-bay > + - keylargo-media-bay > + - lm87cimt > + - MAC,adm1030 > + - MAC,ds1775 > + - max6690 > + - ohare-media-bay > + - ohare-swim3 > + - smu-sat > + - swim3 > + > + - description: Incorrect compatibles used on other PowerPC devices > + enum: > + - 1682m-rng > + - IBM,lhca > + - IBM,lhea > + - IBM,lhea-ethernet > + - mpc5200b-fec-phy > + - mpc5200-serial > + - mpc5200-sram Tell Grant he needs to document these. ;) JK > + - ohci-bigendian > + - ohci-le > + - ohci-littledian Given the typo, I think we can just drop this one from the driver. > + > + - description: Incorrect compatibles used on SPARC devices > + enum: > + - bq4802 > + - ds1287 > + - isa-m5819p > + - isa-m5823p > + - m5819 > + - sab82532 > + - SUNW,bbc-beep > + - SUNW,bbc-i2c > + - SUNW,CS4231 > + - SUNW,ebus-pic16f747-env > + - SUNW,kt-cwq > + - SUNW,kt-mau > + - SUNW,n2-cwq > + - SUNW,n2-mau > + - SUNW,niusl > + - SUNW,smbus-beep > + - SUNW,sun4v-console > + - SUNW,sun4v-pci > + - SUNW,vf-cwq > + - SUNW,vf-mau > + > + - description: Incomplete and incorrect compatibles for unknown devices > + enum: > + - electra-cf > + - i2cpcf,8584 > + - virtio,uml > + > + - description: Linux kernel unit tests and sample code > + enum: > + - audio-graph-card2-custom-sample > + - compat1 > + - compat2 > + - compat3 > + - linux,spi-loopback-test > + - mailbox-test > + - regulator-virtual-consumer > + - unittest-gpio > + - unittest-pci We recently added "test" as a vendor prefix and don't complain if "test,.*" compatible is not documented. It's on my todo to change these. So I'd drop the unittest ones. > + > + - description: > + Devices on MIPS platform, without any DTS users. These are > + unlikely to get converted to DT schema. > + enum: > + - mti,ranchu > + > + - description: > + Devices on PowerPC platform, without any DTS users. These are > + unlikely to get converted to DT schema. > + enum: > + - fujitsu,coral > + - fujitsu,lime > + - fujitsu,MB86276 > + - fujitsu,MB86277 > + - fujitsu,MB86293 > + - fujitsu,MB86294 > + - fujitsu,mint > + - ibm,axon-msic > + - ibm,pmemory > + - ibm,pmemory-v2 > + - ibm,power-rng > + - ibm,ppc4xx-spi > + - ibm,sdram-4xx-ddr2 > + - ibm,secureboot > + - ibm,secureboot-v1 > + - ibm,secureboot-v2 > + - ibm,secvar-backend > + - sgy,gpio-halt > + - wrs,epld-localbus > + > +required: > + - compatible > + - broken-usage-of-incorrect-compatible > + > +additionalProperties: false > -- > 2.43.0 > >
On 11/07/2024 15:01, Rob Herring wrote: >> + >> +properties: >> + compatible: >> + oneOf: >> + - description: >> + Rejected compatibles in Devicetree, but used in ACPI-based devices >> + with non-updatable firmware/ACPI tables (via ACPI PRP0001) >> + enum: >> + - broadcom,bcm5241 >> + - ltr,ltrf216a >> + >> + - description: Incorrect compatibles used on Macintosh devices > > They were correct at the time. Rules/standards evolve though. I would > just say 'Legacy" rather than "Incorrect". ack > >> + enum: >> + - adm1030 >> + - bmac+ >> + - heathrow-media-bay >> + - keylargo-media-bay >> + - lm87cimt >> + - MAC,adm1030 >> + - MAC,ds1775 >> + - max6690 >> + - ohare-media-bay >> + - ohare-swim3 >> + - smu-sat >> + - swim3 >> + >> + - description: Incorrect compatibles used on other PowerPC devices >> + enum: >> + - 1682m-rng >> + - IBM,lhca >> + - IBM,lhea >> + - IBM,lhea-ethernet > >> + - mpc5200b-fec-phy >> + - mpc5200-serial >> + - mpc5200-sram > > Tell Grant he needs to document these. ;) JK > >> + - ohci-bigendian >> + - ohci-le >> + - ohci-littledian > > Given the typo, I think we can just drop this one from the driver. Sure, I'll send a patch. It could affect some ancient user, though... Although I really wonder if any of these PowerPC boxes are still alive. > >> + >> + - description: Incorrect compatibles used on SPARC devices >> + enum: >> + - bq4802 >> + - ds1287 >> + - isa-m5819p >> + - isa-m5823p >> + - m5819 >> + - sab82532 >> + - SUNW,bbc-beep >> + - SUNW,bbc-i2c >> + - SUNW,CS4231 >> + - SUNW,ebus-pic16f747-env >> + - SUNW,kt-cwq >> + - SUNW,kt-mau >> + - SUNW,n2-cwq >> + - SUNW,n2-mau >> + - SUNW,niusl >> + - SUNW,smbus-beep >> + - SUNW,sun4v-console >> + - SUNW,sun4v-pci >> + - SUNW,vf-cwq >> + - SUNW,vf-mau >> + >> + - description: Incomplete and incorrect compatibles for unknown devices >> + enum: >> + - electra-cf >> + - i2cpcf,8584 >> + - virtio,uml >> + >> + - description: Linux kernel unit tests and sample code >> + enum: >> + - audio-graph-card2-custom-sample >> + - compat1 >> + - compat2 >> + - compat3 >> + - linux,spi-loopback-test >> + - mailbox-test >> + - regulator-virtual-consumer >> + - unittest-gpio >> + - unittest-pci > > We recently added "test" as a vendor prefix and don't complain if > "test,.*" compatible is not documented. It's on my todo to change > these. So I'd drop the unittest ones. Ack Best regards, Krzysztof
Hi Krzysztof,
Sorry for being late to the party, as v2 was sent, and applied ;-)
On Fri, Jul 12, 2024 at 11:41 AM Krzysztof Kozlowski
<krzysztof.kozlowski@linaro.org> wrote:
> On 11/07/2024 15:01, Rob Herring wrote:
> >> + - description: Incorrect compatibles used on other PowerPC devices
> >> + enum:
> >> + - 1682m-rng
> >> + - IBM,lhca
> >> + - IBM,lhea
> >> + - IBM,lhea-ethernet
> >
> >> + - mpc5200b-fec-phy
> >> + - mpc5200-serial
> >> + - mpc5200-sram
> >
> > Tell Grant he needs to document these. ;) JK
> >
> >> + - ohci-bigendian
> >> + - ohci-le
> >> + - ohci-littledian
> >
> > Given the typo, I think we can just drop this one from the driver.
>
> Sure, I'll send a patch. It could affect some ancient user, though...
> Although I really wonder if any of these PowerPC boxes are still alive.
Looks like you forgot various "chrp,*" and "pnpPNP,*" ;-)
You can scavenge a few from my old LongTrail DTS
http://g33rt.be/migrated/Linux/PPC/DeviceTree.html
Note that my actual machine died 20 years ago...
Gr{oetje,eeting}s,
Geert
--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org
In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
-- Linus Torvalds
On Mon, Jul 15, 2024 at 3:57 AM Geert Uytterhoeven <geert@linux-m68k.org> wrote: > > Hi Krzysztof, > > Sorry for being late to the party, as v2 was sent, and applied ;-) > > On Fri, Jul 12, 2024 at 11:41 AM Krzysztof Kozlowski > <krzysztof.kozlowski@linaro.org> wrote: > > On 11/07/2024 15:01, Rob Herring wrote: > > >> + - description: Incorrect compatibles used on other PowerPC devices > > >> + enum: > > >> + - 1682m-rng > > >> + - IBM,lhca > > >> + - IBM,lhea > > >> + - IBM,lhea-ethernet > > > > > >> + - mpc5200b-fec-phy > > >> + - mpc5200-serial > > >> + - mpc5200-sram > > > > > > Tell Grant he needs to document these. ;) JK > > > > > >> + - ohci-bigendian > > >> + - ohci-le > > >> + - ohci-littledian > > > > > > Given the typo, I think we can just drop this one from the driver. > > > > Sure, I'll send a patch. It could affect some ancient user, though... > > Although I really wonder if any of these PowerPC boxes are still alive. > > Looks like you forgot various "chrp,*" and "pnpPNP,*" ;-) There aren't any cases of 'pnpPNP' flagged by 'make dt_compatible_check'. Most of the cases in the kernel are with of_find_compatible_node() which doesn't get parsed. Maybe it could be. The intent wasn't really to be complete. Doesn't really matter until we get 'make dt_compatible_check' to zero. Still 1300 bindings to convert. Rob
On 15/07/2024 11:57, Geert Uytterhoeven wrote: >>> >>>> + - mpc5200b-fec-phy >>>> + - mpc5200-serial >>>> + - mpc5200-sram >>> >>> Tell Grant he needs to document these. ;) JK >>> >>>> + - ohci-bigendian >>>> + - ohci-le >>>> + - ohci-littledian >>> >>> Given the typo, I think we can just drop this one from the driver. >> >> Sure, I'll send a patch. It could affect some ancient user, though... >> Although I really wonder if any of these PowerPC boxes are still alive. > > Looks like you forgot various "chrp,*" and "pnpPNP,*" ;-) chrp is documented in the vendor-prefixes, so I assume it is reasonable compatible. You think it will never get a DT schema bindings? It indeed looks like ancient PowerPC stuff. pnpPNP probably falls to the same category but without documented vendor prefix. I guess no one is going to add proper bindings for AmigOne? > > You can scavenge a few from my old LongTrail DTS > http://g33rt.be/migrated/Linux/PPC/DeviceTree.html > Note that my actual machine died 20 years ago... Yeah... that's convincing :) Best regards, Krzysztof
© 2016 - 2025 Red Hat, Inc.