[PATCH v15 0/6] altera fpga area and fpga bus

[PATCH v15 0/6] altera fpga area and fpga bus

[atull]

From: Alan Tull <atull@opensource.altera.com>

For v15, I'm not using the FPGA Manager as the bus.  I'm adding a FPGA Bus;
the FPGA Manager and bridges go below it.

I've gotten enough feedback that my proposals are Altera specific that I am
going with that and changing the bindings to include an 'altr,' prefix.

I've combined the bindings document and the other Documentation/fpga/ document
and done a rewrite there.

Anybody who tried the previous patchset will not have much changes to do to get
this going.  The changes are:
 * The live tree has a 'altr,fpga-bus' which contains the FPGA Manager and
    FPGA Bridges.
 * The target path in your overlays needs to be adjusted accordingly.

That said, the changes for each of these submissions is getting to be less and
less; most of these patches are unchanged for v15.

Alan Tull (6):
  fpga: add bindings document for fpga area and fpga bus
  add sysfs document for fpga bridge class
  ARM: socfpga: add bindings document for fpga bridge drivers
  fpga: add fpga bridge framework
  fpga: fpga-area and fpga-bus: device tree control for FPGA
  ARM: socfpga: fpga bridge driver support

 Documentation/ABI/testing/sysfs-class-fpga-bridge  |   11 +
 .../bindings/fpga/altera-fpga-bus-fpga-area.txt    |  452 ++++++++++++++++++++
 .../bindings/fpga/altera-fpga2sdram-bridge.txt     |   15 +
 .../bindings/fpga/altera-hps2fpga-bridge.txt       |   43 ++
 drivers/fpga/Kconfig                               |   21 +
 drivers/fpga/Makefile                              |    7 +
 drivers/fpga/altera-fpga2sdram.c                   |  174 ++++++++
 drivers/fpga/altera-hps2fpga.c                     |  213 +++++++++
 drivers/fpga/fpga-area.c                           |  352 +++++++++++++++
 drivers/fpga/fpga-bridge.c                         |  388 +++++++++++++++++
 include/linux/fpga/fpga-bridge.h                   |   56 +++
 11 files changed, 1732 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-class-fpga-bridge
 create mode 100644 Documentation/devicetree/bindings/fpga/altera-fpga-bus-fpga-area.txt
 create mode 100644 Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt
 create mode 100644 Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt
 create mode 100644 drivers/fpga/altera-fpga2sdram.c
 create mode 100644 drivers/fpga/altera-hps2fpga.c
 create mode 100644 drivers/fpga/fpga-area.c
 create mode 100644 drivers/fpga/fpga-bridge.c
 create mode 100644 include/linux/fpga/fpga-bridge.h

-- 
1.7.9.5

[PATCH v15 1/6] fpga: add bindings document for fpga area and fpga bus

[atull]

From: Alan Tull <atull@opensource.altera.com>

New bindings document for FPGA Area for reprogramming
FPGA's under Device Tree control

Signed-off-by: Alan Tull <atull@opensource.altera.com>
---
v9:  initial version added to this patchset
v10: s/fpga/FPGA/g
     replace DT overlay example with slightly more complicated example
     move to staging/simple-fpga-bus
v11: No change in this patch for v11 of the patch set
v12: Moved out of staging.
     Changed to use FPGA bridges framework instead of resets
     for bridges.
v13: bridge@0xff20000 -> bridge@ff200000, etc
     Leave out directly talking about overlays
     Remove regs and clocks directly under simple-fpga-bus in example
     Use common "firmware-name" binding instead of "fpga-firmware"
v14: Use firmware-name in bindings description
     Call it FPGA Area
     Remove bindings that specify FPGA Manager and FPGA Bridges
v15: Cleanup as per Rob's comments
     Combine usage doc with bindings document
     Document as being Altera specific
     Additions and changes to add FPGA Bus
---
 .../bindings/fpga/altera-fpga-bus-fpga-area.txt    |  452 ++++++++++++++++++++
 1 file changed, 452 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/fpga/altera-fpga-bus-fpga-area.txt

diff --git a/Documentation/devicetree/bindings/fpga/altera-fpga-bus-fpga-area.txt b/Documentation/devicetree/bindings/fpga/altera-fpga-bus-fpga-area.txt
new file mode 100644
index 0000000..8ea38ca
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/altera-fpga-bus-fpga-area.txt
@@ -0,0 +1,452 @@
+Altera FPGA Area and FPGA Bus Device Tree Binding
+
+Alan Tull 2016
+
+ CONTENTS
+ - Introduction
+ - Terminology
+ - Overview
+ - Constraints
+ - FPGA Bus
+ - FPGA Area
+ - Supported Use Models
+ - Sequence
+ - Device Tree Examples
+
+
+Introduction
+============
+
+FPGA Buses and FPGA Areas are introduced as a way to solve the problem of how to
+reprogram an Altera FPGA under an operating system and have the new hardware
+show up in the device tree.  By adding these bindings to the Device Tree, a
+system can have the information needed to do the FPGA programming to add the
+desired hardware, and also the information about the devices to be added to the
+Device Tree once the programming has succeeded.
+
+
+Terminology
+===========
+
+Full Reconfiguration
+ * The entire FPGA is programmed.
+
+Partial Reconfiguration (PR)
+ * The FPGA is broken up into regions.  One of these regions is reprogrammed
+   while the rest of the FPGA is not affected.  Not all FPGA's support this.
+
+FPGA Manager & 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 & 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 may not be needed in implementations where the FPGA Manager
+   handles this.
+
+Freeze Blocks
+ * Freeze Blocks function as FPGA Bridges within the FPGA fabric.  In the case
+   of PR, the buses from the processor are split within the FPGA.  Each PR
+   region gets its own split of the buses, protected by an independently
+   controlled Freeze Block.  Several busses may be connected to a single
+   PR region; a Freeze Block controls the traffic of all these busses
+   together.
+
+Controlling Bridge
+ * The processor and FPGA may be connected by multiple FPGA Bridges.  In a text
+   based hierarchy, it is difficult to show this properly as a device would
+   have several parents.
+ * The bridge that handles register access to the FPGA is designated the
+   "controlling" bridge.
+ * The controlling bridge will be the target point under which the overlay is
+   inserted.
+
+
+Overview
+========
+
+This binding introduces the FPGA Bus and FPGA Area.
+
+An FPGA Bus is a virtualized bus that contains the devices needed to be able to
+program an FPGA device.  It contains a child FPGA Manager and may contain child
+FPGA Bridges, if needed.  The FPGA Manager is the hardware block that handles
+programming the FPGA.  FPGA Bridges function to prevent spurious data from the
+FPGA going on the processor busses during FPGA programming.  In the case of
+partial reconfiguration, additional bridges (Freeze Blocks) for each
+reconfiguration region are required.
+
+An FPGA Area contains information about a section of an FPGA (in the case of
+partial reconfiguration or the whole FPGA (for full reconfiguration).  The FPGA
+Area contains the name of the FPGA image file to be programmed and the child
+devices that will be contained in the FPGA after programming.
+
+The intended use is that device tree overlays can be used to add hardware to an
+FPGA while an operating system is running.  In that case, the FPGA Bus and its
+associated information will exist in the live device tree, while FPGA Areas are
+added to the device tree by applying device tree overlays while the operating
+system is running.  Loading such an overlay will cause the FPGA to be programmed
+and the child devices to be populated.  Removing an overlay will cause the
+devices to be removed from the device tree and free up those FPGA resources.
+
+
+Constraints
+===========
+
+It is beyond the scope of this document to fully describe all the FPGA design
+constraints required to make partial reconfiguration work[1] [2], but a few
+deserve quick mention.  A partial reconfiguration FPGA image must have
+boundary connections that line up with those the current programming of the
+FPGA.  Also, those during programming, those connections must be frozen.  This
+can be achieved by "Freeze Blocks" which are FPGA Bridges that exist on the FPGA
+fabric prior to the partial reconfiguration.
+
+
+FPGA Bus
+========
+
+An FPGA bus is a virtualized bus that specifies the devices needed to program an
+FPGA.
+
+Required properties:
+- compatible : should contain "altr,fpga-bus" and "simple-bus"
+	       "simple-bus" is required to allow populating the child nodes.
+
+A FPGA Bus should contain an FPGA Manager as a child node.
+
+A FPGA Bus may require FPGA Bridges as child nodes if the FPGA Manager does not
+control the hardware bridges.
+
+The FPGA Bridge that allows memory mapped register access is designated the
+"controlling" bridge.  This bridge serves as the insertion point of DT overlays.
+Both the FPGA Area and the controlling bridge require the "simple-bus"
+compatibility string to allow populating the child nodes contained in the
+overlay.
+
+In the example below, fpgamgr@ff706000 would be used to do any programming
+operations on the FPGA and the two bridges specified would be disabled
+during the programming and re-enabled afterwards if the programming
+succeeds.
+
+Example:
+	fpgabus@0 {
+		compatible = "altr,fpga-bus", "simple-bus";
+		#address-cells = <0x1>;
+		#size-cells = <0x1>;
+		ranges;
+
+		fpgamgr@ff706000 {
+			compatible = "altr,socfpga-fpga-mgr";
+			reg = <0xff706000 0x1000
+			       0xffb90000 0x1000>;
+			interrupts = <0 175 4>;
+		};
+
+		bridge@0 {
+			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 {
+			compatible = "altr,socfpga-hps2fpga-bridge";
+			resets = <&rst HPS2FPGA_RESET>;
+			reset-names = "hps2fpga";
+			clocks = <&l4_main_clk>;
+		};
+	};
+
+FPGA Area
+=========
+
+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.
+
+An FPGA Area corresponds to the whole FPGA in the case of full reconfiguration
+or a section of an FPGA in the case of partial reconfiguration.
+
+Required properties:
+- compatible : should contain "altr,fpga-area"
+- #address-cells, #size-cells, ranges: must be present to handle address space
+  mapping for children.
+
+Optional properties:
+- firmware-name : should contain the name of an FPGA image file located on the
+  firmware search path.
+- partial-reconfig : boolean property should be defined if partial
+  reconfiguration of the FPGA is to be done, otherwise full reconfiguration
+  is done.
+
+In the example below, the target path is the controlling bridge of the FPGA Bus
+example.  The FPGA would be programmed with the image contained in the
+"soc_system.rbf" specified.  Assuming programming succeeds, the child devices
+would be populated afterwords.  In this particular example, ranges has two
+chip selects as one memory region is tied to the host processor and the
+other is a memory region on the FPGA.
+
+If there are no bridges in the FPGA Bus, the target path would point to
+the FPGA Manager.
+
+Example:
+
+/dts-v1/;
+/plugin/;
+/ {
+	fragment@0 {
+		target-path="/soc/fpgamgr@ff706000/bridge@0";
+		__overlay__ {
+			#address-cells = <1>;
+		        #size-cells = <1>;
+
+			bridge@ff200000 {
+				compatible = "fpga-area";
+
+				#address-cells = <2>;
+				#size-cells = <1>;
+
+				ranges = <0 0x00000000 0xc0000000 0x00010000>,
+					 <1 0x00020000 0xff220000 0x00000008>,
+					 <1 0x00010040 0xff210040 0x00000020>;
+
+				firmware-name = "soc_system.rbf";
+
+				onchip_memory2_0: memory@0 {
+					device_type = "memory";
+					compatible = "altr,onchipmem-15.1";
+					reg = <0 0x00000000 0x00010000>;
+				};
+
+				jtag_uart: serial@100020000 {
+					compatible = "altr,juart-1.0";
+					reg = <1 0x00020000 0x00000008>;
+					interrupt-parent = <&intc>;
+					interrupts = <0 42 4>;
+				};
+
+				led_pio: gpio@100010040 {
+					compatible = "altr,pio-1.0";
+					reg = <1 0x00010040 0x00000020>;
+					altr,gpio-bank-width = <4>;
+					#gpio-cells = <2>;
+					gpio-controller;
+				};
+			};
+		};
+	};
+};
+
+Supported Use Models
+====================
+
+Here's a list of supported use models.  We may need to add more.  Some uses are
+specific to one FPGA device or another.
+
+ * No FPGA Bridges
+   In this case, the FPGA Manager which programs the FPGA also handles the
+   bridges.  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 live DT before the
+   overlay is applied will have an FPGA Bus.
+
+   The DT overlay will specify the controlling bridge as the overlay target.
+
+ * Partial reconfiguration with bridges in the FPGA
+   In this case, the FPGA will have more than one section that will be
+   programmed separately.  Other sections may be active on the bus while FPGA
+   is being programmed.  To manage this, Freeze blocks 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.
+
+Sequence
+========
+
+When a DT overlay is loaded, the FPGA Area will 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.
+
+When the overlay is removed, the FPGA Area in it is removed.  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, especially:
+ * FPGA Bus and associated FPGA Manager and FPGA Bridges
+ * FPGA Area and associated properties
+ * simple-bus
+ * ranges
+ * target-path
+
+For the purposes of this section, I'm dividing the Device Tree into two parts,
+each with its own requirements.  The two parts are:
+ * The live DT prior to the overlay being added
+ * The DT overlay
+
+The live Device Tree must contain an FPGA Bus, which has a child 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 Bus.  During full reconfiguration, the
+FPGA Area will disable any bridges that are direct children of the FPGA Bus and
+will re-enable them after FPGA programming has succeeded.
+
+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.
+
+
+Device Tree Example: Partial Reconfiguration with no Bridges
+============================================================
+
+Live Device Tree contains:
+	fpgamgr@ffd03000 {
+		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@ffd03000";  /* 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@100010010 {
+					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@ff706000 {
+		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@ff706000/bridge@0"; /* controlling bridge */
+		__overlay__ {
+			#address-cells = <1>;
+		        #size-cells = <1>;
+
+			area@0 {
+				compatible = "fpga-area";
+
+				#address-cells = <2>;
+				#size-cells = <1>;
+				ranges = <0 0x00000000 0xc0000000 0x00010000>,
+					 <1 0x00020000 0xff220000 0x00000008>;
+
+				firmware-name = "soc_system.rbf";
+
+				onchip_memory2_0: memory@0 {
+					device_type = "memory";
+					compatible = "altr,onchipmem-15.1";
+					reg = <0 0x00000000 0x00010000>;
+				};
+
+				jtag_uart: serial@100020000 {
+					compatible = "altr,juart-1.0";
+					reg = <1 0x00020000 0x00000008>;
+					interrupt-parent = <&intc>;
+					interrupts = <0 42 4>;
+					clocks = <&osc2>;
+				};
+			};
+		};
+	};
+};
+
+--
+[1] www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/ug/ug_partrecon.pdf
+[2] tspace.library.utoronto.ca/bitstream/1807/67932/1/Byma_Stuart_A_201411_MAS_thesis.pdf
-- 
1.7.9.5

[PATCH v15 2/6] add sysfs document for fpga bridge class

[atull]

From: Alan Tull <atull@opensource.altera.com>

Add documentation for new FPGA bridge class's sysfs interface.

Signed-off-by: Alan Tull <atull@opensource.altera.com>

[PATCH v15 3/6] ARM: socfpga: add bindings document for fpga bridge drivers

[atull]

From: Alan Tull <atull@opensource.altera.com>

Add bindings documentation for Altera SOCFPGA bridges:
 * fpga2sdram
 * fpga2hps
 * hps2fpga
 * lwhps2fpga

Signed-off-by: Alan Tull <atull@opensource.altera.com>
Signed-off-by: Matthew Gerlach <mgerlach@altera.com>
Signed-off-by: Dinh Nguyen <dinguyen@opensource.altera.com>
---
v2:  separate into 2 documents for the 2 drivers
v12: bump version to line up with simple-fpga-bus version
     remove Linux specific notes such as references to sysfs
     move non-DT specific documentation elsewhere
     remove bindings that would have been used to pass configuration
     clean up formatting
v13: Remove 'label' property
     Change property from init-val to bridge-enable
     Fix email address
v14: Add resets
     Change order of bridges to put lw bridge (controlling bridge) first
v15: No change in this patch for v15 of this patch set
---
 .../bindings/fpga/altera-fpga2sdram-bridge.txt     |   15 +++++++
 .../bindings/fpga/altera-hps2fpga-bridge.txt       |   43 ++++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt
 create mode 100644 Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt

diff --git a/Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt b/Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt
new file mode 100644
index 0000000..81e2f06
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt
@@ -0,0 +1,15 @@
+Altera FPGA To SDRAM Bridge Driver
+
+Required properties:
+- compatible		: Should contain "altr,socfpga-fpga2sdram-bridge"
+
+Optional properties:
+- bridge-enable		: 0 if driver should disable bridge at startup
+			  1 if driver should enable bridge at startup
+			  Default is to leave bridge in current state.
+
+Example:
+	fpga2sdram_br: fpgabridge@3 {
+		compatible = "altr,socfpga-fpga2sdram-bridge";
+		bridge-enable = <0>;
+	};
diff --git a/Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt b/Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt
new file mode 100644
index 0000000..16db3b0
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt
@@ -0,0 +1,43 @@
+Altera FPGA/HPS Bridge Driver
+
+Required properties:
+- compatible	: Should contain one of:
+		  "altr,socfpga-lwhps2fpga-bridge",
+		  "altr,socfpga-hps2fpga-bridge", or
+		  "altr,socfpga-fpga2hps-bridge"
+- reset-names	: Should contain one of:
+		  "lwhps2fpga",
+		  "hps2fpga", or
+		  "fpga2hps"
+- resets	: Phandle and reset specifier for the reset listed in
+		  reset-names
+- clocks	: Clocks used by this module.
+
+Optional properties:
+- bridge-enable	: 0 if driver should disable bridge at startup.
+		  1 if driver should enable bridge at startup.
+		  Default is to leave bridge in its current state.
+
+Example:
+	hps_fpgabridge0: fpgabridge@0 {
+		compatible = "altr,socfpga-lwhps2fpga-bridge";
+		resets = <&rst LWHPS2FPGA_RESET>;
+		reset-names = "lwhps2fpga";
+		clocks = <&l4_main_clk>;
+		bridge-enable = <0>;
+	};
+
+	hps_fpgabridge1: fpgabridge@1 {
+		compatible = "altr,socfpga-hps2fpga-bridge";
+		resets = <&rst HPS2FPGA_RESET>;
+		reset-names = "hps2fpga";
+		clocks = <&l4_main_clk>;
+		bridge-enable = <1>;
+	};
+
+	hps_fpgabridge2: fpgabridge@2 {
+		compatible = "altr,socfpga-fpga2hps-bridge";
+		resets = <&rst FPGA2HPS_RESET>;
+		reset-names = "fpga2hps";
+		clocks = <&l4_main_clk>;
+	};
-- 
1.7.9.5

[PATCH v15 4/6] fpga: add fpga bridge framework

[atull]

From: Alan Tull <atull@opensource.altera.com>

This framework adds API functions for enabling/
disabling FPGA bridges under kernel control.

This allows the Linux kernel to disable FPGA bridges
during FPGA reprogramming and to enable FPGA bridges
when FPGA reprogramming is done.  This framework is
be manufacturer-agnostic, allowing it to be used in
interfaces that use the FPGA Manager Framework to
reprogram FPGA's.

The functions are:
* of_fpga_bridge_get
* fpga_bridge_put
   Get/put an exclusive reference to a FPGA bridge.

* fpga_bridge_enable
* fpga_bridge_disable
   Enable/Disable traffic through a bridge.

* fpga_bridge_register
* fpga_bridge_unregister
   Register/unregister a device-specific low level FPGA
   Bridge driver.

Get an exclusive reference to a bridge and add it to a list:
* fpga_bridge_get_to_list

To enable/disable/put a set of bridges that are on a list:
* fpga_bridges_enable
* fpga_bridges_disable
* fpga_bridges_put

Signed-off-by: Alan Tull <atull@opensource.altera.com>
---
v2:  Minor cleanup
v12: Bump version to line up with simple fpga bus
     Remove sysfs
     Improve get/put functions, get the low level driver too.
     Clean up class implementation
     Add kernel doc documentation
     Rename (un)register_fpga_bridge -> fpga_bridge_(un)register
v13: Add inlined empty functions for if not CONFIG_FPGA_BRIDGE
     Clean up debugging
     Remove unneeded #include in .h
     Remove unnecessary prints
     Remove 'label' DT binding.
     Document the mutex
v14: Allow bridges with no ops
     *const* struct fpga_bridge_ops
     Add functions to git/put/enable/disable list of bridges
     Add list node to struct fpga_bridge
     Do of_node_get/put in of_fpga_bridge_get()
     Add r/o attributes: name and state
v15: No change in this patch for v15 of this patch set
---
 drivers/fpga/Kconfig             |    7 +
 drivers/fpga/Makefile            |    3 +
 drivers/fpga/fpga-bridge.c       |  388 ++++++++++++++++++++++++++++++++++++++
 include/linux/fpga/fpga-bridge.h |   56 ++++++
 4 files changed, 454 insertions(+)
 create mode 100644 drivers/fpga/fpga-bridge.c
 create mode 100644 include/linux/fpga/fpga-bridge.h

diff --git a/drivers/fpga/Kconfig b/drivers/fpga/Kconfig
index c9b9fdf..b6cfd89 100644
--- a/drivers/fpga/Kconfig
+++ b/drivers/fpga/Kconfig
@@ -24,6 +24,13 @@ config FPGA_MGR_ZYNQ_FPGA
 	help
 	  FPGA manager driver support for Xilinx Zynq FPGAs.
 
+config FPGA_BRIDGE
+       bool "FPGA Bridge Framework"
+       depends on OF
+       help
+         Say Y here if you want to support bridges connected between host
+	 processors and FPGAs or between FPGAs.
+
 endif # FPGA
 
 endmenu
diff --git a/drivers/fpga/Makefile b/drivers/fpga/Makefile
index 8d83fc6..4baef00 100644
--- a/drivers/fpga/Makefile
+++ b/drivers/fpga/Makefile
@@ -8,3 +8,6 @@ obj-$(CONFIG_FPGA)			+= fpga-mgr.o
 # FPGA Manager Drivers
 obj-$(CONFIG_FPGA_MGR_SOCFPGA)		+= socfpga.o
 obj-$(CONFIG_FPGA_MGR_ZYNQ_FPGA)	+= zynq-fpga.o
+
+# FPGA Bridge Drivers
+obj-$(CONFIG_FPGA_BRIDGE)		+= fpga-bridge.o
diff --git a/drivers/fpga/fpga-bridge.c b/drivers/fpga/fpga-bridge.c
new file mode 100644
index 0000000..5119d8e
--- /dev/null
+++ b/drivers/fpga/fpga-bridge.c
@@ -0,0 +1,388 @@
+/*
+ * FPGA Bridge Framework Driver
+ *
+ *  Copyright (C) 2013-2015 Altera Corporation, All Rights Reserved.
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms and conditions of the GNU General Public License,
+ * version 2, as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+#include <linux/fpga/fpga-bridge.h>
+#include <linux/idr.h>
+#include <linux/kernel.h>
+#include <linux/module.h>
+#include <linux/of_platform.h>
+#include <linux/slab.h>
+#include <linux/spinlock.h>
+
+static DEFINE_IDA(fpga_bridge_ida);
+static struct class *fpga_bridge_class;
+
+/* Lock for adding/removing bridges to linked lists*/
+spinlock_t bridge_list_lock;
+
+static int fpga_bridge_of_node_match(struct device *dev, const void *data)
+{
+	return dev->of_node == data;
+}
+
+/**
+ * fpga_bridge_enable - Enable transactions on the bridge
+ *
+ * @bridge: FPGA bridge
+ *
+ * Return: 0 for success, error code otherwise.
+ */
+int fpga_bridge_enable(struct fpga_bridge *bridge)
+{
+	dev_dbg(&bridge->dev, "enable\n");
+
+	if (bridge->br_ops && bridge->br_ops->enable_set)
+		return bridge->br_ops->enable_set(bridge, 1);
+
+	return 0;
+}
+EXPORT_SYMBOL_GPL(fpga_bridge_enable);
+
+/**
+ * fpga_bridge_disable - Disable transactions on the bridge
+ *
+ * @bridge: FPGA bridge
+ *
+ * Return: 0 for success, error code otherwise.
+ */
+int fpga_bridge_disable(struct fpga_bridge *bridge)
+{
+	dev_dbg(&bridge->dev, "disable\n");
+
+	if (bridge->br_ops && bridge->br_ops->enable_set)
+		return bridge->br_ops->enable_set(bridge, 0);
+
+	return 0;
+}
+EXPORT_SYMBOL_GPL(fpga_bridge_disable);
+
+/**
+ * of_fpga_bridge_get - get an exclusive reference to a fpga bridge
+ *
+ * @np: node pointer of a FPGA bridge
+ *
+ * Return fpga_bridge struct if successful.
+ * Return -EBUSY if someone already has a reference to the bridge.
+ * Return -ENODEV if @np is not a FPGA Bridge.
+ */
+struct fpga_bridge *of_fpga_bridge_get(struct device_node *np)
+{
+	struct device *dev;
+	struct fpga_bridge *bridge;
+	int ret = -ENODEV;
+
+	of_node_get(np);
+
+	dev = class_find_device(fpga_bridge_class, NULL, np,
+				fpga_bridge_of_node_match);
+	if (!dev)
+		goto err_dev;
+
+	bridge = to_fpga_bridge(dev);
+	if (!bridge)
+		goto err_dev;
+
+	if (!mutex_trylock(&bridge->mutex)) {
+		ret = -EBUSY;
+		goto err_dev;
+	}
+
+	if (!try_module_get(dev->parent->driver->owner))
+		goto err_ll_mod;
+
+	dev_dbg(&bridge->dev, "get\n");
+
+	return bridge;
+
+err_ll_mod:
+	mutex_unlock(&bridge->mutex);
+err_dev:
+	put_device(dev);
+	of_node_put(np);
+	return ERR_PTR(ret);
+}
+EXPORT_SYMBOL_GPL(of_fpga_bridge_get);
+
+/**
+ * fpga_bridge_put - release a reference to a bridge
+ *
+ * @bridge: FPGA bridge
+ */
+void fpga_bridge_put(struct fpga_bridge *bridge)
+{
+	dev_dbg(&bridge->dev, "put\n");
+
+	module_put(bridge->dev.parent->driver->owner);
+	mutex_unlock(&bridge->mutex);
+	put_device(&bridge->dev);
+}
+EXPORT_SYMBOL_GPL(fpga_bridge_put);
+
+/**
+ * fpga_bridges_enable - enable bridges in a list
+ * @bridge_list: list of FPGA bridges
+ *
+ * Enable each bridge in the list.  If list is empty, do nothing.
+ *
+ * Return 0 for success or empty bridge list; return error code otherwise.
+ */
+int fpga_bridges_enable(struct list_head *bridge_list)
+{
+	struct fpga_bridge *bridge;
+	struct list_head *node;
+	int ret;
+
+	list_for_each(node, bridge_list) {
+		bridge = list_entry(node, struct fpga_bridge, node);
+		ret = fpga_bridge_enable(bridge);
+		if (ret)
+			return ret;
+	}
+
+	return 0;
+}
+EXPORT_SYMBOL_GPL(fpga_bridges_enable);
+
+/**
+ * fpga_bridges_disable - disable bridges in a list
+ *
+ * @bridge_list: list of FPGA bridges
+ *
+ * Disable each bridge in the list.  If list is empty, do nothing.
+ *
+ * Return 0 for success or empty bridge list; return error code otherwise.
+ */
+int fpga_bridges_disable(struct list_head *bridge_list)
+{
+	struct fpga_bridge *bridge;
+	struct list_head *node;
+	int ret;
+
+	list_for_each(node, bridge_list) {
+		bridge = list_entry(node, struct fpga_bridge, node);
+		ret = fpga_bridge_disable(bridge);
+		if (ret)
+			return ret;
+	}
+
+	return 0;
+}
+EXPORT_SYMBOL_GPL(fpga_bridges_disable);
+
+/**
+ * fpga_bridges_put - put bridges
+ *
+ * @bridge_list: list of FPGA bridges
+ *
+ * For each bridge in the list, put the bridge and remove it from the list.
+ * If list is empty, do nothing.
+ */
+void fpga_bridges_put(struct list_head *bridge_list)
+{
+	struct fpga_bridge *bridge;
+	struct list_head *node, *next;
+	unsigned long flags;
+
+	list_for_each_safe(node, next, bridge_list) {
+		bridge = list_entry(node, struct fpga_bridge, node);
+
+		fpga_bridge_put(bridge);
+
+		spin_lock_irqsave(&bridge_list_lock, flags);
+		list_del(&bridge->node);
+		spin_unlock_irqrestore(&bridge_list_lock, flags);
+	}
+}
+EXPORT_SYMBOL_GPL(fpga_bridges_put);
+
+/**
+ * fpga_bridges_get_to_list - get a bridge, add it to a list
+ *
+ * @np: node pointer of a FPGA bridge
+ * @bridge_list: list of FPGA bridges
+ *
+ * Get an exclusive reference to the bridge and and it to the list.
+ *
+ * Return 0 for success, error code from of_fpga_bridge_get() othewise.
+ */
+int fpga_bridge_get_to_list(struct device_node *np,
+			    struct list_head *bridge_list)
+{
+	struct fpga_bridge *bridge;
+	unsigned long flags;
+
+	bridge = of_fpga_bridge_get(np);
+	if (IS_ERR(bridge))
+		return PTR_ERR(bridge);
+
+	spin_lock_irqsave(&bridge_list_lock, flags);
+	list_add(&bridge->node, bridge_list);
+	spin_unlock_irqrestore(&bridge_list_lock, flags);
+
+	return 0;
+}
+EXPORT_SYMBOL_GPL(fpga_bridge_get_to_list);
+
+static ssize_t name_show(struct device *dev,
+			 struct device_attribute *attr, char *buf)
+{
+	struct fpga_bridge *bridge = to_fpga_bridge(dev);
+
+	return sprintf(buf, "%s\n", bridge->name);
+}
+
+static ssize_t state_show(struct device *dev,
+			  struct device_attribute *attr, char *buf)
+{
+	struct fpga_bridge *bridge = to_fpga_bridge(dev);
+	int enable = 1;
+
+	if (bridge->br_ops && bridge->br_ops->enable_show)
+		enable = bridge->br_ops->enable_show(bridge);
+
+	return sprintf(buf, "%s\n", enable ? "enabled" : "disabled");
+}
+
+static DEVICE_ATTR_RO(name);
+static DEVICE_ATTR_RO(state);
+
+static struct attribute *fpga_bridge_attrs[] = {
+	&dev_attr_name.attr,
+	&dev_attr_state.attr,
+	NULL,
+};
+ATTRIBUTE_GROUPS(fpga_bridge);
+
+/**
+ * fpga_bridge_register - register a fpga bridge driver
+ * @dev:	FPGA bridge device from pdev
+ * @name:	FPGA bridge name
+ * @br_ops:	pointer to structure of fpga bridge ops
+ * @priv:	FPGA bridge private data
+ *
+ * Return: 0 for success, error code otherwise.
+ */
+int fpga_bridge_register(struct device *dev, const char *name,
+			 const struct fpga_bridge_ops *br_ops, void *priv)
+{
+	struct fpga_bridge *bridge;
+	int id, ret = 0;
+
+	if (!name || !strlen(name)) {
+		dev_err(dev, "Attempt to register with no name!\n");
+		return -EINVAL;
+	}
+
+	bridge = kzalloc(sizeof(*bridge), GFP_KERNEL);
+	if (!bridge)
+		return -ENOMEM;
+
+	id = ida_simple_get(&fpga_bridge_ida, 0, 0, GFP_KERNEL);
+	if (id < 0) {
+		ret = id;
+		goto error_kfree;
+	}
+
+	mutex_init(&bridge->mutex);
+	INIT_LIST_HEAD(&bridge->node);
+
+	bridge->name = name;
+	bridge->br_ops = br_ops;
+	bridge->priv = priv;
+
+	device_initialize(&bridge->dev);
+	bridge->dev.class = fpga_bridge_class;
+	bridge->dev.parent = dev;
+	bridge->dev.of_node = dev->of_node;
+	bridge->dev.id = id;
+	dev_set_drvdata(dev, bridge);
+
+	ret = dev_set_name(&bridge->dev, "br%d", id);
+	if (ret)
+		goto error_device;
+
+	ret = device_add(&bridge->dev);
+	if (ret)
+		goto error_device;
+
+	dev_info(bridge->dev.parent, "fpga bridge [%s] registered\n",
+		 bridge->name);
+
+	return 0;
+
+error_device:
+	ida_simple_remove(&fpga_bridge_ida, id);
+error_kfree:
+	kfree(bridge);
+
+	return ret;
+}
+EXPORT_SYMBOL_GPL(fpga_bridge_register);
+
+/**
+ * fpga_bridge_unregister - unregister a fpga bridge driver
+ * @dev: FPGA bridge device from pdev
+ */
+void fpga_bridge_unregister(struct device *dev)
+{
+	struct fpga_bridge *bridge = dev_get_drvdata(dev);
+
+	/*
+	 * If the low level driver provides a method for putting bridge into
+	 * a desired state upon unregister, do it.
+	 */
+	if (bridge->br_ops && bridge->br_ops->fpga_bridge_remove)
+		bridge->br_ops->fpga_bridge_remove(bridge);
+
+	device_unregister(&bridge->dev);
+}
+EXPORT_SYMBOL_GPL(fpga_bridge_unregister);
+
+static void fpga_bridge_dev_release(struct device *dev)
+{
+	struct fpga_bridge *bridge = to_fpga_bridge(dev);
+
+	ida_simple_remove(&fpga_bridge_ida, bridge->dev.id);
+	kfree(bridge);
+}
+
+static int __init fpga_bridge_dev_init(void)
+{
+	spin_lock_init(&bridge_list_lock);
+
+	fpga_bridge_class = class_create(THIS_MODULE, "fpga_bridge");
+	if (IS_ERR(fpga_bridge_class))
+		return PTR_ERR(fpga_bridge_class);
+
+	fpga_bridge_class->dev_groups = fpga_bridge_groups;
+	fpga_bridge_class->dev_release = fpga_bridge_dev_release;
+
+	return 0;
+}
+
+static void __exit fpga_bridge_dev_exit(void)
+{
+	class_destroy(fpga_bridge_class);
+	ida_destroy(&fpga_bridge_ida);
+}
+
+MODULE_DESCRIPTION("FPGA Bridge Driver");
+MODULE_AUTHOR("Alan Tull <atull@opensource.altera.com>");
+MODULE_LICENSE("GPL v2");
+
+subsys_initcall(fpga_bridge_dev_init);
+module_exit(fpga_bridge_dev_exit);
diff --git a/include/linux/fpga/fpga-bridge.h b/include/linux/fpga/fpga-bridge.h
new file mode 100644
index 0000000..ad8471c
--- /dev/null
+++ b/include/linux/fpga/fpga-bridge.h
@@ -0,0 +1,56 @@
+#include <linux/device.h>
+
+#ifndef _LINUX_FPGA_BRIDGE_H
+#define _LINUX_FPGA_BRIDGE_H
+
+struct fpga_bridge;
+
+/**
+ * struct fpga_bridge_ops - ops for low level FPGA bridge drivers
+ * @enable_show: returns the FPGA bridge's status
+ * @enable_set: set a FPGA bridge as enabled or disabled
+ * @fpga_bridge_remove: set FPGA into a specific state during driver remove
+ */
+struct fpga_bridge_ops {
+	int (*enable_show)(struct fpga_bridge *bridge);
+	int (*enable_set)(struct fpga_bridge *bridge, bool enable);
+	void (*fpga_bridge_remove)(struct fpga_bridge *bridge);
+};
+
+/**
+ * struct fpga_bridge - FPGA bridge structure
+ * @name: name of low level FPGA bridge
+ * @dev: FPGA bridge device
+ * @mutex: enforces exclusive reference to bridge
+ * @br_ops: pointer to struct of FPGA bridge ops
+ * @node: FPGA bridge list node
+ * @priv: low level driver private date
+ */
+struct fpga_bridge {
+	const char *name;
+	struct device dev;
+	struct mutex mutex; /* for exclusive reference to bridge */
+	const struct fpga_bridge_ops *br_ops;
+	struct list_head node;
+	void *priv;
+};
+
+#define to_fpga_bridge(d) container_of(d, struct fpga_bridge, dev)
+
+struct fpga_bridge *of_get_fpga_bus(struct device_node *np);
+struct fpga_bridge *of_fpga_bridge_get(struct device_node *node);
+void fpga_bridge_put(struct fpga_bridge *bridge);
+int fpga_bridge_enable(struct fpga_bridge *bridge);
+int fpga_bridge_disable(struct fpga_bridge *bridge);
+
+int fpga_bridges_enable(struct list_head *bridge_list);
+int fpga_bridges_disable(struct list_head *bridge_list);
+void fpga_bridges_put(struct list_head *bridge_list);
+int fpga_bridge_get_to_list(struct device_node *np,
+			    struct list_head *bridge_list);
+
+int fpga_bridge_register(struct device *dev, const char *name,
+			 const struct fpga_bridge_ops *br_ops, void *priv);
+void fpga_bridge_unregister(struct device *dev);
+
+#endif /* _LINUX_FPGA_BRIDGE_H */
-- 
1.7.9.5

[PATCH v15 5/6] fpga: fpga-area and fpga-bus: device tree control for FPGA

[atull]

From: Alan Tull <atull@opensource.altera.com>

FPGA Area and FPGA Bus support programming FPGA under control of
the Device Tree.

A FPGA Bus contains the devices necessary for programming an
FPGA.

When a Device Tree Overlay containing a FPGA Area is
applied, the FPGA Area will be probed and will:
 * check to see if there is an image to program to a FPGA
 * get references to the FPGA manager and bridges if any
 * disable FPGA bridges to prevent spurious data on busses
 * reprogram the FPGA
 * enable the specified FPGA bridges
 * populate the child devices

Removing the Device Tree Overlay is also supported.

This supports fpga use where hardware blocks on a fpga will
need drivers.

Signed-off-by: Alan Tull <atull@opensource.altera.com>
---
v9:  initial version (this patch added during rest of patchset's v9)
v10: request deferral if fpga mgr or bridges not available yet
     cleanup as fpga manager core goes into the real kernel
     Don't assume bridges are disabled before programming FPGA
     Don't hang onto reference for fpga manager
     Move to staging/simple-fpga-bus
v11: No change in this patch for v11 of the patch set
v12: Moved out of staging.
     Use fpga bridges framework.
v13: If no bridges are specified, assume we don't need any.
     Clean up debug messages
     Some dev_info -> dev_dbg
     Remove unneeded #include
     Fix size of array of pointers
     Don't need to specify .owner
     Use common binding: firmware-name
v14: OK it's not a simple bus.  Call it "FPGA Area"
     Remove bindings that specify FPGA manager and FPGA bridges
     Use parent FPGA bridge and bridges that are its peers
     Use ancestor FPGA Manager
v15: Add altr,fpga-bus implementation
     Change compatible string "fpga-area" -> "altr,fpga-area"
---
 drivers/fpga/Kconfig     |    7 +
 drivers/fpga/Makefile    |    3 +
 drivers/fpga/fpga-area.c |  352 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 362 insertions(+)
 create mode 100644 drivers/fpga/fpga-area.c

diff --git a/drivers/fpga/Kconfig b/drivers/fpga/Kconfig
index b6cfd89..6ac916b 100644
--- a/drivers/fpga/Kconfig
+++ b/drivers/fpga/Kconfig
@@ -31,6 +31,13 @@ config FPGA_BRIDGE
          Say Y here if you want to support bridges connected between host
 	 processors and FPGAs or between FPGAs.
 
+config FPGA_AREA
+       bool "Device Tree Based FPGA Reprogramming"
+       depends on FPGA_BRIDGE
+       help
+         Enable FPGA Area which supports programming FPGAs under control of
+	 Device Tree.
+
 endif # FPGA
 
 endmenu
diff --git a/drivers/fpga/Makefile b/drivers/fpga/Makefile
index 4baef00..4f7e49f 100644
--- a/drivers/fpga/Makefile
+++ b/drivers/fpga/Makefile
@@ -11,3 +11,6 @@ obj-$(CONFIG_FPGA_MGR_ZYNQ_FPGA)	+= zynq-fpga.o
 
 # FPGA Bridge Drivers
 obj-$(CONFIG_FPGA_BRIDGE)		+= fpga-bridge.o
+
+# High Level Interfaces
+obj-$(CONFIG_FPGA_AREA)			+= fpga-area.o
diff --git a/drivers/fpga/fpga-area.c b/drivers/fpga/fpga-area.c
new file mode 100644
index 0000000..cec332f
--- /dev/null
+++ b/drivers/fpga/fpga-area.c
@@ -0,0 +1,352 @@
+/*
+ * FPGA Tree Area Support for Device Tree controlled FPGA reprogramming
+ *
+ *  Copyright (C) 2013-2015 Altera Corporation
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms and conditions of the GNU General Public License,
+ * version 2, as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <linux/fpga/fpga-bridge.h>
+#include <linux/fpga/fpga-mgr.h>
+#include <linux/kernel.h>
+#include <linux/module.h>
+#include <linux/of_platform.h>
+
+/*
+ * In the case of a FPGA doing full reconfiguration, the area == the whole
+ * FPGA.  In the case of partial reconfiguration, several areas can be
+ * reconfigured separately.
+ */
+
+/**
+ * struct fpga_area
+ * @mgr:	FPGA Manager
+ * @flags:	Flags for reconfiguration
+ * @firmware_name: Name of FPGA image file
+ * @bridge_list: Linked list of FPGA bridges controlled by area
+ * @br:		FPGA Bridge corresponding to area
+ * @bus_np:	device node of ancestor FPGA Bus
+ */
+struct fpga_area {
+	struct fpga_manager *mgr;
+	u32 flags;
+	const char *firmware_name;
+	struct list_head bridge_list;
+	struct fpga_bridge *br;
+	struct device_node *bus_np;
+};
+
+/**
+ * fpga_area_get_parent_peer_bridges - get bridges that are peers of parent
+ * @area: FPGA Area struct
+ *
+ * Intended to support case where multiple bridges need to be disabled
+ * during FPGA reprogramming.
+ *
+ * Finds the FPGA bridge that is the parent of @area in the device tree.
+ * Creates a linked list of FPGA bridges that includes the parent bridge and
+ * its peers.  Gets an exclusive reference to each of these bridges as they
+ * are added to the list.  The list of bridges is saved in @area's
+ * fpga_bridge struct.
+ *
+ * These bridges must be disabled while the FPGA is being reprogrammed to
+ * support the children of the @area bridge and enabled after FPGA
+ * programming is finished.
+ *
+ * For the use case where no FPGA bridges are required, the parent node should
+ * be a FPGA Manager.  In this case, the bridge list will end up empty.
+ *
+ * Returns error code or 0 for success.  Returns 0 if the parent is a FPGA
+ * manager.
+ */
+static int fpga_area_get_parent_peer_bridges(struct fpga_area *area)
+{
+	struct device_node *parent, *child;
+	struct fpga_bridge *bridge;
+	int ret;
+
+	/* Create a list of bridges that are peers of area's parent */
+	parent = of_get_parent(area->br->dev.of_node);
+	parent = of_get_next_parent(parent);
+
+	for_each_child_of_node(parent, child) {
+		/* If node is a bridge, get it and add to list */
+		ret = fpga_bridge_get_to_list(child, &area->bridge_list);
+
+		/* if any of the bridges are in use, give up */
+		if (ret == -EBUSY) {
+			fpga_bridges_put(&area->bridge_list);
+			of_node_put(parent);
+			return PTR_ERR(bridge);
+		}
+	}
+	of_node_put(parent);
+
+	return 0;
+}
+
+/**
+ * fpga_area_get_bridges - create list of exclusive references to fpga bridges
+ * @area: FPGA Area struct
+ *
+ * Get exclusive references to a FPGA bridge or bridges.
+ * In the case of full reconfiguration build a list of bridges that are the
+ * parent of @area and its peers.  We are reprogramming the full FPGA and
+ * need to have no communication on the processor/FPGA bridges while that
+ * is happening
+ * In the case of partial reconfiguration, only add the parent of @area to
+ * the list.  This one bridge is a freeze block which is in the FPGA itself
+ * and is downstream from its parent bridge and the parent's peers.
+ *
+ * Return 0 for success. Return -ENODEV is there are no bridges.
+ * Pass other error codes ultimately from of_fpga_bridge_get() such as:
+ * Return -EBUSY if any of the bridges were already gotten.
+ */
+static int fpga_area_get_bridges(struct fpga_area *area)
+{
+	struct device_node *parent;
+	int ret = 0;
+
+	/* If parent is FPGA Manager, no bridges to get */
+	parent = of_get_parent(area->br->dev.of_node);
+	if (parent == area->mgr->dev.of_node) {
+		of_node_put(parent);
+		return -ENODEV;
+	}
+
+	if (area->flags & FPGA_MGR_PARTIAL_RECONFIG)
+		ret = fpga_bridge_get_to_list(parent, &area->bridge_list);
+	else
+		ret = fpga_area_get_parent_peer_bridges(area);
+
+	of_node_put(parent);
+
+	return ret;
+}
+
+/**
+ * fpga_area_load - program the FPGA based on info in area
+ * @area: FPGA Area struct
+ *
+ * Program the FPGA that the area has a reference to.
+ *
+ * Returns 0 for success or error codes passed down from
+ * fpga_mgr_firmware_load()
+ */
+static int fpga_area_load(struct fpga_area *area)
+{
+	return fpga_mgr_firmware_load(area->mgr,
+				      area->flags,
+				      area->firmware_name);
+}
+
+/**
+ * fpga_area_get_bus - find ancestor FPGA Bus, get a reference
+ * @area: FPGA Area struct
+ *
+ * Returns 0 for success or -ENODEV if not a child of a FPGA Bus.
+ */
+static int fpga_area_get_bus(struct fpga_area *area)
+{
+	struct device_node *np = area->br->dev.of_node;
+
+	of_node_get(np);
+
+	while (np && !of_device_is_compatible(np, "altr,fpga-bus"))
+		np = of_get_next_parent(np);
+
+	if (!np)
+		return -ENODEV;
+
+	area->bus_np = np;
+
+	return 0;
+}
+
+/**
+ * fpga_area_put_bus - put FPGA Bus saved in @area
+ * @area: FPGA Area struct
+ */
+static void fpga_area_put_bus(struct fpga_area *area)
+{
+	of_node_put(area->bus_np);
+	area->bus_np = NULL;
+}
+
+/**
+ * fpga_area_get_manager - get exclusive reference for FPGA Manager
+ * @area: FPGA Area struct
+ *
+ * One of the ancestor nodes of the FPGA Area should be a FPGA Bus.  One of
+ * the children of that FPGA Bus should be a FPGA Manager.
+ * Assuming that fpga_area_get_bus() has already found the bus, this function
+ * finds the FPGA Manager and saves it in the area struct.
+ *
+ * Return: 0 for success or IS_ERR() condition containing error code.
+ */
+static int fpga_area_get_manager(struct fpga_area *area)
+{
+	struct device_node  *child;
+	struct fpga_manager *mgr;
+
+	for_each_child_of_node(area->bus_np, child) {
+		mgr = of_fpga_mgr_get(child);
+		if (IS_ERR(mgr))
+			continue;
+
+		area->mgr = mgr;
+		return 0;
+	}
+
+	return -ENODEV;
+}
+
+/**
+ * fpga_area_put_manager - put exclusive reference to FPGA Manager
+ * @area: FPGA Area struct
+ */
+static void fpga_area_put_manager(struct fpga_area *area)
+{
+	fpga_mgr_put(area->mgr);
+	area->mgr = NULL;
+}
+
+/**
+ * fpga_area_probe - probe function for FPGA area
+ * @pdev: platform device
+ *
+ * If there is an image to program to a FPGA, get the FPGA Manager and bridges,
+ * reprogram the FPGA, and  populate the child devices.
+ *
+ * If there are FPGA Bridges, this function will hold the references to the
+ * bridges; they are released in fpga_area_remove().
+ *
+ * Return:  0 for success, -EBUSY if someone already got the bridges or manager.
+ */
+static int fpga_area_probe(struct platform_device *pdev)
+{
+	struct device *dev = &pdev->dev;
+	struct device_node *np = dev->of_node;
+	struct fpga_area *area;
+	int ret;
+
+	area = devm_kzalloc(dev, sizeof(*area), GFP_KERNEL);
+	if (!area)
+		return -ENOMEM;
+
+	INIT_LIST_HEAD(&area->bridge_list);
+
+	ret = fpga_bridge_register(dev, "FPGA Area", NULL, area);
+	if (ret)
+		return ret;
+	area->br = dev_get_drvdata(dev);
+
+	if (of_property_read_string(np, "firmware-name",
+				    &area->firmware_name)) {
+		of_platform_populate(np, of_default_bus_match_table, NULL, dev);
+		return 0;
+	}
+
+	if (of_property_read_bool(np, "partial-reconfig"))
+		area->flags |= FPGA_MGR_PARTIAL_RECONFIG;
+
+	ret = fpga_area_get_bus(area);
+	if (ret) {
+		dev_dbg(dev, "Should be child of a FPGA Bus");
+		goto err_unreg;
+	}
+
+	ret = fpga_area_get_manager(area);
+	if (ret) {
+		dev_dbg(dev, "Could not find FPGA Manager");
+		goto err_unreg;
+	}
+
+	/* Give up if there is an error other than no bridges. */
+	ret = fpga_area_get_bridges(area);
+	if (ret && ret != -ENODEV)
+		goto err_release;
+
+	ret = fpga_bridges_disable(&area->bridge_list);
+	if (ret)
+		goto err_release;
+
+	ret = fpga_area_load(area);
+	if (ret)
+		goto err_release;
+
+	ret = fpga_bridges_enable(&area->bridge_list);
+	if (ret)
+		goto err_release;
+
+	/* If successful, put the mgr, but keep the bridges */
+	fpga_area_put_manager(area);
+
+	of_platform_populate(np, of_default_bus_match_table, NULL, dev);
+
+	return 0;
+
+err_release:
+	fpga_bridges_put(&area->bridge_list);
+	fpga_area_put_manager(area);
+err_unreg:
+	fpga_bridge_unregister(dev);
+
+	return ret;
+}
+
+/**
+ * fpga_area_remove - remove a FPGA area
+ * @pdev: platform device
+ *
+ * Called when an FPGA Area is removed.  If there are any FPGA Bridges in the
+ * area's bridge list, disable them and put them.
+ *
+ * Return: 0
+ */
+static int fpga_area_remove(struct platform_device *pdev)
+{
+	struct device *dev = &pdev->dev;
+	struct fpga_bridge *bridge = dev_get_drvdata(dev);
+	struct fpga_area *area = bridge->priv;
+
+	fpga_area_put_bus(area);
+
+	fpga_bridges_disable(&area->bridge_list);
+	fpga_bridges_put(&area->bridge_list);
+
+	fpga_bridge_unregister(dev);
+
+	return 0;
+}
+
+static const struct of_device_id fpga_area_of_match[] = {
+	{ .compatible = "fpga-area", },
+	{},
+};
+MODULE_DEVICE_TABLE(of, fpga_area_of_match);
+
+static struct platform_driver fpga_area_driver = {
+	.probe = fpga_area_probe,
+	.remove = fpga_area_remove,
+	.driver = {
+		.name	= "FPGA Area",
+		.of_match_table = of_match_ptr(fpga_area_of_match),
+	},
+};
+
+module_platform_driver(fpga_area_driver);
+
+MODULE_DESCRIPTION("Altera FPGA Bus");
+MODULE_AUTHOR("Alan Tull <atull@opensource.altera.com>");
+MODULE_LICENSE("GPL v2");
-- 
1.7.9.5

[PATCH v15 6/6] ARM: socfpga: fpga bridge driver support

[atull]

From: Alan Tull <atull@opensource.altera.com>

Supports Altera SOCFPGA bridges:
 * fpga2sdram
 * fpga2hps
 * hps2fpga
 * lwhps2fpga

Allows enabling/disabling the bridges through the FPGA
Bridge Framework API functions.

The fpga2sdram driver only supports enabling and disabling
of the ports that been configured early on.  This is due to
a hardware limitation where the read, write, and command
ports on the fpga2sdram bridge can only be reconfigured
while there are no transactions to the sdram, i.e. when
running out of OCRAM before the kernel boots.

Device tree property 'init-val' configures the driver to
enable or disable the bridge during probe.  If the property
does not exist, the driver will leave the bridge in its
current state.

Signed-off-by: Alan Tull <atull@opensource.altera.com>
Signed-off-by: Matthew Gerlach <mgerlach@altera.com>
Signed-off-by: Dinh Nguyen <dinguyen@opensource.altera.com>
---
v2:  Use resets instead of directly writing reset registers
v12: Bump version to align with simple-fpga-bus version
     Get rid of the sysfs interface
     fpga2sdram: get configuration stored in handoff register
v13: Remove unneeded WARN_ON
     Change property from init-val to bridge-enable
     Checkpatch cleanup
     Fix email address
v14: use module_platform_driver
     remove unused struct field and some #defines
     don't really need exclamation points on error msgs
     *const* struct fpga_bridge_ops
v15: No change in this patch for v15 of this patch set
---
 drivers/fpga/Kconfig             |    7 ++
 drivers/fpga/Makefile            |    1 +
 drivers/fpga/altera-fpga2sdram.c |  174 +++++++++++++++++++++++++++++++
 drivers/fpga/altera-hps2fpga.c   |  213 ++++++++++++++++++++++++++++++++++++++
 4 files changed, 395 insertions(+)
 create mode 100644 drivers/fpga/altera-fpga2sdram.c
 create mode 100644 drivers/fpga/altera-hps2fpga.c

diff --git a/drivers/fpga/Kconfig b/drivers/fpga/Kconfig
index 6ac916b..30ebe42 100644
--- a/drivers/fpga/Kconfig
+++ b/drivers/fpga/Kconfig
@@ -38,6 +38,13 @@ config FPGA_AREA
          Enable FPGA Area which supports programming FPGAs under control of
 	 Device Tree.
 
+config SOCFPGA_FPGA_BRIDGE
+	bool "Altera SoCFPGA FPGA Bridges"
+	depends on ARCH_SOCFPGA && FPGA_BRIDGE
+	help
+	  Say Y to enable drivers for FPGA bridges for Altera SOCFPGA
+	  devices.
+
 endif # FPGA
 
 endmenu
diff --git a/drivers/fpga/Makefile b/drivers/fpga/Makefile
index 4f7e49f..3efc132 100644
--- a/drivers/fpga/Makefile
+++ b/drivers/fpga/Makefile
@@ -11,6 +11,7 @@ obj-$(CONFIG_FPGA_MGR_ZYNQ_FPGA)	+= zynq-fpga.o
 
 # FPGA Bridge Drivers
 obj-$(CONFIG_FPGA_BRIDGE)		+= fpga-bridge.o
+obj-$(CONFIG_SOCFPGA_FPGA_BRIDGE)	+= altera-hps2fpga.o altera-fpga2sdram.o
 
 # High Level Interfaces
 obj-$(CONFIG_FPGA_AREA)			+= fpga-area.o
diff --git a/drivers/fpga/altera-fpga2sdram.c b/drivers/fpga/altera-fpga2sdram.c
new file mode 100644
index 0000000..91f4a40
--- /dev/null
+++ b/drivers/fpga/altera-fpga2sdram.c
@@ -0,0 +1,174 @@
+/*
+ * FPGA to SDRAM Bridge Driver for Altera SoCFPGA Devices
+ *
+ *  Copyright (C) 2013-2015 Altera Corporation, All Rights Reserved.
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms and conditions of the GNU General Public License,
+ * version 2, as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+/*
+ * This driver manages a bridge between an FPGA and the SDRAM used by the ARM
+ * host processor system (HPS).
+ *
+ * The bridge contains 4 read ports, 4 write ports, and 6 command ports.
+ * Reconfiguring these ports requires that no SDRAM transactions occur during
+ * reconfiguration.  The code reconfiguring the ports cannot run out of SDRAM
+ * nor can the FPGA access the SDRAM during reconfiguration.  This driver does
+ * not support reconfiguring the ports.  The ports are configured by code
+ * running out of on chip ram before Linux is started and the configuration
+ * is passed in a handoff register in the system manager.
+ *
+ * This driver supports enabling and disabling of the configured ports, which
+ * allows for safe reprogramming of the FPGA, assuming that the new FPGA image
+ * uses the same port configuration.  Bridges must be disabled before
+ * reprogramming the FPGA and re-enabled after the FPGA has been programmed.
+ */
+
+#include <linux/fpga/fpga-bridge.h>
+#include <linux/kernel.h>
+#include <linux/mfd/syscon.h>
+#include <linux/module.h>
+#include <linux/of_platform.h>
+#include <linux/regmap.h>
+
+#define ALT_SDR_CTL_FPGAPORTRST_OFST		0x80
+#define ALT_SDR_CTL_FPGAPORTRST_PORTRSTN_MSK	0x00003fff
+#define ALT_SDR_CTL_FPGAPORTRST_RD_SHIFT	0
+#define ALT_SDR_CTL_FPGAPORTRST_WR_SHIFT	4
+#define ALT_SDR_CTL_FPGAPORTRST_CTRL_SHIFT	8
+
+#define SYSMGR_ISWGRP_HANDOFF3          (0x8C)
+#define ISWGRP_HANDOFF_FPGA2SDR         SYSMGR_ISWGRP_HANDOFF3
+
+#define F2S_BRIDGE_NAME "fpga2sdram"
+
+struct alt_fpga2sdram_data {
+	struct device *dev;
+	struct regmap *sdrctl;
+	int mask;
+};
+
+static int alt_fpga2sdram_enable_show(struct fpga_bridge *bridge)
+{
+	struct alt_fpga2sdram_data *priv = bridge->priv;
+	int value;
+
+	regmap_read(priv->sdrctl, ALT_SDR_CTL_FPGAPORTRST_OFST, &value);
+
+	return (value & priv->mask) == priv->mask;
+}
+
+static inline int _alt_fpga2sdram_enable_set(struct alt_fpga2sdram_data *priv,
+					     bool enable)
+{
+	return regmap_update_bits(priv->sdrctl, ALT_SDR_CTL_FPGAPORTRST_OFST,
+				  priv->mask, enable ? priv->mask : 0);
+}
+
+static int alt_fpga2sdram_enable_set(struct fpga_bridge *bridge, bool enable)
+{
+	return _alt_fpga2sdram_enable_set(bridge->priv, enable);
+}
+
+struct prop_map {
+	char *prop_name;
+	u32 *prop_value;
+	u32 prop_max;
+};
+
+static const struct fpga_bridge_ops altera_fpga2sdram_br_ops = {
+	.enable_set = alt_fpga2sdram_enable_set,
+	.enable_show = alt_fpga2sdram_enable_show,
+};
+
+static const struct of_device_id altera_fpga_of_match[] = {
+	{ .compatible = "altr,socfpga-fpga2sdram-bridge" },
+	{},
+};
+
+static int alt_fpga_bridge_probe(struct platform_device *pdev)
+{
+	struct device *dev = &pdev->dev;
+	struct alt_fpga2sdram_data *priv;
+	u32 enable;
+	struct regmap *sysmgr;
+	int ret = 0;
+
+	priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);
+	if (!priv)
+		return -ENOMEM;
+
+	priv->dev = dev;
+
+	priv->sdrctl = syscon_regmap_lookup_by_compatible("altr,sdr-ctl");
+	if (IS_ERR(priv->sdrctl)) {
+		dev_err(dev, "regmap for altr,sdr-ctl lookup failed.\n");
+		return PTR_ERR(priv->sdrctl);
+	}
+
+	sysmgr = syscon_regmap_lookup_by_compatible("altr,sys-mgr");
+	if (IS_ERR(priv->sdrctl)) {
+		dev_err(dev, "regmap for altr,sys-mgr lookup failed.\n");
+		return PTR_ERR(sysmgr);
+	}
+
+	/* Get f2s bridge configuration saved in handoff register */
+	regmap_read(sysmgr, SYSMGR_ISWGRP_HANDOFF3, &priv->mask);
+
+	ret = fpga_bridge_register(dev, F2S_BRIDGE_NAME,
+				   &altera_fpga2sdram_br_ops, priv);
+	if (ret)
+		return ret;
+
+	dev_info(dev, "driver initialized with handoff %08x\n", priv->mask);
+
+	if (!of_property_read_u32(dev->of_node, "bridge-enable", &enable)) {
+		if (enable > 1) {
+			dev_warn(dev, "invalid bridge-enable %u > 1\n", enable);
+		} else {
+			dev_info(dev, "%s bridge\n",
+				 (enable ? "enabling" : "disabling"));
+			ret = _alt_fpga2sdram_enable_set(priv, enable);
+			if (ret) {
+				fpga_bridge_unregister(&pdev->dev);
+				return ret;
+			}
+		}
+	}
+
+	return ret;
+}
+
+static int alt_fpga_bridge_remove(struct platform_device *pdev)
+{
+	fpga_bridge_unregister(&pdev->dev);
+
+	return 0;
+}
+
+MODULE_DEVICE_TABLE(of, altera_fpga_of_match);
+
+static struct platform_driver altera_fpga_driver = {
+	.probe = alt_fpga_bridge_probe,
+	.remove = alt_fpga_bridge_remove,
+	.driver = {
+		.name	= "altera_fpga2sdram_bridge",
+		.of_match_table = of_match_ptr(altera_fpga_of_match),
+	},
+};
+
+module_platform_driver(altera_fpga_driver);
+
+MODULE_DESCRIPTION("Altera SoCFPGA FPGA to SDRAM Bridge");
+MODULE_AUTHOR("Alan Tull <atull@opensource.altera.com>");
+MODULE_LICENSE("GPL v2");
diff --git a/drivers/fpga/altera-hps2fpga.c b/drivers/fpga/altera-hps2fpga.c
new file mode 100644
index 0000000..c15df47
--- /dev/null
+++ b/drivers/fpga/altera-hps2fpga.c
@@ -0,0 +1,213 @@
+/*
+ * FPGA to/from HPS Bridge Driver for Altera SoCFPGA Devices
+ *
+ *  Copyright (C) 2013-2015 Altera Corporation, All Rights Reserved.
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms and conditions of the GNU General Public License,
+ * version 2, as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+/*
+ * This driver manages bridges on a Altera SOCFPGA between the ARM host
+ * processor system (HPS) and the embedded FPGA.
+ *
+ * This driver supports enabling and disabling of the configured ports, which
+ * allows for safe reprogramming of the FPGA, assuming that the new FPGA image
+ * uses the same port configuration.  Bridges must be disabled before
+ * reprogramming the FPGA and re-enabled after the FPGA has been programmed.
+ */
+
+#include <linux/clk.h>
+#include <linux/fpga/fpga-bridge.h>
+#include <linux/kernel.h>
+#include <linux/mfd/syscon.h>
+#include <linux/module.h>
+#include <linux/of_platform.h>
+#include <linux/regmap.h>
+#include <linux/reset.h>
+
+#define ALT_L3_REMAP_OFST			0x0
+#define ALT_L3_REMAP_MPUZERO_MSK		0x00000001
+#define ALT_L3_REMAP_H2F_MSK			0x00000008
+#define ALT_L3_REMAP_LWH2F_MSK			0x00000010
+
+#define HPS2FPGA_BRIDGE_NAME			"hps2fpga"
+#define LWHPS2FPGA_BRIDGE_NAME			"lwhps2fpga"
+#define FPGA2HPS_BRIDGE_NAME			"fpga2hps"
+
+struct altera_hps2fpga_data {
+	const char *name;
+	struct reset_control *bridge_reset;
+	struct regmap *l3reg;
+	/* The L3 REMAP register is write only, so keep a cached value. */
+	unsigned int l3_remap_value;
+	unsigned int remap_mask;
+	struct clk *clk;
+};
+
+static int alt_hps2fpga_enable_show(struct fpga_bridge *bridge)
+{
+	struct altera_hps2fpga_data *priv = bridge->priv;
+
+	return reset_control_status(priv->bridge_reset);
+}
+
+static int _alt_hps2fpga_enable_set(struct altera_hps2fpga_data *priv,
+				    bool enable)
+{
+	int ret;
+
+	/* bring bridge out of reset */
+	if (enable)
+		ret = reset_control_deassert(priv->bridge_reset);
+	else
+		ret = reset_control_assert(priv->bridge_reset);
+	if (ret)
+		return ret;
+
+	/* Allow bridge to be visible to L3 masters or not */
+	if (priv->remap_mask) {
+		priv->l3_remap_value |= ALT_L3_REMAP_MPUZERO_MSK;
+
+		if (enable)
+			priv->l3_remap_value |= priv->remap_mask;
+		else
+			priv->l3_remap_value &= ~priv->remap_mask;
+
+		ret = regmap_write(priv->l3reg, ALT_L3_REMAP_OFST,
+				   priv->l3_remap_value);
+	}
+
+	return ret;
+}
+
+static int alt_hps2fpga_enable_set(struct fpga_bridge *bridge, bool enable)
+{
+	return _alt_hps2fpga_enable_set(bridge->priv, enable);
+}
+
+static const struct fpga_bridge_ops altera_hps2fpga_br_ops = {
+	.enable_set = alt_hps2fpga_enable_set,
+	.enable_show = alt_hps2fpga_enable_show,
+};
+
+static struct altera_hps2fpga_data hps2fpga_data  = {
+	.name = HPS2FPGA_BRIDGE_NAME,
+	.remap_mask = ALT_L3_REMAP_H2F_MSK,
+};
+
+static struct altera_hps2fpga_data lwhps2fpga_data  = {
+	.name = LWHPS2FPGA_BRIDGE_NAME,
+	.remap_mask = ALT_L3_REMAP_LWH2F_MSK,
+};
+
+static struct altera_hps2fpga_data fpga2hps_data  = {
+	.name = FPGA2HPS_BRIDGE_NAME,
+};
+
+static const struct of_device_id altera_fpga_of_match[] = {
+	{ .compatible = "altr,socfpga-hps2fpga-bridge",
+	  .data = &hps2fpga_data },
+	{ .compatible = "altr,socfpga-lwhps2fpga-bridge",
+	  .data = &lwhps2fpga_data },
+	{ .compatible = "altr,socfpga-fpga2hps-bridge",
+	  .data = &fpga2hps_data },
+	{},
+};
+
+static int alt_fpga_bridge_probe(struct platform_device *pdev)
+{
+	struct device *dev = &pdev->dev;
+	struct altera_hps2fpga_data *priv;
+	const struct of_device_id *of_id;
+	u32 enable;
+	int ret;
+
+	of_id = of_match_device(altera_fpga_of_match, dev);
+	priv = (struct altera_hps2fpga_data *)of_id->data;
+
+	priv->bridge_reset = devm_reset_control_get(dev, priv->name);
+	if (IS_ERR(priv->bridge_reset)) {
+		dev_err(dev, "Could not get %s reset control\n", priv->name);
+		return PTR_ERR(priv->bridge_reset);
+	}
+
+	priv->l3reg = syscon_regmap_lookup_by_compatible("altr,l3regs");
+	if (IS_ERR(priv->l3reg)) {
+		dev_err(dev, "regmap for altr,l3regs lookup failed\n");
+		return PTR_ERR(priv->l3reg);
+	}
+
+	priv->clk = of_clk_get(dev->of_node, 0);
+	if (IS_ERR(priv->clk)) {
+		dev_err(dev, "no clock specified\n");
+		return PTR_ERR(priv->clk);
+	}
+
+	ret = clk_prepare_enable(priv->clk);
+	if (ret) {
+		dev_err(dev, "could not enable clock\n");
+		return -EBUSY;
+	}
+
+	ret = fpga_bridge_register(dev, priv->name, &altera_hps2fpga_br_ops,
+				   priv);
+	if (ret)
+		return ret;
+
+	if (!of_property_read_u32(dev->of_node, "bridge-enable", &enable)) {
+		if (enable > 1) {
+			dev_warn(dev, "invalid bridge-enable %u > 1\n", enable);
+		} else {
+			dev_info(dev, "%s bridge\n",
+				 (enable ? "enabling" : "disabling"));
+
+			ret = _alt_hps2fpga_enable_set(priv, enable);
+			if (ret) {
+				fpga_bridge_unregister(&pdev->dev);
+				return ret;
+			}
+		}
+	}
+
+	return ret;
+}
+
+static int alt_fpga_bridge_remove(struct platform_device *pdev)
+{
+	struct fpga_bridge *bridge = platform_get_drvdata(pdev);
+	struct altera_hps2fpga_data *priv = bridge->priv;
+
+	fpga_bridge_unregister(&pdev->dev);
+
+	clk_disable_unprepare(priv->clk);
+	clk_put(priv->clk);
+
+	return 0;
+}
+
+MODULE_DEVICE_TABLE(of, altera_fpga_of_match);
+
+static struct platform_driver alt_fpga_bridge_driver = {
+	.probe = alt_fpga_bridge_probe,
+	.remove = alt_fpga_bridge_remove,
+	.driver = {
+		.name	= "altera_hps2fpga_bridge",
+		.of_match_table = of_match_ptr(altera_fpga_of_match),
+	},
+};
+
+module_platform_driver(alt_fpga_bridge_driver);
+
+MODULE_DESCRIPTION("Altera SoCFPGA HPS to FPGA Bridge");
+MODULE_AUTHOR("Alan Tull <atull@opensource.altera.com>");
+MODULE_LICENSE("GPL v2");
-- 
1.7.9.5

Re: [PATCH v15 0/6] altera fpga area and fpga bus

[Moritz Fischer]

Hi Alan,

On Wed, Jan 20, 2016 at 8:24 PM,  <atull-yzvPICuk2ABMcg4IHK0kFoH6Mc4MB0Vx@public.gmane.org> wrote:
> From: Alan Tull <atull-yzvPICuk2ABMcg4IHK0kFoH6Mc4MB0Vx@public.gmane.org>
>
> For v15, I'm not using the FPGA Manager as the bus.  I'm adding a FPGA Bus;
> the FPGA Manager and bridges go below it.
>
> I've gotten enough feedback that my proposals are Altera specific that I am
> going with that and changing the bindings to include an 'altr,' prefix.

I hope this wasn't a misunderstanding of one of my earlier remarks. I
think the fpga-area & fpga bus
parts do apply to to Xilinx FPGAs, too. I think for fpga-area and
fpga-bus we could drop the 'altr' prefix.

>
> I've combined the bindings document and the other Documentation/fpga/ document
> and done a rewrite there.

Looks great!

I'll test it on hardware and look at the patches individually,

Cheers,

Moritz
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v15 2/6] add sysfs document for fpga bridge class

[Måns Rullgård]

<atull@opensource.altera.com> writes:

> From: Alan Tull <atull@opensource.altera.com>
>
> Add documentation for new FPGA bridge class's sysfs interface.
>
> Signed-off-by: Alan Tull <atull@opensource.altera.com>

I don't see a patch in this email.

-- 
Måns Rullgård

Re: [PATCH v15 2/6] add sysfs document for fpga bridge class

[Moritz Fischer]

On Thu, Jan 21, 2016 at 1:17 PM, Måns Rullgård <mans@mansr.com> wrote:

> I don't see a patch in this email.

So it's not just me :-)

Cheers,

Moritz

Re: [PATCH v15 5/6] fpga: fpga-area and fpga-bus: device tree control for FPGA

[Moritz Fischer]

Hi Alan,

minor nits inline:

On Wed, Jan 20, 2016 at 8:24 PM,  <atull@opensource.altera.com> wrote:

> v15: Add altr,fpga-bus implementation
>      Change compatible string "fpga-area" -> "altr,fpga-area"

Doesn't look that way down there. Or am I reading the code wrong?

> +static const struct of_device_id fpga_area_of_match[] = {
> +       { .compatible = "fpga-area", },

I'm fine with keeping it as fpga-area, this isn't altera specific imho

Cheers,

Moritz

Re: [PATCH v15 1/6] fpga: add bindings document for fpga area and fpga bus

[Moritz Fischer]

Hi Alan,

I tried getting a simple example to work with overlays, however so far
I failed getting
the child nodes to probe drivers, maybe you have an idea? The fpga
image is loaded just fine.

in dts:

               fpga_bus@0 {
                       compatible = "altr,fpga-bus", "simple-bus";
                       #address-cells = <1>;
                       #size-cells = <1>;
                       ranges;

                       fpga_mgr0: devcfg@f8007000 {
                               compatible = "xlnx,zynq-devcfg-1.0",
"simple-bus";
                               reg = <0xf8007000 0x100>;
                               interrupt-parent = <&intc>;
                               interrupts = <0 8 4>;
                               clocks = <&clkc 12>;
                               clock-names = "ref_clk";
                               syscon = <&slcr>;

                               #address-cells = <1>;
                               #size-cells = <1>;
                               ranges;
                       };
              };

overlay:

fragment@0 {
        target-path = "/amba/devcfg@f8007000";
        __overlay__ {
                #address-cells = <1>;
                #size-cells = <1>;

                area@0 {
                        compatible = "fpga-area";
                        #address-cells = <1>;
                        #size-cells = <1>;
                        ranges;

                        firmware-name = "dmac.bin";

                        axi_dma0: axidma@40000000 {
                                compatible = "xlnx,axi-dma-1.00.a";
                                reg = <0x40000000 0x10000>;
                               #dma-cells = <1>;
                               xlnx,include-sg = <1>;
                               xlnx,include-dre = <1>;
                              status = "okay";
                              [...]
                       };
                };
        };
};


I also stumbled across those while looking through the examples:

> +Example:
> +
> +/dts-v1/;
> +/plugin/;

/dts-v1/ / plugin/; the above syntax is deprecated:

Warning (deprecated_plugin_syntax): Use '/dts-v1/ /plugin/'; syntax.
/dts-v1/; /plugin/; is going to be removed in next versions

> +Device Tree Example: Partial Reconfiguration with no Bridges
> +============================================================
> +
> +Live Device Tree contains:
> +       fpgamgr@ffd03000 {
> +               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/;

see above

Cheers,

Moritz

Re: [PATCH v15 2/6] add sysfs document for fpga bridge class

[atull]

On Wed, 20 Jan 2016, atull-yzvPICuk2ABMcg4IHK0kFoH6Mc4MB0Vx@public.gmane.org wrote:

> From: Alan Tull <atull-yzvPICuk2ABMcg4IHK0kFoH6Mc4MB0Vx@public.gmane.org>
> 
> Add documentation for new FPGA bridge class's sysfs interface.
> 
> Signed-off-by: Alan Tull <atull-yzvPICuk2ABMcg4IHK0kFoH6Mc4MB0Vx@public.gmane.org>

I've received two emails that there was no patch in this email.  The
copy I received has 11 lines of changes, adding one file
Documentation/ABI/testing/sysfs-class-fpga-bridge

Alan

> --
> v15: Document added in v15 of patch set
> ---
>  Documentation/ABI/testing/sysfs-class-fpga-bridge |   11 +++++++++++
>  1 file changed, 11 insertions(+)
>  create mode 100644 Documentation/ABI/testing/sysfs-class-fpga-bridge
> 
> diff --git a/Documentation/ABI/testing/sysfs-class-fpga-bridge b/Documentation/ABI/testing/sysfs-class-fpga-bridge
> new file mode 100644
> index 0000000..312ae2c
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-class-fpga-bridge
> @@ -0,0 +1,11 @@
> +What:		/sys/class/fpga_bridge/<bridge>/name
> +Date:		January 2016
> +KernelVersion:	4.5
> +Contact:	Alan Tull <atull-yzvPICuk2ABMcg4IHK0kFoH6Mc4MB0Vx@public.gmane.org>
> +Description:	Name of low level FPGA bridge driver.
> +
> +What:		/sys/class/fpga_bridge/<bridge>/state
> +Date:		January 2016
> +KernelVersion:	4.5
> +Contact:	Alan Tull <atull-yzvPICuk2ABMcg4IHK0kFoH6Mc4MB0Vx@public.gmane.org>
> +Description:	Show bridge state as "enabled" or "disabled"
> -- 
> 1.7.9.5
> 
> 
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v15 0/6] altera fpga area and fpga bus

[atull]

On Thu, 21 Jan 2016, Moritz Fischer wrote:

> Hi Alan,
> 
> On Wed, Jan 20, 2016 at 8:24 PM,  <atull@opensource.altera.com> wrote:
> > From: Alan Tull <atull@opensource.altera.com>
> >
> > For v15, I'm not using the FPGA Manager as the bus.  I'm adding a FPGA Bus;
> > the FPGA Manager and bridges go below it.
> >
> > I've gotten enough feedback that my proposals are Altera specific that I am
> > going with that and changing the bindings to include an 'altr,' prefix.
> 
> I hope this wasn't a misunderstanding of one of my earlier remarks. I
> think the fpga-area & fpga bus
> parts do apply to to Xilinx FPGAs, too. I think for fpga-area and
> fpga-bus we could drop the 'altr' prefix.

Yes, I would very much like to drop the altr prefix if we have general
acceptance that this isn't all Altera specific.  I'll need to rename
altera-fpga-bus-fpga-area.txt to drop the 'altera-' prefix and clean
up a little there.

If you want to send me a Xilinx example of usage for me to include in that
document, that would be useful also.  I think you might have sent me
something a while ago, but I can't find it now.

> 
> >
> > I've combined the bindings document and the other Documentation/fpga/ document
> > and done a rewrite there.
> 
> Looks great!
> 
> I'll test it on hardware and look at the patches individually,

Thank you!

> 
> Cheers,
> 
> Moritz
> 

Re: [PATCH v15 1/6] fpga: add bindings document for fpga area and fpga bus

[atull]

On Thu, 21 Jan 2016, Moritz Fischer wrote:

> Hi Alan,
> 
> I tried getting a simple example to work with overlays, however so far
> I failed getting
> the child nodes to probe drivers, maybe you have an idea? The fpga
> image is loaded just fine.
> 
> in dts:
> 
>                fpga_bus@0 {
>                        compatible = "altr,fpga-bus", "simple-bus";
>                        #address-cells = <1>;
>                        #size-cells = <1>;
>                        ranges;
> 
>                        fpga_mgr0: devcfg@f8007000 {
>                                compatible = "xlnx,zynq-devcfg-1.0",
> "simple-bus";
>                                reg = <0xf8007000 0x100>;
>                                interrupt-parent = <&intc>;
>                                interrupts = <0 8 4>;
>                                clocks = <&clkc 12>;
>                                clock-names = "ref_clk";
>                                syscon = <&slcr>;
> 
>                                #address-cells = <1>;
>                                #size-cells = <1>;
>                                ranges;
>                        };
>               };
> 
> overlay:
> 
> fragment@0 {
>         target-path = "/amba/devcfg@f8007000";

Hi Moritz,

          target-path = "/amba/fpga_bus@0/devcfg@f8007000";

should work, I hope.  If it doesn't, turn on debugging for
fpga-area.c and maybe add more printk's in the probe function.
Hopefully you get to the fpga-area's probe function and can
see which step is bailing out.  If you get as far as 
of_platform_populate, but your axidma's probe isn't getting
called then you could add some debug to drivers/of/platform.c
to see why it's not getting populated.

Alan

>         __overlay__ {
>                 #address-cells = <1>;
>                 #size-cells = <1>;
> 
>                 area@0 {
>                         compatible = "fpga-area";
>                         #address-cells = <1>;
>                         #size-cells = <1>;
>                         ranges;
> 
>                         firmware-name = "dmac.bin";
> 
>                         axi_dma0: axidma@40000000 {
>                                 compatible = "xlnx,axi-dma-1.00.a";
>                                 reg = <0x40000000 0x10000>;
>                                #dma-cells = <1>;
>                                xlnx,include-sg = <1>;
>                                xlnx,include-dre = <1>;
>                               status = "okay";
>                               [...]
>                        };
>                 };
>         };
> };
> 
> 
> I also stumbled across those while looking through the examples:
> 
> > +Example:
> > +
> > +/dts-v1/;
> > +/plugin/;
> 
> /dts-v1/ / plugin/; the above syntax is deprecated:
> 
> Warning (deprecated_plugin_syntax): Use '/dts-v1/ /plugin/'; syntax.
> /dts-v1/; /plugin/; is going to be removed in next versions
> 
> > +Device Tree Example: Partial Reconfiguration with no Bridges
> > +============================================================
> > +
> > +Live Device Tree contains:
> > +       fpgamgr@ffd03000 {
> > +               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/;

Yes, thanks! I will adjust the documentation to reflect that.

Alan

> 
> see above
> 
> Cheers,
> 
> Moritz
> 

Re: [PATCH v15 5/6] fpga: fpga-area and fpga-bus: device tree control for FPGA

[atull]

On Thu, 21 Jan 2016, Moritz Fischer wrote:

> Hi Alan,
> 
> minor nits inline:
> 
> On Wed, Jan 20, 2016 at 8:24 PM,  <atull@opensource.altera.com> wrote:
> 
> > v15: Add altr,fpga-bus implementation
> >      Change compatible string "fpga-area" -> "altr,fpga-area"
> 
> Doesn't look that way down there. Or am I reading the code wrong?

Hi Moritz,

Yes, I left that out accidentally.  But hopefully we won't have
pushback around this issue and I can leave it out permanently
and also change altr,fpga-bus to fpga-bus.

Alan

> 
> > +static const struct of_device_id fpga_area_of_match[] = {
> > +       { .compatible = "fpga-area", },
> 
> I'm fine with keeping it as fpga-area, this isn't altera specific imho
> 
> Cheers,
> 
> Moritz
> 

Re: [PATCH v15 1/6] fpga: add bindings document for fpga area and fpga bus

[Moritz Fischer]

Hi Alan,

On Thu, Jan 21, 2016 at 6:21 PM, atull <atull@opensource.altera.com> wrote:

>           target-path = "/amba/fpga_bus@0/devcfg@f8007000";

derp ... building in the driver helps ... all good on your side ;-)

Cheers,

Moritz

Re: [PATCH v15 0/6] altera fpga area and fpga bus

[Moritz Fischer]

Hi Alan,

On Thu, Jan 21, 2016 at 5:42 PM, atull <atull@opensource.altera.com> wrote:

> If you want to send me a Xilinx example of usage for me to include in that
> document, that would be useful also.  I think you might have sent me
> something a while ago, but I can't find it now.

Will do. I'll clean up some of my examples with an in-tree driver and
get back to you.
Having more examples never hurts.

Cheers,

Moritz

Re: [PATCH v15 5/6] fpga: fpga-area and fpga-bus: device tree control for FPGA

[Moritz Fischer]

Alan,

On Wed, Jan 20, 2016 at 8:24 PM,  <atull@opensource.altera.com> wrote:

> +static int fpga_area_probe(struct platform_device *pdev)
> +{
> +       struct device *dev = &pdev->dev;
> +       struct device_node *np = dev->of_node;
> +       struct fpga_area *area;
> +       int ret;
> +
> +       area = devm_kzalloc(dev, sizeof(*area), GFP_KERNEL);
> +       if (!area)
> +               return -ENOMEM;
> +
> +       INIT_LIST_HEAD(&area->bridge_list);
> +
> +       ret = fpga_bridge_register(dev, "FPGA Area", NULL, area);
> +       if (ret)
> +               return ret;
> +       area->br = dev_get_drvdata(dev);
> +
> +       if (of_property_read_string(np, "firmware-name",
> +                                   &area->firmware_name)) {
> +               of_platform_populate(np, of_default_bus_match_table, NULL, dev);
> +               return 0;
> +       }

This is the use case where the bootloader loaded the fpga, and you
just want to populate
the devices in the fabric, right?

> +       if (of_property_read_bool(np, "partial-reconfig"))
> +               area->flags |= FPGA_MGR_PARTIAL_RECONFIG;
> +
> +       ret = fpga_area_get_bus(area);
> +       if (ret) {
> +               dev_dbg(dev, "Should be child of a FPGA Bus");
> +               goto err_unreg;
> +       }

Looking at socfpga.dtsi, would that mean that the fpgamgr0 node would
need to become a subnode of fpgabus@0 at the same place?

i.e. /soc/fpgamgr@ff706000 -> /soc/fpgabus@0/fpgamgr@ff706000

and the ranges property would be used to translate to the fpga memory
mapped space?

I know we're going back and forth on this. I think Rob brought up a
similar question:
"Does the bus really go thru the fpgamgr and then the bridge as this
implies? Or fpgamgr is a sideband controller?"

To which I think the answer is 'sideband' controller, yet with the new
bindings it looks like
the bus goes through the fpgamgr.

Cheers,

Moritz

Re: [PATCH v15 5/6] fpga: fpga-area and fpga-bus: device tree control for FPGA

[atull]

On Fri, 22 Jan 2016, Moritz Fischer wrote:

> Alan,
> 
> On Wed, Jan 20, 2016 at 8:24 PM,  <atull@opensource.altera.com> wrote:
> 
> > +static int fpga_area_probe(struct platform_device *pdev)
> > +{
> > +       struct device *dev = &pdev->dev;
> > +       struct device_node *np = dev->of_node;
> > +       struct fpga_area *area;
> > +       int ret;
> > +
> > +       area = devm_kzalloc(dev, sizeof(*area), GFP_KERNEL);
> > +       if (!area)
> > +               return -ENOMEM;
> > +
> > +       INIT_LIST_HEAD(&area->bridge_list);
> > +
> > +       ret = fpga_bridge_register(dev, "FPGA Area", NULL, area);
> > +       if (ret)
> > +               return ret;
> > +       area->br = dev_get_drvdata(dev);
> > +
> > +       if (of_property_read_string(np, "firmware-name",
> > +                                   &area->firmware_name)) {
> > +               of_platform_populate(np, of_default_bus_match_table, NULL, dev);
> > +               return 0;
> > +       }
> 
> This is the use case where the bootloader loaded the fpga, and you
> just want to populate
> the devices in the fabric, right?

Hi Moritz,

Yes

> 
> > +       if (of_property_read_bool(np, "partial-reconfig"))
> > +               area->flags |= FPGA_MGR_PARTIAL_RECONFIG;
> > +
> > +       ret = fpga_area_get_bus(area);
> > +       if (ret) {
> > +               dev_dbg(dev, "Should be child of a FPGA Bus");
> > +               goto err_unreg;
> > +       }
> 
> Looking at socfpga.dtsi, would that mean that the fpgamgr0 node would
> need to become a subnode of fpgabus@0 at the same place?
> 
> i.e. /soc/fpgamgr@ff706000 -> /soc/fpgabus@0/fpgamgr@ff706000
> 
> and the ranges property would be used to translate to the fpga memory
> mapped space?
> 
> I know we're going back and forth on this. I think Rob brought up a
> similar question:
> "Does the bus really go thru the fpgamgr and then the bridge as this
> implies? Or fpgamgr is a sideband controller?"
> 
> To which I think the answer is 'sideband' controller, yet with the new
> bindings it looks like
> the bus goes through the fpgamgr.

Yeah, let's get this right.  First, let's be clear on the reason for FPGA Bus to
exist.  There may be >1 FPGA in a system.  I want the FPGA Bus bring together
the bridges and manager that are associated with a certain FPGA.  This allows
the system designer to specify which FPGA is getting programmed with which
image/hardware.  So at minimum, we need some way of associating a FPGA Bus with
a FPGA Manager.

As far as the target path is concerned, in the case of no bridges, we could have
the overlay target the FPGA Bus instead of the FPGA Manager.  That may be more
logical.  This would just be a documentation change; I think fpga-area.c will
work OK if you specify the FPGA bus as your target (the manager still has to
be a child of the bus so the bus knows what manager to use).

Alan

> 
> Cheers,
> 
> Moritz
> 

Re: [PATCH v15 5/6] fpga: fpga-area and fpga-bus: device tree control for FPGA

[Moritz Fischer]

On Fri, Jan 22, 2016 at 5:37 PM, atull <atull@opensource.altera.com> wrote:
> On Fri, 22 Jan 2016, Moritz Fischer wrote:
>
>> Alan,
>>
>> On Wed, Jan 20, 2016 at 8:24 PM,  <atull@opensource.altera.com> wrote:
>>
>> > +static int fpga_area_probe(struct platform_device *pdev)
>> > +{
>> > +       struct device *dev = &pdev->dev;
>> > +       struct device_node *np = dev->of_node;
>> > +       struct fpga_area *area;
>> > +       int ret;
>> > +
>> > +       area = devm_kzalloc(dev, sizeof(*area), GFP_KERNEL);
>> > +       if (!area)
>> > +               return -ENOMEM;
>> > +
>> > +       INIT_LIST_HEAD(&area->bridge_list);
>> > +
>> > +       ret = fpga_bridge_register(dev, "FPGA Area", NULL, area);
>> > +       if (ret)
>> > +               return ret;
>> > +       area->br = dev_get_drvdata(dev);
>> > +
>> > +       if (of_property_read_string(np, "firmware-name",
>> > +                                   &area->firmware_name)) {
>> > +               of_platform_populate(np, of_default_bus_match_table, NULL, dev);
>> > +               return 0;
>> > +       }
>>
>> This is the use case where the bootloader loaded the fpga, and you
>> just want to populate
>> the devices in the fabric, right?
>
> Hi Moritz,
>
> Yes
>
>>
>> > +       if (of_property_read_bool(np, "partial-reconfig"))
>> > +               area->flags |= FPGA_MGR_PARTIAL_RECONFIG;
>> > +
>> > +       ret = fpga_area_get_bus(area);
>> > +       if (ret) {
>> > +               dev_dbg(dev, "Should be child of a FPGA Bus");
>> > +               goto err_unreg;
>> > +       }
>>
>> Looking at socfpga.dtsi, would that mean that the fpgamgr0 node would
>> need to become a subnode of fpgabus@0 at the same place?
>>
>> i.e. /soc/fpgamgr@ff706000 -> /soc/fpgabus@0/fpgamgr@ff706000
>>
>> and the ranges property would be used to translate to the fpga memory
>> mapped space?
>>
>> I know we're going back and forth on this. I think Rob brought up a
>> similar question:
>> "Does the bus really go thru the fpgamgr and then the bridge as this
>> implies? Or fpgamgr is a sideband controller?"
>>
>> To which I think the answer is 'sideband' controller, yet with the new
>> bindings it looks like
>> the bus goes through the fpgamgr.
>
> Yeah, let's get this right.  First, let's be clear on the reason for FPGA Bus to
> exist.  There may be >1 FPGA in a system.  I want the FPGA Bus bring together
> the bridges and manager that are associated with a certain FPGA.  This allows
> the system designer to specify which FPGA is getting programmed with which
> image/hardware.  So at minimum, we need some way of associating a FPGA Bus with
> a FPGA Manager.

I see your argument for the FPGA bus. I agree that we need to
distinguish different FPGAs,
and we need a way to associate an area with a manager (and potentially bridges).

> As far as the target path is concerned, in the case of no bridges, we could have
> the overlay target the FPGA Bus instead of the FPGA Manager.  That may be more
> logical.  This would just be a documentation change; I think fpga-area.c will
> work OK if you specify the FPGA bus as your target (the manager still has to
> be a child of the bus so the bus knows what manager to use).

Could the bus not just use a phandle to the manager? Or the area a
phandle to the bus?
Like that one could have potentially disjunct groups. Say I have a SPI
device that is in an FPGA area.
With our current system, I'd have a FPGA Manager that needs to be a
child of the bus as child of the SPI controller
with the memory addresses being addresses on the SOC's memory bus:

spi_ctrl@deadbeef {
        fpga_bus@0 {
                fpgamgr@f8007000 {
                    mgr regs etc...
                ... and now the SPI slaves ...
                    slave@42 {
                    };
                };
        };
};

(or something like that, maybe I'm confused)

with my proposed one it looks like it would work with any bus (maybe
then areas would have to register with
the manager or something like that...)

spi_ctrl@deadbeef {
        fpga_area {
                fpga-mgr = <&fpgamgr0>;
                slave0@42 {
                };
        };
};

I keep bringing up SPI because it's another bus with addresses, not
because I think we should particularly
optimize for that use case ;-)

Cheers,

Moritz

PS: Feel free to 'break' my suggestion above. It's just an idea

Re: [PATCH v15 5/6] fpga: fpga-area and fpga-bus: device tree control for FPGA

[Rob Herring]

On Fri, Jan 22, 2016 at 6:07 PM, Moritz Fischer
<moritz.fischer@ettus.com> wrote:
> On Fri, Jan 22, 2016 at 5:37 PM, atull <atull@opensource.altera.com> wrote:
>> On Fri, 22 Jan 2016, Moritz Fischer wrote:
>>
>>> Alan,
>>>
>>> On Wed, Jan 20, 2016 at 8:24 PM,  <atull@opensource.altera.com> wrote:
>>>
>>> > +static int fpga_area_probe(struct platform_device *pdev)
>>> > +{
>>> > +       struct device *dev = &pdev->dev;
>>> > +       struct device_node *np = dev->of_node;
>>> > +       struct fpga_area *area;
>>> > +       int ret;
>>> > +
>>> > +       area = devm_kzalloc(dev, sizeof(*area), GFP_KERNEL);
>>> > +       if (!area)
>>> > +               return -ENOMEM;
>>> > +
>>> > +       INIT_LIST_HEAD(&area->bridge_list);
>>> > +
>>> > +       ret = fpga_bridge_register(dev, "FPGA Area", NULL, area);
>>> > +       if (ret)
>>> > +               return ret;
>>> > +       area->br = dev_get_drvdata(dev);
>>> > +
>>> > +       if (of_property_read_string(np, "firmware-name",
>>> > +                                   &area->firmware_name)) {
>>> > +               of_platform_populate(np, of_default_bus_match_table, NULL, dev);
>>> > +               return 0;
>>> > +       }
>>>
>>> This is the use case where the bootloader loaded the fpga, and you
>>> just want to populate
>>> the devices in the fabric, right?
>>
>> Hi Moritz,
>>
>> Yes

That is very strange logic. It should be fine to just call
of_platform_populate unconditionally. If there are no children of np,
then it will be a nop.

>>> > +       if (of_property_read_bool(np, "partial-reconfig"))
>>> > +               area->flags |= FPGA_MGR_PARTIAL_RECONFIG;
>>> > +
>>> > +       ret = fpga_area_get_bus(area);
>>> > +       if (ret) {
>>> > +               dev_dbg(dev, "Should be child of a FPGA Bus");
>>> > +               goto err_unreg;
>>> > +       }
>>>
>>> Looking at socfpga.dtsi, would that mean that the fpgamgr0 node would
>>> need to become a subnode of fpgabus@0 at the same place?
>>>
>>> i.e. /soc/fpgamgr@ff706000 -> /soc/fpgabus@0/fpgamgr@ff706000
>>>
>>> and the ranges property would be used to translate to the fpga memory
>>> mapped space?
>>>
>>> I know we're going back and forth on this. I think Rob brought up a
>>> similar question:
>>> "Does the bus really go thru the fpgamgr and then the bridge as this
>>> implies? Or fpgamgr is a sideband controller?"
>>>
>>> To which I think the answer is 'sideband' controller, yet with the new
>>> bindings it looks like
>>> the bus goes through the fpgamgr.
>>
>> Yeah, let's get this right.  First, let's be clear on the reason for FPGA Bus to
>> exist.  There may be >1 FPGA in a system.  I want the FPGA Bus bring together
>> the bridges and manager that are associated with a certain FPGA.  This allows
>> the system designer to specify which FPGA is getting programmed with which
>> image/hardware.  So at minimum, we need some way of associating a FPGA Bus with
>> a FPGA Manager.
>
> I see your argument for the FPGA bus. I agree that we need to
> distinguish different FPGAs,
> and we need a way to associate an area with a manager (and potentially bridges).
>
>> As far as the target path is concerned, in the case of no bridges, we could have
>> the overlay target the FPGA Bus instead of the FPGA Manager.  That may be more
>> logical.  This would just be a documentation change; I think fpga-area.c will
>> work OK if you specify the FPGA bus as your target (the manager still has to
>> be a child of the bus so the bus knows what manager to use).
>
> Could the bus not just use a phandle to the manager? Or the area a
> phandle to the bus?

That may be better as it would avoid the virtual fpga-bus which is a
bit questionable. I'm okay with allowing it, but will happily take any
examples where it doesn't work. However, I'm not sure this case is
one.

> Like that one could have potentially disjunct groups. Say I have a SPI
> device that is in an FPGA area.
> With our current system, I'd have a FPGA Manager that needs to be a
> child of the bus as child of the SPI controller
> with the memory addresses being addresses on the SOC's memory bus:
>
> spi_ctrl@deadbeef {
>         fpga_bus@0 {
>                 fpgamgr@f8007000 {
>                     mgr regs etc...
>                 ... and now the SPI slaves ...
>                     slave@42 {
>                     };
>                 };
>         };
> };

I think Alan's assumption is there's always a memory mapped control
interface and the DT hierarchy follows that. While I see you could
have other interfaces like SPI, that would not be the control
interface related to FPGA programming AIUI. You could also have GPIOs,
I2C, or any other bus/interface we describe in DT in theory.

How to deal with additional connections like this is similar to
overlays for daughterboards (e.g. capes, hats, shields) where the need
for mapping slave devices on a connector to host controllers/buses
which can vary. In that case, you don't want to have to create a
different overlay for every host board just to change the parent
devices of each child. If there is a SPI connection to FPGA (or area),
then we need a way to map the host SPI bus to the FPGA. In this
example, the overlay should only say "slave@42" is connected to the
spi bus of the FPGA area and it would not have direct reference to
"spi_ctrl@deadbeef." There's some ideas around how to support these
usecases probably involving a connector node with mappings of
connector i/o's to host i/o's (paging Pantelis, where's your
proposal?). I think the same would work here, so I would suggest we
not try to address it immediately other than decide the requirements
here are similar enough to what is needed for connectors.

Rob

Re: [PATCH v15 1/6] fpga: add bindings document for fpga area and fpga bus

[Rob Herring]

On Wed, Jan 20, 2016 at 01:24:22PM -0600, atull@opensource.altera.com wrote:
> From: Alan Tull <atull@opensource.altera.com>
> 
> New bindings document for FPGA Area for reprogramming
> FPGA's under Device Tree control
> 
> Signed-off-by: Alan Tull <atull@opensource.altera.com>
> ---
> v9:  initial version added to this patchset
> v10: s/fpga/FPGA/g
>      replace DT overlay example with slightly more complicated example
>      move to staging/simple-fpga-bus
> v11: No change in this patch for v11 of the patch set
> v12: Moved out of staging.
>      Changed to use FPGA bridges framework instead of resets
>      for bridges.
> v13: bridge@0xff20000 -> bridge@ff200000, etc
>      Leave out directly talking about overlays
>      Remove regs and clocks directly under simple-fpga-bus in example
>      Use common "firmware-name" binding instead of "fpga-firmware"
> v14: Use firmware-name in bindings description
>      Call it FPGA Area
>      Remove bindings that specify FPGA Manager and FPGA Bridges
> v15: Cleanup as per Rob's comments
>      Combine usage doc with bindings document
>      Document as being Altera specific
>      Additions and changes to add FPGA Bus
> ---
>  .../bindings/fpga/altera-fpga-bus-fpga-area.txt    |  452 ++++++++++++++++++++
>  1 file changed, 452 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/fpga/altera-fpga-bus-fpga-area.txt
> 
> diff --git a/Documentation/devicetree/bindings/fpga/altera-fpga-bus-fpga-area.txt b/Documentation/devicetree/bindings/fpga/altera-fpga-bus-fpga-area.txt
> new file mode 100644
> index 0000000..8ea38ca
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/fpga/altera-fpga-bus-fpga-area.txt
> @@ -0,0 +1,452 @@
> +Altera FPGA Area and FPGA Bus Device Tree Binding

Getting closer I think...

> +
> +Alan Tull 2016
> +
> + CONTENTS
> + - Introduction
> + - Terminology
> + - Overview
> + - Constraints
> + - FPGA Bus
> + - FPGA Area
> + - Supported Use Models
> + - Sequence
> + - Device Tree Examples
> +
> +
> +Introduction
> +============
> +
> +FPGA Buses and FPGA Areas are introduced as a way to solve the problem of how to
> +reprogram an Altera FPGA under an operating system and have the new hardware
> +show up in the device tree.  By adding these bindings to the Device Tree, a
> +system can have the information needed to do the FPGA programming to add the
> +desired hardware, and also the information about the devices to be added to the
> +Device Tree once the programming has succeeded.
> +
> +
> +Terminology
> +===========
> +
> +Full Reconfiguration
> + * The entire FPGA is programmed.
> +
> +Partial Reconfiguration (PR)
> + * The FPGA is broken up into regions.  One of these regions is reprogrammed
> +   while the rest of the FPGA is not affected.  Not all FPGA's support this.
> +
> +FPGA Manager & 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 & 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 may not be needed in implementations where the FPGA Manager
> +   handles this.
> +
> +Freeze Blocks
> + * Freeze Blocks function as FPGA Bridges within the FPGA fabric.  In the case
> +   of PR, the buses from the processor are split within the FPGA.  Each PR
> +   region gets its own split of the buses, protected by an independently
> +   controlled Freeze Block.  Several busses may be connected to a single
> +   PR region; a Freeze Block controls the traffic of all these busses
> +   together.
> +
> +Controlling Bridge
> + * The processor and FPGA may be connected by multiple FPGA Bridges.  In a text
> +   based hierarchy, it is difficult to show this properly as a device would
> +   have several parents.
> + * The bridge that handles register access to the FPGA is designated the
> +   "controlling" bridge.
> + * The controlling bridge will be the target point under which the overlay is
> +   inserted.
> +
> +
> +Overview
> +========
> +
> +This binding introduces the FPGA Bus and FPGA Area.
> +
> +An FPGA Bus is a virtualized bus that contains the devices needed to be able to
> +program an FPGA device.  It contains a child FPGA Manager and may contain child
> +FPGA Bridges, if needed.  The FPGA Manager is the hardware block that handles
> +programming the FPGA.  FPGA Bridges function to prevent spurious data from the
> +FPGA going on the processor busses during FPGA programming.  In the case of
> +partial reconfiguration, additional bridges (Freeze Blocks) for each
> +reconfiguration region are required.
> +
> +An FPGA Area contains information about a section of an FPGA (in the case of
> +partial reconfiguration or the whole FPGA (for full reconfiguration).  The FPGA
> +Area contains the name of the FPGA image file to be programmed and the child
> +devices that will be contained in the FPGA after programming.
> +
> +The intended use is that device tree overlays can be used to add hardware to an
> +FPGA while an operating system is running.  In that case, the FPGA Bus and its
> +associated information will exist in the live device tree, while FPGA Areas are
> +added to the device tree by applying device tree overlays while the operating
> +system is running.  Loading such an overlay will cause the FPGA to be programmed
> +and the child devices to be populated.  Removing an overlay will cause the
> +devices to be removed from the device tree and free up those FPGA resources.
> +
> +
> +Constraints
> +===========
> +
> +It is beyond the scope of this document to fully describe all the FPGA design
> +constraints required to make partial reconfiguration work[1] [2], but a few
> +deserve quick mention.  A partial reconfiguration FPGA image must have
> +boundary connections that line up with those the current programming of the
> +FPGA.  Also, those during programming, those connections must be frozen.  This
> +can be achieved by "Freeze Blocks" which are FPGA Bridges that exist on the FPGA
> +fabric prior to the partial reconfiguration.
> +
> +
> +FPGA Bus
> +========
> +
> +An FPGA bus is a virtualized bus that specifies the devices needed to program an
> +FPGA.
> +
> +Required properties:
> +- compatible : should contain "altr,fpga-bus" and "simple-bus"
> +	       "simple-bus" is required to allow populating the child nodes.

I think I said this before, but you should not need simple-bus. Having 
it is wrong if the bus requires some configuration before enumerating 
the child nodes. The way you have it, the bridge driver could probe 
before the FPGA manager or vice-versa. I'm guessing one way will work 
and the other will not, and you are getting lucky. You should also test 
will the overlay applied before boot (i.e. single dtb with all areas 
populated). The simple rule is does the node (containing simple-bus) 
require configuration for child nodes to be accessed? If yes, you can't 
use simple-bus.

Part of your problem is you may need a custom match table. Using 
of_default_bus_match_table will only match the immediate child nodes of 
the starting node. Alternatively, you need to make the bridge node the 
starting node.

> +
> +A FPGA Bus should contain an FPGA Manager as a child node.
> +
> +A FPGA Bus may require FPGA Bridges as child nodes if the FPGA Manager does not
> +control the hardware bridges.
> +
> +The FPGA Bridge that allows memory mapped register access is designated the
> +"controlling" bridge.  This bridge serves as the insertion point of DT overlays.
> +Both the FPGA Area and the controlling bridge require the "simple-bus"
> +compatibility string to allow populating the child nodes contained in the
> +overlay.
> +
> +In the example below, fpgamgr@ff706000 would be used to do any programming
> +operations on the FPGA and the two bridges specified would be disabled
> +during the programming and re-enabled afterwards if the programming
> +succeeds.
> +
> +Example:
> +	fpgabus@0 {

If you have a unit-address, then there should be a reg property or 
ranges parent bus addr.

> +		compatible = "altr,fpga-bus", "simple-bus";
> +		#address-cells = <0x1>;
> +		#size-cells = <0x1>;
> +		ranges;
> +
> +		fpgamgr@ff706000 {

As mentioned in the other thread, this may be better done as a phandle, 
but I don't feel too strongly either way.

> +			compatible = "altr,socfpga-fpga-mgr";
> +			reg = <0xff706000 0x1000
> +			       0xffb90000 0x1000>;
> +			interrupts = <0 175 4>;
> +		};
> +
> +		bridge@0 {

Same here. Doesn't this bridge have some associated address range.

Essentially, the hierarchy from child devices up to the root should 
reflect the address decoding at each step.

> +			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 {
> +			compatible = "altr,socfpga-hps2fpga-bridge";
> +			resets = <&rst HPS2FPGA_RESET>;
> +			reset-names = "hps2fpga";
> +			clocks = <&l4_main_clk>;
> +		};
> +	};
> +
> +FPGA Area
> +=========
> +
> +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.
> +
> +An FPGA Area corresponds to the whole FPGA in the case of full reconfiguration
> +or a section of an FPGA in the case of partial reconfiguration.
> +
> +Required properties:
> +- compatible : should contain "altr,fpga-area"
> +- #address-cells, #size-cells, ranges: must be present to handle address space
> +  mapping for children.
> +
> +Optional properties:
> +- firmware-name : should contain the name of an FPGA image file located on the
> +  firmware search path.
> +- partial-reconfig : boolean property should be defined if partial
> +  reconfiguration of the FPGA is to be done, otherwise full reconfiguration
> +  is done.
> +
> +In the example below, the target path is the controlling bridge of the FPGA Bus
> +example.  The FPGA would be programmed with the image contained in the
> +"soc_system.rbf" specified.  Assuming programming succeeds, the child devices
> +would be populated afterwords.  In this particular example, ranges has two
> +chip selects as one memory region is tied to the host processor and the
> +other is a memory region on the FPGA.
> +
> +If there are no bridges in the FPGA Bus, the target path would point to
> +the FPGA Manager.

How do you not have a bridge? There has to be something preventing 
access. Do you really mean the bridge and fpga-mgr blocks are combined 
into 1?

> +
> +Example:
> +
> +/dts-v1/;
> +/plugin/;
> +/ {
> +	fragment@0 {
> +		target-path="/soc/fpgamgr@ff706000/bridge@0";
> +		__overlay__ {
> +			#address-cells = <1>;
> +		        #size-cells = <1>;
> +
> +			bridge@ff200000 {

Wouldn't this be area@...? area is a bit too generic. I'd use 
"fpga-area" for the node name too.

> +				compatible = "fpga-area";
> +
> +				#address-cells = <2>;
> +				#size-cells = <1>;
> +
> +				ranges = <0 0x00000000 0xc0000000 0x00010000>,
> +					 <1 0x00020000 0xff220000 0x00000008>,
> +					 <1 0x00010040 0xff210040 0x00000020>;
> +
> +				firmware-name = "soc_system.rbf";
> +
> +				onchip_memory2_0: memory@0 {
> +					device_type = "memory";
> +					compatible = "altr,onchipmem-15.1";
> +					reg = <0 0x00000000 0x00010000>;
> +				};
> +
> +				jtag_uart: serial@100020000 {
> +					compatible = "altr,juart-1.0";
> +					reg = <1 0x00020000 0x00000008>;
> +					interrupt-parent = <&intc>;
> +					interrupts = <0 42 4>;
> +				};
> +
> +				led_pio: gpio@100010040 {
> +					compatible = "altr,pio-1.0";
> +					reg = <1 0x00010040 0x00000020>;
> +					altr,gpio-bank-width = <4>;
> +					#gpio-cells = <2>;
> +					gpio-controller;
> +				};
> +			};
> +		};
> +	};
> +};
> +
> +Supported Use Models
> +====================
> +
> +Here's a list of supported use models.  We may need to add more.  Some uses are
> +specific to one FPGA device or another.
> +
> + * No FPGA Bridges
> +   In this case, the FPGA Manager which programs the FPGA also handles the
> +   bridges.  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 live DT before the
> +   overlay is applied will have an FPGA Bus.
> +
> +   The DT overlay will specify the controlling bridge as the overlay target.
> +
> + * Partial reconfiguration with bridges in the FPGA
> +   In this case, the FPGA will have more than one section that will be
> +   programmed separately.  Other sections may be active on the bus while FPGA
> +   is being programmed.  To manage this, Freeze blocks 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.
> +
> +Sequence
> +========
> +
> +When a DT overlay is loaded, the FPGA Area will 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.
> +
> +When the overlay is removed, the FPGA Area in it is removed.  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, especially:
> + * FPGA Bus and associated FPGA Manager and FPGA Bridges
> + * FPGA Area and associated properties
> + * simple-bus
> + * ranges
> + * target-path
> +
> +For the purposes of this section, I'm dividing the Device Tree into two parts,
> +each with its own requirements.  The two parts are:
> + * The live DT prior to the overlay being added
> + * The DT overlay
> +
> +The live Device Tree must contain an FPGA Bus, which has a child 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 Bus.  During full reconfiguration, the
> +FPGA Area will disable any bridges that are direct children of the FPGA Bus and
> +will re-enable them after FPGA programming has succeeded.
> +
> +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.
> +
> +
> +Device Tree Example: Partial Reconfiguration with no Bridges
> +============================================================
> +
> +Live Device Tree contains:
> +	fpgamgr@ffd03000 {
> +		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@ffd03000";  /* targeted to the manager */
> +		__overlay__ {
> +			#address-cells = <1>;
> +		        #size-cells = <1>;
> +
> +			area@0 {

Are the number of areas software configurable? If not, then the areas 
should be part of the base DT rather than the overlay.

> +				compatible = "fpga-area";
> +
> +				#address-cells = <1>;
> +				#size-cells = <1>;
> +				ranges = <0x10010 0xff210010 0x10>;
> +
> +				firmware-name = "fit_pr_v1.rbf";
> +				partial-reconfig;
> +
> +				gpio@100010010 {

gpio@10010

> +					compatible = "altr,pio-1.0";
> +					reg = <0x10010 0x10>;
> +					altr,ngpio = <4>;
> +					#gpio-cells = <0x2>;
> +					gpio-controller;
> +				};
> +			};
> +		};
> +	};
> +};

Re: [PATCH v15 5/6] fpga: fpga-area and fpga-bus: device tree control for FPGA

[atull]

On Mon, 25 Jan 2016, Rob Herring wrote:

> On Fri, Jan 22, 2016 at 6:07 PM, Moritz Fischer
> <moritz.fischer@ettus.com> wrote:
> > On Fri, Jan 22, 2016 at 5:37 PM, atull <atull@opensource.altera.com> wrote:
> >> On Fri, 22 Jan 2016, Moritz Fischer wrote:
> >>
> >>> Alan,
> >>>
> >>> On Wed, Jan 20, 2016 at 8:24 PM,  <atull@opensource.altera.com> wrote:
> >>>
> >>> > +static int fpga_area_probe(struct platform_device *pdev)
> >>> > +{
> >>> > +       struct device *dev = &pdev->dev;
> >>> > +       struct device_node *np = dev->of_node;
> >>> > +       struct fpga_area *area;
> >>> > +       int ret;
> >>> > +
> >>> > +       area = devm_kzalloc(dev, sizeof(*area), GFP_KERNEL);
> >>> > +       if (!area)
> >>> > +               return -ENOMEM;
> >>> > +
> >>> > +       INIT_LIST_HEAD(&area->bridge_list);
> >>> > +
> >>> > +       ret = fpga_bridge_register(dev, "FPGA Area", NULL, area);
> >>> > +       if (ret)
> >>> > +               return ret;
> >>> > +       area->br = dev_get_drvdata(dev);
> >>> > +
> >>> > +       if (of_property_read_string(np, "firmware-name",
> >>> > +                                   &area->firmware_name)) {
> >>> > +               of_platform_populate(np, of_default_bus_match_table, NULL, dev);
> >>> > +               return 0;
> >>> > +       }
> >>>
> >>> This is the use case where the bootloader loaded the fpga, and you
> >>> just want to populate
> >>> the devices in the fabric, right?
> >>
> >> Hi Moritz,
> >>
> >> Yes
> 
> That is very strange logic. It should be fine to just call
> of_platform_populate unconditionally. If there are no children of np,
> then it will be a nop.

That's what it is doing.  It's coded this way to reduce indentation.  If there
is no FPGA image to load, call of_platform_populate() and return.  Otherwise do
a bunch of steps to load the FPGA image and handle the bridges, then call
of_platform_populate() and return.  If there's no children, no problem.

> 
> >>> > +       if (of_property_read_bool(np, "partial-reconfig"))
> >>> > +               area->flags |= FPGA_MGR_PARTIAL_RECONFIG;
> >>> > +
> >>> > +       ret = fpga_area_get_bus(area);
> >>> > +       if (ret) {
> >>> > +               dev_dbg(dev, "Should be child of a FPGA Bus");
> >>> > +               goto err_unreg;
> >>> > +       }
> >>>
> >>> Looking at socfpga.dtsi, would that mean that the fpgamgr0 node would
> >>> need to become a subnode of fpgabus@0 at the same place?
> >>>
> >>> i.e. /soc/fpgamgr@ff706000 -> /soc/fpgabus@0/fpgamgr@ff706000
> >>>
> >>> and the ranges property would be used to translate to the fpga memory
> >>> mapped space?
> >>>
> >>> I know we're going back and forth on this. I think Rob brought up a
> >>> similar question:
> >>> "Does the bus really go thru the fpgamgr and then the bridge as this
> >>> implies? Or fpgamgr is a sideband controller?"
> >>>
> >>> To which I think the answer is 'sideband' controller, yet with the new
> >>> bindings it looks like
> >>> the bus goes through the fpgamgr.
> >>
> >> Yeah, let's get this right.  First, let's be clear on the reason for FPGA Bus to
> >> exist.  There may be >1 FPGA in a system.  I want the FPGA Bus bring together
> >> the bridges and manager that are associated with a certain FPGA.  This allows
> >> the system designer to specify which FPGA is getting programmed with which
> >> image/hardware.  So at minimum, we need some way of associating a FPGA Bus with
> >> a FPGA Manager.
> >
> > I see your argument for the FPGA bus. I agree that we need to
> > distinguish different FPGAs,
> > and we need a way to associate an area with a manager (and potentially bridges).
> >
> >> As far as the target path is concerned, in the case of no bridges, we could have
> >> the overlay target the FPGA Bus instead of the FPGA Manager.  That may be more
> >> logical.  This would just be a documentation change; I think fpga-area.c will
> >> work OK if you specify the FPGA bus as your target (the manager still has to
> >> be a child of the bus so the bus knows what manager to use).
> >
> > Could the bus not just use a phandle to the manager? Or the area a
> > phandle to the bus?
> 
> That may be better as it would avoid the virtual fpga-bus which is a
> bit questionable. I'm okay with allowing it, but will happily take any
> examples where it doesn't work. However, I'm not sure this case is
> one.

I have no problem with specifying FPGA manager with a phandle, seems
like it will be better in some cases.

I'm proposing FPGA Bus to specify all the things (manager and bridges) that are
needed to do a reprogramming cycle on a specific FPGA. The FPGA Bus may seem
less necessary in Moritz' case where there are no FPGA Bridges in the DT.

I'll discuss this more on the other thread.

> 
> > Like that one could have potentially disjunct groups. Say I have a SPI
> > device that is in an FPGA area.
> > With our current system, I'd have a FPGA Manager that needs to be a
> > child of the bus as child of the SPI controller
> > with the memory addresses being addresses on the SOC's memory bus:
> >
> > spi_ctrl@deadbeef {
> >         fpga_bus@0 {
> >                 fpgamgr@f8007000 {
> >                     mgr regs etc...
> >                 ... and now the SPI slaves ...
> >                     slave@42 {
> >                     };
> >                 };
> >         };
> > };
> 
> I think Alan's assumption is there's always a memory mapped control
> interface and the DT hierarchy follows that. While I see you could
> have other interfaces like SPI, that would not be the control
> interface related to FPGA programming AIUI. You could also have GPIOs,
> I2C, or any other bus/interface we describe in DT in theory.
> 
> How to deal with additional connections like this is similar to
> overlays for daughterboards (e.g. capes, hats, shields) where the need
> for mapping slave devices on a connector to host controllers/buses
> which can vary. In that case, you don't want to have to create a
> different overlay for every host board just to change the parent
> devices of each child. If there is a SPI connection to FPGA (or area),
> then we need a way to map the host SPI bus to the FPGA. In this
> example, the overlay should only say "slave@42" is connected to the
> spi bus of the FPGA area and it would not have direct reference to
> "spi_ctrl@deadbeef." There's some ideas around how to support these
> usecases probably involving a connector node with mappings of
> connector i/o's to host i/o's (paging Pantelis, where's your
> proposal?). I think the same would work here, so I would suggest we
> not try to address it immediately other than decide the requirements
> here are similar enough to what is needed for connectors.
> 
> Rob
> 

Re: [PATCH v15 1/6] fpga: add bindings document for fpga area and fpga bus

[atull]

On Mon, 25 Jan 2016, Rob Herring wrote:

> On Wed, Jan 20, 2016 at 01:24:22PM -0600, atull@opensource.altera.com wrote:
> > From: Alan Tull <atull@opensource.altera.com>
> > 
> > New bindings document for FPGA Area for reprogramming
> > FPGA's under Device Tree control
> > 
> > Signed-off-by: Alan Tull <atull@opensource.altera.com>
> > ---
> > v9:  initial version added to this patchset
> > v10: s/fpga/FPGA/g
> >      replace DT overlay example with slightly more complicated example
> >      move to staging/simple-fpga-bus
> > v11: No change in this patch for v11 of the patch set
> > v12: Moved out of staging.
> >      Changed to use FPGA bridges framework instead of resets
> >      for bridges.
> > v13: bridge@0xff20000 -> bridge@ff200000, etc
> >      Leave out directly talking about overlays
> >      Remove regs and clocks directly under simple-fpga-bus in example
> >      Use common "firmware-name" binding instead of "fpga-firmware"
> > v14: Use firmware-name in bindings description
> >      Call it FPGA Area
> >      Remove bindings that specify FPGA Manager and FPGA Bridges
> > v15: Cleanup as per Rob's comments
> >      Combine usage doc with bindings document
> >      Document as being Altera specific
> >      Additions and changes to add FPGA Bus
> > ---
> >  .../bindings/fpga/altera-fpga-bus-fpga-area.txt    |  452 ++++++++++++++++++++
> >  1 file changed, 452 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/fpga/altera-fpga-bus-fpga-area.txt
> > 
> > diff --git a/Documentation/devicetree/bindings/fpga/altera-fpga-bus-fpga-area.txt b/Documentation/devicetree/bindings/fpga/altera-fpga-bus-fpga-area.txt
> > new file mode 100644
> > index 0000000..8ea38ca
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/fpga/altera-fpga-bus-fpga-area.txt
> > @@ -0,0 +1,452 @@
> > +Altera FPGA Area and FPGA Bus Device Tree Binding
> 
> Getting closer I think...

Great!

> 
> > +
> > +Alan Tull 2016
> > +
> > + CONTENTS
> > + - Introduction
> > + - Terminology
> > + - Overview
> > + - Constraints
> > + - FPGA Bus
> > + - FPGA Area
> > + - Supported Use Models
> > + - Sequence
> > + - Device Tree Examples
> > +
> > +
> > +Introduction
> > +============
> > +
> > +FPGA Buses and FPGA Areas are introduced as a way to solve the problem of how to
> > +reprogram an Altera FPGA under an operating system and have the new hardware
> > +show up in the device tree.  By adding these bindings to the Device Tree, a
> > +system can have the information needed to do the FPGA programming to add the
> > +desired hardware, and also the information about the devices to be added to the
> > +Device Tree once the programming has succeeded.
> > +
> > +
> > +Terminology
> > +===========
> > +
> > +Full Reconfiguration
> > + * The entire FPGA is programmed.
> > +
> > +Partial Reconfiguration (PR)
> > + * The FPGA is broken up into regions.  One of these regions is reprogrammed
> > +   while the rest of the FPGA is not affected.  Not all FPGA's support this.
> > +
> > +FPGA Manager & 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 & 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 may not be needed in implementations where the FPGA Manager
> > +   handles this.
> > +
> > +Freeze Blocks
> > + * Freeze Blocks function as FPGA Bridges within the FPGA fabric.  In the case
> > +   of PR, the buses from the processor are split within the FPGA.  Each PR
> > +   region gets its own split of the buses, protected by an independently
> > +   controlled Freeze Block.  Several busses may be connected to a single
> > +   PR region; a Freeze Block controls the traffic of all these busses
> > +   together.
> > +
> > +Controlling Bridge
> > + * The processor and FPGA may be connected by multiple FPGA Bridges.  In a text
> > +   based hierarchy, it is difficult to show this properly as a device would
> > +   have several parents.
> > + * The bridge that handles register access to the FPGA is designated the
> > +   "controlling" bridge.
> > + * The controlling bridge will be the target point under which the overlay is
> > +   inserted.
> > +
> > +
> > +Overview
> > +========
> > +
> > +This binding introduces the FPGA Bus and FPGA Area.
> > +
> > +An FPGA Bus is a virtualized bus that contains the devices needed to be able to
> > +program an FPGA device.  It contains a child FPGA Manager and may contain child
> > +FPGA Bridges, if needed.  The FPGA Manager is the hardware block that handles
> > +programming the FPGA.  FPGA Bridges function to prevent spurious data from the
> > +FPGA going on the processor busses during FPGA programming.  In the case of
> > +partial reconfiguration, additional bridges (Freeze Blocks) for each
> > +reconfiguration region are required.
> > +
> > +An FPGA Area contains information about a section of an FPGA (in the case of
> > +partial reconfiguration or the whole FPGA (for full reconfiguration).  The FPGA
> > +Area contains the name of the FPGA image file to be programmed and the child
> > +devices that will be contained in the FPGA after programming.
> > +
> > +The intended use is that device tree overlays can be used to add hardware to an
> > +FPGA while an operating system is running.  In that case, the FPGA Bus and its
> > +associated information will exist in the live device tree, while FPGA Areas are
> > +added to the device tree by applying device tree overlays while the operating
> > +system is running.  Loading such an overlay will cause the FPGA to be programmed
> > +and the child devices to be populated.  Removing an overlay will cause the
> > +devices to be removed from the device tree and free up those FPGA resources.
> > +
> > +
> > +Constraints
> > +===========
> > +
> > +It is beyond the scope of this document to fully describe all the FPGA design
> > +constraints required to make partial reconfiguration work[1] [2], but a few
> > +deserve quick mention.  A partial reconfiguration FPGA image must have
> > +boundary connections that line up with those the current programming of the
> > +FPGA.  Also, those during programming, those connections must be frozen.  This
> > +can be achieved by "Freeze Blocks" which are FPGA Bridges that exist on the FPGA
> > +fabric prior to the partial reconfiguration.
> > +
> > +
> > +FPGA Bus
> > +========
> > +
> > +An FPGA bus is a virtualized bus that specifies the devices needed to program an
> > +FPGA.
> > +
> > +Required properties:
> > +- compatible : should contain "altr,fpga-bus" and "simple-bus"
> > +	       "simple-bus" is required to allow populating the child nodes.
> 
> I think I said this before, but you should not need simple-bus. Having 
> it is wrong if the bus requires some configuration before enumerating 
> the child nodes. The way you have it, the bridge driver could probe 
> before the FPGA manager or vice-versa. I'm guessing one way will work 
> and the other will not, and you are getting lucky. You should also test 
> will the overlay applied before boot (i.e. single dtb with all areas 
> populated). The simple rule is does the node (containing simple-bus) 
> require configuration for child nodes to be accessed? If yes, you can't 
> use simple-bus.

Yes you did say that before.  Thanks for the explanation here, it
clarifies a lot.  I'll work on something that implements this without
relying on luck and simple-busses.

> 
> Part of your problem is you may need a custom match table. Using 
> of_default_bus_match_table will only match the immediate child nodes of 
> the starting node. Alternatively, you need to make the bridge node the 
> starting node.
> 

Not sure what you ment here, maybe you mean leaving out the fpga-bus?
I'm using fpga-bus to bring the specific manager and bridges together
needed to handle reprogramming cycles on a specific FPGA.

> > +
> > +A FPGA Bus should contain an FPGA Manager as a child node.
> > +
> > +A FPGA Bus may require FPGA Bridges as child nodes if the FPGA Manager does not
> > +control the hardware bridges.
> > +
> > +The FPGA Bridge that allows memory mapped register access is designated the
> > +"controlling" bridge.  This bridge serves as the insertion point of DT overlays.
> > +Both the FPGA Area and the controlling bridge require the "simple-bus"
> > +compatibility string to allow populating the child nodes contained in the
> > +overlay.
> > +
> > +In the example below, fpgamgr@ff706000 would be used to do any programming
> > +operations on the FPGA and the two bridges specified would be disabled
> > +during the programming and re-enabled afterwards if the programming
> > +succeeds.
> > +
> > +Example:
> > +	fpgabus@0 {
> 
> If you have a unit-address, then there should be a reg property or 
> ranges parent bus addr.
> 
> > +		compatible = "altr,fpga-bus", "simple-bus";
> > +		#address-cells = <0x1>;
> > +		#size-cells = <0x1>;
> > +		ranges;
> > +
> > +		fpgamgr@ff706000 {
> 
> As mentioned in the other thread, this may be better done as a phandle, 
> but I don't feel too strongly either way.

I can see reasons for having the fpga manager and also the bridges
specified by phandle within a fpga-bus.  So an fpga-bus will add the
following propertities:

        fpga-mgr = <fpgamgr0>;
	fpga-bridges = <bridge0>, <bridge1>;

> 
> > +			compatible = "altr,socfpga-fpga-mgr";
> > +			reg = <0xff706000 0x1000
> > +			       0xffb90000 0x1000>;
> > +			interrupts = <0 175 4>;
> > +		};
> > +
> > +		bridge@0 {
> 
> Same here. Doesn't this bridge have some associated address range.
> 
> Essentially, the hierarchy from child devices up to the root should 
> reflect the address decoding at each step.

Yes

> 
> > +			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 {
> > +			compatible = "altr,socfpga-hps2fpga-bridge";
> > +			resets = <&rst HPS2FPGA_RESET>;
> > +			reset-names = "hps2fpga";
> > +			clocks = <&l4_main_clk>;
> > +		};
> > +	};
> > +
> > +FPGA Area
> > +=========
> > +
> > +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.
> > +
> > +An FPGA Area corresponds to the whole FPGA in the case of full reconfiguration
> > +or a section of an FPGA in the case of partial reconfiguration.
> > +
> > +Required properties:
> > +- compatible : should contain "altr,fpga-area"
> > +- #address-cells, #size-cells, ranges: must be present to handle address space
> > +  mapping for children.
> > +
> > +Optional properties:
> > +- firmware-name : should contain the name of an FPGA image file located on the
> > +  firmware search path.
> > +- partial-reconfig : boolean property should be defined if partial
> > +  reconfiguration of the FPGA is to be done, otherwise full reconfiguration
> > +  is done.
> > +
> > +In the example below, the target path is the controlling bridge of the FPGA Bus
> > +example.  The FPGA would be programmed with the image contained in the
> > +"soc_system.rbf" specified.  Assuming programming succeeds, the child devices
> > +would be populated afterwords.  In this particular example, ranges has two
> > +chip selects as one memory region is tied to the host processor and the
> > +other is a memory region on the FPGA.
> > +
> > +If there are no bridges in the FPGA Bus, the target path would point to
> > +the FPGA Manager.
> 
> How do you not have a bridge? There has to be something preventing 
> access. Do you really mean the bridge and fpga-mgr blocks are combined 
> into 1?

In the Xilinx case, the manager and bridge are still two hardware
blocks but handled together by the manager driver.  I didn't want to
make Moritz write a FPGA Bridge when he already had code that handled
his hardware bridges when he told his manager to do a write cycle.

> 
> > +
> > +Example:
> > +
> > +/dts-v1/;
> > +/plugin/;
> > +/ {
> > +	fragment@0 {
> > +		target-path="/soc/fpgamgr@ff706000/bridge@0";
> > +		__overlay__ {
> > +			#address-cells = <1>;
> > +		        #size-cells = <1>;
> > +
> > +			bridge@ff200000 {
> 
> Wouldn't this be area@...? area is a bit too generic. I'd use 
> "fpga-area" for the node name too.

This could be called fpga-area or fpga-region.  More on that below.

> 
> > +				compatible = "fpga-area";
> > +
> > +				#address-cells = <2>;
> > +				#size-cells = <1>;
> > +
> > +				ranges = <0 0x00000000 0xc0000000 0x00010000>,
> > +					 <1 0x00020000 0xff220000 0x00000008>,
> > +					 <1 0x00010040 0xff210040 0x00000020>;
> > +
> > +				firmware-name = "soc_system.rbf";
> > +
> > +				onchip_memory2_0: memory@0 {
> > +					device_type = "memory";
> > +					compatible = "altr,onchipmem-15.1";
> > +					reg = <0 0x00000000 0x00010000>;
> > +				};
> > +
> > +				jtag_uart: serial@100020000 {
> > +					compatible = "altr,juart-1.0";
> > +					reg = <1 0x00020000 0x00000008>;
> > +					interrupt-parent = <&intc>;
> > +					interrupts = <0 42 4>;
> > +				};
> > +
> > +				led_pio: gpio@100010040 {
> > +					compatible = "altr,pio-1.0";
> > +					reg = <1 0x00010040 0x00000020>;
> > +					altr,gpio-bank-width = <4>;
> > +					#gpio-cells = <2>;
> > +					gpio-controller;
> > +				};
> > +			};
> > +		};
> > +	};
> > +};
> > +
> > +Supported Use Models
> > +====================
> > +
> > +Here's a list of supported use models.  We may need to add more.  Some uses are
> > +specific to one FPGA device or another.
> > +
> > + * No FPGA Bridges
> > +   In this case, the FPGA Manager which programs the FPGA also handles the
> > +   bridges.  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 live DT before the
> > +   overlay is applied will have an FPGA Bus.
> > +
> > +   The DT overlay will specify the controlling bridge as the overlay target.
> > +
> > + * Partial reconfiguration with bridges in the FPGA
> > +   In this case, the FPGA will have more than one section that will be
> > +   programmed separately.  Other sections may be active on the bus while FPGA
> > +   is being programmed.  To manage this, Freeze blocks 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.
> > +
> > +Sequence
> > +========
> > +
> > +When a DT overlay is loaded, the FPGA Area will 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.
> > +
> > +When the overlay is removed, the FPGA Area in it is removed.  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, especially:
> > + * FPGA Bus and associated FPGA Manager and FPGA Bridges
> > + * FPGA Area and associated properties
> > + * simple-bus
> > + * ranges
> > + * target-path
> > +
> > +For the purposes of this section, I'm dividing the Device Tree into two parts,
> > +each with its own requirements.  The two parts are:
> > + * The live DT prior to the overlay being added
> > + * The DT overlay
> > +
> > +The live Device Tree must contain an FPGA Bus, which has a child 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 Bus.  During full reconfiguration, the
> > +FPGA Area will disable any bridges that are direct children of the FPGA Bus and
> > +will re-enable them after FPGA programming has succeeded.
> > +
> > +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.
> > +
> > +
> > +Device Tree Example: Partial Reconfiguration with no Bridges
> > +============================================================
> > +
> > +Live Device Tree contains:
> > +	fpgamgr@ffd03000 {
> > +		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@ffd03000";  /* targeted to the manager */
> > +		__overlay__ {
> > +			#address-cells = <1>;
> > +		        #size-cells = <1>;
> > +
> > +			area@0 {
> 
> Are the number of areas software configurable? If not, then the areas 
> should be part of the base DT rather than the overlay.

The number of areas is set by the FPGA image that creates the areas.
A base FPGA image could be loaded by the bootloader or by the OS with
a set number of area slots available.

So this could be done differently, divided into something where the
areas (some call them "regions") are created in the live DT when the
base FPGA image is loaded.  Then the overlays would have something
called 'personas' that plug into them.  The areas would contain the
information of which bridges to control and which fpga manager.  Maybe
this heirarchy (indexes are probably screwed up below).

Below, the fpga manager and hardware fpga bridges are specified
outside the fpga bus and are referred to by phandles.  Leaving out
ranges, cells for brevity.

Live tree (after base FPGA image is loaded):
fpga-bus@0 {
	compatible = "fpga-bus";
	fpga-mgr = <fpgamgr@something>;
	fpga-bridges = <..>, <..>;

	fpga-area@0 { 
		compatible = "fpga-area";
		bridges = <bridge@>;
	};

	fpga-area@... { 
		compatible = "fpga-area";
		bridges = <bridge@...>;
	};
};		

The overlay would target one of the fpga-area's and contain
the firmware-name and children.

In the case of full reconfiguration, there would not be any
fpga-areas.  The overlay would target the fpga-bus.

> 
> > +				compatible = "fpga-area";
> > +
> > +				#address-cells = <1>;
> > +				#size-cells = <1>;
> > +				ranges = <0x10010 0xff210010 0x10>;
> > +
> > +				firmware-name = "fit_pr_v1.rbf";
> > +				partial-reconfig;
> > +
> > +				gpio@100010010 {
> 
> gpio@10010

OK

> 
> > +					compatible = "altr,pio-1.0";
> > +					reg = <0x10010 0x10>;
> > +					altr,ngpio = <4>;
> > +					#gpio-cells = <0x2>;
> > +					gpio-controller;
> > +				};
> > +			};
> > +		};
> > +	};
> > +};
> 

Re: [PATCH v15 1/6] fpga: add bindings document for fpga area and fpga bus

[Moritz Fischer]

Hi,

On Wed, Jan 27, 2016 at 9:24 PM, atull <atull@opensource.altera.com> wrote:

>> I think I said this before, but you should not need simple-bus. Having
>> it is wrong if the bus requires some configuration before enumerating
>> the child nodes. The way you have it, the bridge driver could probe
>> before the FPGA manager or vice-versa. I'm guessing one way will work
>> and the other will not, and you are getting lucky. You should also test
>> will the overlay applied before boot (i.e. single dtb with all areas
>> populated). The simple rule is does the node (containing simple-bus)
>> require configuration for child nodes to be accessed? If yes, you can't
>> use simple-bus.
>
> Yes you did say that before.  Thanks for the explanation here, it
> clarifies a lot.  I'll work on something that implements this without
> relying on luck and simple-busses.
>
>>
>> Part of your problem is you may need a custom match table. Using
>> of_default_bus_match_table will only match the immediate child nodes of
>> the starting node. Alternatively, you need to make the bridge node the
>> starting node.
>>
>
> Not sure what you ment here, maybe you mean leaving out the fpga-bus?
> I'm using fpga-bus to bring the specific manager and bridges together
> needed to handle reprogramming cycles on a specific FPGA.

While I see the grouping argument I don't see binding wise why the manager
needs to move into the bus. If each area specifies the bridges by handle,
would that make more sense?

> I can see reasons for having the fpga manager and also the bridges
> specified by phandle within a fpga-bus.  So an fpga-bus will add the
> following propertities:
>
>         fpga-mgr = <fpgamgr0>;
>         fpga-bridges = <bridge0>, <bridge1>;
>
>>
>> > +                   compatible = "altr,socfpga-fpga-mgr";
>> > +                   reg = <0xff706000 0x1000
>> > +                          0xffb90000 0x1000>;
>> > +                   interrupts = <0 175 4>;
>> > +           };
>> > +
>> > +           bridge@0 {
>>
>> Same here. Doesn't this bridge have some associated address range.
>>
>> Essentially, the hierarchy from child devices up to the root should
>> reflect the address decoding at each step.
>
> Yes
>
>>
>> > +                   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 {
>> > +                   compatible = "altr,socfpga-hps2fpga-bridge";
>> > +                   resets = <&rst HPS2FPGA_RESET>;
>> > +                   reset-names = "hps2fpga";
>> > +                   clocks = <&l4_main_clk>;
>> > +           };
>> > +   };
>> > +

>> How do you not have a bridge? There has to be something preventing
>> access. Do you really mean the bridge and fpga-mgr blocks are combined
>> into 1?
>
> In the Xilinx case, the manager and bridge are still two hardware
> blocks but handled together by the manager driver.  I didn't want to
> make Moritz write a FPGA Bridge when he already had code that handled
> his hardware bridges when he told his manager to do a write cycle.

If we all feel that as a good abstraction bridges are necessary, I can add that.
They're basically level shifters that you turn on and off, there's nothing smart
beyond that. If you disable the bridge and try to access stuff it just
doesn't work.

> This could be called fpga-area or fpga-region.  More on that below.


>> Are the number of areas software configurable? If not, then the areas
>> should be part of the base DT rather than the overlay.
>
> The number of areas is set by the FPGA image that creates the areas.
> A base FPGA image could be loaded by the bootloader or by the OS with
> a set number of area slots available.

Not a big fan of this idea. See below. Somehow the info needs. That
seems like an unnatural abstraction for an FPGA. See below:
>
> So this could be done differently, divided into something where the
> areas (some call them "regions") are created in the live DT when the
> base FPGA image is loaded.  Then the overlays would have something
> called 'personas' that plug into them.  The areas would contain the
> information of which bridges to control and which fpga manager.  Maybe
> this heirarchy (indexes are probably screwed up below).
>
> Below, the fpga manager and hardware fpga bridges are specified
> outside the fpga bus and are referred to by phandles.  Leaving out
> ranges, cells for brevity.
>
> Live tree (after base FPGA image is loaded):
> fpga-bus@0 {
>         compatible = "fpga-bus";
>         fpga-mgr = <fpgamgr@something>;
>         fpga-bridges = <..>, <..>;
>
>         fpga-area@0 {
>                 compatible = "fpga-area";
>                 bridges = <bridge@>;
>         };
>
>         fpga-area@... {
>                 compatible = "fpga-area";
>                 bridges = <bridge@...>;
>         };
> };

Where would we get this info from, though? There would have to be a
first overlay to update the live tree, I suppose. Or anything that updates
the live tree based on the non-inspectable bitstream / firmware.

How would the above make the connection between the address hierarchy
i.e. fpga-area and bus the FPGA logic is child of. In the same image
one area could be
connected via ... GMII and MDIO while another one is connected via AXI4 (mmio),
SPI or I2C.

I checked on socfpga you can also (as well as zynq) implement the e.g.
sgmii part
of a gigabit ethernet connection to an sfp connector in the FPGA.
In that case the address hierarchy would be (in my opinion) an
fpga-area as a child node of
your gigabit mac containing the phy.

Tell me if I'm crazy. Communication is hard :) Maybe I'm trying to
solve, too many
issues at the same time. And we should tackle this separately using
some sort of connector
mapping as Rob suggested in one of the last mails.

> The overlay would target one of the fpga-area's and contain
> the firmware-name and children.
>
> In the case of full reconfiguration, there would not be any
> fpga-areas.  The overlay would target the fpga-bus.

Or a single area for consistency reasons? Full reconfiguration is just
a special case of partial reconfiguration,
right?

Cheers,

Moritz