[v2,03/14] dt-bindings: pci: Add common schema for devices accessible through PCI BARs

Common YAML schema for devices that exports internal peripherals through
PCI BARs. The BARs are exposed as simple-buses through which the
peripherals can be accessed.

This is not intended to be used as a standalone binding, but should be
included by device specific bindings.

Signed-off-by: Andrea della Porta <andrea.porta@suse.com>
---
 .../devicetree/bindings/pci/pci-ep-bus.yaml   | 69 +++++++++++++++++++
 MAINTAINERS                                   |  1 +
 2 files changed, 70 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/pci/pci-ep-bus.yaml

On Mon, 07 Oct 2024 14:39:46 +0200, Andrea della Porta wrote:
> Common YAML schema for devices that exports internal peripherals through
> PCI BARs. The BARs are exposed as simple-buses through which the
> peripherals can be accessed.
> 
> This is not intended to be used as a standalone binding, but should be
> included by device specific bindings.
> 
> Signed-off-by: Andrea della Porta <andrea.porta@suse.com>
> ---
>  .../devicetree/bindings/pci/pci-ep-bus.yaml   | 69 +++++++++++++++++++
>  MAINTAINERS                                   |  1 +
>  2 files changed, 70 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/pci/pci-ep-bus.yaml
> 

My bot found errors running 'make dt_binding_check' on your patch:

yamllint warnings/errors:

dtschema/dtc warnings/errors:
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/pci/pci-ep-bus.yaml: 'oneOf' conditional failed, one must be fixed:
	'unevaluatedProperties' is a required property
	'additionalProperties' is a required property
	hint: Either unevaluatedProperties or additionalProperties must be present
	from schema $id: http://devicetree.org/meta-schemas/core.yaml#

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/e1d6c72d9f41218e755b615b9a985db075ce9c28.1728300189.git.andrea.porta@suse.com

The base for the series is generally the latest rc1. A different dependency
should be noted in *this* patch.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit after running the above command yourself. Note
that DT_SCHEMA_FILES can be set to your schema file to speed up checking
your schema. However, it must be unset to test all examples with your schema.

On Mon, Oct 07, 2024 at 02:39:46PM +0200, Andrea della Porta wrote:
> Common YAML schema for devices that exports internal peripherals through
> PCI BARs. The BARs are exposed as simple-buses through which the
> peripherals can be accessed.
> 
> This is not intended to be used as a standalone binding, but should be
> included by device specific bindings.

It still has to be tested before posting... Mailing list is not a
testing service. My and Rob's machines are not a testing service.

> 
> Signed-off-by: Andrea della Porta <andrea.porta@suse.com>
> ---
>  .../devicetree/bindings/pci/pci-ep-bus.yaml   | 69 +++++++++++++++++++
>  MAINTAINERS                                   |  1 +
>  2 files changed, 70 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/pci/pci-ep-bus.yaml
> 
> diff --git a/Documentation/devicetree/bindings/pci/pci-ep-bus.yaml b/Documentation/devicetree/bindings/pci/pci-ep-bus.yaml
> new file mode 100644
> index 000000000000..9d7a784b866a
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/pci/pci-ep-bus.yaml
> @@ -0,0 +1,69 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/pci/pci-ep-bus.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Common properties for PCI MFD endpoints with peripherals addressable from BARs.

Drop full stop and capitalize it.

> +
> +maintainers:
> +  - Andrea della Porta  <andrea.porta@suse.com>
> +
> +description:
> +  Define a generic node representing a PCI endpoint which contains several sub-
> +  peripherals. The peripherals can be accessed through one or more BARs.
> +  This common schema is intended to be referenced from device tree bindings, and
> +  does not represent a device tree binding by itself.
> +
> +properties:
> +  "#address-cells":

Use consistent quotes, either ' or ".

Best regards,
Krzysztof

On Mon, Oct 07, 2024 at 02:39:46PM +0200, Andrea della Porta wrote:
> Common YAML schema for devices that exports internal peripherals through
> PCI BARs. The BARs are exposed as simple-buses through which the
> peripherals can be accessed.
> 
> This is not intended to be used as a standalone binding, but should be
> included by device specific bindings.
> 
> Signed-off-by: Andrea della Porta <andrea.porta@suse.com>
> ---
>  .../devicetree/bindings/pci/pci-ep-bus.yaml   | 69 +++++++++++++++++++
>  MAINTAINERS                                   |  1 +
>  2 files changed, 70 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/pci/pci-ep-bus.yaml
> 
> diff --git a/Documentation/devicetree/bindings/pci/pci-ep-bus.yaml b/Documentation/devicetree/bindings/pci/pci-ep-bus.yaml
> new file mode 100644
> index 000000000000..9d7a784b866a
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/pci/pci-ep-bus.yaml
> @@ -0,0 +1,69 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/pci/pci-ep-bus.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Common properties for PCI MFD endpoints with peripherals addressable from BARs.
> +
> +maintainers:
> +  - Andrea della Porta  <andrea.porta@suse.com>
> +
> +description:
> +  Define a generic node representing a PCI endpoint which contains several sub-
> +  peripherals. The peripherals can be accessed through one or more BARs.
> +  This common schema is intended to be referenced from device tree bindings, and
> +  does not represent a device tree binding by itself.
> +
> +properties:
> +  "#address-cells":
> +    const: 3
> +
> +  "#size-cells":
> +    const: 2
> +
> +  ranges:
> +    minItems: 1
> +    maxItems: 6
> +    items:
> +      maxItems: 8
> +      additionalItems: true
> +      items:
> +        - maximum: 5  # The BAR number
> +        - const: 0
> +        - const: 0
> +
> +patternProperties:
> +  "^pci-ep-bus@[0-5]$":
> +    $ref: '#/$defs/pci-ep-bus'

This should just be:

additionalProperties: true

properties:
  compatible:
    const: simple-bus

required:
  - compatible

Then the compatible will cause simple-bus.yaml to be applied to this 
node.

> +    description:
> +      One node for each BAR used by peripherals contained in the PCI endpoint.
> +      Each node represent a bus on which peripherals are connected.
> +      This allows for some segmentation, e.g. one peripheral is accessible
> +      through BAR0 and another through BAR1, and you don't want the two
> +      peripherals to be able to act on the other BAR. Alternatively, when
> +      different peripherals need to share BARs, you can define only one node
> +      and use 'ranges' property to map all the used BARs.
> +
> +required:
> +  - ranges
> +  - '#address-cells'
> +  - '#size-cells'
> +
> +$defs:
> +  pci-ep-bus:
> +    type: object
> +    additionalProperties: true
> +    properties:
> +      compatible:
> +        const: simple-bus
> +      dma-ranges: true
> +      ranges: true
> +      "#address-cells": true
> +      "#size-cells": true
> +    required:
> +      - compatible
> +      - ranges
> +      - '#address-cells'
> +      - '#size-cells'

All this should be covered by simple-bus.yaml.

Rob

Hi Krzysztof,

On 08:24 Tue 08 Oct     , Krzysztof Kozlowski wrote:
> On Mon, Oct 07, 2024 at 02:39:46PM +0200, Andrea della Porta wrote:
> > Common YAML schema for devices that exports internal peripherals through
> > PCI BARs. The BARs are exposed as simple-buses through which the
> > peripherals can be accessed.
> > 
> > This is not intended to be used as a standalone binding, but should be
> > included by device specific bindings.
> 
> It still has to be tested before posting... Mailing list is not a
> testing service. My and Rob's machines are not a testing service.

Sorry about that, I must have missed that file when rechecking all the schemas
after rebasing on 6.12-rc1.

> 
> > 
> > Signed-off-by: Andrea della Porta <andrea.porta@suse.com>
> > ---
> >  .../devicetree/bindings/pci/pci-ep-bus.yaml   | 69 +++++++++++++++++++
> >  MAINTAINERS                                   |  1 +
> >  2 files changed, 70 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/pci/pci-ep-bus.yaml
> > 
> > diff --git a/Documentation/devicetree/bindings/pci/pci-ep-bus.yaml b/Documentation/devicetree/bindings/pci/pci-ep-bus.yaml
> > new file mode 100644
> > index 000000000000..9d7a784b866a
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/pci/pci-ep-bus.yaml
> > @@ -0,0 +1,69 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/pci/pci-ep-bus.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Common properties for PCI MFD endpoints with peripherals addressable from BARs.
> 
> Drop full stop and capitalize it.

Ack.

> 
> > +
> > +maintainers:
> > +  - Andrea della Porta  <andrea.porta@suse.com>
> > +
> > +description:
> > +  Define a generic node representing a PCI endpoint which contains several sub-
> > +  peripherals. The peripherals can be accessed through one or more BARs.
> > +  This common schema is intended to be referenced from device tree bindings, and
> > +  does not represent a device tree binding by itself.
> > +
> > +properties:
> > +  "#address-cells":
> 
> Use consistent quotes, either ' or ".

Ack.

Many thanks,
Andrea

> 
> Best regards,
> Krzysztof
>

Hi Rob,

On 21:47 Wed 09 Oct     , Rob Herring wrote:
> On Mon, Oct 07, 2024 at 02:39:46PM +0200, Andrea della Porta wrote:
> > Common YAML schema for devices that exports internal peripherals through
> > PCI BARs. The BARs are exposed as simple-buses through which the
> > peripherals can be accessed.
> > 
> > This is not intended to be used as a standalone binding, but should be
> > included by device specific bindings.
> > 
> > Signed-off-by: Andrea della Porta <andrea.porta@suse.com>
> > ---
> >  .../devicetree/bindings/pci/pci-ep-bus.yaml   | 69 +++++++++++++++++++
> >  MAINTAINERS                                   |  1 +
> >  2 files changed, 70 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/pci/pci-ep-bus.yaml
> > 
> > diff --git a/Documentation/devicetree/bindings/pci/pci-ep-bus.yaml b/Documentation/devicetree/bindings/pci/pci-ep-bus.yaml
> > new file mode 100644
> > index 000000000000..9d7a784b866a
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/pci/pci-ep-bus.yaml
> > @@ -0,0 +1,69 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/pci/pci-ep-bus.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Common properties for PCI MFD endpoints with peripherals addressable from BARs.
> > +
> > +maintainers:
> > +  - Andrea della Porta  <andrea.porta@suse.com>
> > +
> > +description:
> > +  Define a generic node representing a PCI endpoint which contains several sub-
> > +  peripherals. The peripherals can be accessed through one or more BARs.
> > +  This common schema is intended to be referenced from device tree bindings, and
> > +  does not represent a device tree binding by itself.
> > +
> > +properties:
> > +  "#address-cells":
> > +    const: 3
> > +
> > +  "#size-cells":
> > +    const: 2
> > +
> > +  ranges:
> > +    minItems: 1
> > +    maxItems: 6
> > +    items:
> > +      maxItems: 8
> > +      additionalItems: true
> > +      items:
> > +        - maximum: 5  # The BAR number
> > +        - const: 0
> > +        - const: 0
> > +
> > +patternProperties:
> > +  "^pci-ep-bus@[0-5]$":
> > +    $ref: '#/$defs/pci-ep-bus'
> 
> This should just be:
> 
> additionalProperties: true
> 
> properties:
>   compatible:
>     const: simple-bus
> 
> required:
>   - compatible
> 
> Then the compatible will cause simple-bus.yaml to be applied to this 
> node.
>

Ack.
 
> > +    description:
> > +      One node for each BAR used by peripherals contained in the PCI endpoint.
> > +      Each node represent a bus on which peripherals are connected.
> > +      This allows for some segmentation, e.g. one peripheral is accessible
> > +      through BAR0 and another through BAR1, and you don't want the two
> > +      peripherals to be able to act on the other BAR. Alternatively, when
> > +      different peripherals need to share BARs, you can define only one node
> > +      and use 'ranges' property to map all the used BARs.
> > +
> > +required:
> > +  - ranges
> > +  - '#address-cells'
> > +  - '#size-cells'
> > +
> > +$defs:
> > +  pci-ep-bus:
> > +    type: object
> > +    additionalProperties: true
> > +    properties:
> > +      compatible:
> > +        const: simple-bus
> > +      dma-ranges: true
> > +      ranges: true
> > +      "#address-cells": true
> > +      "#size-cells": true
> > +    required:
> > +      - compatible
> > +      - ranges
> > +      - '#address-cells'
> > +      - '#size-cells'
> 
> All this should be covered by simple-bus.yaml.

Ack.

Many thanks,
Andrea
> 
> Rob