tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1# SPDX-License-Identifier: GPL-2.0
2%YAML 1.2
3---
4$id: http://devicetree.org/schemas/fpga/fpga-region.yaml#
5$schema: http://devicetree.org/meta-schemas/core.yaml#
6
7title: FPGA Region
8
9maintainers:
10 - Michal Simek <michal.simek@amd.com>
11
12description: |
13 CONTENTS
14 - Introduction
15 - Terminology
16 - Sequence
17 - FPGA Region
18 - Supported Use Models
19 - Constraints
20
21 Introduction
22 ============
23
24 FPGA Regions represent FPGA's and partial reconfiguration regions of FPGA's in
25 the Device Tree. FPGA Regions provide a way to program FPGAs under device tree
26 control.
27
28 The documentation hits some of the high points of FPGA usage and
29 attempts to include terminology used by both major FPGA manufacturers. This
30 document isn't a replacement for any manufacturers specifications for FPGA
31 usage.
32
33 Terminology
34 ===========
35
36 Full Reconfiguration
37 * The entire FPGA is programmed.
38
39 Partial Reconfiguration (PR)
40 * A section of an FPGA is reprogrammed while the rest of the FPGA is not
41 affected.
42 * Not all FPGA's support PR.
43
44 Partial Reconfiguration Region (PRR)
45 * Also called a "reconfigurable partition"
46 * A PRR is a specific section of an FPGA reserved for reconfiguration.
47 * A base (or static) FPGA image may create a set of PRR's that later may
48 be independently reprogrammed many times.
49 * The size and specific location of each PRR is fixed.
50 * The connections at the edge of each PRR are fixed. The image that is loaded
51 into a PRR must fit and must use a subset of the region's connections.
52 * The busses within the FPGA are split such that each region gets its own
53 branch that may be gated independently.
54
55 Persona
56 * Also called a "partial bit stream"
57 * An FPGA image that is designed to be loaded into a PRR. There may be
58 any number of personas designed to fit into a PRR, but only one at a time
59 may be loaded.
60 * A persona may create more regions.
61
62 FPGA Bridge
63 * FPGA Bridges gate bus signals between a host and FPGA.
64 * FPGA Bridges should be disabled while the FPGA is being programmed to
65 prevent spurious signals on the cpu bus and to the soft logic.
66 * FPGA bridges may be actual hardware or soft logic on an FPGA.
67 * During Full Reconfiguration, hardware bridges between the host and FPGA
68 will be disabled.
69 * During Partial Reconfiguration of a specific region, that region's bridge
70 will be used to gate the busses. Traffic to other regions is not affected.
71 * In some implementations, the FPGA Manager transparently handles gating the
72 buses, eliminating the need to show the hardware FPGA bridges in the
73 device tree.
74 * An FPGA image may create a set of reprogrammable regions, each having its
75 own bridge and its own split of the busses in the FPGA.
76
77 FPGA Manager
78 * An FPGA Manager is a hardware block that programs an FPGA under the control
79 of a host processor.
80
81 Base Image
82 * Also called the "static image"
83 * An FPGA image that is designed to do full reconfiguration of the FPGA.
84 * A base image may set up a set of partial reconfiguration regions that may
85 later be reprogrammed.
86
87 ---------------- ----------------------------------
88 | Host CPU | | FPGA |
89 | | | |
90 | ----| | ----------- -------- |
91 | | H | | |==>| Bridge0 |<==>| PRR0 | |
92 | | W | | | ----------- -------- |
93 | | | | | |
94 | | B |<=====>|<==| ----------- -------- |
95 | | R | | |==>| Bridge1 |<==>| PRR1 | |
96 | | I | | | ----------- -------- |
97 | | D | | | |
98 | | G | | | ----------- -------- |
99 | | E | | |==>| Bridge2 |<==>| PRR2 | |
100 | ----| | ----------- -------- |
101 | | | |
102 ---------------- ----------------------------------
103
104 Figure 1: An FPGA set up with a base image that created three regions. Each
105 region (PRR0-2) gets its own split of the busses that is independently gated by
106 a soft logic bridge (Bridge0-2) in the FPGA. The contents of each PRR can be
107 reprogrammed independently while the rest of the system continues to function.
108
109 Sequence
110 ========
111
112 When a DT overlay that targets an FPGA Region is applied, the FPGA Region will
113 do the following:
114
115 1. Disable appropriate FPGA bridges.
116 2. Program the FPGA using the FPGA manager.
117 3. Enable the FPGA bridges.
118 4. The Device Tree overlay is accepted into the live tree.
119 5. Child devices are populated.
120
121 When the overlay is removed, the child nodes will be removed and the FPGA Region
122 will disable the bridges.
123
124 FPGA Region
125 ===========
126
127 FPGA Regions represent FPGA's and FPGA PR regions in the device tree. An FPGA
128 Region brings together the elements needed to program on a running system and
129 add the child devices:
130
131 * FPGA Manager
132 * FPGA Bridges
133 * image-specific information needed to the programming.
134 * child nodes
135
136 The intended use is that a Device Tree overlay (DTO) can be used to reprogram an
137 FPGA while an operating system is running.
138
139 An FPGA Region that exists in the live Device Tree reflects the current state.
140 If the live tree shows a "firmware-name" property or child nodes under an FPGA
141 Region, the FPGA already has been programmed. A DTO that targets an FPGA Region
142 and adds the "firmware-name" property is taken as a request to reprogram the
143 FPGA. After reprogramming is successful, the overlay is accepted into the live
144 tree.
145
146 The base FPGA Region in the device tree represents the FPGA and supports full
147 reconfiguration. It must include a phandle to an FPGA Manager. The base
148 FPGA region will be the child of one of the hardware bridges (the bridge that
149 allows register access) between the cpu and the FPGA. If there are more than
150 one bridge to control during FPGA programming, the region will also contain a
151 list of phandles to the additional hardware FPGA Bridges.
152
153 For partial reconfiguration (PR), each PR region will have an FPGA Region.
154 These FPGA regions are children of FPGA bridges which are then children of the
155 base FPGA region. The "Full Reconfiguration to add PRR's" example below shows
156 this.
157
158 If an FPGA Region does not specify an FPGA Manager, it will inherit the FPGA
159 Manager specified by its ancestor FPGA Region. This supports both the case
160 where the same FPGA Manager is used for all of an FPGA as well the case where
161 a different FPGA Manager is used for each region.
162
163 FPGA Regions do not inherit their ancestor FPGA regions' bridges. This prevents
164 shutting down bridges that are upstream from the other active regions while one
165 region is getting reconfigured (see Figure 1 above). During PR, the FPGA's
166 hardware bridges remain enabled. The PR regions' bridges will be FPGA bridges
167 within the static image of the FPGA.
168
169 Supported Use Models
170 ====================
171
172 In all cases the live DT must have the FPGA Manager, FPGA Bridges (if any), and
173 a FPGA Region. The target of the Device Tree Overlay is the FPGA Region. Some
174 uses are specific to an FPGA device.
175
176 * No FPGA Bridges
177 In this case, the FPGA Manager which programs the FPGA also handles the
178 bridges behind the scenes. No FPGA Bridge devices are needed for full
179 reconfiguration.
180
181 * Full reconfiguration with hardware bridges
182 In this case, there are hardware bridges between the processor and FPGA that
183 need to be controlled during full reconfiguration. Before the overlay is
184 applied, the live DT must include the FPGA Manager, FPGA Bridges, and a
185 FPGA Region. The FPGA Region is the child of the bridge that allows
186 register access to the FPGA. Additional bridges may be listed in a
187 fpga-bridges property in the FPGA region or in the device tree overlay.
188
189 * Partial reconfiguration with bridges in the FPGA
190 In this case, the FPGA will have one or more PRR's that may be programmed
191 separately while the rest of the FPGA can remain active. To manage this,
192 bridges need to exist in the FPGA that can gate the buses going to each FPGA
193 region while the buses are enabled for other sections. Before any partial
194 reconfiguration can be done, a base FPGA image must be loaded which includes
195 PRR's with FPGA bridges. The device tree should have an FPGA region for each
196 PRR.
197
198 Constraints
199 ===========
200
201 It is beyond the scope of this document to fully describe all the FPGA design
202 constraints required to make partial reconfiguration work[1] [2] [3], but a few
203 deserve quick mention.
204
205 A persona must have boundary connections that line up with those of the partition
206 or region it is designed to go into.
207
208 During programming, transactions through those connections must be stopped and
209 the connections must be held at a fixed logic level. This can be achieved by
210 FPGA Bridges that exist on the FPGA fabric prior to the partial reconfiguration.
211
212 --
213 [1] https://www.intel.com/programmable/technical-pdfs/683404.pdf
214 [2] tspace.library.utoronto.ca/bitstream/1807/67932/1/Byma_Stuart_A_201411_MAS_thesis.pdf
215 [3] https://docs.amd.com/v/u/en-US/ug702
216
217properties:
218 $nodename:
219 pattern: "^fpga-region(@.*|-([0-9]|[1-9][0-9]+))?$"
220
221 compatible:
222 const: fpga-region
223
224 reg:
225 maxItems: 1
226
227 ranges: true
228 "#address-cells": true
229 "#size-cells": true
230
231 config-complete-timeout-us:
232 description:
233 The maximum time in microseconds time for the FPGA to go to operating
234 mode after the region has been programmed.
235
236 encrypted-fpga-config:
237 type: boolean
238 description:
239 Set if the bitstream is encrypted.
240
241 external-fpga-config:
242 type: boolean
243 description:
244 Set if the FPGA has already been configured prior to OS boot up.
245
246 firmware-name:
247 maxItems: 1
248 description:
249 Should contain the name of an FPGA image file located on the firmware
250 search path. If this property shows up in a live device tree it indicates
251 that the FPGA has already been programmed with this image.
252 If this property is in an overlay targeting an FPGA region, it is
253 a request to program the FPGA with that image.
254
255 fpga-bridges:
256 $ref: /schemas/types.yaml#/definitions/phandle-array
257 description:
258 Should contain a list of phandles to FPGA Bridges that must be
259 controlled during FPGA programming along with the parent FPGA bridge.
260 This property is optional if the FPGA Manager handles the bridges.
261 If the fpga-region is the child of an fpga-bridge, the list should not
262 contain the parent bridge.
263
264 fpga-mgr:
265 $ref: /schemas/types.yaml#/definitions/phandle
266 description:
267 Should contain a phandle to an FPGA Manager. Child FPGA Regions
268 inherit this property from their ancestor regions. An fpga-mgr property
269 in a region will override any inherited FPGA manager.
270
271 partial-fpga-config:
272 type: boolean
273 description:
274 Set if partial reconfiguration is to be done, otherwise full
275 reconfiguration is done.
276
277 region-freeze-timeout-us:
278 description:
279 The maximum time in microseconds to wait for bridges to successfully
280 become disabled before the region has been programmed.
281
282 region-unfreeze-timeout-us:
283 description:
284 The maximum time in microseconds to wait for bridges to successfully
285 become enabled after the region has been programmed.
286
287required:
288 - compatible
289 - fpga-mgr
290
291additionalProperties:
292 type: object
293
294examples:
295 - |
296 /*
297 * Full Reconfiguration without Bridges with DT overlay
298 */
299 fpga_region0: fpga-region@0 {
300 compatible = "fpga-region";
301 reg = <0 0>;
302 #address-cells = <1>;
303 #size-cells = <1>;
304 fpga-mgr = <&fpga_mgr0>;
305 ranges = <0x10000000 0x20000000 0x10000000>;
306
307 /* DT Overlay contains: &fpga_region0 */
308 firmware-name = "zynq-gpio.bin";
309 gpio@40000000 {
310 compatible = "xlnx,xps-gpio-1.00.a";
311 reg = <0x40000000 0x10000>;
312 gpio-controller;
313 #gpio-cells = <2>;
314 clocks = <&clk>;
315 };
316 };
317
318 - |
319 /*
320 * Partial reconfiguration with bridge
321 */
322 fpga_region1: fpga-region@0 {
323 compatible = "fpga-region";
324 reg = <0 0>;
325 ranges;
326 #address-cells = <1>;
327 #size-cells = <1>;
328 fpga-mgr = <&fpga_mgr1>;
329 fpga-bridges = <&fpga_bridge1>;
330 partial-fpga-config;
331
332 /* DT Overlay contains: &fpga_region1 */
333 firmware-name = "zynq-gpio-partial.bin";
334 clk: clock {
335 compatible = "fixed-factor-clock";
336 clocks = <&parentclk>;
337 #clock-cells = <0>;
338 clock-div = <2>;
339 clock-mult = <1>;
340 };
341 axi {
342 compatible = "simple-bus";
343 #address-cells = <1>;
344 #size-cells = <1>;
345 ranges;
346 gpio@40000000 {
347 compatible = "xlnx,xps-gpio-1.00.a";
348 reg = <0x40000000 0x10000>;
349 #gpio-cells = <2>;
350 gpio-controller;
351 clocks = <&clk>;
352 };
353 };
354 };