fpga-region.txt 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497
  1. FPGA Region Device Tree Binding
  2. Alan Tull 2016
  3. CONTENTS
  4. - Introduction
  5. - Terminology
  6. - Sequence
  7. - FPGA Region
  8. - Supported Use Models
  9. - Device Tree Examples
  10. - Constraints
  11. Introduction
  12. ============
  13. FPGA Regions represent FPGA's and partial reconfiguration regions of FPGA's in
  14. the Device Tree. FPGA Regions provide a way to program FPGAs under device tree
  15. control.
  16. This device tree binding document hits some of the high points of FPGA usage and
  17. attempts to include terminology used by both major FPGA manufacturers. This
  18. document isn't a replacement for any manufacturers specifications for FPGA
  19. usage.
  20. Terminology
  21. ===========
  22. Full Reconfiguration
  23. * The entire FPGA is programmed.
  24. Partial Reconfiguration (PR)
  25. * A section of an FPGA is reprogrammed while the rest of the FPGA is not
  26. affected.
  27. * Not all FPGA's support PR.
  28. Partial Reconfiguration Region (PRR)
  29. * Also called a "reconfigurable partition"
  30. * A PRR is a specific section of a FPGA reserved for reconfiguration.
  31. * A base (or static) FPGA image may create a set of PRR's that later may
  32. be independently reprogrammed many times.
  33. * The size and specific location of each PRR is fixed.
  34. * The connections at the edge of each PRR are fixed. The image that is loaded
  35. into a PRR must fit and must use a subset of the region's connections.
  36. * The busses within the FPGA are split such that each region gets its own
  37. branch that may be gated independently.
  38. Persona
  39. * Also called a "partial bit stream"
  40. * An FPGA image that is designed to be loaded into a PRR. There may be
  41. any number of personas designed to fit into a PRR, but only one at at time
  42. may be loaded.
  43. * A persona may create more regions.
  44. FPGA Bridge
  45. * FPGA Bridges gate bus signals between a host and FPGA.
  46. * FPGA Bridges should be disabled while the FPGA is being programmed to
  47. prevent spurious signals on the cpu bus and to the soft logic.
  48. * FPGA bridges may be actual hardware or soft logic on an FPGA.
  49. * During Full Reconfiguration, hardware bridges between the host and FPGA
  50. will be disabled.
  51. * During Partial Reconfiguration of a specific region, that region's bridge
  52. will be used to gate the busses. Traffic to other regions is not affected.
  53. * In some implementations, the FPGA Manager transparantly handles gating the
  54. buses, eliminating the need to show the hardware FPGA bridges in the
  55. device tree.
  56. * An FPGA image may create a set of reprogrammable regions, each having its
  57. own bridge and its own split of the busses in the FPGA.
  58. FPGA Manager
  59. * An FPGA Manager is a hardware block that programs an FPGA under the control
  60. of a host processor.
  61. Base Image
  62. * Also called the "static image"
  63. * An FPGA image that is designed to do full reconfiguration of the FPGA.
  64. * A base image may set up a set of partial reconfiguration regions that may
  65. later be reprogrammed.
  66. ---------------- ----------------------------------
  67. | Host CPU | | FPGA |
  68. | | | |
  69. | ----| | ----------- -------- |
  70. | | H | | |==>| Bridge0 |<==>| PRR0 | |
  71. | | W | | | ----------- -------- |
  72. | | | | | |
  73. | | B |<=====>|<==| ----------- -------- |
  74. | | R | | |==>| Bridge1 |<==>| PRR1 | |
  75. | | I | | | ----------- -------- |
  76. | | D | | | |
  77. | | G | | | ----------- -------- |
  78. | | E | | |==>| Bridge2 |<==>| PRR2 | |
  79. | ----| | ----------- -------- |
  80. | | | |
  81. ---------------- ----------------------------------
  82. Figure 1: An FPGA set up with a base image that created three regions. Each
  83. region (PRR0-2) gets its own split of the busses that is independently gated by
  84. a soft logic bridge (Bridge0-2) in the FPGA. The contents of each PRR can be
  85. reprogrammed independently while the rest of the system continues to function.
  86. Sequence
  87. ========
  88. When a DT overlay that targets a FPGA Region is applied, the FPGA Region will
  89. do the following:
  90. 1. Disable appropriate FPGA bridges.
  91. 2. Program the FPGA using the FPGA manager.
  92. 3. Enable the FPGA bridges.
  93. 4. The Device Tree overlay is accepted into the live tree.
  94. 5. Child devices are populated.
  95. When the overlay is removed, the child nodes will be removed and the FPGA Region
  96. will disable the bridges.
  97. FPGA Region
  98. ===========
  99. FPGA Regions represent FPGA's and FPGA PR regions in the device tree. An FPGA
  100. Region brings together the elements needed to program on a running system and
  101. add the child devices:
  102. * FPGA Manager
  103. * FPGA Bridges
  104. * image-specific information needed to to the programming.
  105. * child nodes
  106. The intended use is that a Device Tree overlay (DTO) can be used to reprogram an
  107. FPGA while an operating system is running.
  108. An FPGA Region that exists in the live Device Tree reflects the current state.
  109. If the live tree shows a "firmware-name" property or child nodes under a FPGA
  110. Region, the FPGA already has been programmed. A DTO that targets a FPGA Region
  111. and adds the "firmware-name" property is taken as a request to reprogram the
  112. FPGA. After reprogramming is successful, the overlay is accepted into the live
  113. tree.
  114. The base FPGA Region in the device tree represents the FPGA and supports full
  115. reconfiguration. It must include a phandle to an FPGA Manager. The base
  116. FPGA region will be the child of one of the hardware bridges (the bridge that
  117. allows register access) between the cpu and the FPGA. If there are more than
  118. one bridge to control during FPGA programming, the region will also contain a
  119. list of phandles to the additional hardware FPGA Bridges.
  120. For partial reconfiguration (PR), each PR region will have an FPGA Region.
  121. These FPGA regions are children of FPGA bridges which are then children of the
  122. base FPGA region. The "Full Reconfiguration to add PRR's" example below shows
  123. this.
  124. If an FPGA Region does not specify a FPGA Manager, it will inherit the FPGA
  125. Manager specified by its ancestor FPGA Region. This supports both the case
  126. where the same FPGA Manager is used for all of a FPGA as well the case where
  127. a different FPGA Manager is used for each region.
  128. FPGA Regions do not inherit their ancestor FPGA regions' bridges. This prevents
  129. shutting down bridges that are upstream from the other active regions while one
  130. region is getting reconfigured (see Figure 1 above). During PR, the FPGA's
  131. hardware bridges remain enabled. The PR regions' bridges will be FPGA bridges
  132. within the static image of the FPGA.
  133. Required properties:
  134. - compatible : should contain "fpga-region"
  135. - fpga-mgr : should contain a phandle to an FPGA Manager. Child FPGA Regions
  136. inherit this property from their ancestor regions. A fpga-mgr property
  137. in a region will override any inherited FPGA manager.
  138. - #address-cells, #size-cells, ranges : must be present to handle address space
  139. mapping for child nodes.
  140. Optional properties:
  141. - firmware-name : should contain the name of an FPGA image file located on the
  142. firmware search path. If this property shows up in a live device tree
  143. it indicates that the FPGA has already been programmed with this image.
  144. If this property is in an overlay targeting a FPGA region, it is a
  145. request to program the FPGA with that image.
  146. - fpga-bridges : should contain a list of phandles to FPGA Bridges that must be
  147. controlled during FPGA programming along with the parent FPGA bridge.
  148. This property is optional if the FPGA Manager handles the bridges.
  149. If the fpga-region is the child of a fpga-bridge, the list should not
  150. contain the parent bridge.
  151. - partial-fpga-config : boolean, set if partial reconfiguration is to be done,
  152. otherwise full reconfiguration is done.
  153. - external-fpga-config : boolean, set if the FPGA has already been configured
  154. prior to OS boot up.
  155. - encrypted-fpga-config : boolean, set if the bitstream is encrypted
  156. - region-unfreeze-timeout-us : The maximum time in microseconds to wait for
  157. bridges to successfully become enabled after the region has been
  158. programmed.
  159. - region-freeze-timeout-us : The maximum time in microseconds to wait for
  160. bridges to successfully become disabled before the region has been
  161. programmed.
  162. - config-complete-timeout-us : The maximum time in microseconds time for the
  163. FPGA to go to operating mode after the region has been programmed.
  164. - child nodes : devices in the FPGA after programming.
  165. In the example below, when an overlay is applied targeting fpga-region0,
  166. fpga_mgr is used to program the FPGA. Two bridges are controlled during
  167. programming: the parent fpga_bridge0 and fpga_bridge1. Because the region is
  168. the child of fpga_bridge0, only fpga_bridge1 needs to be specified in the
  169. fpga-bridges property. During programming, these bridges are disabled, the
  170. firmware specified in the overlay is loaded to the FPGA using the FPGA manager
  171. specified in the region. If FPGA programming succeeds, the bridges are
  172. reenabled and the overlay makes it into the live device tree. The child devices
  173. are then populated. If FPGA programming fails, the bridges are left disabled
  174. and the overlay is rejected. The overlay's ranges property maps the lwhps
  175. bridge's region (0xff200000) and the hps bridge's region (0xc0000000) for use by
  176. the two child devices.
  177. Example:
  178. Base tree contains:
  179. fpga_mgr: fpga-mgr@ff706000 {
  180. compatible = "altr,socfpga-fpga-mgr";
  181. reg = <0xff706000 0x1000
  182. 0xffb90000 0x20>;
  183. interrupts = <0 175 4>;
  184. };
  185. fpga_bridge0: fpga-bridge@ff400000 {
  186. compatible = "altr,socfpga-lwhps2fpga-bridge";
  187. reg = <0xff400000 0x100000>;
  188. resets = <&rst LWHPS2FPGA_RESET>;
  189. clocks = <&l4_main_clk>;
  190. #address-cells = <1>;
  191. #size-cells = <1>;
  192. ranges;
  193. fpga_region0: fpga-region0 {
  194. compatible = "fpga-region";
  195. fpga-mgr = <&fpga_mgr>;
  196. };
  197. };
  198. fpga_bridge1: fpga-bridge@ff500000 {
  199. compatible = "altr,socfpga-hps2fpga-bridge";
  200. reg = <0xff500000 0x10000>;
  201. resets = <&rst HPS2FPGA_RESET>;
  202. clocks = <&l4_main_clk>;
  203. };
  204. Overlay contains:
  205. /dts-v1/ /plugin/;
  206. / {
  207. fragment@0 {
  208. target = <&fpga_region0>;
  209. #address-cells = <1>;
  210. #size-cells = <1>;
  211. __overlay__ {
  212. #address-cells = <1>;
  213. #size-cells = <1>;
  214. firmware-name = "soc_system.rbf";
  215. fpga-bridges = <&fpga_bridge1>;
  216. ranges = <0x20000 0xff200000 0x100000>,
  217. <0x0 0xc0000000 0x20000000>;
  218. gpio@10040 {
  219. compatible = "altr,pio-1.0";
  220. reg = <0x10040 0x20>;
  221. altr,gpio-bank-width = <4>;
  222. #gpio-cells = <2>;
  223. clocks = <2>;
  224. gpio-controller;
  225. };
  226. onchip-memory {
  227. device_type = "memory";
  228. compatible = "altr,onchipmem-15.1";
  229. reg = <0x0 0x10000>;
  230. };
  231. };
  232. };
  233. };
  234. Supported Use Models
  235. ====================
  236. In all cases the live DT must have the FPGA Manager, FPGA Bridges (if any), and
  237. a FPGA Region. The target of the Device Tree Overlay is the FPGA Region. Some
  238. uses are specific to a FPGA device.
  239. * No FPGA Bridges
  240. In this case, the FPGA Manager which programs the FPGA also handles the
  241. bridges behind the scenes. No FPGA Bridge devices are needed for full
  242. reconfiguration.
  243. * Full reconfiguration with hardware bridges
  244. In this case, there are hardware bridges between the processor and FPGA that
  245. need to be controlled during full reconfiguration. Before the overlay is
  246. applied, the live DT must include the FPGA Manager, FPGA Bridges, and a
  247. FPGA Region. The FPGA Region is the child of the bridge that allows
  248. register access to the FPGA. Additional bridges may be listed in a
  249. fpga-bridges property in the FPGA region or in the device tree overlay.
  250. * Partial reconfiguration with bridges in the FPGA
  251. In this case, the FPGA will have one or more PRR's that may be programmed
  252. separately while the rest of the FPGA can remain active. To manage this,
  253. bridges need to exist in the FPGA that can gate the buses going to each FPGA
  254. region while the buses are enabled for other sections. Before any partial
  255. reconfiguration can be done, a base FPGA image must be loaded which includes
  256. PRR's with FPGA bridges. The device tree should have a FPGA region for each
  257. PRR.
  258. Device Tree Examples
  259. ====================
  260. The intention of this section is to give some simple examples, focusing on
  261. the placement of the elements detailed above, especially:
  262. * FPGA Manager
  263. * FPGA Bridges
  264. * FPGA Region
  265. * ranges
  266. * target-path or target
  267. For the purposes of this section, I'm dividing the Device Tree into two parts,
  268. each with its own requirements. The two parts are:
  269. * The live DT prior to the overlay being added
  270. * The DT overlay
  271. The live Device Tree must contain an FPGA Region, an FPGA Manager, and any FPGA
  272. Bridges. The FPGA Region's "fpga-mgr" property specifies the manager by phandle
  273. to handle programming the FPGA. If the FPGA Region is the child of another FPGA
  274. Region, the parent's FPGA Manager is used. If FPGA Bridges need to be involved,
  275. they are specified in the FPGA Region by the "fpga-bridges" property. During
  276. FPGA programming, the FPGA Region will disable the bridges that are in its
  277. "fpga-bridges" list and will re-enable them after FPGA programming has
  278. succeeded.
  279. The Device Tree Overlay will contain:
  280. * "target-path" or "target"
  281. The insertion point where the the contents of the overlay will go into the
  282. live tree. target-path is a full path, while target is a phandle.
  283. * "ranges"
  284. The address space mapping from processor to FPGA bus(ses).
  285. * "firmware-name"
  286. Specifies the name of the FPGA image file on the firmware search
  287. path. The search path is described in the firmware class documentation.
  288. * "partial-fpga-config"
  289. This binding is a boolean and should be present if partial reconfiguration
  290. is to be done.
  291. * child nodes corresponding to hardware that will be loaded in this region of
  292. the FPGA.
  293. Device Tree Example: Full Reconfiguration without Bridges
  294. =========================================================
  295. Live Device Tree contains:
  296. fpga_mgr0: fpga-mgr@f8007000 {
  297. compatible = "xlnx,zynq-devcfg-1.0";
  298. reg = <0xf8007000 0x100>;
  299. interrupt-parent = <&intc>;
  300. interrupts = <0 8 4>;
  301. clocks = <&clkc 12>;
  302. clock-names = "ref_clk";
  303. syscon = <&slcr>;
  304. };
  305. fpga_region0: fpga-region0 {
  306. compatible = "fpga-region";
  307. fpga-mgr = <&fpga_mgr0>;
  308. #address-cells = <0x1>;
  309. #size-cells = <0x1>;
  310. ranges;
  311. };
  312. DT Overlay contains:
  313. /dts-v1/ /plugin/;
  314. / {
  315. fragment@0 {
  316. target = <&fpga_region0>;
  317. #address-cells = <1>;
  318. #size-cells = <1>;
  319. __overlay__ {
  320. #address-cells = <1>;
  321. #size-cells = <1>;
  322. firmware-name = "zynq-gpio.bin";
  323. gpio1: gpio@40000000 {
  324. compatible = "xlnx,xps-gpio-1.00.a";
  325. reg = <0x40000000 0x10000>;
  326. gpio-controller;
  327. #gpio-cells = <0x2>;
  328. xlnx,gpio-width= <0x6>;
  329. };
  330. };
  331. };
  332. Device Tree Example: Full Reconfiguration to add PRR's
  333. ======================================================
  334. The base FPGA Region is specified similar to the first example above.
  335. This example programs the FPGA to have two regions that can later be partially
  336. configured. Each region has its own bridge in the FPGA fabric.
  337. DT Overlay contains:
  338. /dts-v1/ /plugin/;
  339. / {
  340. fragment@0 {
  341. target = <&fpga_region0>;
  342. #address-cells = <1>;
  343. #size-cells = <1>;
  344. __overlay__ {
  345. #address-cells = <1>;
  346. #size-cells = <1>;
  347. firmware-name = "base.rbf";
  348. fpga-bridge@4400 {
  349. compatible = "altr,freeze-bridge";
  350. reg = <0x4400 0x10>;
  351. fpga_region1: fpga-region1 {
  352. compatible = "fpga-region";
  353. #address-cells = <0x1>;
  354. #size-cells = <0x1>;
  355. ranges;
  356. };
  357. };
  358. fpga-bridge@4420 {
  359. compatible = "altr,freeze-bridge";
  360. reg = <0x4420 0x10>;
  361. fpga_region2: fpga-region2 {
  362. compatible = "fpga-region";
  363. #address-cells = <0x1>;
  364. #size-cells = <0x1>;
  365. ranges;
  366. };
  367. };
  368. };
  369. };
  370. };
  371. Device Tree Example: Partial Reconfiguration
  372. ============================================
  373. This example reprograms one of the PRR's set up in the previous example.
  374. The sequence that occurs when this overlay is similar to the above, the only
  375. differences are that the FPGA is partially reconfigured due to the
  376. "partial-fpga-config" boolean and the only bridge that is controlled during
  377. programming is the FPGA based bridge of fpga_region1.
  378. /dts-v1/ /plugin/;
  379. / {
  380. fragment@0 {
  381. target = <&fpga_region1>;
  382. #address-cells = <1>;
  383. #size-cells = <1>;
  384. __overlay__ {
  385. #address-cells = <1>;
  386. #size-cells = <1>;
  387. firmware-name = "soc_image2.rbf";
  388. partial-fpga-config;
  389. gpio@10040 {
  390. compatible = "altr,pio-1.0";
  391. reg = <0x10040 0x20>;
  392. clocks = <0x2>;
  393. altr,gpio-bank-width = <0x4>;
  394. resetvalue = <0x0>;
  395. #gpio-cells = <0x2>;
  396. gpio-controller;
  397. };
  398. };
  399. };
  400. };
  401. Constraints
  402. ===========
  403. It is beyond the scope of this document to fully describe all the FPGA design
  404. constraints required to make partial reconfiguration work[1] [2] [3], but a few
  405. deserve quick mention.
  406. A persona must have boundary connections that line up with those of the partion
  407. or region it is designed to go into.
  408. During programming, transactions through those connections must be stopped and
  409. the connections must be held at a fixed logic level. This can be achieved by
  410. FPGA Bridges that exist on the FPGA fabric prior to the partial reconfiguration.
  411. --
  412. [1] www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/ug/ug_partrecon.pdf
  413. [2] tspace.library.utoronto.ca/bitstream/1807/67932/1/Byma_Stuart_A_201411_MAS_thesis.pdf
  414. [3] http://www.xilinx.com/support/documentation/sw_manuals/xilinx14_1/ug702.pdf