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