[v3] dt-bindings: fpga: Convert fpga-region binding to yaml

Commit Message

Michal Simek Jan. 17, 2024, 11:30 a.m. UTC

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 <[e-mail]>
---

Changes in v3:
- drop fpga bridge and mgr descriptions in example
- use additionalProperties: true
- use fixed-factor-clock instead
- fixed matching pattern

Changes in v2:
- Fix typo in subject
- Fix comment in bridge example
- Change license back to gpl-2.0 only
- Do not define firware-name type and add maxItems 1
- Make fpga-bridge phandle-array
- Drop ranges property because of missing reg property of fpga-region
- Also describe case with fixed clock node and axi bus
- Fix fpga-region names in example

Please let me know if there is a way to describe overlays to dt root to be
able to reference fpga region back.

---
 .../devicetree/bindings/fpga/fpga-region.txt  | 479 ------------------
 .../devicetree/bindings/fpga/fpga-region.yaml | 351 +++++++++++++
 2 files changed, 351 insertions(+), 479 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/fpga/fpga-region.txt
 create mode 100644 Documentation/devicetree/bindings/fpga/fpga-region.yaml

Comments

Rob Herring (Arm) Jan. 17, 2024, 9:47 p.m. UTC | #1

On Wed, Jan 17, 2024 at 12:30:58PM +0100, 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 <[e-mail]>
> ---
> 
> Changes in v3:
> - drop fpga bridge and mgr descriptions in example
> - use additionalProperties: true
> - use fixed-factor-clock instead
> - fixed matching pattern
> 
> Changes in v2:
> - Fix typo in subject
> - Fix comment in bridge example
> - Change license back to gpl-2.0 only
> - Do not define firware-name type and add maxItems 1
> - Make fpga-bridge phandle-array
> - Drop ranges property because of missing reg property of fpga-region
> - Also describe case with fixed clock node and axi bus
> - Fix fpga-region names in example
> 
> Please let me know if there is a way to describe overlays to dt root to be
> able to reference fpga region back.

No. Overlays are somewhat outside the scope of schema. Certainly not 
supported in the examples. When the dts files are free of warnings I'll 
worry about overlays. :)

> ---
>  .../devicetree/bindings/fpga/fpga-region.txt  | 479 ------------------
>  .../devicetree/bindings/fpga/fpga-region.yaml | 351 +++++++++++++
>  2 files changed, 351 insertions(+), 479 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/fpga/fpga-region.txt
>  create mode 100644 Documentation/devicetree/bindings/fpga/fpga-region.yaml


> diff --git a/Documentation/devicetree/bindings/fpga/fpga-region.yaml b/Documentation/devicetree/bindings/fpga/fpga-region.yaml
> new file mode 100644
> index 000000000000..fb6fe6f43fa8
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/fpga/fpga-region.yaml
> @@ -0,0 +1,351 @@
> +# SPDX-License-Identifier: GPL-2.0
> +%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 <[e-mail]>
> +
> +description: |
> +  CONTENTS
> +   - Introduction
> +   - Terminology
> +   - Sequence
> +   - FPGA Region
> +   - Supported Use Models
> +   - Constraints
> +
> +
> +  Introduction
> +  ============
> +
> +  FPGA Regions represent FPGA's and partial reconfiguration regions of FPGA's in
> +  the Device Tree.  FPGA Regions provide a way to program FPGAs under device tree
> +  control.
> +
> +  The documentation hits some of the high points of FPGA usage and
> +  attempts to include terminology used by both major FPGA manufacturers.  This
> +  document isn't a replacement for any manufacturers specifications for FPGA
> +  usage.
> +
> +
> +  Terminology
> +  ===========
> +
> +  Full Reconfiguration
> +   * The entire FPGA is programmed.
> +
> +  Partial Reconfiguration (PR)
> +   * A section of an FPGA is reprogrammed while the rest of the FPGA is not
> +     affected.
> +   * Not all FPGA's support PR.
> +
> +  Partial Reconfiguration Region (PRR)
> +   * Also called a "reconfigurable partition"
> +   * A PRR is a specific section of an FPGA reserved for reconfiguration.
> +   * A base (or static) FPGA image may create a set of PRR's that later may
> +     be independently reprogrammed many times.
> +   * The size and specific location of each PRR is fixed.
> +   * The connections at the edge of each PRR are fixed.  The image that is loaded
> +     into a PRR must fit and must use a subset of the region's connections.
> +   * The busses within the FPGA are split such that each region gets its own
> +     branch that may be gated independently.
> +
> +  Persona
> +   * Also called a "partial bit stream"
> +   * An FPGA image that is designed to be loaded into a PRR.  There may be
> +     any number of personas designed to fit into a PRR, but only one at a time
> +     may be loaded.
> +   * A persona may create more regions.
> +
> +  FPGA Bridge
> +   * FPGA Bridges gate bus signals between a host and FPGA.
> +   * FPGA Bridges should be disabled while the FPGA is being programmed to
> +     prevent spurious signals on the cpu bus and to the soft logic.
> +   * FPGA bridges may be actual hardware or soft logic on an FPGA.
> +   * During Full Reconfiguration, hardware bridges between the host and FPGA
> +     will be disabled.
> +   * During Partial Reconfiguration of a specific region, that region's bridge
> +     will be used to gate the busses.  Traffic to other regions is not affected.
> +   * In some implementations, the FPGA Manager transparently handles gating the
> +     buses, eliminating the need to show the hardware FPGA bridges in the
> +     device tree.
> +   * An FPGA image may create a set of reprogrammable regions, each having its
> +     own bridge and its own split of the busses in the FPGA.
> +
> +  FPGA Manager
> +   * An FPGA Manager is a hardware block that programs an FPGA under the control
> +     of a host processor.
> +
> +  Base Image
> +   * Also called the "static image"
> +   * An FPGA image that is designed to do full reconfiguration of the FPGA.
> +   * A base image may set up a set of partial reconfiguration regions that may
> +     later be reprogrammed.
> +
> +      ----------------       ----------------------------------
> +      |  Host CPU    |       |             FPGA               |
> +      |              |       |                                |
> +      |          ----|       |       -----------    --------  |
> +      |          | H |       |   |==>| Bridge0 |<==>| PRR0 |  |
> +      |          | W |       |   |   -----------    --------  |
> +      |          |   |       |   |                            |
> +      |          | B |<=====>|<==|   -----------    --------  |
> +      |          | R |       |   |==>| Bridge1 |<==>| PRR1 |  |
> +      |          | I |       |   |   -----------    --------  |
> +      |          | D |       |   |                            |
> +      |          | G |       |   |   -----------    --------  |
> +      |          | E |       |   |==>| Bridge2 |<==>| PRR2 |  |
> +      |          ----|       |       -----------    --------  |
> +      |              |       |                                |
> +      ----------------       ----------------------------------
> +
> +  Figure 1: An FPGA set up with a base image that created three regions.  Each
> +  region (PRR0-2) gets its own split of the busses that is independently gated by
> +  a soft logic bridge (Bridge0-2) in the FPGA.  The contents of each PRR can be
> +  reprogrammed independently while the rest of the system continues to function.
> +
> +
> +  Sequence
> +  ========
> +
> +  When a DT overlay that targets an FPGA Region is applied, the FPGA Region will
> +  do the following:
> +
> +   1. Disable appropriate FPGA bridges.
> +   2. Program the FPGA using the FPGA manager.
> +   3. Enable the FPGA bridges.
> +   4. The Device Tree overlay is accepted into the live tree.
> +   5. Child devices are populated.
> +
> +  When the overlay is removed, the child nodes will be removed and the FPGA Region
> +  will disable the bridges.
> +
> +
> +  FPGA Region
> +  ===========
> +
> +  FPGA Regions represent FPGA's and FPGA PR regions in the device tree.  An FPGA
> +  Region brings together the elements needed to program on a running system and
> +  add the child devices:
> +
> +   * FPGA Manager
> +   * FPGA Bridges
> +   * image-specific information needed to the programming.
> +   * child nodes
> +
> +  The intended use is that a Device Tree overlay (DTO) can be used to reprogram an
> +  FPGA while an operating system is running.
> +
> +  An FPGA Region that exists in the live Device Tree reflects the current state.
> +  If the live tree shows a "firmware-name" property or child nodes under an FPGA
> +  Region, the FPGA already has been programmed.  A DTO that targets an FPGA Region
> +  and adds the "firmware-name" property is taken as a request to reprogram the
> +  FPGA.  After reprogramming is successful, the overlay is accepted into the live
> +  tree.
> +
> +  The base FPGA Region in the device tree represents the FPGA and supports full
> +  reconfiguration.  It must include a phandle to an FPGA Manager.  The base
> +  FPGA region will be the child of one of the hardware bridges (the bridge that
> +  allows register access) between the cpu and the FPGA.  If there are more than
> +  one bridge to control during FPGA programming, the region will also contain a
> +  list of phandles to the additional hardware FPGA Bridges.
> +
> +  For partial reconfiguration (PR), each PR region will have an FPGA Region.
> +  These FPGA regions are children of FPGA bridges which are then children of the
> +  base FPGA region.  The "Full Reconfiguration to add PRR's" example below shows
> +  this.
> +
> +  If an FPGA Region does not specify an FPGA Manager, it will inherit the FPGA
> +  Manager specified by its ancestor FPGA Region.  This supports both the case
> +  where the same FPGA Manager is used for all of an FPGA as well the case where
> +  a different FPGA Manager is used for each region.
> +
> +  FPGA Regions do not inherit their ancestor FPGA regions' bridges.  This prevents
> +  shutting down bridges that are upstream from the other active regions while one
> +  region is getting reconfigured (see Figure 1 above).  During PR, the FPGA's
> +  hardware bridges remain enabled.  The PR regions' bridges will be FPGA bridges
> +  within the static image of the FPGA.
> +
> +
> +  Supported Use Models
> +  ====================
> +
> +  In all cases the live DT must have the FPGA Manager, FPGA Bridges (if any), and
> +  a FPGA Region.  The target of the Device Tree Overlay is the FPGA Region.  Some
> +  uses are specific to an FPGA device.
> +
> +   * No FPGA Bridges
> +     In this case, the FPGA Manager which programs the FPGA also handles the
> +     bridges behind the scenes.  No FPGA Bridge devices are needed for full
> +     reconfiguration.
> +
> +   * Full reconfiguration with hardware bridges
> +     In this case, there are hardware bridges between the processor and FPGA that
> +     need to be controlled during full reconfiguration.  Before the overlay is
> +     applied, the live DT must include the FPGA Manager, FPGA Bridges, and a
> +     FPGA Region.  The FPGA Region is the child of the bridge that allows
> +     register access to the FPGA.  Additional bridges may be listed in a
> +     fpga-bridges property in the FPGA region or in the device tree overlay.
> +
> +   * Partial reconfiguration with bridges in the FPGA
> +     In this case, the FPGA will have one or more PRR's that may be programmed
> +     separately while the rest of the FPGA can remain active.  To manage this,
> +     bridges need to exist in the FPGA that can gate the buses going to each FPGA
> +     region while the buses are enabled for other sections.  Before any partial
> +     reconfiguration can be done, a base FPGA image must be loaded which includes
> +     PRR's with FPGA bridges.  The device tree should have an FPGA region for each
> +     PRR.
> +
> +  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]+))?$"
> +
> +  compatible:
> +    const: fpga-region
> +
> +  "#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:
> +    maxItems: 1
> +    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-array
> +    description:
> +      Should contain a list of phandles to FPGA Bridges that must be
> +      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.
> +
> +required:
> +  - compatible
> +  - "#address-cells"
> +  - "#size-cells"
> +  - fpga-mgr
> +
> +additionalProperties: true

Why? This should only be used if another schema is going to include this 
one. That's not the case here.

'type: object' would be acceptable here as that says only nodes can be 
added.

> +
> +examples:
> +  - |
> +    /*
> +     * Full Reconfiguration without Bridges with DT overlay
> +     */
> +    fpga_region0: fpga-region {

Drop unused labels.

> +      compatible = "fpga-region";
> +      #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>;

This example implies this is a translatable address, but the lack of 
'ranges' in the parent prevents that. In turn, that means unit-addresses 
should be accepted in the parent node name as well.

Rob

Michal Simek Jan. 18, 2024, 12:34 p.m. UTC | #2

On 1/17/24 22:47, Rob Herring wrote:
> On Wed, Jan 17, 2024 at 12:30:58PM +0100, 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 <[e-mail]>
>> ---
>>
>> Changes in v3:
>> - drop fpga bridge and mgr descriptions in example
>> - use additionalProperties: true
>> - use fixed-factor-clock instead
>> - fixed matching pattern
>>
>> Changes in v2:
>> - Fix typo in subject
>> - Fix comment in bridge example
>> - Change license back to gpl-2.0 only
>> - Do not define firware-name type and add maxItems 1
>> - Make fpga-bridge phandle-array
>> - Drop ranges property because of missing reg property of fpga-region
>> - Also describe case with fixed clock node and axi bus
>> - Fix fpga-region names in example
>>
>> Please let me know if there is a way to describe overlays to dt root to be
>> able to reference fpga region back.
> 
> No. Overlays are somewhat outside the scope of schema. Certainly not
> supported in the examples. When the dts files are free of warnings I'll
> worry about overlays. :)
> 
>> ---
>>   .../devicetree/bindings/fpga/fpga-region.txt  | 479 ------------------
>>   .../devicetree/bindings/fpga/fpga-region.yaml | 351 +++++++++++++
>>   2 files changed, 351 insertions(+), 479 deletions(-)
>>   delete mode 100644 Documentation/devicetree/bindings/fpga/fpga-region.txt
>>   create mode 100644 Documentation/devicetree/bindings/fpga/fpga-region.yaml
> 
> 
>> diff --git a/Documentation/devicetree/bindings/fpga/fpga-region.yaml b/Documentation/devicetree/bindings/fpga/fpga-region.yaml
>> new file mode 100644
>> index 000000000000..fb6fe6f43fa8
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/fpga/fpga-region.yaml
>> @@ -0,0 +1,351 @@
>> +# SPDX-License-Identifier: GPL-2.0
>> +%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 <[e-mail]>
>> +
>> +description: |
>> +  CONTENTS
>> +   - Introduction
>> +   - Terminology
>> +   - Sequence
>> +   - FPGA Region
>> +   - Supported Use Models
>> +   - Constraints
>> +
>> +
>> +  Introduction
>> +  ============
>> +
>> +  FPGA Regions represent FPGA's and partial reconfiguration regions of FPGA's in
>> +  the Device Tree.  FPGA Regions provide a way to program FPGAs under device tree
>> +  control.
>> +
>> +  The documentation hits some of the high points of FPGA usage and
>> +  attempts to include terminology used by both major FPGA manufacturers.  This
>> +  document isn't a replacement for any manufacturers specifications for FPGA
>> +  usage.
>> +
>> +
>> +  Terminology
>> +  ===========
>> +
>> +  Full Reconfiguration
>> +   * The entire FPGA is programmed.
>> +
>> +  Partial Reconfiguration (PR)
>> +   * A section of an FPGA is reprogrammed while the rest of the FPGA is not
>> +     affected.
>> +   * Not all FPGA's support PR.
>> +
>> +  Partial Reconfiguration Region (PRR)
>> +   * Also called a "reconfigurable partition"
>> +   * A PRR is a specific section of an FPGA reserved for reconfiguration.
>> +   * A base (or static) FPGA image may create a set of PRR's that later may
>> +     be independently reprogrammed many times.
>> +   * The size and specific location of each PRR is fixed.
>> +   * The connections at the edge of each PRR are fixed.  The image that is loaded
>> +     into a PRR must fit and must use a subset of the region's connections.
>> +   * The busses within the FPGA are split such that each region gets its own
>> +     branch that may be gated independently.
>> +
>> +  Persona
>> +   * Also called a "partial bit stream"
>> +   * An FPGA image that is designed to be loaded into a PRR.  There may be
>> +     any number of personas designed to fit into a PRR, but only one at a time
>> +     may be loaded.
>> +   * A persona may create more regions.
>> +
>> +  FPGA Bridge
>> +   * FPGA Bridges gate bus signals between a host and FPGA.
>> +   * FPGA Bridges should be disabled while the FPGA is being programmed to
>> +     prevent spurious signals on the cpu bus and to the soft logic.
>> +   * FPGA bridges may be actual hardware or soft logic on an FPGA.
>> +   * During Full Reconfiguration, hardware bridges between the host and FPGA
>> +     will be disabled.
>> +   * During Partial Reconfiguration of a specific region, that region's bridge
>> +     will be used to gate the busses.  Traffic to other regions is not affected.
>> +   * In some implementations, the FPGA Manager transparently handles gating the
>> +     buses, eliminating the need to show the hardware FPGA bridges in the
>> +     device tree.
>> +   * An FPGA image may create a set of reprogrammable regions, each having its
>> +     own bridge and its own split of the busses in the FPGA.
>> +
>> +  FPGA Manager
>> +   * An FPGA Manager is a hardware block that programs an FPGA under the control
>> +     of a host processor.
>> +
>> +  Base Image
>> +   * Also called the "static image"
>> +   * An FPGA image that is designed to do full reconfiguration of the FPGA.
>> +   * A base image may set up a set of partial reconfiguration regions that may
>> +     later be reprogrammed.
>> +
>> +      ----------------       ----------------------------------
>> +      |  Host CPU    |       |             FPGA               |
>> +      |              |       |                                |
>> +      |          ----|       |       -----------    --------  |
>> +      |          | H |       |   |==>| Bridge0 |<==>| PRR0 |  |
>> +      |          | W |       |   |   -----------    --------  |
>> +      |          |   |       |   |                            |
>> +      |          | B |<=====>|<==|   -----------    --------  |
>> +      |          | R |       |   |==>| Bridge1 |<==>| PRR1 |  |
>> +      |          | I |       |   |   -----------    --------  |
>> +      |          | D |       |   |                            |
>> +      |          | G |       |   |   -----------    --------  |
>> +      |          | E |       |   |==>| Bridge2 |<==>| PRR2 |  |
>> +      |          ----|       |       -----------    --------  |
>> +      |              |       |                                |
>> +      ----------------       ----------------------------------
>> +
>> +  Figure 1: An FPGA set up with a base image that created three regions.  Each
>> +  region (PRR0-2) gets its own split of the busses that is independently gated by
>> +  a soft logic bridge (Bridge0-2) in the FPGA.  The contents of each PRR can be
>> +  reprogrammed independently while the rest of the system continues to function.
>> +
>> +
>> +  Sequence
>> +  ========
>> +
>> +  When a DT overlay that targets an FPGA Region is applied, the FPGA Region will
>> +  do the following:
>> +
>> +   1. Disable appropriate FPGA bridges.
>> +   2. Program the FPGA using the FPGA manager.
>> +   3. Enable the FPGA bridges.
>> +   4. The Device Tree overlay is accepted into the live tree.
>> +   5. Child devices are populated.
>> +
>> +  When the overlay is removed, the child nodes will be removed and the FPGA Region
>> +  will disable the bridges.
>> +
>> +
>> +  FPGA Region
>> +  ===========
>> +
>> +  FPGA Regions represent FPGA's and FPGA PR regions in the device tree.  An FPGA
>> +  Region brings together the elements needed to program on a running system and
>> +  add the child devices:
>> +
>> +   * FPGA Manager
>> +   * FPGA Bridges
>> +   * image-specific information needed to the programming.
>> +   * child nodes
>> +
>> +  The intended use is that a Device Tree overlay (DTO) can be used to reprogram an
>> +  FPGA while an operating system is running.
>> +
>> +  An FPGA Region that exists in the live Device Tree reflects the current state.
>> +  If the live tree shows a "firmware-name" property or child nodes under an FPGA
>> +  Region, the FPGA already has been programmed.  A DTO that targets an FPGA Region
>> +  and adds the "firmware-name" property is taken as a request to reprogram the
>> +  FPGA.  After reprogramming is successful, the overlay is accepted into the live
>> +  tree.
>> +
>> +  The base FPGA Region in the device tree represents the FPGA and supports full
>> +  reconfiguration.  It must include a phandle to an FPGA Manager.  The base
>> +  FPGA region will be the child of one of the hardware bridges (the bridge that
>> +  allows register access) between the cpu and the FPGA.  If there are more than
>> +  one bridge to control during FPGA programming, the region will also contain a
>> +  list of phandles to the additional hardware FPGA Bridges.
>> +
>> +  For partial reconfiguration (PR), each PR region will have an FPGA Region.
>> +  These FPGA regions are children of FPGA bridges which are then children of the
>> +  base FPGA region.  The "Full Reconfiguration to add PRR's" example below shows
>> +  this.
>> +
>> +  If an FPGA Region does not specify an FPGA Manager, it will inherit the FPGA
>> +  Manager specified by its ancestor FPGA Region.  This supports both the case
>> +  where the same FPGA Manager is used for all of an FPGA as well the case where
>> +  a different FPGA Manager is used for each region.
>> +
>> +  FPGA Regions do not inherit their ancestor FPGA regions' bridges.  This prevents
>> +  shutting down bridges that are upstream from the other active regions while one
>> +  region is getting reconfigured (see Figure 1 above).  During PR, the FPGA's
>> +  hardware bridges remain enabled.  The PR regions' bridges will be FPGA bridges
>> +  within the static image of the FPGA.
>> +
>> +
>> +  Supported Use Models
>> +  ====================
>> +
>> +  In all cases the live DT must have the FPGA Manager, FPGA Bridges (if any), and
>> +  a FPGA Region.  The target of the Device Tree Overlay is the FPGA Region.  Some
>> +  uses are specific to an FPGA device.
>> +
>> +   * No FPGA Bridges
>> +     In this case, the FPGA Manager which programs the FPGA also handles the
>> +     bridges behind the scenes.  No FPGA Bridge devices are needed for full
>> +     reconfiguration.
>> +
>> +   * Full reconfiguration with hardware bridges
>> +     In this case, there are hardware bridges between the processor and FPGA that
>> +     need to be controlled during full reconfiguration.  Before the overlay is
>> +     applied, the live DT must include the FPGA Manager, FPGA Bridges, and a
>> +     FPGA Region.  The FPGA Region is the child of the bridge that allows
>> +     register access to the FPGA.  Additional bridges may be listed in a
>> +     fpga-bridges property in the FPGA region or in the device tree overlay.
>> +
>> +   * Partial reconfiguration with bridges in the FPGA
>> +     In this case, the FPGA will have one or more PRR's that may be programmed
>> +     separately while the rest of the FPGA can remain active.  To manage this,
>> +     bridges need to exist in the FPGA that can gate the buses going to each FPGA
>> +     region while the buses are enabled for other sections.  Before any partial
>> +     reconfiguration can be done, a base FPGA image must be loaded which includes
>> +     PRR's with FPGA bridges.  The device tree should have an FPGA region for each
>> +     PRR.
>> +
>> +  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]+))?$"
>> +
>> +  compatible:
>> +    const: fpga-region
>> +
>> +  "#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:
>> +    maxItems: 1
>> +    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-array
>> +    description:
>> +      Should contain a list of phandles to FPGA Bridges that must be
>> +      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.
>> +
>> +required:
>> +  - compatible
>> +  - "#address-cells"
>> +  - "#size-cells"
>> +  - fpga-mgr
>> +
>> +additionalProperties: true
> 
> Why? This should only be used if another schema is going to include this
> one. That's not the case here.

In v2 we discussed this with Krzysztof. I used pattern properties from 
simple-bus.yaml in v2.

https://lore.kernel.org/all/[e-mail]/

> 
> 'type: object' would be acceptable here as that says only nodes can be
> added.

What do you think should be patternProperties in this case?

I played with it a little bit but all nodes with @ are likely object type.
But what to do with others?
There are nodes as you see in examples like fixed-factor-clock nodes which are 
also object type.

Standard property like firmware-name or encrypted-fpga-config are coming via 
overlay for sure. Others are not permitted. That's why others then listed 
properties likely must be type object. Is there an elegant way to encode it?

> 
>> +
>> +examples:
>> +  - |
>> +    /*
>> +     * Full Reconfiguration without Bridges with DT overlay
>> +     */
>> +    fpga_region0: fpga-region {
> 
> Drop unused labels.

Actually it is kind of used. I kept it to be able to reference something in 
comment below.

> 
>> +      compatible = "fpga-region";
>> +      #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>;
> 
> This example implies this is a translatable address, but the lack of
> 'ranges' in the parent prevents that. In turn, that means unit-addresses
> should be accepted in the parent node name as well.

v1 contains ranges property and it was removed based on Krzysztof comment that 
fpga-region has no unit address that's why ranges shouldn't be used.

https://lore.kernel.org/all/[e-mail]/

Thanks,
Michal

Rob Herring (Arm) Jan. 19, 2024, 11:32 p.m. UTC | #3

On Thu, Jan 18, 2024 at 01:34:16PM +0100, Michal Simek wrote:
> 
> 
> On 1/17/24 22:47, Rob Herring wrote:
> > On Wed, Jan 17, 2024 at 12:30:58PM +0100, 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 <[e-mail]>

[...]

> > > +additionalProperties: true
> > 
> > Why? This should only be used if another schema is going to include this
> > one. That's not the case here.
> 
> In v2 we discussed this with Krzysztof. I used pattern properties from
> simple-bus.yaml in v2.
> 
> https://lore.kernel.org/all/[e-mail]/

You didn't answer his question. You just picked up 
'additionalProperties: true' which is easy because it avoids 'problems'.

His question was is this a common schema referenced by other schemas? If 
so, then use 'additionalProperties: true'. But it is not. You've 
defined exactly what 'compatible' must be and that means it can't be a 
common schema.

> 
> > 
> > 'type: object' would be acceptable here as that says only nodes can be
> > added.
> 
> What do you think should be patternProperties in this case?

You are the one with FPGAs, what do you need?


> I played with it a little bit but all nodes with @ are likely object type.

'@' is only allowed in node names, so it's more than just likely.

> But what to do with others?
> There are nodes as you see in examples like fixed-factor-clock nodes which
> are also object type.

Then the node names can be anything and you should use what I suggested.

> Standard property like firmware-name or encrypted-fpga-config are coming via
> overlay for sure. Others are not permitted. That's why others then listed
> properties likely must be type object. Is there an elegant way to encode it?

Sorry, I don't follow. You should list every possible property, then the 
only thing left are nodes and my suggestion covers them. If there's a 
pattern to the node names, then you can use patternProperties.

> > > +
> > > +examples:
> > > +  - |
> > > +    /*
> > > +     * Full Reconfiguration without Bridges with DT overlay
> > > +     */
> > > +    fpga_region0: fpga-region {
> > 
> > Drop unused labels.
> 
> Actually it is kind of used. I kept it to be able to reference something in
> comment below.

Okay. Kind of outside the scope of examples and schema as I mentioned.


> > > +      compatible = "fpga-region";
> > > +      #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>;
> > 
> > This example implies this is a translatable address, but the lack of
> > 'ranges' in the parent prevents that. In turn, that means unit-addresses
> > should be accepted in the parent node name as well.
> 
> v1 contains ranges property and it was removed based on Krzysztof comment
> that fpga-region has no unit address that's why ranges shouldn't be used.
> 
> https://lore.kernel.org/all/[e-mail]/

Plain "ranges;" does not have a unit-address. But really, you should 
allow a non-empty ranges too and therefore allow for a unit-address.

Rob

Krzysztof Kozlowski Jan. 25, 2024, 11:02 a.m. UTC | #4

On 20/01/2024 00:32, Rob Herring wrote:
> On Thu, Jan 18, 2024 at 01:34:16PM +0100, Michal Simek wrote:
>>
>>
>> On 1/17/24 22:47, Rob Herring wrote:
>>> On Wed, Jan 17, 2024 at 12:30:58PM +0100, Michal Simek wrote:

> 
>>>> +additionalProperties: true
>>>
>>> Why? This should only be used if another schema is going to include this
>>> one. That's not the case here.
>>
>> In v2 we discussed this with Krzysztof. I used pattern properties from
>> simple-bus.yaml in v2.
>>
>> https://lore.kernel.org/all/[e-mail]/
> 
> You didn't answer his question. You just picked up 
> 'additionalProperties: true' which is easy because it avoids 'problems'.
> 
> His question was is this a common schema referenced by other schemas? If 
> so, then use 'additionalProperties: true'. But it is not. You've 
> defined exactly what 'compatible' must be and that means it can't be a 
> common schema.

Yes, I missed that it has a compatible, so it is not expected to be
referenced from other schema, thus it should end with
'additionalProperties: false'.

Best regards,
Krzysztof

Michal Simek Jan. 25, 2024, 11:47 a.m. UTC | #5

On 1/25/24 12:02, Krzysztof Kozlowski wrote:
> On 20/01/2024 00:32, Rob Herring wrote:
>> On Thu, Jan 18, 2024 at 01:34:16PM +0100, Michal Simek wrote:
>>>
>>>
>>> On 1/17/24 22:47, Rob Herring wrote:
>>>> On Wed, Jan 17, 2024 at 12:30:58PM +0100, Michal Simek wrote:
> 
>>
>>>>> +additionalProperties: true
>>>>
>>>> Why? This should only be used if another schema is going to include this
>>>> one. That's not the case here.
>>>
>>> In v2 we discussed this with Krzysztof. I used pattern properties from
>>> simple-bus.yaml in v2.
>>>
>>> https://lore.kernel.org/all/[e-mail]/
>>
>> You didn't answer his question. You just picked up
>> 'additionalProperties: true' which is easy because it avoids 'problems'.
>>
>> His question was is this a common schema referenced by other schemas? If
>> so, then use 'additionalProperties: true'. But it is not. You've
>> defined exactly what 'compatible' must be and that means it can't be a
>> common schema.
> 
> Yes, I missed that it has a compatible, so it is not expected to be
> referenced from other schema, thus it should end with
> 'additionalProperties: false'.

I think out of listed properties only nodes with and without regs can be 
present. The only thing is how to encode it.
Do you have any suggestion how to describe it?

Thanks,
Michal

Patch

diff --git a/Documentation/devicetree/bindings/fpga/fpga-region.txt b/Documentation/devicetree/bindings/fpga/fpga-region.txt
deleted file mode 100644
index 528df8a0e6d8..000000000000
--- a/Documentation/devicetree/bindings/fpga/fpga-region.txt
+++ /dev/null
@@ -1,479 +0,0 @@ 
-FPGA Region Device Tree Binding
-
-Alan Tull 2016
-
- CONTENTS
- - Introduction
- - Terminology
- - Sequence
- - FPGA Region
- - Supported Use Models
- - Device Tree Examples
- - Constraints
-
-
-Introduction
-============
-
-FPGA Regions represent FPGA's and partial reconfiguration regions of FPGA's in
-the Device Tree.  FPGA Regions provide a way to program FPGAs under device tree
-control.
-
-This device tree binding document hits some of the high points of FPGA usage and
-attempts to include terminology used by both major FPGA manufacturers.  This
-document isn't a replacement for any manufacturers specifications for FPGA
-usage.
-
-
-Terminology
-===========
-
-Full Reconfiguration
- * The entire FPGA is programmed.
-
-Partial Reconfiguration (PR)
- * A section of an FPGA is reprogrammed while the rest of the FPGA is not
-   affected.
- * Not all FPGA's support PR.
-
-Partial Reconfiguration Region (PRR)
- * Also called a "reconfigurable partition"
- * A PRR is a specific section of an FPGA reserved for reconfiguration.
- * A base (or static) FPGA image may create a set of PRR's that later may
-   be independently reprogrammed many times.
- * The size and specific location of each PRR is fixed.
- * The connections at the edge of each PRR are fixed.  The image that is loaded
-   into a PRR must fit and must use a subset of the region's connections.
- * The busses within the FPGA are split such that each region gets its own
-   branch that may be gated independently.
-
-Persona
- * Also called a "partial bit stream"
- * An FPGA image that is designed to be loaded into a PRR.  There may be
-   any number of personas designed to fit into a PRR, but only one at at time
-   may be loaded.
- * A persona may create more regions.
-
-FPGA Bridge
- * FPGA Bridges gate bus signals between a host and FPGA.
- * FPGA Bridges should be disabled while the FPGA is being programmed to
-   prevent spurious signals on the cpu bus and to the soft logic.
- * FPGA bridges may be actual hardware or soft logic on an FPGA.
- * During Full Reconfiguration, hardware bridges between the host and FPGA
-   will be disabled.
- * During Partial Reconfiguration of a specific region, that region's bridge
-   will be used to gate the busses.  Traffic to other regions is not affected.
- * In some implementations, the FPGA Manager transparently handles gating the
-   buses, eliminating the need to show the hardware FPGA bridges in the
-   device tree.
- * An FPGA image may create a set of reprogrammable regions, each having its
-   own bridge and its own split of the busses in the FPGA.
-
-FPGA Manager
- * An FPGA Manager is a hardware block that programs an FPGA under the control
-   of a host processor.
-
-Base Image
- * Also called the "static image"
- * An FPGA image that is designed to do full reconfiguration of the FPGA.
- * A base image may set up a set of partial reconfiguration regions that may
-   later be reprogrammed.
-
-    ----------------       ----------------------------------
-    |  Host CPU    |       |             FPGA               |
-    |              |       |                                |
-    |          ----|       |       -----------    --------  |
-    |          | H |       |   |==>| Bridge0 |<==>| PRR0 |  |
-    |          | W |       |   |   -----------    --------  |
-    |          |   |       |   |                            |
-    |          | B |<=====>|<==|   -----------    --------  |
-    |          | R |       |   |==>| Bridge1 |<==>| PRR1 |  |
-    |          | I |       |   |   -----------    --------  |
-    |          | D |       |   |                            |
-    |          | G |       |   |   -----------    --------  |
-    |          | E |       |   |==>| Bridge2 |<==>| PRR2 |  |
-    |          ----|       |       -----------    --------  |
-    |              |       |                                |
-    ----------------       ----------------------------------
-
-Figure 1: An FPGA set up with a base image that created three regions.  Each
-region (PRR0-2) gets its own split of the busses that is independently gated by
-a soft logic bridge (Bridge0-2) in the FPGA.  The contents of each PRR can be
-reprogrammed independently while the rest of the system continues to function.
-
-
-Sequence
-========
-
-When a DT overlay that targets an FPGA Region is applied, the FPGA Region will
-do the following:
-
- 1. Disable appropriate FPGA bridges.
- 2. Program the FPGA using the FPGA manager.
- 3. Enable the FPGA bridges.
- 4. The Device Tree overlay is accepted into the live tree.
- 5. Child devices are populated.
-
-When the overlay is removed, the child nodes will be removed and the FPGA Region
-will disable the bridges.
-
-
-FPGA Region
-===========
-
-FPGA Regions represent FPGA's and FPGA PR regions in the device tree.  An FPGA
-Region brings together the elements needed to program on a running system and
-add the child devices:
-
- * FPGA Manager
- * FPGA Bridges
- * image-specific information needed to to the programming.
- * child nodes
-
-The intended use is that a Device Tree overlay (DTO) can be used to reprogram an
-FPGA while an operating system is running.
-
-An FPGA Region that exists in the live Device Tree reflects the current state.
-If the live tree shows a "firmware-name" property or child nodes under an FPGA
-Region, the FPGA already has been programmed.  A DTO that targets an FPGA Region
-and adds the "firmware-name" property is taken as a request to reprogram the
-FPGA.  After reprogramming is successful, the overlay is accepted into the live
-tree.
-
-The base FPGA Region in the device tree represents the FPGA and supports full
-reconfiguration.  It must include a phandle to an FPGA Manager.  The base
-FPGA region will be the child of one of the hardware bridges (the bridge that
-allows register access) between the cpu and the FPGA.  If there are more than
-one bridge to control during FPGA programming, the region will also contain a
-list of phandles to the additional hardware FPGA Bridges.
-
-For partial reconfiguration (PR), each PR region will have an FPGA Region.
-These FPGA regions are children of FPGA bridges which are then children of the
-base FPGA region.  The "Full Reconfiguration to add PRR's" example below shows
-this.
-
-If an FPGA Region does not specify an FPGA Manager, it will inherit the FPGA
-Manager specified by its ancestor FPGA Region.  This supports both the case
-where the same FPGA Manager is used for all of an FPGA as well the case where
-a different FPGA Manager is used for each region.
-
-FPGA Regions do not inherit their ancestor FPGA regions' bridges.  This prevents
-shutting down bridges that are upstream from the other active regions while one
-region is getting reconfigured (see Figure 1 above).  During PR, the FPGA's
-hardware bridges remain enabled.  The PR regions' bridges will be FPGA bridges
-within the static image of the FPGA.
-
-Required properties:
-- compatible : should contain "fpga-region"
-- fpga-mgr : 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.
-- #address-cells, #size-cells, ranges : must be present to handle address space
-	mapping for child nodes.
-
-Optional properties:
-- firmware-name : 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 : should contain a list of phandles to FPGA Bridges that must be
-	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.
-- partial-fpga-config : boolean, set if partial reconfiguration is to be done,
-	otherwise full reconfiguration is done.
-- external-fpga-config : boolean, set if the FPGA has already been configured
-	prior to OS boot up.
-- encrypted-fpga-config : boolean, set if the bitstream is encrypted
-- region-unfreeze-timeout-us : The maximum time in microseconds to wait for
-	bridges to successfully become enabled after the region has been
-	programmed.
-- region-freeze-timeout-us : The maximum time in microseconds to wait for
-	bridges to successfully become disabled before the region has been
-	programmed.
-- config-complete-timeout-us : The maximum time in microseconds time for the
-	FPGA to go to operating mode after the region has been programmed.
-- child nodes : devices in the FPGA after programming.
-
-In the example below, when an overlay is applied targeting fpga-region0,
-fpga_mgr is used to program the FPGA.  Two bridges are controlled during
-programming: the parent fpga_bridge0 and fpga_bridge1.  Because the region is
-the child of fpga_bridge0, only fpga_bridge1 needs to be specified in the
-fpga-bridges property.  During programming, these bridges are disabled, the
-firmware specified in the overlay is loaded to the FPGA using the FPGA manager
-specified in the region.  If FPGA programming succeeds, the bridges are
-reenabled and the overlay makes it into the live device tree.  The child devices
-are then populated.  If FPGA programming fails, the bridges are left disabled
-and the overlay is rejected.  The overlay's ranges property maps the lwhps
-bridge's region (0xff200000) and the hps bridge's region (0xc0000000) for use by
-the two child devices.
-
-Example:
-Base tree contains:
-
-	fpga_mgr: fpga-mgr@ff706000 {
-		compatible = "altr,socfpga-fpga-mgr";
-		reg = <0xff706000 0x1000
-		       0xffb90000 0x20>;
-		interrupts = <0 175 4>;
-	};
-
-	fpga_bridge0: fpga-bridge@ff400000 {
-		compatible = "altr,socfpga-lwhps2fpga-bridge";
-		reg = <0xff400000 0x100000>;
-		resets = <&rst LWHPS2FPGA_RESET>;
-		clocks = <&l4_main_clk>;
-
-		#address-cells = <1>;
-		#size-cells = <1>;
-		ranges;
-
-		fpga_region0: fpga-region0 {
-			compatible = "fpga-region";
-			fpga-mgr = <&fpga_mgr>;
-		};
-	};
-
-	fpga_bridge1: fpga-bridge@ff500000 {
-		compatible = "altr,socfpga-hps2fpga-bridge";
-		reg = <0xff500000 0x10000>;
-		resets = <&rst HPS2FPGA_RESET>;
-		clocks = <&l4_main_clk>;
-	};
-
-Overlay contains:
-
-/dts-v1/;
-/plugin/;
-
-&fpga_region0 {
-	#address-cells = <1>;
-	#size-cells = <1>;
-
-	firmware-name = "soc_system.rbf";
-	fpga-bridges = <&fpga_bridge1>;
-	ranges = <0x20000 0xff200000 0x100000>,
-		 <0x0 0xc0000000 0x20000000>;
-
-	gpio@10040 {
-		compatible = "altr,pio-1.0";
-		reg = <0x10040 0x20>;
-		altr,ngpio = <4>;
-		#gpio-cells = <2>;
-		clocks = <2>;
-		gpio-controller;
-	};
-
-	onchip-memory {
-		device_type = "memory";
-		compatible = "altr,onchipmem-15.1";
-		reg = <0x0 0x10000>;
-	};
-};
-
-
-Supported Use Models
-====================
-
-In all cases the live DT must have the FPGA Manager, FPGA Bridges (if any), and
-a FPGA Region.  The target of the Device Tree Overlay is the FPGA Region.  Some
-uses are specific to an FPGA device.
-
- * No FPGA Bridges
-   In this case, the FPGA Manager which programs the FPGA also handles the
-   bridges behind the scenes.  No FPGA Bridge devices are needed for full
-   reconfiguration.
-
- * Full reconfiguration with hardware bridges
-   In this case, there are hardware bridges between the processor and FPGA that
-   need to be controlled during full reconfiguration.  Before the overlay is
-   applied, the live DT must include the FPGA Manager, FPGA Bridges, and a
-   FPGA Region.  The FPGA Region is the child of the bridge that allows
-   register access to the FPGA.  Additional bridges may be listed in a
-   fpga-bridges property in the FPGA region or in the device tree overlay.
-
- * Partial reconfiguration with bridges in the FPGA
-   In this case, the FPGA will have one or more PRR's that may be programmed
-   separately while the rest of the FPGA can remain active.  To manage this,
-   bridges need to exist in the FPGA that can gate the buses going to each FPGA
-   region while the buses are enabled for other sections.  Before any partial
-   reconfiguration can be done, a base FPGA image must be loaded which includes
-   PRR's with FPGA bridges.  The device tree should have an FPGA region for each
-   PRR.
-
-Device Tree Examples
-====================
-
-The intention of this section is to give some simple examples, focusing on
-the placement of the elements detailed above, especially:
- * FPGA Manager
- * FPGA Bridges
- * FPGA Region
- * ranges
- * target-path or target
-
-For the purposes of this section, I'm dividing the Device Tree into two parts,
-each with its own requirements.  The two parts are:
- * The live DT prior to the overlay being added
- * The DT overlay
-
-The live Device Tree must contain an FPGA Region, an FPGA Manager, and any FPGA
-Bridges.  The FPGA Region's "fpga-mgr" property specifies the manager by phandle
-to handle programming the FPGA.  If the FPGA Region is the child of another FPGA
-Region, the parent's FPGA Manager is used.  If FPGA Bridges need to be involved,
-they are specified in the FPGA Region by the "fpga-bridges" property.  During
-FPGA programming, the FPGA Region will disable the bridges that are in its
-"fpga-bridges" list and will re-enable them after FPGA programming has
-succeeded.
-
-The Device Tree Overlay will contain:
- * "target-path" or "target"
-   The insertion point where the contents of the overlay will go into the
-   live tree.  target-path is a full path, while target is a phandle.
- * "ranges"
-    The address space mapping from processor to FPGA bus(ses).
- * "firmware-name"
-   Specifies the name of the FPGA image file on the firmware search
-   path.  The search path is described in the firmware class documentation.
- * "partial-fpga-config"
-   This binding is a boolean and should be present if partial reconfiguration
-   is to be done.
- * child nodes corresponding to hardware that will be loaded in this region of
-   the FPGA.
-
-Device Tree Example: Full Reconfiguration without Bridges
-=========================================================
-
-Live Device Tree contains:
-	fpga_mgr0: fpga-mgr@f8007000 {
-		compatible = "xlnx,zynq-devcfg-1.0";
-		reg = <0xf8007000 0x100>;
-		interrupt-parent = <&intc>;
-		interrupts = <0 8 4>;
-		clocks = <&clkc 12>;
-		clock-names = "ref_clk";
-		syscon = <&slcr>;
-	};
-
-	fpga_region0: fpga-region0 {
-		compatible = "fpga-region";
-		fpga-mgr = <&fpga_mgr0>;
-		#address-cells = <0x1>;
-		#size-cells = <0x1>;
-		ranges;
-	};
-
-DT Overlay contains:
-
-/dts-v1/;
-/plugin/;
-
-&fpga_region0 {
-	#address-cells = <1>;
-	#size-cells = <1>;
-
-	firmware-name = "zynq-gpio.bin";
-
-	gpio1: gpio@40000000 {
-		compatible = "xlnx,xps-gpio-1.00.a";
-		reg = <0x40000000 0x10000>;
-		gpio-controller;
-		#gpio-cells = <0x2>;
-		xlnx,gpio-width= <0x6>;
-	};
-};
-
-Device Tree Example: Full Reconfiguration to add PRR's
-======================================================
-
-The base FPGA Region is specified similar to the first example above.
-
-This example programs the FPGA to have two regions that can later be partially
-configured.  Each region has its own bridge in the FPGA fabric.
-
-DT Overlay contains:
-
-/dts-v1/;
-/plugin/;
-
-&fpga_region0 {
-	#address-cells = <1>;
-	#size-cells = <1>;
-
-	firmware-name = "base.rbf";
-
-	fpga-bridge@4400 {
-		compatible = "altr,freeze-bridge-controller";
-		reg = <0x4400 0x10>;
-
-		fpga_region1: fpga-region1 {
-			compatible = "fpga-region";
-			#address-cells = <0x1>;
-			#size-cells = <0x1>;
-			ranges;
-		};
-	};
-
-	fpga-bridge@4420 {
-		compatible = "altr,freeze-bridge-controller";
-		reg = <0x4420 0x10>;
-
-		fpga_region2: fpga-region2 {
-			compatible = "fpga-region";
-			#address-cells = <0x1>;
-			#size-cells = <0x1>;
-			ranges;
-		};
-	};
-};
-
-Device Tree Example: Partial Reconfiguration
-============================================
-
-This example reprograms one of the PRR's set up in the previous example.
-
-The sequence that occurs when this overlay is similar to the above, the only
-differences are that the FPGA is partially reconfigured due to the
-"partial-fpga-config" boolean and the only bridge that is controlled during
-programming is the FPGA based bridge of fpga_region1.
-
-/dts-v1/;
-/plugin/;
-
-&fpga_region1 {
-	#address-cells = <1>;
-	#size-cells = <1>;
-
-	firmware-name = "soc_image2.rbf";
-	partial-fpga-config;
-
-	gpio@10040 {
-		compatible = "altr,pio-1.0";
-		reg = <0x10040 0x20>;
-		clocks = <0x2>;
-		altr,ngpio = <0x4>;
-		#gpio-cells = <0x2>;
-		gpio-controller;
-	};
-};
-
-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
diff --git a/Documentation/devicetree/bindings/fpga/fpga-region.yaml b/Documentation/devicetree/bindings/fpga/fpga-region.yaml
new file mode 100644
index 000000000000..fb6fe6f43fa8
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/fpga-region.yaml
@@ -0,0 +1,351 @@ 
+# SPDX-License-Identifier: GPL-2.0
+%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 <[e-mail]>
+
+description: |
+  CONTENTS
+   - Introduction
+   - Terminology
+   - Sequence
+   - FPGA Region
+   - Supported Use Models
+   - Constraints
+
+
+  Introduction
+  ============
+
+  FPGA Regions represent FPGA's and partial reconfiguration regions of FPGA's in
+  the Device Tree.  FPGA Regions provide a way to program FPGAs under device tree
+  control.
+
+  The documentation hits some of the high points of FPGA usage and
+  attempts to include terminology used by both major FPGA manufacturers.  This
+  document isn't a replacement for any manufacturers specifications for FPGA
+  usage.
+
+
+  Terminology
+  ===========
+
+  Full Reconfiguration
+   * The entire FPGA is programmed.
+
+  Partial Reconfiguration (PR)
+   * A section of an FPGA is reprogrammed while the rest of the FPGA is not
+     affected.
+   * Not all FPGA's support PR.
+
+  Partial Reconfiguration Region (PRR)
+   * Also called a "reconfigurable partition"
+   * A PRR is a specific section of an FPGA reserved for reconfiguration.
+   * A base (or static) FPGA image may create a set of PRR's that later may
+     be independently reprogrammed many times.
+   * The size and specific location of each PRR is fixed.
+   * The connections at the edge of each PRR are fixed.  The image that is loaded
+     into a PRR must fit and must use a subset of the region's connections.
+   * The busses within the FPGA are split such that each region gets its own
+     branch that may be gated independently.
+
+  Persona
+   * Also called a "partial bit stream"
+   * An FPGA image that is designed to be loaded into a PRR.  There may be
+     any number of personas designed to fit into a PRR, but only one at a time
+     may be loaded.
+   * A persona may create more regions.
+
+  FPGA Bridge
+   * FPGA Bridges gate bus signals between a host and FPGA.
+   * FPGA Bridges should be disabled while the FPGA is being programmed to
+     prevent spurious signals on the cpu bus and to the soft logic.
+   * FPGA bridges may be actual hardware or soft logic on an FPGA.
+   * During Full Reconfiguration, hardware bridges between the host and FPGA
+     will be disabled.
+   * During Partial Reconfiguration of a specific region, that region's bridge
+     will be used to gate the busses.  Traffic to other regions is not affected.
+   * In some implementations, the FPGA Manager transparently handles gating the
+     buses, eliminating the need to show the hardware FPGA bridges in the
+     device tree.
+   * An FPGA image may create a set of reprogrammable regions, each having its
+     own bridge and its own split of the busses in the FPGA.
+
+  FPGA Manager
+   * An FPGA Manager is a hardware block that programs an FPGA under the control
+     of a host processor.
+
+  Base Image
+   * Also called the "static image"
+   * An FPGA image that is designed to do full reconfiguration of the FPGA.
+   * A base image may set up a set of partial reconfiguration regions that may
+     later be reprogrammed.
+
+      ----------------       ----------------------------------
+      |  Host CPU    |       |             FPGA               |
+      |              |       |                                |
+      |          ----|       |       -----------    --------  |
+      |          | H |       |   |==>| Bridge0 |<==>| PRR0 |  |
+      |          | W |       |   |   -----------    --------  |
+      |          |   |       |   |                            |
+      |          | B |<=====>|<==|   -----------    --------  |
+      |          | R |       |   |==>| Bridge1 |<==>| PRR1 |  |
+      |          | I |       |   |   -----------    --------  |
+      |          | D |       |   |                            |
+      |          | G |       |   |   -----------    --------  |
+      |          | E |       |   |==>| Bridge2 |<==>| PRR2 |  |
+      |          ----|       |       -----------    --------  |
+      |              |       |                                |
+      ----------------       ----------------------------------
+
+  Figure 1: An FPGA set up with a base image that created three regions.  Each
+  region (PRR0-2) gets its own split of the busses that is independently gated by
+  a soft logic bridge (Bridge0-2) in the FPGA.  The contents of each PRR can be
+  reprogrammed independently while the rest of the system continues to function.
+
+
+  Sequence
+  ========
+
+  When a DT overlay that targets an FPGA Region is applied, the FPGA Region will
+  do the following:
+
+   1. Disable appropriate FPGA bridges.
+   2. Program the FPGA using the FPGA manager.
+   3. Enable the FPGA bridges.
+   4. The Device Tree overlay is accepted into the live tree.
+   5. Child devices are populated.
+
+  When the overlay is removed, the child nodes will be removed and the FPGA Region
+  will disable the bridges.
+
+
+  FPGA Region
+  ===========
+
+  FPGA Regions represent FPGA's and FPGA PR regions in the device tree.  An FPGA
+  Region brings together the elements needed to program on a running system and
+  add the child devices:
+
+   * FPGA Manager
+   * FPGA Bridges
+   * image-specific information needed to the programming.
+   * child nodes
+
+  The intended use is that a Device Tree overlay (DTO) can be used to reprogram an
+  FPGA while an operating system is running.
+
+  An FPGA Region that exists in the live Device Tree reflects the current state.
+  If the live tree shows a "firmware-name" property or child nodes under an FPGA
+  Region, the FPGA already has been programmed.  A DTO that targets an FPGA Region
+  and adds the "firmware-name" property is taken as a request to reprogram the
+  FPGA.  After reprogramming is successful, the overlay is accepted into the live
+  tree.
+
+  The base FPGA Region in the device tree represents the FPGA and supports full
+  reconfiguration.  It must include a phandle to an FPGA Manager.  The base
+  FPGA region will be the child of one of the hardware bridges (the bridge that
+  allows register access) between the cpu and the FPGA.  If there are more than
+  one bridge to control during FPGA programming, the region will also contain a
+  list of phandles to the additional hardware FPGA Bridges.
+
+  For partial reconfiguration (PR), each PR region will have an FPGA Region.
+  These FPGA regions are children of FPGA bridges which are then children of the
+  base FPGA region.  The "Full Reconfiguration to add PRR's" example below shows
+  this.
+
+  If an FPGA Region does not specify an FPGA Manager, it will inherit the FPGA
+  Manager specified by its ancestor FPGA Region.  This supports both the case
+  where the same FPGA Manager is used for all of an FPGA as well the case where
+  a different FPGA Manager is used for each region.
+
+  FPGA Regions do not inherit their ancestor FPGA regions' bridges.  This prevents
+  shutting down bridges that are upstream from the other active regions while one
+  region is getting reconfigured (see Figure 1 above).  During PR, the FPGA's
+  hardware bridges remain enabled.  The PR regions' bridges will be FPGA bridges
+  within the static image of the FPGA.
+
+
+  Supported Use Models
+  ====================
+
+  In all cases the live DT must have the FPGA Manager, FPGA Bridges (if any), and
+  a FPGA Region.  The target of the Device Tree Overlay is the FPGA Region.  Some
+  uses are specific to an FPGA device.
+
+   * No FPGA Bridges
+     In this case, the FPGA Manager which programs the FPGA also handles the
+     bridges behind the scenes.  No FPGA Bridge devices are needed for full
+     reconfiguration.
+
+   * Full reconfiguration with hardware bridges
+     In this case, there are hardware bridges between the processor and FPGA that
+     need to be controlled during full reconfiguration.  Before the overlay is
+     applied, the live DT must include the FPGA Manager, FPGA Bridges, and a
+     FPGA Region.  The FPGA Region is the child of the bridge that allows
+     register access to the FPGA.  Additional bridges may be listed in a
+     fpga-bridges property in the FPGA region or in the device tree overlay.
+
+   * Partial reconfiguration with bridges in the FPGA
+     In this case, the FPGA will have one or more PRR's that may be programmed
+     separately while the rest of the FPGA can remain active.  To manage this,
+     bridges need to exist in the FPGA that can gate the buses going to each FPGA
+     region while the buses are enabled for other sections.  Before any partial
+     reconfiguration can be done, a base FPGA image must be loaded which includes
+     PRR's with FPGA bridges.  The device tree should have an FPGA region for each
+     PRR.
+
+  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]+))?$"
+
+  compatible:
+    const: fpga-region
+
+  "#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:
+    maxItems: 1
+    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-array
+    description:
+      Should contain a list of phandles to FPGA Bridges that must be
+      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.
+
+required:
+  - compatible
+  - "#address-cells"
+  - "#size-cells"
+  - fpga-mgr
+
+additionalProperties: true
+
+examples:
+  - |
+    /*
+     * Full Reconfiguration without Bridges with DT overlay
+     */
+    fpga_region0: fpga-region {
+      compatible = "fpga-region";
+      #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 bridge
+     */
+    fpga_region1: fpga-region {
+      compatible = "fpga-region";
+      #address-cells = <1>;
+      #size-cells = <1>;
+      fpga-mgr = <&fpga_mgr1>;
+      fpga-bridges = <&fpga_bridge1>;
+      partial-fpga-config;
+
+      /* DT Overlay contains: &fpga_region1 */
+      firmware-name = "zynq-gpio-partial.bin";
+      clk: clock {
+        compatible = "fixed-factor-clock";
+        clocks = <&parentclk>;
+        #clock-cells = <0>;
+        clock-div = <2>;
+        clock-mult = <1>;
+      };
+      axi {
+        compatible = "simple-bus";
+        #address-cells = <1>;
+        #size-cells = <1>;
+        ranges;
+        gpio@40000000 {
+          compatible = "xlnx,xps-gpio-1.00.a";
+          reg = <0x40000000 0x10000>;
+          #gpio-cells = <2>;
+          gpio-controller;
+          clocks = <&clk>;
+        };
+      };
+    };