Message-ID: <4ce186aa-2cf3-a36c-a5c5-923029b12a29@linaro.org>
Date:   Wed, 22 Feb 2023 10:24:05 +0100
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.8.0
Subject: Re: [PATCH v2] dt-bindings: fpga: xilinx-pr-decoupler: convert
 bindings to json-schema
Content-Language: en-US
To:     Nava kishore Manne <nava.kishore.manne@amd.com>, mdf@kernel.org,
        hao.wu@intel.com, yilun.xu@intel.com, trix@redhat.com,
        robh+dt@kernel.org, krzysztof.kozlowski+dt@linaro.org,
        michal.simek@xilinx.com, linux-fpga@vger.kernel.org,
        devicetree@vger.kernel.org, linux-arm-kernel@lists.infradead.org,
        linux-kernel@vger.kernel.org
References: <20230221115012.3468798-1-nava.kishore.manne@amd.com>
From:   Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
In-Reply-To: <20230221115012.3468798-1-nava.kishore.manne@amd.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 21/02/2023 12:50, Nava kishore Manne wrote:
> Convert xilinx-pr-decoupler bindings to DT schema format using json-schema
> 
> Signed-off-by: Nava kishore Manne <nava.kishore.manne@amd.com>
> ---
> Changes for v2:
>               - Updated the description and addressed some minor comments
>                 as suggested by Krzysztof.
> 
>  .../bindings/fpga/xilinx-pr-decoupler.txt     | 54 --------------
>  .../bindings/fpga/xlnx,pr-decoupler.yaml      | 71 +++++++++++++++++++
>  2 files changed, 71 insertions(+), 54 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt
>  create mode 100644 Documentation/devicetree/bindings/fpga/xlnx,pr-decoupler.yaml
> 
> diff --git a/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt b/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt
> deleted file mode 100644
> index 0acdfa6d62a4..000000000000
> --- a/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt
> +++ /dev/null
> @@ -1,54 +0,0 @@
> -Xilinx LogiCORE Partial Reconfig Decoupler Softcore
> -
> -The Xilinx LogiCORE Partial Reconfig Decoupler manages one or more
> -decouplers / fpga bridges.
> -The controller can decouple/disable the bridges which prevents signal
> -changes from passing through the bridge.  The controller can also
> -couple / enable the bridges which allows traffic to pass through the
> -bridge normally.
> -
> -Xilinx LogiCORE Dynamic Function eXchange(DFX) AXI shutdown manager
> -Softcore is compatible with the Xilinx LogiCORE pr-decoupler.
> -
> -The Dynamic Function eXchange AXI shutdown manager prevents AXI traffic
> -from passing through the bridge. The controller safely handles AXI4MM
> -and AXI4-Lite interfaces on a Reconfigurable Partition when it is
> -undergoing dynamic reconfiguration, preventing the system deadlock
> -that can occur if AXI transactions are interrupted by DFX
> -
> -The Driver supports only MMIO handling. A PR region can have multiple
> -PR Decouplers which can be handled independently or chained via decouple/
> -decouple_status signals.
> -
> -Required properties:
> -- compatible		: Should contain "xlnx,pr-decoupler-1.00" followed by
> -                          "xlnx,pr-decoupler" or
> -                          "xlnx,dfx-axi-shutdown-manager-1.00" followed by
> -                          "xlnx,dfx-axi-shutdown-manager"
> -- regs			: base address and size for decoupler module
> -- clocks		: input clock to IP
> -- clock-names		: should contain "aclk"
> -
> -See Documentation/devicetree/bindings/fpga/fpga-region.txt and
> -Documentation/devicetree/bindings/fpga/fpga-bridge.txt for generic bindings.
> -
> -Example:
> -Partial Reconfig Decoupler:
> -	fpga-bridge@100000450 {
> -		compatible = "xlnx,pr-decoupler-1.00",
> -			     "xlnx-pr-decoupler";
> -		regs = <0x10000045 0x10>;
> -		clocks = <&clkc 15>;
> -		clock-names = "aclk";
> -		bridge-enable = <0>;
> -	};
> -
> -Dynamic Function eXchange AXI shutdown manager:
> -	fpga-bridge@100000450 {
> -		compatible = "xlnx,dfx-axi-shutdown-manager-1.00",
> -			     "xlnx,dfx-axi-shutdown-manager";
> -		regs = <0x10000045 0x10>;
> -		clocks = <&clkc 15>;
> -		clock-names = "aclk";
> -		bridge-enable = <0>;
> -	};
> diff --git a/Documentation/devicetree/bindings/fpga/xlnx,pr-decoupler.yaml b/Documentation/devicetree/bindings/fpga/xlnx,pr-decoupler.yaml
> new file mode 100644
> index 000000000000..4a08d4bfa20d
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/fpga/xlnx,pr-decoupler.yaml
> @@ -0,0 +1,71 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/fpga/xlnx,pr-decoupler.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Xilinx LogiCORE Partial Reconfig Decoupler/AXI shutdown manager Softcore
> +
> +maintainers:
> +  - Nava kishore Manne <nava.kishore.manne@amd.com>
> +
> +description: The Xilinx LogiCORE Partial Reconfig Decoupler manages one or more

Blank line before text... don't use your own style. Use style consistent
with the project.

> +  decouplers / fpga bridges. The controller can decouple/disable the bridges
> +  which prevents signal changes from passing through the bridge.  The controller
> +  can also couple / enable the bridges which allows traffic to pass through the
> +  bridge normally.
> +  Xilinx LogiCORE Dynamic Function eXchange(DFX) AXI shutdown manager Softcore
> +  is compatible with the Xilinx LogiCORE pr-decoupler. The Dynamic Function
> +  eXchange AXI shutdown manager prevents AXI traffic from passing through the
> +  bridge. The controller safely handles AXI4MM and AXI4-Lite interfaces on a
> +  Reconfigurable Partition when it is undergoing dynamic reconfiguration,
> +  preventing the system deadlock that can occur if AXI transactions are
> +  interrupted by DFX.
> +  Please refer to fpga-region.txt and fpga-bridge.txt in this directory for
> +  common binding part and usage.
> +
> +properties:
> +  compatible:
> +    oneOf:
> +      - items:
> +          - const: xlnx,pr-decoupler-1.00 #For PR-Decoupler.

Drop the comment, it duplicates the compatible. There is no point in it.

> +          - const: xlnx,pr-decoupler
> +      - items:
> +          - const: xlnx,dfx-axi-shutdown-manager-1.00 #For AXI shutdown manager.

Ditto

> +          - const: xlnx,dfx-axi-shutdown-manager
> +
> +  reg:
> +    maxItems: 1
> +
> +  clocks:
> +    maxItems: 1
> +
> +  clock-names:
> +    items:
> +      - const: aclk
> +
> +  bridge-enable:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    enum: [0, 1]
> +    description:
> +      Zero if driver should disable bridge at startup. One if driver should
> +      enable bridge at startup. Default is to leave bridge in current state.

This property wasn't in original binding. Even though it is
fpga-bridge.txt, why do you need it? It's not used. Also, do not
describe driver but rather hardware.


Best regards,
Krzysztof