[PATCH v9 2/7] staging: usage documentation for simple fpga bus

atull
2015-07-17T15:51:12Z

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

Add a document spelling out usage of the simple fpga bus.

Signed-off-by: Alan Tull <atull@opensource.altera.com>
---
.../staging/fpga/Documentation/simple-fpga-bus.txt | 48 ++++++++++++++++++++
1 file changed, 48 insertions(+)
create mode 100644 drivers/staging/fpga/Documentation/simple-fpga-bus.txt

diff --git a/drivers/staging/fpga/Documentation/simple-fpga-bus.txt b/drivers/staging/fpga/Documentation/simple-fpga-bus.txt
new file mode 100644
index 0000000..9df519f
--- /dev/null
+++ b/drivers/staging/fpga/Documentation/simple-fpga-bus.txt
@@ -0,0 +1,48 @@
+ Simple FPGA Bus
+
+ Alan Tull 2015
+
+ Overview
+ --------
+The simple FPGA bus adds device tree overlay support for FPGA's. Loading a
+DT overlay will result in the FGPA getting an image loaded, its bridges will
+be released, and the DT populated for nodes below the simple-fpga-bus. This
+results in drivers getting probed for the hardware that just got added. This
+is intended to support the FPGA usage where the FPGA has hardware that
+requires drivers. Removing the overlay will result in the drivers getting
+removed and the bridges being disabled.
+
+
+ Requirements
+ ------------
+ 1. An FPGA image that has a hardware block or blocks that use drivers that are
+ supported in the kernel.
+ 2. A device tree overlay.
+ 3. A FPGA manager driver supporting writing the FPGA.
+ 4. FPGA bridge resets supported as reset controllers.
+
+The DT overlay includes bindings (documented in bindings/simple-fpga-bus.txt)
+that specify:
+ * Which fpga manager to use
+ * Which image file to load
+ * Flags indicating whether this this image is for full reconfiguration or
+ partial.
+ * a list of resets that should be released. These enable the FPGA bridges.
+ * child nodes specifying the devices that will be added with appropriate
+ compatible strings, etc.
+
+Since this code uses the firmware interface to get the image and DT overlay,
+they currently have to be files on the filesystem. It doesn't have to be that
+way forever as DT bindings could be added to point to other sources for the
+image.
+
+
+ Sequence
+ --------
+ 1. Load the DT overlay. One convenient way to do that is to use Pantelis'
+ handy configfs interface (more below).
+ 2. The simple FPGA bus gets probed and will do the following:
+ a. call the fpga manager core to program the FPGA
+ b. release the FPGA bridges
+ c. call of_platform_populate resulting in device drivers getting probed.
+
--
1.7.9.5