0001 FPGA Region Device Tree Binding
0002
0003 Alan Tull 2016
0004
0005 CONTENTS
0006 - Introduction
0007 - Terminology
0008 - Sequence
0009 - FPGA Region
0010 - Supported Use Models
0011 - Device Tree Examples
0012 - Constraints
0013
0014
0015 Introduction
0016 ============
0017
0018 FPGA Regions represent FPGA's and partial reconfiguration regions of FPGA's in
0019 the Device Tree. FPGA Regions provide a way to program FPGAs under device tree
0020 control.
0021
0022 This device tree binding document hits some of the high points of FPGA usage and
0023 attempts to include terminology used by both major FPGA manufacturers. This
0024 document isn't a replacement for any manufacturers specifications for FPGA
0025 usage.
0026
0027
0028 Terminology
0029 ===========
0030
0031 Full Reconfiguration
0032 * The entire FPGA is programmed.
0033
0034 Partial Reconfiguration (PR)
0035 * A section of an FPGA is reprogrammed while the rest of the FPGA is not
0036 affected.
0037 * Not all FPGA's support PR.
0038
0039 Partial Reconfiguration Region (PRR)
0040 * Also called a "reconfigurable partition"
0041 * A PRR is a specific section of an FPGA reserved for reconfiguration.
0042 * A base (or static) FPGA image may create a set of PRR's that later may
0043 be independently reprogrammed many times.
0044 * The size and specific location of each PRR is fixed.
0045 * The connections at the edge of each PRR are fixed. The image that is loaded
0046 into a PRR must fit and must use a subset of the region's connections.
0047 * The busses within the FPGA are split such that each region gets its own
0048 branch that may be gated independently.
0049
0050 Persona
0051 * Also called a "partial bit stream"
0052 * An FPGA image that is designed to be loaded into a PRR. There may be
0053 any number of personas designed to fit into a PRR, but only one at at time
0054 may be loaded.
0055 * A persona may create more regions.
0056
0057 FPGA Bridge
0058 * FPGA Bridges gate bus signals between a host and FPGA.
0059 * FPGA Bridges should be disabled while the FPGA is being programmed to
0060 prevent spurious signals on the cpu bus and to the soft logic.
0061 * FPGA bridges may be actual hardware or soft logic on an FPGA.
0062 * During Full Reconfiguration, hardware bridges between the host and FPGA
0063 will be disabled.
0064 * During Partial Reconfiguration of a specific region, that region's bridge
0065 will be used to gate the busses. Traffic to other regions is not affected.
0066 * In some implementations, the FPGA Manager transparantly handles gating the
0067 buses, eliminating the need to show the hardware FPGA bridges in the
0068 device tree.
0069 * An FPGA image may create a set of reprogrammable regions, each having its
0070 own bridge and its own split of the busses in the FPGA.
0071
0072 FPGA Manager
0073 * An FPGA Manager is a hardware block that programs an FPGA under the control
0074 of a host processor.
0075
0076 Base Image
0077 * Also called the "static image"
0078 * An FPGA image that is designed to do full reconfiguration of the FPGA.
0079 * A base image may set up a set of partial reconfiguration regions that may
0080 later be reprogrammed.
0081
0082 ---------------- ----------------------------------
0083 | Host CPU | | FPGA |
0084 | | | |
0085 | ----| | ----------- -------- |
0086 | | H | | |==>| Bridge0 |<==>| PRR0 | |
0087 | | W | | | ----------- -------- |
0088 | | | | | |
0089 | | B |<=====>|<==| ----------- -------- |
0090 | | R | | |==>| Bridge1 |<==>| PRR1 | |
0091 | | I | | | ----------- -------- |
0092 | | D | | | |
0093 | | G | | | ----------- -------- |
0094 | | E | | |==>| Bridge2 |<==>| PRR2 | |
0095 | ----| | ----------- -------- |
0096 | | | |
0097 ---------------- ----------------------------------
0098
0099 Figure 1: An FPGA set up with a base image that created three regions. Each
0100 region (PRR0-2) gets its own split of the busses that is independently gated by
0101 a soft logic bridge (Bridge0-2) in the FPGA. The contents of each PRR can be
0102 reprogrammed independently while the rest of the system continues to function.
0103
0104
0105 Sequence
0106 ========
0107
0108 When a DT overlay that targets an FPGA Region is applied, the FPGA Region will
0109 do the following:
0110
0111 1. Disable appropriate FPGA bridges.
0112 2. Program the FPGA using the FPGA manager.
0113 3. Enable the FPGA bridges.
0114 4. The Device Tree overlay is accepted into the live tree.
0115 5. Child devices are populated.
0116
0117 When the overlay is removed, the child nodes will be removed and the FPGA Region
0118 will disable the bridges.
0119
0120
0121 FPGA Region
0122 ===========
0123
0124 FPGA Regions represent FPGA's and FPGA PR regions in the device tree. An FPGA
0125 Region brings together the elements needed to program on a running system and
0126 add the child devices:
0127
0128 * FPGA Manager
0129 * FPGA Bridges
0130 * image-specific information needed to to the programming.
0131 * child nodes
0132
0133 The intended use is that a Device Tree overlay (DTO) can be used to reprogram an
0134 FPGA while an operating system is running.
0135
0136 An FPGA Region that exists in the live Device Tree reflects the current state.
0137 If the live tree shows a "firmware-name" property or child nodes under an FPGA
0138 Region, the FPGA already has been programmed. A DTO that targets an FPGA Region
0139 and adds the "firmware-name" property is taken as a request to reprogram the
0140 FPGA. After reprogramming is successful, the overlay is accepted into the live
0141 tree.
0142
0143 The base FPGA Region in the device tree represents the FPGA and supports full
0144 reconfiguration. It must include a phandle to an FPGA Manager. The base
0145 FPGA region will be the child of one of the hardware bridges (the bridge that
0146 allows register access) between the cpu and the FPGA. If there are more than
0147 one bridge to control during FPGA programming, the region will also contain a
0148 list of phandles to the additional hardware FPGA Bridges.
0149
0150 For partial reconfiguration (PR), each PR region will have an FPGA Region.
0151 These FPGA regions are children of FPGA bridges which are then children of the
0152 base FPGA region. The "Full Reconfiguration to add PRR's" example below shows
0153 this.
0154
0155 If an FPGA Region does not specify an FPGA Manager, it will inherit the FPGA
0156 Manager specified by its ancestor FPGA Region. This supports both the case
0157 where the same FPGA Manager is used for all of an FPGA as well the case where
0158 a different FPGA Manager is used for each region.
0159
0160 FPGA Regions do not inherit their ancestor FPGA regions' bridges. This prevents
0161 shutting down bridges that are upstream from the other active regions while one
0162 region is getting reconfigured (see Figure 1 above). During PR, the FPGA's
0163 hardware bridges remain enabled. The PR regions' bridges will be FPGA bridges
0164 within the static image of the FPGA.
0165
0166 Required properties:
0167 - compatible : should contain "fpga-region"
0168 - fpga-mgr : should contain a phandle to an FPGA Manager. Child FPGA Regions
0169 inherit this property from their ancestor regions. An fpga-mgr property
0170 in a region will override any inherited FPGA manager.
0171 - #address-cells, #size-cells, ranges : must be present to handle address space
0172 mapping for child nodes.
0173
0174 Optional properties:
0175 - firmware-name : should contain the name of an FPGA image file located on the
0176 firmware search path. If this property shows up in a live device tree
0177 it indicates that the FPGA has already been programmed with this image.
0178 If this property is in an overlay targeting an FPGA region, it is a
0179 request to program the FPGA with that image.
0180 - fpga-bridges : should contain a list of phandles to FPGA Bridges that must be
0181 controlled during FPGA programming along with the parent FPGA bridge.
0182 This property is optional if the FPGA Manager handles the bridges.
0183 If the fpga-region is the child of an fpga-bridge, the list should not
0184 contain the parent bridge.
0185 - partial-fpga-config : boolean, set if partial reconfiguration is to be done,
0186 otherwise full reconfiguration is done.
0187 - external-fpga-config : boolean, set if the FPGA has already been configured
0188 prior to OS boot up.
0189 - encrypted-fpga-config : boolean, set if the bitstream is encrypted
0190 - region-unfreeze-timeout-us : The maximum time in microseconds to wait for
0191 bridges to successfully become enabled after the region has been
0192 programmed.
0193 - region-freeze-timeout-us : The maximum time in microseconds to wait for
0194 bridges to successfully become disabled before the region has been
0195 programmed.
0196 - config-complete-timeout-us : The maximum time in microseconds time for the
0197 FPGA to go to operating mode after the region has been programmed.
0198 - child nodes : devices in the FPGA after programming.
0199
0200 In the example below, when an overlay is applied targeting fpga-region0,
0201 fpga_mgr is used to program the FPGA. Two bridges are controlled during
0202 programming: the parent fpga_bridge0 and fpga_bridge1. Because the region is
0203 the child of fpga_bridge0, only fpga_bridge1 needs to be specified in the
0204 fpga-bridges property. During programming, these bridges are disabled, the
0205 firmware specified in the overlay is loaded to the FPGA using the FPGA manager
0206 specified in the region. If FPGA programming succeeds, the bridges are
0207 reenabled and the overlay makes it into the live device tree. The child devices
0208 are then populated. If FPGA programming fails, the bridges are left disabled
0209 and the overlay is rejected. The overlay's ranges property maps the lwhps
0210 bridge's region (0xff200000) and the hps bridge's region (0xc0000000) for use by
0211 the two child devices.
0212
0213 Example:
0214 Base tree contains:
0215
0216 fpga_mgr: fpga-mgr@ff706000 {
0217 compatible = "altr,socfpga-fpga-mgr";
0218 reg = <0xff706000 0x1000
0219 0xffb90000 0x20>;
0220 interrupts = <0 175 4>;
0221 };
0222
0223 fpga_bridge0: fpga-bridge@ff400000 {
0224 compatible = "altr,socfpga-lwhps2fpga-bridge";
0225 reg = <0xff400000 0x100000>;
0226 resets = <&rst LWHPS2FPGA_RESET>;
0227 clocks = <&l4_main_clk>;
0228
0229 #address-cells = <1>;
0230 #size-cells = <1>;
0231 ranges;
0232
0233 fpga_region0: fpga-region0 {
0234 compatible = "fpga-region";
0235 fpga-mgr = <&fpga_mgr>;
0236 };
0237 };
0238
0239 fpga_bridge1: fpga-bridge@ff500000 {
0240 compatible = "altr,socfpga-hps2fpga-bridge";
0241 reg = <0xff500000 0x10000>;
0242 resets = <&rst HPS2FPGA_RESET>;
0243 clocks = <&l4_main_clk>;
0244 };
0245
0246 Overlay contains:
0247
0248 /dts-v1/;
0249 /plugin/;
0250
0251 &fpga_region0 {
0252 #address-cells = <1>;
0253 #size-cells = <1>;
0254
0255 firmware-name = "soc_system.rbf";
0256 fpga-bridges = <&fpga_bridge1>;
0257 ranges = <0x20000 0xff200000 0x100000>,
0258 <0x0 0xc0000000 0x20000000>;
0259
0260 gpio@10040 {
0261 compatible = "altr,pio-1.0";
0262 reg = <0x10040 0x20>;
0263 altr,ngpio = <4>;
0264 #gpio-cells = <2>;
0265 clocks = <2>;
0266 gpio-controller;
0267 };
0268
0269 onchip-memory {
0270 device_type = "memory";
0271 compatible = "altr,onchipmem-15.1";
0272 reg = <0x0 0x10000>;
0273 };
0274 };
0275
0276
0277 Supported Use Models
0278 ====================
0279
0280 In all cases the live DT must have the FPGA Manager, FPGA Bridges (if any), and
0281 a FPGA Region. The target of the Device Tree Overlay is the FPGA Region. Some
0282 uses are specific to an FPGA device.
0283
0284 * No FPGA Bridges
0285 In this case, the FPGA Manager which programs the FPGA also handles the
0286 bridges behind the scenes. No FPGA Bridge devices are needed for full
0287 reconfiguration.
0288
0289 * Full reconfiguration with hardware bridges
0290 In this case, there are hardware bridges between the processor and FPGA that
0291 need to be controlled during full reconfiguration. Before the overlay is
0292 applied, the live DT must include the FPGA Manager, FPGA Bridges, and a
0293 FPGA Region. The FPGA Region is the child of the bridge that allows
0294 register access to the FPGA. Additional bridges may be listed in a
0295 fpga-bridges property in the FPGA region or in the device tree overlay.
0296
0297 * Partial reconfiguration with bridges in the FPGA
0298 In this case, the FPGA will have one or more PRR's that may be programmed
0299 separately while the rest of the FPGA can remain active. To manage this,
0300 bridges need to exist in the FPGA that can gate the buses going to each FPGA
0301 region while the buses are enabled for other sections. Before any partial
0302 reconfiguration can be done, a base FPGA image must be loaded which includes
0303 PRR's with FPGA bridges. The device tree should have an FPGA region for each
0304 PRR.
0305
0306 Device Tree Examples
0307 ====================
0308
0309 The intention of this section is to give some simple examples, focusing on
0310 the placement of the elements detailed above, especially:
0311 * FPGA Manager
0312 * FPGA Bridges
0313 * FPGA Region
0314 * ranges
0315 * target-path or target
0316
0317 For the purposes of this section, I'm dividing the Device Tree into two parts,
0318 each with its own requirements. The two parts are:
0319 * The live DT prior to the overlay being added
0320 * The DT overlay
0321
0322 The live Device Tree must contain an FPGA Region, an FPGA Manager, and any FPGA
0323 Bridges. The FPGA Region's "fpga-mgr" property specifies the manager by phandle
0324 to handle programming the FPGA. If the FPGA Region is the child of another FPGA
0325 Region, the parent's FPGA Manager is used. If FPGA Bridges need to be involved,
0326 they are specified in the FPGA Region by the "fpga-bridges" property. During
0327 FPGA programming, the FPGA Region will disable the bridges that are in its
0328 "fpga-bridges" list and will re-enable them after FPGA programming has
0329 succeeded.
0330
0331 The Device Tree Overlay will contain:
0332 * "target-path" or "target"
0333 The insertion point where the contents of the overlay will go into the
0334 live tree. target-path is a full path, while target is a phandle.
0335 * "ranges"
0336 The address space mapping from processor to FPGA bus(ses).
0337 * "firmware-name"
0338 Specifies the name of the FPGA image file on the firmware search
0339 path. The search path is described in the firmware class documentation.
0340 * "partial-fpga-config"
0341 This binding is a boolean and should be present if partial reconfiguration
0342 is to be done.
0343 * child nodes corresponding to hardware that will be loaded in this region of
0344 the FPGA.
0345
0346 Device Tree Example: Full Reconfiguration without Bridges
0347 =========================================================
0348
0349 Live Device Tree contains:
0350 fpga_mgr0: fpga-mgr@f8007000 {
0351 compatible = "xlnx,zynq-devcfg-1.0";
0352 reg = <0xf8007000 0x100>;
0353 interrupt-parent = <&intc>;
0354 interrupts = <0 8 4>;
0355 clocks = <&clkc 12>;
0356 clock-names = "ref_clk";
0357 syscon = <&slcr>;
0358 };
0359
0360 fpga_region0: fpga-region0 {
0361 compatible = "fpga-region";
0362 fpga-mgr = <&fpga_mgr0>;
0363 #address-cells = <0x1>;
0364 #size-cells = <0x1>;
0365 ranges;
0366 };
0367
0368 DT Overlay contains:
0369
0370 /dts-v1/;
0371 /plugin/;
0372
0373 &fpga_region0 {
0374 #address-cells = <1>;
0375 #size-cells = <1>;
0376
0377 firmware-name = "zynq-gpio.bin";
0378
0379 gpio1: gpio@40000000 {
0380 compatible = "xlnx,xps-gpio-1.00.a";
0381 reg = <0x40000000 0x10000>;
0382 gpio-controller;
0383 #gpio-cells = <0x2>;
0384 xlnx,gpio-width= <0x6>;
0385 };
0386 };
0387
0388 Device Tree Example: Full Reconfiguration to add PRR's
0389 ======================================================
0390
0391 The base FPGA Region is specified similar to the first example above.
0392
0393 This example programs the FPGA to have two regions that can later be partially
0394 configured. Each region has its own bridge in the FPGA fabric.
0395
0396 DT Overlay contains:
0397
0398 /dts-v1/;
0399 /plugin/;
0400
0401 &fpga_region0 {
0402 #address-cells = <1>;
0403 #size-cells = <1>;
0404
0405 firmware-name = "base.rbf";
0406
0407 fpga-bridge@4400 {
0408 compatible = "altr,freeze-bridge-controller";
0409 reg = <0x4400 0x10>;
0410
0411 fpga_region1: fpga-region1 {
0412 compatible = "fpga-region";
0413 #address-cells = <0x1>;
0414 #size-cells = <0x1>;
0415 ranges;
0416 };
0417 };
0418
0419 fpga-bridge@4420 {
0420 compatible = "altr,freeze-bridge-controller";
0421 reg = <0x4420 0x10>;
0422
0423 fpga_region2: fpga-region2 {
0424 compatible = "fpga-region";
0425 #address-cells = <0x1>;
0426 #size-cells = <0x1>;
0427 ranges;
0428 };
0429 };
0430 };
0431
0432 Device Tree Example: Partial Reconfiguration
0433 ============================================
0434
0435 This example reprograms one of the PRR's set up in the previous example.
0436
0437 The sequence that occurs when this overlay is similar to the above, the only
0438 differences are that the FPGA is partially reconfigured due to the
0439 "partial-fpga-config" boolean and the only bridge that is controlled during
0440 programming is the FPGA based bridge of fpga_region1.
0441
0442 /dts-v1/;
0443 /plugin/;
0444
0445 &fpga_region1 {
0446 #address-cells = <1>;
0447 #size-cells = <1>;
0448
0449 firmware-name = "soc_image2.rbf";
0450 partial-fpga-config;
0451
0452 gpio@10040 {
0453 compatible = "altr,pio-1.0";
0454 reg = <0x10040 0x20>;
0455 clocks = <0x2>;
0456 altr,ngpio = <0x4>;
0457 #gpio-cells = <0x2>;
0458 gpio-controller;
0459 };
0460 };
0461
0462 Constraints
0463 ===========
0464
0465 It is beyond the scope of this document to fully describe all the FPGA design
0466 constraints required to make partial reconfiguration work[1] [2] [3], but a few
0467 deserve quick mention.
0468
0469 A persona must have boundary connections that line up with those of the partion
0470 or region it is designed to go into.
0471
0472 During programming, transactions through those connections must be stopped and
0473 the connections must be held at a fixed logic level. This can be achieved by
0474 FPGA Bridges that exist on the FPGA fabric prior to the partial reconfiguration.
0475
0476 --
0477 [1] www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/ug/ug_partrecon.pdf
0478 [2] tspace.library.utoronto.ca/bitstream/1807/67932/1/Byma_Stuart_A_201411_MAS_thesis.pdf
0479 [3] https://www.xilinx.com/support/documentation/sw_manuals/xilinx14_1/ug702.pdf
