Re: [PATCH v2] dt-bindings: incomplete-devices: document devices without bindings

[Rob Herring]

On Thu, Jul 11, 2024 at 2:59 AM Krzysztof Kozlowski
<krzysztof.kozlowski@xxxxxxxxxx> 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@xxxxxxx/
> Link: https://lore.kernel.org/lkml/20220731173446.7400bfa8@jic23-huawei/T/#me55be502302d70424a85368c2645c89f860b7b40
> Cc: Marek Vasut <marex@xxxxxxx>
> Cc: Jonathan Cameron <jic23@xxxxxxxxxx>
> Cc: Sebastian Reichel <sebastian.reichel@xxxxxxxxxxxxx>
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@xxxxxxxxxx>
>
> ---
>
> 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@xxxxxxxxxx>
> +
> +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
>
>