Documentation/devicetree/bindings/fpga/fpga-region.txt

   1 FPGA Region Device Tree Binding
   2
   3 Alan Tull 2016
   4
   5  CONTENTS
   6  - Introduction
   7  - Terminology
   8  - Sequence
   9  - FPGA Region
  10  - Supported Use Models
  11  - Device Tree Examples
  12  - Constraints
  13
  14
  15 Introduction
  16 ============
  17
  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
  20 control.
  21
  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
  25 usage.
  26
  27
  28 Terminology
  29 ===========
  30
  31 Full Reconfiguration
  32  * The entire FPGA is programmed.
  33
  34 Partial Reconfiguration (PR)
  35  * A section of an FPGA is reprogrammed while the rest of the FPGA is not
  36    affected.
  37  * Not all FPGA's support PR.
  38
  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.
  49
  50 Persona
  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
  54    may be loaded.
  55  * A persona may create more regions.
  56
  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
  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
  63    will be disabled.
  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
  68    device tree.
  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.
  71
  72 FPGA Manager
  73  * An FPGA Manager is a hardware block that programs an FPGA under the control
  74    of a host processor.
  75
  76 Base Image
  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.
  81
  82     ----------------       ----------------------------------
  83     |  Host CPU    |       |             FPGA               |
  84     |              |       |                                |
  85     |          ----|       |       -----------    --------  |
  86     |          | H |       |   |==>| Bridge0 |<==>| PRR0 |  |
  87     |          | W |       |   |   -----------    --------  |
  88     |          |   |       |   |                            |
  89     |          | B |<=====>|<==|   -----------    --------  |
  90     |          | R |       |   |==>| Bridge1 |<==>| PRR1 |  |
  91     |          | I |       |   |   -----------    --------  |
  92     |          | D |       |   |                            |
  93     |          | G |       |   |   -----------    --------  |
  94     |          | E |       |   |==>| Bridge2 |<==>| PRR2 |  |
  95     |          ----|       |       -----------    --------  |
  96     |              |       |                                |
  97     ----------------       ----------------------------------
  98
  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.
 103
 104
 105 Sequence
 106 ========
 107
 108 When a DT overlay that targets a FPGA Region is applied, the FPGA Region will
 109 do the following:
 110
 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.
 116
 117 When the overlay is removed, the child nodes will be removed and the FPGA Region
 118 will disable the bridges.
 119
 120
 121 FPGA Region
 122 ===========
 123
 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:
 127
 128  * FPGA Manager
 129  * FPGA Bridges
 130  * image-specific information needed to to the programming.
 131  * child nodes
 132
 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.
 135
 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
 141 tree.
 142
 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.
 149
 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
 153 this.
 154
 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.
 159
 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.
 165
 166 Required properties:
 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.
 173
 174 Optional properties:
 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
 188         prior to OS boot up.
 189 - encrypted-fpga-config : boolean, set if the bitstream is encrypted
 190 - region-unfreeze-timeout-us : The maximum time in microseconds to wait for
 191         bridges to successfully become enabled after the region has been
 192         programmed.
 193 - region-freeze-timeout-us : The maximum time in microseconds to wait for
 194         bridges to successfully become disabled before the region has been
 195         programmed.
 196 - config-complete-timeout-us : The maximum time in microseconds time for the
 197         FPGA to go to operating mode after the region has been programmed.
 198 - child nodes : devices in the FPGA after programming.
 199
 200 In the example below, when an overlay is applied targeting fpga-region0,
 201 fpga_mgr is used to program the FPGA.  Two bridges are controlled during
 202 programming: the parent fpga_bridge0 and fpga_bridge1.  Because the region is
 203 the child of fpga_bridge0, only fpga_bridge1 needs to be specified in the
 204 fpga-bridges property.  During programming, these bridges are disabled, the
 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
 207 reenabled and the overlay makes it into the live device tree.  The child devices
 208 are then populated.  If FPGA programming fails, the bridges are left disabled
 209 and the overlay is rejected.  The overlay's ranges property maps the lwhps
 210 bridge's region (0xff200000) and the hps bridge's region (0xc0000000) for use by
 211 the two child devices.
 212
 213 Example:
 214 Base tree contains:
 215
 216         fpga_mgr: fpga-mgr@ff706000 {
 217                 compatible = "altr,socfpga-fpga-mgr";
 218                 reg = <0xff706000 0x1000
 219                        0xffb90000 0x20>;
 220                 interrupts = <0 175 4>;
 221         };
 222
 223         fpga_bridge0: fpga-bridge@ff400000 {
 224                 compatible = "altr,socfpga-lwhps2fpga-bridge";
 225                 reg = <0xff400000 0x100000>;
 226                 resets = <&rst LWHPS2FPGA_RESET>;
 227                 clocks = <&l4_main_clk>;
 228
 229                 #address-cells = <1>;
 230                 #size-cells = <1>;
 231                 ranges;
 232
 233                 fpga_region0: fpga-region0 {
 234                         compatible = "fpga-region";
 235                         fpga-mgr = <&fpga_mgr>;
 236                 };
 237         };
 238
 239         fpga_bridge1: fpga-bridge@ff500000 {
 240                 compatible = "altr,socfpga-hps2fpga-bridge";
 241                 reg = <0xff500000 0x10000>;
 242                 resets = <&rst HPS2FPGA_RESET>;
 243                 clocks = <&l4_main_clk>;
 244         };
 245
 246 Overlay contains:
 247
 248 /dts-v1/ /plugin/;
 249 / {
 250         fragment@0 {
 251                 target = <&fpga_region0>;
 252                 #address-cells = <1>;
 253                 #size-cells = <1>;
 254                 __overlay__ {
 255                         #address-cells = <1>;
 256                         #size-cells = <1>;
 257
 258                         firmware-name = "soc_system.rbf";
 259                         fpga-bridges = <&fpga_bridge1>;
 260                         ranges = <0x20000 0xff200000 0x100000>,
 261                                  <0x0 0xc0000000 0x20000000>;
 262
 263                         gpio@10040 {
 264                                 compatible = "altr,pio-1.0";
 265                                 reg = <0x10040 0x20>;
 266                                 altr,gpio-bank-width = <4>;
 267                                 #gpio-cells = <2>;
 268                                 clocks = <2>;
 269                                 gpio-controller;
 270                         };
 271
 272                         onchip-memory {
 273                                 device_type = "memory";
 274                                 compatible = "altr,onchipmem-15.1";
 275                                 reg = <0x0 0x10000>;
 276                         };
 277                 };
 278         };
 279 };
 280
 281
 282 Supported Use Models
 283 ====================
 284
 285 In all cases the live DT must have the FPGA Manager, FPGA Bridges (if any), and
 286 a FPGA Region.  The target of the Device Tree Overlay is the FPGA Region.  Some
 287 uses are specific to a FPGA device.
 288
 289  * No FPGA Bridges
 290    In this case, the FPGA Manager which programs the FPGA also handles the
 291    bridges behind the scenes.  No FPGA Bridge devices are needed for full
 292    reconfiguration.
 293
 294  * Full reconfiguration with hardware bridges
 295    In this case, there are hardware bridges between the processor and FPGA that
 296    need to be controlled during full reconfiguration.  Before the overlay is
 297    applied, the live DT must include the FPGA Manager, FPGA Bridges, and a
 298    FPGA Region.  The FPGA Region is the child of the bridge that allows
 299    register access to the FPGA.  Additional bridges may be listed in a
 300    fpga-bridges property in the FPGA region or in the device tree overlay.
 301
 302  * Partial reconfiguration with bridges in the FPGA
 303    In this case, the FPGA will have one or more PRR's that may be programmed
 304    separately while the rest of the FPGA can remain active.  To manage this,
 305    bridges need to exist in the FPGA that can gate the buses going to each FPGA
 306    region while the buses are enabled for other sections.  Before any partial
 307    reconfiguration can be done, a base FPGA image must be loaded which includes
 308    PRR's with FPGA bridges.  The device tree should have a FPGA region for each
 309    PRR.
 310
 311 Device Tree Examples
 312 ====================
 313
 314 The intention of this section is to give some simple examples, focusing on
 315 the placement of the elements detailed above, especially:
 316  * FPGA Manager
 317  * FPGA Bridges
 318  * FPGA Region
 319  * ranges
 320  * target-path or target
 321
 322 For the purposes of this section, I'm dividing the Device Tree into two parts,
 323 each with its own requirements.  The two parts are:
 324  * The live DT prior to the overlay being added
 325  * The DT overlay
 326
 327 The live Device Tree must contain an FPGA Region, an FPGA Manager, and any FPGA
 328 Bridges.  The FPGA Region's "fpga-mgr" property specifies the manager by phandle
 329 to handle programming the FPGA.  If the FPGA Region is the child of another FPGA
 330 Region, the parent's FPGA Manager is used.  If FPGA Bridges need to be involved,
 331 they are specified in the FPGA Region by the "fpga-bridges" property.  During
 332 FPGA programming, the FPGA Region will disable the bridges that are in its
 333 "fpga-bridges" list and will re-enable them after FPGA programming has
 334 succeeded.
 335
 336 The Device Tree Overlay will contain:
 337  * "target-path" or "target"
 338    The insertion point where the the contents of the overlay will go into the
 339    live tree.  target-path is a full path, while target is a phandle.
 340  * "ranges"
 341     The address space mapping from processor to FPGA bus(ses).
 342  * "firmware-name"
 343    Specifies the name of the FPGA image file on the firmware search
 344    path.  The search path is described in the firmware class documentation.
 345  * "partial-fpga-config"
 346    This binding is a boolean and should be present if partial reconfiguration
 347    is to be done.
 348  * child nodes corresponding to hardware that will be loaded in this region of
 349    the FPGA.
 350
 351 Device Tree Example: Full Reconfiguration without Bridges
 352 =========================================================
 353
 354 Live Device Tree contains:
 355         fpga_mgr0: fpga-mgr@f8007000 {
 356                 compatible = "xlnx,zynq-devcfg-1.0";
 357                 reg = <0xf8007000 0x100>;
 358                 interrupt-parent = <&intc>;
 359                 interrupts = <0 8 4>;
 360                 clocks = <&clkc 12>;
 361                 clock-names = "ref_clk";
 362                 syscon = <&slcr>;
 363         };
 364
 365         fpga_region0: fpga-region0 {
 366                 compatible = "fpga-region";
 367                 fpga-mgr = <&fpga_mgr0>;
 368                 #address-cells = <0x1>;
 369                 #size-cells = <0x1>;
 370                 ranges;
 371         };
 372
 373 DT Overlay contains:
 374 /dts-v1/ /plugin/;
 375 / {
 376 fragment@0 {
 377         target = <&fpga_region0>;
 378         #address-cells = <1>;
 379         #size-cells = <1>;
 380         __overlay__ {
 381                 #address-cells = <1>;
 382                 #size-cells = <1>;
 383
 384                 firmware-name = "zynq-gpio.bin";
 385
 386                 gpio1: gpio@40000000 {
 387                         compatible = "xlnx,xps-gpio-1.00.a";
 388                         reg = <0x40000000 0x10000>;
 389                         gpio-controller;
 390                         #gpio-cells = <0x2>;
 391                         xlnx,gpio-width= <0x6>;
 392                 };
 393         };
 394 };
 395
 396 Device Tree Example: Full Reconfiguration to add PRR's
 397 ======================================================
 398
 399 The base FPGA Region is specified similar to the first example above.
 400
 401 This example programs the FPGA to have two regions that can later be partially
 402 configured.  Each region has its own bridge in the FPGA fabric.
 403
 404 DT Overlay contains:
 405 /dts-v1/ /plugin/;
 406 / {
 407         fragment@0 {
 408                 target = <&fpga_region0>;
 409                 #address-cells = <1>;
 410                 #size-cells = <1>;
 411                 __overlay__ {
 412                         #address-cells = <1>;
 413                         #size-cells = <1>;
 414
 415                         firmware-name = "base.rbf";
 416
 417                         fpga-bridge@4400 {
 418                                 compatible = "altr,freeze-bridge-controller";
 419                                 reg = <0x4400 0x10>;
 420
 421                                 fpga_region1: fpga-region1 {
 422                                         compatible = "fpga-region";
 423                                         #address-cells = <0x1>;
 424                                         #size-cells = <0x1>;
 425                                         ranges;
 426                                 };
 427                         };
 428
 429                         fpga-bridge@4420 {
 430                                 compatible = "altr,freeze-bridge-controller";
 431                                 reg = <0x4420 0x10>;
 432
 433                                 fpga_region2: fpga-region2 {
 434                                         compatible = "fpga-region";
 435                                         #address-cells = <0x1>;
 436                                         #size-cells = <0x1>;
 437                                         ranges;
 438                                 };
 439                         };
 440                 };
 441         };
 442 };
 443
 444 Device Tree Example: Partial Reconfiguration
 445 ============================================
 446
 447 This example reprograms one of the PRR's set up in the previous example.
 448
 449 The sequence that occurs when this overlay is similar to the above, the only
 450 differences are that the FPGA is partially reconfigured due to the
 451 "partial-fpga-config" boolean and the only bridge that is controlled during
 452 programming is the FPGA based bridge of fpga_region1.
 453
 454 /dts-v1/ /plugin/;
 455 / {
 456         fragment@0 {
 457                 target = <&fpga_region1>;
 458                 #address-cells = <1>;
 459                 #size-cells = <1>;
 460                 __overlay__ {
 461                         #address-cells = <1>;
 462                         #size-cells = <1>;
 463
 464                         firmware-name = "soc_image2.rbf";
 465                         partial-fpga-config;
 466
 467                         gpio@10040 {
 468                                 compatible = "altr,pio-1.0";
 469                                 reg = <0x10040 0x20>;
 470                                 clocks = <0x2>;
 471                                 altr,gpio-bank-width = <0x4>;
 472                                 resetvalue = <0x0>;
 473                                 #gpio-cells = <0x2>;
 474                                 gpio-controller;
 475                         };
 476                 };
 477         };
 478 };
 479
 480 Constraints
 481 ===========
 482
 483 It is beyond the scope of this document to fully describe all the FPGA design
 484 constraints required to make partial reconfiguration work[1] [2] [3], but a few
 485 deserve quick mention.
 486
 487 A persona must have boundary connections that line up with those of the partion
 488 or region it is designed to go into.
 489
 490 During programming, transactions through those connections must be stopped and
 491 the connections must be held at a fixed logic level.  This can be achieved by
 492 FPGA Bridges that exist on the FPGA fabric prior to the partial reconfiguration.
 493
 494 --
 495 [1] www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/ug/ug_partrecon.pdf
 496 [2] tspace.library.utoronto.ca/bitstream/1807/67932/1/Byma_Stuart_A_201411_MAS_thesis.pdf
 497 [3] http://www.xilinx.com/support/documentation/sw_manuals/xilinx14_1/ug702.pdf