[PATCH next 1/6] dt-bindings: soc: ti: k3-ringacc: convert bindings to json-schema

[Grygorii Strashko]

Hi Rob,

On 01/07/2020 13:30, Grygorii Strashko wrote:
> Convert the K3 NavigatorSS Ring Accelerator bindings documentation to
> json-schema.
> 
> Cc: Rob Herring <robh+dt at kernel.org>
> Signed-off-by: Grygorii Strashko <grygorii.strashko at ti.com>
> ---
>   .../devicetree/bindings/soc/ti/k3-ringacc.txt |  59 ----------
>   .../bindings/soc/ti/k3-ringacc.yaml           | 102 ++++++++++++++++++
>   2 files changed, 102 insertions(+), 59 deletions(-)
>   delete mode 100644 Documentation/devicetree/bindings/soc/ti/k3-ringacc.txt
>   create mode 100644 Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml
> 
> diff --git a/Documentation/devicetree/bindings/soc/ti/k3-ringacc.txt b/Documentation/devicetree/bindings/soc/ti/k3-ringacc.txt
> deleted file mode 100644
> index 59758ccce809..000000000000
> --- a/Documentation/devicetree/bindings/soc/ti/k3-ringacc.txt
> +++ /dev/null
> @@ -1,59 +0,0 @@
> -* Texas Instruments K3 NavigatorSS Ring Accelerator
> -
> -The Ring Accelerator (RA) is a machine which converts read/write accesses
> -from/to a constant address into corresponding read/write accesses from/to a
> -circular data structure in memory. The RA eliminates the need for each DMA
> -controller which needs to access ring elements from having to know the current
> -state of the ring (base address, current offset). The DMA controller
> -performs a read or write access to a specific address range (which maps to the
> -source interface on the RA) and the RA replaces the address for the transaction
> -with a new address which corresponds to the head or tail element of the ring
> -(head for reads, tail for writes).
> -
> -The Ring Accelerator is a hardware module that is responsible for accelerating
> -management of the packet queues. The K3 SoCs can have more than one RA instances
> -
> -Required properties:
> -- compatible	: Must be "ti,am654-navss-ringacc";
> -- reg		: Should contain register location and length of the following
> -		  named register regions.
> -- reg-names	: should be
> -		  "rt" - The RA Ring Real-time Control/Status Registers
> -		  "fifos" - The RA Queues Registers
> -		  "proxy_gcfg" - The RA Proxy Global Config Registers
> -		  "proxy_target" - The RA Proxy Datapath Registers
> -- ti,num-rings	: Number of rings supported by RA
> -- ti,sci-rm-range-gp-rings : TI-SCI RM subtype for GP ring range
> -- ti,sci	: phandle on TI-SCI compatible System controller node
> -- ti,sci-dev-id	: TI-SCI device id of the ring accelerator
> -- msi-parent	: phandle for "ti,sci-inta" interrupt controller
> -
> -Optional properties:
> - -- ti,dma-ring-reset-quirk : enable ringacc / udma ring state interoperability
> -		  issue software w/a
> -
> -Example:
> -
> -ringacc: ringacc at 3c000000 {
> -	compatible = "ti,am654-navss-ringacc";
> -	reg =	<0x0 0x3c000000 0x0 0x400000>,
> -		<0x0 0x38000000 0x0 0x400000>,
> -		<0x0 0x31120000 0x0 0x100>,
> -		<0x0 0x33000000 0x0 0x40000>;
> -	reg-names = "rt", "fifos",
> -		    "proxy_gcfg", "proxy_target";
> -	ti,num-rings = <818>;
> -	ti,sci-rm-range-gp-rings = <0x2>; /* GP ring range */
> -	ti,dma-ring-reset-quirk;
> -	ti,sci = <&dmsc>;
> -	ti,sci-dev-id = <187>;
> -	msi-parent = <&inta_main_udmass>;
> -};
> -
> -client:
> -
> -dma_ipx: dma_ipx@<addr> {
> -	...
> -	ti,ringacc = <&ringacc>;
> -	...
> -}
> diff --git a/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml b/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml
> new file mode 100644
> index 000000000000..ae33fc957141
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml
> @@ -0,0 +1,102 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +# Copyright (C) 2020 Texas Instruments Incorporated - http://www.ti.com/
> +%YAML 1.2
> +---
> +$id: "http://devicetree.org/schemas/soc/ti/k3-ringacc.yaml#"
> +$schema: "http://devicetree.org/meta-schemas/core.yaml#"
> +
> +title: Texas Instruments K3 NavigatorSS Ring Accelerator
> +
> +maintainers:
> +  - Santosh Shilimkar <ssantosh at kernel.org>
> +  - Grygorii Strashko <grygorii.strashko at ti.com>
> +
> +description: |
> +  The Ring Accelerator (RA) is a machine which converts read/write accesses
> +  from/to a constant address into corresponding read/write accesses from/to a
> +  circular data structure in memory. The RA eliminates the need for each DMA
> +  controller which needs to access ring elements from having to know the current
> +  state of the ring (base address, current offset). The DMA controller
> +  performs a read or write access to a specific address range (which maps to the
> +  source interface on the RA) and the RA replaces the address for the transaction
> +  with a new address which corresponds to the head or tail element of the ring
> +  (head for reads, tail for writes).
> +
> +  The Ring Accelerator is a hardware module that is responsible for accelerating
> +  management of the packet queues. The K3 SoCs can have more than one RA instances
> +
> +properties:
> +  compatible:
> +    items:
> +      - const: ti,am654-navss-ringacc
> +
> +  reg:
> +    items:
> +      - description: real time registers regions
> +      - description: fifos registers regions
> +      - description: proxy gcfg registers regions
> +      - description: proxy target registers regions
> +
> +  reg-names:
> +    items:
> +      - const: rt
> +      - const: fifos
> +      - const: proxy_gcfg
> +      - const: proxy_target
> +
> +  msi-parent: true
> +
> +  ti,num-rings:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description: Number of rings supported by RA
> +
> +  ti,sci-rm-range-gp-rings:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description: TI-SCI RM subtype for GP ring range
> +
> +  ti,sci:
> +    $ref: /schemas/types.yaml#definitions/phandle-array
> +    description: phandle on TI-SCI compatible System controller node
> +
> +  ti,sci-dev-id:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description: TI-SCI device id of the ring accelerator
> +
> +  ti,dma-ring-reset-quirk:
> +    $ref: /schemas/types.yaml#definitions/flag
> +    description: |
> +      enable ringacc/udma ring state interoperability issue software w/a
> +
> +required:
> +  - compatible
> +  - reg
> +  - reg-names
> +  - msi-parent
> +  - ti,num-rings
> +  - ti,sci-rm-range-gp-rings
> +  - ti,sci
> +  - ti,sci-dev-id
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    bus {
> +        #address-cells = <2>;
> +        #size-cells = <2>;
> +
> +        ringacc: ringacc at 3c000000 {
> +            compatible = "ti,am654-navss-ringacc";
> +            reg = <0x0 0x3c000000 0x0 0x400000>,
> +                  <0x0 0x38000000 0x0 0x400000>,
> +                  <0x0 0x31120000 0x0 0x100>,
> +                  <0x0 0x33000000 0x0 0x40000>;
> +            reg-names = "rt", "fifos", "proxy_gcfg", "proxy_target";
> +            ti,num-rings = <818>;
> +            ti,sci-rm-range-gp-rings = <0x2>; /* GP ring range */
> +            ti,dma-ring-reset-quirk;
> +            ti,sci = <&dmsc>;
> +            ti,sci-dev-id = <187>;
> +            msi-parent = <&inta_main_udmass>;
> +        };
> +    };
> 

I'd be very appreciated if you can provide your feedback here.

-- 
Best regards,
grygorii