Date:	Fri, 17 Jul 2015 10:51:11 -0500
From:	<atull@...nsource.altera.com>
To:	<gregkh@...uxfoundation.org>, <jgunthorpe@...idianresearch.com>,
	<hpa@...or.com>, <monstr@...str.eu>, <michal.simek@...inx.com>,
	<rdunlap@...radead.org>
CC:	<linux-kernel@...r.kernel.org>, <devicetree@...r.kernel.org>,
	<pantelis.antoniou@...sulko.com>, <robh+dt@...nel.org>,
	<grant.likely@...aro.org>, <iws@...o.caltech.edu>,
	<linux-doc@...r.kernel.org>, <pavel@...x.de>, <broonie@...nel.org>,
	<philip@...ister.org>, <rubini@...dd.com>,
	<s.trumtrar@...gutronix.de>, <jason@...edaemon.net>,
	<kyle.teske@...com>, <nico@...aro.org>, <balbi@...com>,
	<m.chehab@...sung.com>, <davidb@...eaurora.org>, <rob@...dley.net>,
	<davem@...emloft.net>, <cesarb@...arb.net>,
	<sameo@...ux.intel.com>, <akpm@...ux-foundation.org>,
	<linus.walleij@...aro.org>, <pawel.moll@....com>,
	<mark.rutland@....com>, <ijc+devicetree@...lion.org.uk>,
	<galak@...eaurora.org>, <devel@...verdev.osuosl.org>,
	Petr Cvek <petr.cvek@....cz>, <delicious.quinoa@...il.com>,
	<dinguyen@...nsource.altera.com>, <yvanderv@...nsource.altera.com>,
	Alan Tull <atull@...nsource.altera.com>
Subject: [PATCH v9 1/7] staging: usage documentation for FPGA manager core

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

Add a document on the new FPGA manager core.

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

diff --git a/drivers/staging/fpga/Documentation/fpga-mgr.txt b/drivers/staging/fpga/Documentation/fpga-mgr.txt
new file mode 100644
index 0000000..b5b6ed4
--- /dev/null
+++ b/drivers/staging/fpga/Documentation/fpga-mgr.txt
@@ -0,0 +1,117 @@
+  FPGA Manager Core
+
+  Alan Tull 2015
+
+  Overview
+  --------
+The FPGA manager core exports a set of functions for programming an image to a
+FPGA.  All manufacturor specifics are hidden away in a low level driver.  The
+API is manufacturor agnostic.  Of course the FPGA image data itself is very
+manufacturor specific but for our purposes it's just data in a buffer or file
+or something.  The FPGA manager core won't parse it or know anything about it.
+
+
+  Files
+  -----
+drivers/staging/fpga/fpga-mgr.c
+include/linux/fpga/fpga-mgr.h
+
+
+  The API Functions
+  ----------------
+The API that is exported is currently 6 functions:
+
+   int fpga_mgr_buf_load(struct fpga_manager *mgr,
+                         u32 flags,
+                         const char *buf,
+                         size_t count);
+
+An FPGA image exists as a buffer in memory.  Load it into the FPGA.  The FPGA
+ends up in operating mode or return a negative error code.
+
+   int fpga_mgr_firmware_load(struct fpga_manager *mgr,
+                              u32 flags,
+                              const char *image_name);
+
+An FPGA image exists as a file that is on the firmware search path (see the
+firmware class documentation).  Load as above.
+
+   struct fpga_manager *of_fpga_mgr_get(struct device_node *node);
+
+Given a DT node, get a reference to a fpga manager.
+
+   void fpga_mgr_put(struct fpga_manager *mgr);
+
+Release the reference to the fpga manager.
+
+   int fpga_mgr_register(struct device *dev,
+                         const char *name,
+                         const struct fpga_manager_ops *mops,
+                         void *priv);
+   void fpga_mgr_unregister(struct device *dev);
+
+Register/unregister the lower level device specific driver.
+
+
+  How To Write an Image Buffer to a supported FPGA
+  ------------------------------------------------
+/* device node that specifies the fpga manager to use */
+struct device_node *mgr_node;
+
+/* FPGA image is in this buffer.  count is size of buf. */
+char *buf;
+int count;
+int ret;
+
+struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node);
+ret = fpga_mgr_buf_load(mgr, flags, buf, count);
+fpga_mgr_put(mgr);
+
+
+  How To Write an Image File to a supported FPGA
+  ------------------------------------------------
+/* device node that specifies the fpga manager to use */
+struct device_node *mgr_node;
+
+/* FPGA image is in this buffer.  count is size of buf. */
+const char *path = "fpga-image-9.rbf"
+int ret;
+
+struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node);
+ret = fpga_mgr_firmware_load(mgr, flags, path);
+fpga_mgr_put(mgr);
+
+
+  How To Support a new FPGA device
+  --------------------------------
+To add another fpga manager, look at the bottom part of socfpga.c for an
+example, starting with the declaration of socfpga_fpga_ops.
+
+static const struct fpga_manager_ops socfpga_fpga_ops = {
+       .write_init = socfpga_fpga_ops_configure_init,
+       .write = socfpga_fpga_ops_configure_write,
+       .write_complete = socfpga_fpga_ops_configure_complete,
+       .state = socfpga_fpga_ops_state,
+};
+
+You will want to create a platform driver that has a set of ops like that
+and then register it with fpga_mgr_register in your probe function.  Your
+ops will implement whatever device specific register writes needed and
+will return negative error codes if things don't go well.
+
+The programming seqence is:
+ 1. .write_init
+ 2. .write (may be called once or multiple times)
+ 3. .write_complete
+
+The .write_init function will prepare the FPGA to receive the image data.
+
+The .write function receives an image buffer or a chunk of the image and
+writes it the FPGA.  The buffer may arrive as one chunk or a bunck of
+small chunks through this function being called multiple times.
+
+The .write_complete function is called after all the image has been written
+to put the FPGA into operating mode.
+
+The .state function will read your hardware and return a code of type
+"enum fpga_mgr_states".  It doesn't result in a change in hardware state.
-- 
1.7.9.5

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

Powered by blists - more mailing lists