| # 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>; |
| }; |
| }; |
| }; |
