Re: [PATCH] dt-bindings: fpga: Conver fpga-region binding to yaml

[Krzysztof Kozlowski]

On 12/01/2024 13:25, Michal Simek wrote:
> Convert the generic fpga region DT binding to json-schema.
> There are some differences compare to txt version.
> 1. DT overlay can't be described in example that's why directly include
> information from overlay to node which was referenced. It is visible in
> example with /* DT Overlay contains: &... */
> 
> 2. All example have been rewritten to be simpler and describe only full
> reconfiguration and partial reconfiguration with one bridge.
> Completely drop the case where fpga region can inside partial
> reconfiguration region which is already described in description
> 
> 3. Fixed some typos in descriptions compare to txt version but most of it
> is just c&p from txt file.
> 
> Signed-off-by: Michal Simek <michal.simek@xxxxxxx>
> ---
> 
> Please let me know if there is a way to describe overlays to dt root to be
> able to reference fpga region back.
> ---

..

> ---
> -[1] www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/ug/ug_partrecon.pdf
> -[2] tspace.library.utoronto.ca/bitstream/1807/67932/1/Byma_Stuart_A_201411_MAS_thesis.pdf
> -[3] https://www.xilinx.com/support/documentation/sw_manuals/xilinx14_1/ug702.pdf
> diff --git a/Documentation/devicetree/bindings/fpga/fpga-region.yaml b/Documentation/devicetree/bindings/fpga/fpga-region.yaml
> new file mode 100644
> index 000000000000..bf4bb54bfbfa
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/fpga/fpga-region.yaml
> @@ -0,0 +1,372 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)

You relicense the GPL-2.0, so you need to ask all copyright holders to
ack your patch. At least try to identify them...


> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/fpga/fpga-region.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: FPGA Region
> +
> +maintainers:
> +  - Michal Simek <michal.simek@xxxxxxx>
> +
> +description: |
> +  CONTENTS
> +   - Introduction
> +   - Terminology
> +   - Sequence
> +   - FPGA Region
> +   - Supported Use Models
> +   - Constraints


..


> +  Constraints
> +  ===========
> +
> +  It is beyond the scope of this document to fully describe all the FPGA design
> +  constraints required to make partial reconfiguration work[1] [2] [3], but a few
> +  deserve quick mention.
> +
> +  A persona must have boundary connections that line up with those of the partition
> +  or region it is designed to go into.
> +
> +  During programming, transactions through those connections must be stopped and
> +  the connections must be held at a fixed logic level.  This can be achieved by
> +  FPGA Bridges that exist on the FPGA fabric prior to the partial reconfiguration.
> +
> +  --
> +  [1] www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/ug/ug_partrecon.pdf
> +  [2] tspace.library.utoronto.ca/bitstream/1807/67932/1/Byma_Stuart_A_201411_MAS_thesis.pdf
> +  [3] https://www.xilinx.com/support/documentation/sw_manuals/xilinx14_1/ug702.pdf
> +
> +properties:
> +  $nodename:
> +    pattern: "^fpga-region([0-9]|[1-9][0-9]+)?$"

Missing -:

"^fpga-region(-([0-9]|[1-9][0-9]+))?$"


> +
> +  compatible:
> +    const: fpga-region
> +
> +  ranges: true

This does not feel right - you do not allow any unit address, so ranges
should cause warnings.

> +  "#address-cells": true
> +  "#size-cells": true
> +
> +  config-complete-timeout-us:
> +    description:
> +      The maximum time in microseconds time for the FPGA to go to operating
> +      mode after the region has been programmed.
> +
> +  encrypted-fpga-config:
> +    type: boolean
> +    description:
> +      Set if the bitstream is encrypted.
> +
> +  external-fpga-config:
> +    type: boolean
> +    description:
> +      Set if the FPGA has already been configured prior to OS boot up.
> +
> +  firmware-name:
> +    $ref: /schemas/types.yaml#/definitions/string

This already has a type: string-array. You need maxItems instead.

> +    description:
> +      Should contain the name of an FPGA image file located on the firmware
> +      search path. If this property shows up in a live device tree it indicates
> +      that the FPGA has already been programmed with this image.
> +      If this property is in an overlay targeting an FPGA region, it is
> +      a request to program the FPGA with that image.
> +
> +  fpga-bridges:
> +    $ref: /schemas/types.yaml#/definitions/phandle
> +    description:
> +      Should contain a list of phandles to FPGA Bridges that must be

This says list of phandles, but you allow only one.

> +      controlled during FPGA programming along with the parent FPGA bridge.
> +      This property is optional if the FPGA Manager handles the bridges.
> +      If the fpga-region is  the child of an fpga-bridge, the list should not
> +      contain the parent bridge.
> +
> +  fpga-mgr:
> +    $ref: /schemas/types.yaml#/definitions/phandle
> +    description:
> +      Should contain a phandle to an FPGA Manager.  Child FPGA Regions
> +      inherit this property from their ancestor regions.  An fpga-mgr property
> +      in a region will override any inherited FPGA manager.
> +
> +  partial-fpga-config:
> +    type: boolean
> +    description:
> +      Set if partial reconfiguration is to be done, otherwise full
> +      reconfiguration is done.
> +
> +  region-freeze-timeout-us:
> +    description:
> +      The maximum time in microseconds to wait for bridges to successfully
> +      become disabled before the region has been programmed.
> +
> +  region-unfreeze-timeout-us:
> +    description:
> +      The maximum time in microseconds to wait for bridges to successfully
> +      become enabled after the region has been programmed.
> +
> +patternProperties:
> +  "@[0-9a-f]+$":
> +    type: object
> +
> +required:
> +  - compatible
> +  - ranges
> +  - "#address-cells"
> +  - "#size-cells"
> +  - fpga-mgr
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    /*
> +     * Full Reconfiguration without Bridges
> +     */
> +    fpga_mgr0: fpga-mgr@f8007000 {
> +      compatible = "xlnx,zynq-devcfg-1.0";
> +      reg = <0xf8007000 0x100>;
> +      clocks = <&clkc 12>;
> +      clock-names = "ref_clk";
> +      interrupt-parent = <&intc>;
> +      interrupts = <0 8 4>;
> +      syscon = <&slcr>;
> +    };
> +
> +    fpga_region0: fpga-region0 {

fpga-region {

> +      compatible = "fpga-region";
> +      ranges;
> +      #address-cells = <1>;
> +      #size-cells = <1>;
> +      fpga-mgr = <&fpga_mgr0>;
> +
> +      /* DT Overlay contains: &fpga_region0 */
> +      firmware-name = "zynq-gpio.bin";
> +      gpio@40000000 {
> +        compatible = "xlnx,xps-gpio-1.00.a";
> +        reg = <0x40000000 0x10000>;
> +        gpio-controller;
> +        #gpio-cells = <2>;
> +      };
> +    };
> +
> +  - |
> +    /*
> +     * Partial reconfiguration with Bridges
> +     */
> +    fpga_mgr1: fpga-mgr@f8007000 {
> +      compatible = "xlnx,zynq-devcfg-1.0";
> +      reg = <0xf8007000 0x100>;
> +      clocks = <&clkc 12>;
> +      clock-names = "ref_clk";
> +      interrupt-parent = <&intc>;
> +      interrupts = <0 8 4>;
> +      syscon = <&slcr>;
> +    };
> +
> +    fpga_bridge1: fpga-bridge@100000450 {
> +      compatible = "xlnx,pr-decoupler-1.00", "xlnx,pr-decoupler";
> +      reg = <0x10000045 0x10>;
> +      clocks = <&clkc 15>;
> +      clock-names = "aclk";
> +    };
> +
> +    fpga_region1: fpga-region1 {

fpga-region {

> +      compatible = "fpga-region";


Best regards,
Krzysztof