dts/upstream/Bindings/fpga/fpga-region.yaml

# 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 <michal.simek@amd.com>

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

  reg:
    maxItems: 1

  ranges: true
  "#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
  - fpga-mgr

additionalProperties:
  type: object

examples:
  - |
    /*
     * Full Reconfiguration without Bridges with DT overlay
     */
    fpga_region0: fpga-region@0 {
      compatible = "fpga-region";
      reg = <0 0>;
      #address-cells = <1>;
      #size-cells = <1>;
      fpga-mgr = <&fpga_mgr0>;
      ranges = <0x10000000 0x20000000 0x10000000>;

      /* 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@0 {
      compatible = "fpga-region";
      reg = <0 0>;
      ranges;
      #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>;
        };
      };
    };