1 FPGA Region Device Tree Binding
10 - Supported Use Models
11 - Device Tree Examples
18 FPGA Regions represent FPGA's and partial reconfiguration regions of FPGA's in
19 the Device Tree. FPGA Regions provide a way to program FPGAs under device tree
22 This device tree binding document hits some of the high points of FPGA usage and
23 attempts to include terminology used by both major FPGA manufacturers. This
24 document isn't a replacement for any manufacturers specifications for FPGA
32 * The entire FPGA is programmed.
34 Partial Reconfiguration (PR)
35 * A section of an FPGA is reprogrammed while the rest of the FPGA is not
37 * Not all FPGA's support PR.
39 Partial Reconfiguration Region (PRR)
40 * Also called a "reconfigurable partition"
41 * A PRR is a specific section of a FPGA reserved for reconfiguration.
42 * A base (or static) FPGA image may create a set of PRR's that later may
43 be independently reprogrammed many times.
44 * The size and specific location of each PRR is fixed.
45 * The connections at the edge of each PRR are fixed. The image that is loaded
46 into a PRR must fit and must use a subset of the region's connections.
47 * The busses within the FPGA are split such that each region gets its own
48 branch that may be gated independently.
51 * Also called a "partial bit stream"
52 * An FPGA image that is designed to be loaded into a PRR. There may be
53 any number of personas designed to fit into a PRR, but only one at at time
55 * A persona may create more regions.
58 * FPGA Bridges gate bus signals between a host and FPGA.
59 * FPGA Bridges should be disabled while the FPGA is being programmed to
60 prevent spurious signals on the cpu bus and to the soft logic.
61 * FPGA bridges may be actual hardware or soft logic on an FPGA.
62 * During Full Reconfiguration, hardware bridges between the host and FPGA
64 * During Partial Reconfiguration of a specific region, that region's bridge
65 will be used to gate the busses. Traffic to other regions is not affected.
66 * In some implementations, the FPGA Manager transparantly handles gating the
67 buses, eliminating the need to show the hardware FPGA bridges in the
69 * An FPGA image may create a set of reprogrammable regions, each having its
70 own bridge and its own split of the busses in the FPGA.
73 * An FPGA Manager is a hardware block that programs an FPGA under the control
77 * Also called the "static image"
78 * An FPGA image that is designed to do full reconfiguration of the FPGA.
79 * A base image may set up a set of partial reconfiguration regions that may
80 later be reprogrammed.
82 ---------------- ----------------------------------
85 | ----| | ----------- -------- |
86 | | H | | |==>| Bridge0 |<==>| PRR0 | |
87 | | W | | | ----------- -------- |
89 | | B |<=====>|<==| ----------- -------- |
90 | | R | | |==>| Bridge1 |<==>| PRR1 | |
91 | | I | | | ----------- -------- |
93 | | G | | | ----------- -------- |
94 | | E | | |==>| Bridge2 |<==>| PRR2 | |
95 | ----| | ----------- -------- |
97 ---------------- ----------------------------------
99 Figure 1: An FPGA set up with a base image that created three regions. Each
100 region (PRR0-2) gets its own split of the busses that is independently gated by
101 a soft logic bridge (Bridge0-2) in the FPGA. The contents of each PRR can be
102 reprogrammed independently while the rest of the system continues to function.
108 When a DT overlay that targets a FPGA Region is applied, the FPGA Region will
111 1. Disable appropriate FPGA bridges.
112 2. Program the FPGA using the FPGA manager.
113 3. Enable the FPGA bridges.
114 4. The Device Tree overlay is accepted into the live tree.
115 5. Child devices are populated.
117 When the overlay is removed, the child nodes will be removed and the FPGA Region
118 will disable the bridges.
124 FPGA Regions represent FPGA's and FPGA PR regions in the device tree. An FPGA
125 Region brings together the elements needed to program on a running system and
126 add the child devices:
130 * image-specific information needed to to the programming.
133 The intended use is that a Device Tree overlay (DTO) can be used to reprogram an
134 FPGA while an operating system is running.
136 An FPGA Region that exists in the live Device Tree reflects the current state.
137 If the live tree shows a "firmware-name" property or child nodes under a FPGA
138 Region, the FPGA already has been programmed. A DTO that targets a FPGA Region
139 and adds the "firmware-name" property is taken as a request to reprogram the
140 FPGA. After reprogramming is successful, the overlay is accepted into the live
143 The base FPGA Region in the device tree represents the FPGA and supports full
144 reconfiguration. It must include a phandle to an FPGA Manager. The base
145 FPGA region will be the child of one of the hardware bridges (the bridge that
146 allows register access) between the cpu and the FPGA. If there are more than
147 one bridge to control during FPGA programming, the region will also contain a
148 list of phandles to the additional hardware FPGA Bridges.
150 For partial reconfiguration (PR), each PR region will have an FPGA Region.
151 These FPGA regions are children of FPGA bridges which are then children of the
152 base FPGA region. The "Full Reconfiguration to add PRR's" example below shows
155 If an FPGA Region does not specify a FPGA Manager, it will inherit the FPGA
156 Manager specified by its ancestor FPGA Region. This supports both the case
157 where the same FPGA Manager is used for all of a FPGA as well the case where
158 a different FPGA Manager is used for each region.
160 FPGA Regions do not inherit their ancestor FPGA regions' bridges. This prevents
161 shutting down bridges that are upstream from the other active regions while one
162 region is getting reconfigured (see Figure 1 above). During PR, the FPGA's
163 hardware bridges remain enabled. The PR regions' bridges will be FPGA bridges
164 within the static image of the FPGA.
167 - compatible : should contain "fpga-region"
168 - fpga-mgr : should contain a phandle to an FPGA Manager. Child FPGA Regions
169 inherit this property from their ancestor regions. A fpga-mgr property
170 in a region will override any inherited FPGA manager.
171 - #address-cells, #size-cells, ranges : must be present to handle address space
172 mapping for child nodes.
175 - firmware-name : should contain the name of an FPGA image file located on the
176 firmware search path. If this property shows up in a live device tree
177 it indicates that the FPGA has already been programmed with this image.
178 If this property is in an overlay targeting a FPGA region, it is a
179 request to program the FPGA with that image.
180 - fpga-bridges : should contain a list of phandles to FPGA Bridges that must be
181 controlled during FPGA programming along with the parent FPGA bridge.
182 This property is optional if the FPGA Manager handles the bridges.
183 If the fpga-region is the child of a fpga-bridge, the list should not
184 contain the parent bridge.
185 - partial-fpga-config : boolean, set if partial reconfiguration is to be done,
186 otherwise full reconfiguration is done.
187 - external-fpga-config : boolean, set if the FPGA has already been configured
189 - region-unfreeze-timeout-us : The maximum time in microseconds to wait for
190 bridges to successfully become enabled after the region has been
192 - region-freeze-timeout-us : The maximum time in microseconds to wait for
193 bridges to successfully become disabled before the region has been
195 - config-complete-timeout-us : The maximum time in microseconds time for the
196 FPGA to go to operating mode after the region has been programmed.
197 - child nodes : devices in the FPGA after programming.
199 In the example below, when an overlay is applied targeting fpga-region0,
200 fpga_mgr is used to program the FPGA. Two bridges are controlled during
201 programming: the parent fpga_bridge0 and fpga_bridge1. Because the region is
202 the child of fpga_bridge0, only fpga_bridge1 needs to be specified in the
203 fpga-bridges property. During programming, these bridges are disabled, the
204 firmware specified in the overlay is loaded to the FPGA using the FPGA manager
205 specified in the region. If FPGA programming succeeds, the bridges are
206 reenabled and the overlay makes it into the live device tree. The child devices
207 are then populated. If FPGA programming fails, the bridges are left disabled
208 and the overlay is rejected. The overlay's ranges property maps the lwhps
209 bridge's region (0xff200000) and the hps bridge's region (0xc0000000) for use by
210 the two child devices.
215 fpga_mgr: fpga-mgr@ff706000 {
216 compatible = "altr,socfpga-fpga-mgr";
217 reg = <0xff706000 0x1000
219 interrupts = <0 175 4>;
222 fpga_bridge0: fpga-bridge@ff400000 {
223 compatible = "altr,socfpga-lwhps2fpga-bridge";
224 reg = <0xff400000 0x100000>;
225 resets = <&rst LWHPS2FPGA_RESET>;
226 clocks = <&l4_main_clk>;
228 #address-cells = <1>;
232 fpga_region0: fpga-region0 {
233 compatible = "fpga-region";
234 fpga-mgr = <&fpga_mgr>;
238 fpga_bridge1: fpga-bridge@ff500000 {
239 compatible = "altr,socfpga-hps2fpga-bridge";
240 reg = <0xff500000 0x10000>;
241 resets = <&rst HPS2FPGA_RESET>;
242 clocks = <&l4_main_clk>;
250 target = <&fpga_region0>;
251 #address-cells = <1>;
254 #address-cells = <1>;
257 firmware-name = "soc_system.rbf";
258 fpga-bridges = <&fpga_bridge1>;
259 ranges = <0x20000 0xff200000 0x100000>,
260 <0x0 0xc0000000 0x20000000>;
263 compatible = "altr,pio-1.0";
264 reg = <0x10040 0x20>;
265 altr,gpio-bank-width = <4>;
272 device_type = "memory";
273 compatible = "altr,onchipmem-15.1";
284 In all cases the live DT must have the FPGA Manager, FPGA Bridges (if any), and
285 a FPGA Region. The target of the Device Tree Overlay is the FPGA Region. Some
286 uses are specific to a FPGA device.
289 In this case, the FPGA Manager which programs the FPGA also handles the
290 bridges behind the scenes. No FPGA Bridge devices are needed for full
293 * Full reconfiguration with hardware bridges
294 In this case, there are hardware bridges between the processor and FPGA that
295 need to be controlled during full reconfiguration. Before the overlay is
296 applied, the live DT must include the FPGA Manager, FPGA Bridges, and a
297 FPGA Region. The FPGA Region is the child of the bridge that allows
298 register access to the FPGA. Additional bridges may be listed in a
299 fpga-bridges property in the FPGA region or in the device tree overlay.
301 * Partial reconfiguration with bridges in the FPGA
302 In this case, the FPGA will have one or more PRR's that may be programmed
303 separately while the rest of the FPGA can remain active. To manage this,
304 bridges need to exist in the FPGA that can gate the buses going to each FPGA
305 region while the buses are enabled for other sections. Before any partial
306 reconfiguration can be done, a base FPGA image must be loaded which includes
307 PRR's with FPGA bridges. The device tree should have a FPGA region for each
313 The intention of this section is to give some simple examples, focusing on
314 the placement of the elements detailed above, especially:
319 * target-path or target
321 For the purposes of this section, I'm dividing the Device Tree into two parts,
322 each with its own requirements. The two parts are:
323 * The live DT prior to the overlay being added
326 The live Device Tree must contain an FPGA Region, an FPGA Manager, and any FPGA
327 Bridges. The FPGA Region's "fpga-mgr" property specifies the manager by phandle
328 to handle programming the FPGA. If the FPGA Region is the child of another FPGA
329 Region, the parent's FPGA Manager is used. If FPGA Bridges need to be involved,
330 they are specified in the FPGA Region by the "fpga-bridges" property. During
331 FPGA programming, the FPGA Region will disable the bridges that are in its
332 "fpga-bridges" list and will re-enable them after FPGA programming has
335 The Device Tree Overlay will contain:
336 * "target-path" or "target"
337 The insertion point where the the contents of the overlay will go into the
338 live tree. target-path is a full path, while target is a phandle.
340 The address space mapping from processor to FPGA bus(ses).
342 Specifies the name of the FPGA image file on the firmware search
343 path. The search path is described in the firmware class documentation.
344 * "partial-fpga-config"
345 This binding is a boolean and should be present if partial reconfiguration
347 * child nodes corresponding to hardware that will be loaded in this region of
350 Device Tree Example: Full Reconfiguration without Bridges
351 =========================================================
353 Live Device Tree contains:
354 fpga_mgr0: fpga-mgr@f8007000 {
355 compatible = "xlnx,zynq-devcfg-1.0";
356 reg = <0xf8007000 0x100>;
357 interrupt-parent = <&intc>;
358 interrupts = <0 8 4>;
360 clock-names = "ref_clk";
364 fpga_region0: fpga-region0 {
365 compatible = "fpga-region";
366 fpga-mgr = <&fpga_mgr0>;
367 #address-cells = <0x1>;
376 target = <&fpga_region0>;
377 #address-cells = <1>;
380 #address-cells = <1>;
383 firmware-name = "zynq-gpio.bin";
385 gpio1: gpio@40000000 {
386 compatible = "xlnx,xps-gpio-1.00.a";
387 reg = <0x40000000 0x10000>;
390 xlnx,gpio-width= <0x6>;
395 Device Tree Example: Full Reconfiguration to add PRR's
396 ======================================================
398 The base FPGA Region is specified similar to the first example above.
400 This example programs the FPGA to have two regions that can later be partially
401 configured. Each region has its own bridge in the FPGA fabric.
407 target = <&fpga_region0>;
408 #address-cells = <1>;
411 #address-cells = <1>;
414 firmware-name = "base.rbf";
417 compatible = "altr,freeze-bridge";
420 fpga_region1: fpga-region1 {
421 compatible = "fpga-region";
422 #address-cells = <0x1>;
429 compatible = "altr,freeze-bridge";
432 fpga_region2: fpga-region2 {
433 compatible = "fpga-region";
434 #address-cells = <0x1>;
443 Device Tree Example: Partial Reconfiguration
444 ============================================
446 This example reprograms one of the PRR's set up in the previous example.
448 The sequence that occurs when this overlay is similar to the above, the only
449 differences are that the FPGA is partially reconfigured due to the
450 "partial-fpga-config" boolean and the only bridge that is controlled during
451 programming is the FPGA based bridge of fpga_region1.
456 target = <&fpga_region1>;
457 #address-cells = <1>;
460 #address-cells = <1>;
463 firmware-name = "soc_image2.rbf";
467 compatible = "altr,pio-1.0";
468 reg = <0x10040 0x20>;
470 altr,gpio-bank-width = <0x4>;
482 It is beyond the scope of this document to fully describe all the FPGA design
483 constraints required to make partial reconfiguration work[1] [2] [3], but a few
484 deserve quick mention.
486 A persona must have boundary connections that line up with those of the partion
487 or region it is designed to go into.
489 During programming, transactions through those connections must be stopped and
490 the connections must be held at a fixed logic level. This can be achieved by
491 FPGA Bridges that exist on the FPGA fabric prior to the partial reconfiguration.
494 [1] www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/ug/ug_partrecon.pdf
495 [2] tspace.library.utoronto.ca/bitstream/1807/67932/1/Byma_Stuart_A_201411_MAS_thesis.pdf
496 [3] http://www.xilinx.com/support/documentation/sw_manuals/xilinx14_1/ug702.pdf