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