[PATCH 3/7] dt-bindings: pci: Add document for ASPEED PCIe RC

[Jacky Chou]

> > +++ b/Documentation/devicetree/bindings/pci/aspeed-pcie.yaml
> 
> Same comments.
> 
> > @@ -0,0 +1,159 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/pci/aspeed-pcie.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: ASPEED PCIe Root Complex Controller
> > +
> > +maintainers:
> > +  - Jacky Chou <jacky_chou at aspeedtech.com>
> > +
> > +description: |
> 
> Do not need '|' unless you need to preserve formatting.
>

Agreed.

> 
> > +  Device tree binding for the ASPEED PCIe Root Complex controller.
> 
> No, describe the hardware. Your current description is 100% redundant.
> It is never useful to say in DT binding description that it is a DT binding. It
> cannot be anything else, can it?
> 

Agreed.

> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - aspeed,ast2600-pcie
> > +      - aspeed,ast2700-pcie
> > +
> > +  device_type:
> > +    const: pci
> 
> You need to include proper pci schema and drop all redundant properties.
> 
> Look at other schemas.

Agreed.

> 
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  ranges:
> > +    minItems: 2
> > +    maxItems: 2
> > +
> > +  interrupts:
> > +    description: IntX and MSI interrupt
> 
> Need to list the items. Look at other schemas.

Agreed.

> 
> > +
> > +  resets:
> > +    items:
> > +      - description: Module reset
> > +      - description: PCIe PERST
> > +
> > +  reset-names:
> > +    items:
> > +      - const: h2x
> > +      - const: perst
> > +
> > +  msi-parent: true
> > +
> > +  msi_address:
> 
> Where is this property defined?  I do not see in kernel nor in dtschema.
> Drop and use existing properties. I am not even talking about coding style...

Agreed.

> 
> > +    $ref: /schemas/types.yaml#/definitions/uint32
> > +    description: MSI address
> > +
> > +  aspeed,ahbc:
> > +    $ref: /schemas/types.yaml#/definitions/phandle
> > +    description: Phandle to ASPEED AHBC syscon.
> 
> For what purpose?
> 
> > +
> > +  aspeed,pciecfg:
> > +    $ref: /schemas/types.yaml#/definitions/phandle
> > +    description: Phandle to ASPEED PCIe configuration syscon.
> 
> For what purpose?
> 
> > +
> > +  aspeed,pciephy:
> > +    $ref: /schemas/types.yaml#/definitions/phandle
> > +    description: Phandle to ASPEED PCIe PHY syscon.
> 
> For what purpose?
> 

I will add more description in next version.

> > +
> > +  clocks:
> > +    description: PCIe BUS clock
> 
> Missing constraints.
> 
> Just open any other  binding and do not implement things diferently.
>

Agreed.

> > +
> > +  interrupt-controller:
> > +    description: Interrupt controller node for handling legacy PCI
> interrupts.
> > +    type: object
> > +    properties:
> > +      '#address-cells':
> > +        const: 0
> > +      '#interrupt-cells':
> > +        const: 1
> > +      interrupt-controller: true
> > +
> > +    required:
> > +      - '#address-cells'
> > +      - '#interrupt-cells'
> > +      - interrupt-controller
> > +
> > +    additionalProperties: false
> > +
> > +allOf:
> > +  - $ref: /schemas/pci/pci-bus.yaml#
> > +  - $ref: /schemas/interrupt-controller/msi-controller.yaml#
> > +  - if:
> > +      properties:
> > +        compatible:
> > +          contains:
> > +            const: aspeed,ast2600-pcie
> > +    then:
> > +      required:
> > +        - aspeed,ahbc
> 
> else: make it false
> 

Agreed.

> > +
> > +required:
> > +  - interrupts
> > +  - bus-range
> > +  - ranges
> > +  - resets
> > +  - reset-names
> > +  - msi-parent
> > +  - msi-controller
> > +  - aspeed,pciephy
> > +  - aspeed,pciecfg
> > +  - interrupt-map-mask
> > +  - interrupt-map
> > +  - interrupt-controller
> 
> Messed order, missing properties. Open other bindings...
> 

Agreed.

> > +
> > +unevaluatedProperties: false
> > +
> > +examples:
> > +  - |
> > +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> > +    #include <dt-bindings/clock/ast2600-clock.h>
> > +
> > +    apb {
> > +      #address-cells = <1>;
> > +      #size-cells = <1>;
> > +
> > +      pcie0: pcie at 1e7700C0 {
> > +        compatible = "aspeed,ast2600-pcie";
> > +        device_type = "pci";
> > +        reg = <0x1e7700C0 0x40>;
> 
> Lower case hex. Please follow carefully DTS coding style.
>

Agreed.

Thanks,
Jacky