bindings/fpga/fpga-region.txt

1 FPGA Region Device Tree Binding
9  - FPGA Region
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.
35  * A section of an FPGA is reprogrammed while the rest of the FPGA is not
37  * Not all FPGA's support PR.
41  * A PRR is a specific section of an FPGA reserved for reconfiguration.
42  * A base (or static) FPGA image may create a set of PRR's that later may
47  * The busses within the FPGA are split such that each region gets its own
52  * An FPGA image that is designed to be loaded into a PRR.  There may be
57 FPGA Bridge
58  * FPGA Bridges gate bus signals between a host and FPGA.
59  * FPGA Bridges should be disabled while the FPGA is being programmed to
61  * FPGA bridges may be actual hardware or soft logic on an FPGA.
62  * During Full Reconfiguration, hardware bridges between the host and FPGA
66  * In some implementations, the FPGA Manager transparently 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.
72 FPGA Manager
73  * An FPGA Manager is a hardware block that programs an FPGA under the control
78  * An FPGA image that is designed to do full reconfiguration of the FPGA.
83     |  Host CPU    |       |             FPGA               |
99 Figure 1: An FPGA set up with a base image that created three regions.  Each
101 a soft logic bridge (Bridge0-2) in the FPGA.  The contents of each PRR can be
108 When a DT overlay that targets an 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.
117 When the overlay is removed, the child nodes will be removed and the FPGA Region
121 FPGA Region
124 FPGA Regions represent FPGA's and FPGA PR regions in the device tree.  An FPGA
128  * FPGA Manager
129  * FPGA Bridges
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 an FPGA
138 Region, the FPGA already has been programmed.  A DTO that targets an FPGA Region
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 an 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 an 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
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.
168 - fpga-mgr : should contain a phandle to an FPGA Manager.  Child FPGA Regions
170 	in a region will override any inherited FPGA manager.
175 - firmware-name : should contain the name of an FPGA image file located on the
177 	it indicates that the FPGA has already been programmed with this image.
178 	If this property is in an overlay targeting an 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.
187 - external-fpga-config : boolean, set if the FPGA has already been configured
197 	FPGA to go to operating mode after the region has been programmed.
198 - child nodes : devices in the FPGA after programming.
201 fpga_mgr is used to program the FPGA.  Two bridges are controlled during
205 firmware specified in the overlay is loaded to the FPGA using the FPGA manager
206 specified in the region.  If FPGA programming succeeds, the bridges are
208 are then populated.  If FPGA programming fails, the bridges are left disabled
280 In all cases the live DT must have the FPGA Manager, FPGA Bridges (if any), and
281 a FPGA Region.  The target of the Device Tree Overlay is the FPGA Region.  Some
282 uses are specific to an FPGA device.
284  * No FPGA Bridges
285    In this case, the FPGA Manager which programs the FPGA also handles the
286    bridges behind the scenes.  No FPGA Bridge devices are needed for full
290    In this case, there are hardware bridges between the processor and FPGA that
292    applied, the live DT must include the FPGA Manager, FPGA Bridges, and a
293    FPGA Region.  The FPGA Region is the child of the bridge that allows
294    register access to the FPGA.  Additional bridges may be listed in a
295    fpga-bridges property in the FPGA region or in the device tree overlay.
297  * Partial reconfiguration with bridges in the FPGA
298    In this case, the FPGA will have one or more PRR's that may be programmed
299    separately while the rest of the FPGA can remain active.  To manage this,
300    bridges need to exist in the FPGA that can gate the buses going to each FPGA
302    reconfiguration can be done, a base FPGA image must be loaded which includes
303    PRR's with FPGA bridges.  The device tree should have an FPGA region for each
311  * FPGA Manager
312  * FPGA Bridges
313  * FPGA Region
322 The live Device Tree must contain an FPGA Region, an FPGA Manager, and any FPGA
323 Bridges.  The FPGA Region's "fpga-mgr" property specifies the manager by phandle
324 to handle programming the FPGA.  If the FPGA Region is the child of another FPGA
325 Region, the parent's FPGA Manager is used.  If FPGA Bridges need to be involved,
326 they are specified in the FPGA Region by the "fpga-bridges" property.  During
327 FPGA programming, the FPGA Region will disable the bridges that are in its
328 "fpga-bridges" list and will re-enable them after FPGA programming has
336     The address space mapping from processor to FPGA bus(ses).
338    Specifies the name of the FPGA image file on the firmware search
344    the FPGA.
391 The base FPGA Region is specified similar to the first example above.
393 This example programs the FPGA to have two regions that can later be partially
394 configured.  Each region has its own bridge in the FPGA fabric.
438 differences are that the FPGA is partially reconfigured due to the
440 programming is the FPGA based bridge of fpga_region1.
465 It is beyond the scope of this document to fully describe all the FPGA design
474 FPGA Bridges that exist on the FPGA fabric prior to the partial reconfiguration.