[PATCH v14 1/7] fpga: add usage documentation for fpga area

[atull]

From: Alan Tull <atull@xxxxxxxxxxxxxxxxxxxxx>

Add a document spelling out usage of the FPGA Area for
reprogramming FPGA's under Device Tree control.

Signed-off-by: Alan Tull <atull@xxxxxxxxxxxxxxxxxxxxx>

---
v9:  Initial version of this patch in patchset
v10: s/fpga/FPGA/g
     improve formatting
     some rewriting
     move to staging/simple-fpga-bus
v11: No change in this patch for v11 of the patch set
v12: Moved out of staging
     Small changes due to using FPGA bridge framework and not
     representing the bridges as resets.
v13: Fix some nits
v14: fpga-area instead of simple-fpga-bus
---
 Documentation/fpga/fpga-area.txt |  299 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 299 insertions(+)
 create mode 100644 Documentation/fpga/fpga-area.txt

diff --git a/Documentation/fpga/fpga-area.txt b/Documentation/fpga/fpga-area.txt
new file mode 100644
index 0000000..f031522
--- /dev/null
+++ b/Documentation/fpga/fpga-area.txt
@@ -0,0 +1,299 @@
+FPGA Area
+
+Alan Tull 2015
+
+Overview
+========
+
+An FPGA Area details information about a section of an FPGA including the FPGA
+image needed to program it and the hardware contained once it is programmed.
+
+Loading a Device Tree overlay which contains an FPGA Area will cause the
+FPGA to be programmed and the children of the FPGA Area will get probed.
+
+There may be FPGA Bridges involved to prevent spurious data from going out onto
+the processor bus during FPGA programming.  If so, the FPGA Area will need to
+disable and enable bridges that will only affect the child devices that are
+below the FPGA Area.  In the case of partial reconfiguration, bridges will
+be required within the FPGA design such that the active sections of the
+FPGA are on the bus while sections that are not programmed or being
+reprogrammed at the moment are isolated.
+
+Removing the overlay will result in the child devices getting removed and the
+bridges disabled.  Note that in the case of partial reconfiguration the rest of
+the FPGA continues to function as normal while this is happening.
+
+Below are more details on the structuring of the Device Tree for this.
+
+Terminology
+===========
+
+Full Reconfiguration
+ * The entire FPGA is reprogrammed.
+
+Partial Reconfiguration (PR)
+ * Part of the FPGA is reprogrammed while the rest of the FPGA is live and
+   active.  Not all FPGA's support this.
+
+Associated Blocks
+=================
+
+FPGA Manager Framework
+ * An FPGA Manager is a hardware block that programs an FPGA under the control
+   of a host processor.
+ * The FPGA Manager Framework provides drivers and functions to program an
+   FPGA.
+
+FPGA Bridge Framework
+ * Provides drivers and functions to control bridges that enable/disable
+   data to the FPGA.
+ * FPGA bridges should be disabled while the FPGA is being programmed to
+   prevent spurious data on the bus.
+ * FPGA bridges are not needed in implementations where the FPGA Manager
+   handles this.
+
+Device Tree
+===========
+
+For the purposes of this document, I'm dividing the Device Tree (DT) into two parts,
+each with its own requirements.  The two parts are:
+ * The live DT prior to the overlay being added
+ * The overlay containing an FPGA Area
+
+The live DT will contain:
+ * FPGA Manager
+ * FPGA Bridges as children of the FPGA Manager (optional, architecture specific)
+
+The live Device Tree must contain an FPGA Manager to handle programming the FPGA.
+If FPGA Bridges need to be involved, they show up in the DT as direct children
+of the FPGA Manager.  During full reconfiguration, the FPGA Area will disable
+any bridges that are direct children of the manager during full reconfiguration
+and will re-enable them afterwards.
+
+The insertion point in the live tree will also need the "simple-bus"
+compatibility string to enable populating the child nodes for the overlay.
+That includes the nodes for the FPGA Manager and controlling FPGA Bridges
+as explained below.
+
+The Device Tree Overlay will contain:
+ * "target-path"
+   The insertion point where the the contents of the overlay will go into the
+   live tree.
+ * "ranges"
+ * "firmware-name"
+   Specifies the name of the FPGA image file on the firmware search
+   path.  The search path is described in the firmware class documentation.
+ * "partial-reconfig"
+   This binding is a boolean and should be present if partial reconfiguration
+   is to be done.
+ * child nodes corresponding to hardware that will be loaded in this
+   region of the FPGA.
+
+Supported use models
+====================
+
+Here's a list of the superset of supported use models.  We may need to add
+more.  Some uses are specific to one FPGA or another.
+
+ * No FPGA Bridges
+   In this case, the FPGA Manager which programs the FPGA also handles the
+   bridges and no FPGA Bridge devices are needed for full reconfiguration.
+
+   The DT overlay will specify the FPGA Manager as the overlay target.
+
+ * Full reconfiguration with bridges
+   In the case, there are several bridges between the processor and FPGA,
+   that need to be disabled during full reconfiguration.
+   The DT before the overlay is applied will have an FPGA Manager.  The
+   immediate children of the manager will be the FPGA Bridges that need to be
+   disabled during FPGA programming.
+
+   The DT overlay will specify one of those bridges as the overlay target,
+   typically the bridge that allows memory mapped register access ("the
+   controlling bridge").
+
+ * Partial reconfiguration with bridges in the FPGA
+   In this case, the FPGA can have more than one section that will be
+   reprogrammed separately.  Other sections may be active on the bus while FPGA
+   is being programmed.  To manage this, FPGA Bridges need to exist on the FPGA
+   that can freeze all the buses going to one FPGA area while the buses are
+   enabled for other sections.
+
+Controlling Bridge
+==================
+
+It is possible that there are multiple FPGA Bridges connecting the processor
+and FPGA.  In a text based hierarchy, it is difficult to show this properly
+so what we do is consider the bridge that handles register access to be
+the controlling bridge.  The overlay is targeted to be inserted under the
+controlling bridge.  Other bridges are on the same level of the device tree
+as the controlling bridge, i.e. all are children of the FPGA Manager.  The
+ranges property handles mapping memory ranges through multiple bridges.
+
+Sequence
+========
+
+Load the DT overlay.  One way to do that from user space is to use Pantelis
+Antoniou's DT-Overlay configfs interface.  In that case the sequence from
+userspace is:
+
+ $ mkdir /config/device-tree/overlays/1
+ $ echo "some_overlay.dtb.o" > /config/device-tree/overlays/1/path
+
+This causes the FPGA Area to be probed and will do the following:
+ 1. Disable the FPGA bridges.
+ 2. Use the the FPGA manager core to program the FPGA.
+ 3. Enable the FPGA bridges.
+ 4. Call of_platform_populate resulting in device drivers getting probed.
+
+Removing the overlay is done by:
+
+ $ rmdir /config/device-tree/overlays/1
+
+This causes the child nodes to be removed and then the bridges are disabled.
+
+Device Tree Examples
+====================
+
+The intention of this section is to give some simple examples, focusing on
+the placement of the elements detailed above in, especially:
+ * FPGA Managers
+ * FPGA Bridges in some cases
+ * FPGA Areas and associated properties
+ * simple-bus
+ * ranges
+ * target-path
+
+Please note the "simple-bus" compatible string added for FPGA Managers and for
+FPGA Bridges where the overlay is targeted for insertion.  This is required for
+populating the child nodes.
+
+Device Tree Example: Partial Reconfiguration with no Bridges
+============================================================
+
+Live Device Tree contains:
+	fpgamgr@0 {
+		compatible = "altr,socfpga-a10-fpga-mgr", "simple-bus";
+		clocks = <&l4_mp_clk>;
+		resets = <&rst FPGAMGR_RESET>;
+		reset-names = "fpgamgr";
+		reg = <0xffd03000 0x1000
+		       0xffcfe400 0x1000>;
+
+		#address-cells = <0x1>;
+		#size-cells = <0x1>;
+		ranges;
+	};
+
+DT Overlay contains:
+/dts-v1/;
+/plugin/;
+/ {
+	fragment@0 {
+		target-path="/soc/fpgamgr@0";  /* targeted to the manager */
+		__overlay__ {
+			#address-cells = <1>;
+	                #size-cells = <1>;
+
+			area@0 {
+				compatible = "fpga-area";
+
+				#address-cells = <1>;
+				#size-cells = <1>;
+				ranges = <0x10010 0xff210010 0x10>;
+
+				firmware-name = "fit_pr_v1.rbf";
+				partial-reconfig;
+
+				gpio@0x100010010 {
+					compatible = "altr,pio-1.0";
+					reg = <0x10010 0x10>;
+					altr,ngpio = <4>;
+					#gpio-cells = <0x2>;
+					gpio-controller;
+				};
+			};
+		};
+	};
+};
+
+
+Device Tree Example: Full Reconfiguration with Bridges
+======================================================
+
+Live Device Tree contains:
+	fpgamgr@0 {
+		compatible = "altr,socfpga-fpga-mgr", "simple-bus";
+		reg = <0xFF706000 0x1000
+		       0xFFB90000 0x1000>;
+		interrupts = <0 175 4>;
+
+		#address-cells = <0x1>;
+		#size-cells = <0x1>;
+		ranges;
+
+		bridge@0 {
+			/* both the manager and the controlling bridge have
+			 * the added simple-bus compatible to allow child
+			 * devices to be populated. */
+			compatible = "altr,socfpga-lwhps2fpga-bridge",
+				     "simple-bus";
+			resets = <&rst LWHPS2FPGA_RESET>;
+			reset-names = "lwhps2fpga";
+			clocks = <&l4_main_clk>;
+			#address-cells = <0x1>;
+			#size-cells = <0x1>;
+			ranges;
+		};
+
+		bridge@1 {
+			/* In the case of full reconfiguration, both bridge@0
+			 * and bridge@1 will be disabled during FPGA
+			 * programming and enabled afterwards. */
+			compatible = "altr,socfpga-hps2fpga-bridge";
+			resets = <&rst HPS2FPGA_RESET>;
+			reset-names = "hps2fpga";
+			clocks = <&l4_main_clk>;
+		};
+	};
+
+DT Overlay contains:
+/dts-v1/;
+/plugin/;
+/ {
+	fragment@0 {
+		target-path="/soc/fpgamgr@0/bridge@0"; /* controlling bridge */
+		__overlay__ {
+			#address-cells = <1>;
+	                #size-cells = <1>;
+
+			area@0 {
+				compatible = "fpga-area";
+
+				#address-cells = <2>;
+				#size-cells = <1>;
+				/* Note that two ranges are mapped due to the
+				 * two bridges. */
+				ranges = <0 0x00000000 0xc0000000 0x00010000>,
+					 <1 0x00020000 0xff220000 0x00000008>;
+
+				firmware-name = "soc_system.rbf";
+
+				onchip_memory2_0: memory@000000000 {
+					device_type = "memory";
+					compatible = "altr,onchipmem-15.1";
+					reg = <0 0x00000000 0x00010000>;
+				};
+
+				jtag_uart: serial@0x100020000 {
+					compatible = "altr,juart-1.0";
+					reg = <1 0x00020000 0x00000008>;
+					interrupt-parent = <&intc>;
+					interrupts = <0 42 4>;
+					clocks = <&osc2>;
+				};
+			};
+		};
+	};
+};
+
-- 
1.7.9.5

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/