@@ -11,61 +11,66 @@ hidden away in a low level driver which registers a set of ops with the core.
The FPGA image data itself is very manufacturer specific, but for our purposes
it's just binary data. The FPGA manager core won't parse it.
+The FPGA image to be programmed can be in a scatter gather list, a single
+contiguous buffer, or a firmware file. Because allocating contiguous kernel
+memory for the buffer should be avoided, users are encouraged to use a scatter
+gather list instead if possible.
+
+The particulars for programming the image are presented in a structure (struct
+fpga_image_info). This struct contains parameters such as pointers to the
+FPGA image as well as image-specific particulars such as whether the image was
+built for full or partial reconfiguration.
API Functions:
==============
-To program the FPGA from a file or from a buffer:
--------------------------------------------------
-
- int fpga_mgr_buf_load(struct fpga_manager *mgr,
- struct fpga_image_info *info,
- const char *buf, size_t count);
-
-Load the FPGA from an image which exists as a contiguous buffer in
-memory. Allocating contiguous kernel memory for the buffer should be avoided,
-users are encouraged to use the _sg interface instead of this.
-
- int fpga_mgr_buf_load_sg(struct fpga_manager *mgr,
- struct fpga_image_info *info,
- struct sg_table *sgt);
+To program the FPGA:
+--------------------
-Load the FPGA from an image from non-contiguous in memory. Callers can
-construct a sg_table using alloc_page backed memory.
+ int fpga_mgr_load(struct fpga_manager *mgr,
+ struct fpga_image_info *info);
- int fpga_mgr_firmware_load(struct fpga_manager *mgr,
- struct fpga_image_info *info,
- const char *image_name);
-
-Load the FPGA from an image which exists as a file. The image file must be on
-the firmware search path (see the firmware class documentation). If successful,
+Load the FPGA from an image which is indicated in the info. If successful,
the FPGA ends up in operating mode. Return 0 on success or a negative error
code.
-A FPGA design contained in a FPGA image file will likely have particulars that
-affect how the image is programmed to the FPGA. These are contained in struct
-fpga_image_info. Currently the only such particular is a single flag bit
-indicating whether the image is for full or partial reconfiguration.
+To allocate or free a struct fpga_image_info:
+---------------------------------------------
+
+ struct fpga_image_info *fpga_image_info_alloc(struct device *dev);
+
+ void fpga_image_info_free(struct device *dev,
+ struct fpga_image_info *info);
To get/put a reference to a FPGA manager:
-----------------------------------------
struct fpga_manager *of_fpga_mgr_get(struct device_node *node);
struct fpga_manager *fpga_mgr_get(struct device *dev);
+ void fpga_mgr_put(struct fpga_manager *mgr);
-Given a DT node or device, get an exclusive reference to a FPGA manager.
+Given a DT node or device, get a reference to a FPGA manager. This pointer
+can be saved until you are ready to program the FPGA. fpga_mgr_put
+releases the reference.
- void fpga_mgr_put(struct fpga_manager *mgr);
-Release the reference.
+To get exclusive control of a FPGA manager:
+-------------------------------------------
+
+ int fpga_mgr_lock(struct fpga_magager *mgr);
+ void fpga_mgr_unlock(struct fpga_magager *mgr);
+
+The user should call fpga_mgr_lock and verify that it returns 0 before
+attempting to program the FPGA. Likeqise, the user should call
+fpga_mgr_unlock when done programming the FPGA.
To register or unregister the low level FPGA-specific driver:
-------------------------------------------------------------
int fpga_mgr_register(struct device *dev, const char *name,
- const struct fpga_manager_ops *mops,
- void *priv);
+ const struct fpga_manager_ops *mops,
+ void *priv);
void fpga_mgr_unregister(struct device *dev);
@@ -78,59 +83,61 @@ How to write an image buffer to a supported FPGA
/* Include to get the API */
#include <linux/fpga/fpga-mgr.h>
-/* device node that specifies the FPGA manager to use */
-struct device_node *mgr_node = ...
+struct fpga_manager *mgr;
+struct fpga_image_info *info;
+int ret;
-/* FPGA image is in this buffer. count is size of the buffer. */
-char *buf = ...
-int count = ...
+/*
+ * Get a reference to FPGA manager. This example uses the device node of the
+ * manager. You could use fpga_mgr_get() instead if you have the device instead
+ * of the device node.
+ */
+mgr = of_fpga_mgr_get(mgr_node);
/* struct with information about the FPGA image to program. */
-struct fpga_image_info info;
+info = fpga_image_info_alloc(dev);
/* flags indicates whether to do full or partial reconfiguration */
-info.flags = 0;
+info->flags = FPGA_MGR_PARTIAL_RECONFIG;
-int ret;
+/*
+ * At this point, indicate where the image is. This is pseudo-code; you're
+ * probably going to use one of these three.
+ */
+if (using scatter gather) {
-/* Get exclusive control of FPGA manager */
-struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node);
+ info->sgt = [your scatter gather table]
-/* Load the buffer to the FPGA */
-ret = fpga_mgr_buf_load(mgr, &info, buf, count);
-
-/* Release the FPGA manager */
-fpga_mgr_put(mgr);
+} else if (using a buffer) {
+ info->buf = [your image buffer]
+ info->count = [image buffer size]
-How to write an image file to a supported FPGA
-==============================================
-/* Include to get the API */
-#include <linux/fpga/fpga-mgr.h>
-
-/* device node that specifies the FPGA manager to use */
-struct device_node *mgr_node = ...
+} else if (using a firmware file) {
-/* FPGA image is in this file which is in the firmware search path */
-const char *path = "fpga-image-9.rbf"
+ info->firmware_name = devm_kstrdup(dev, firmware_name, GFP_KERNEL);
-/* struct with information about the FPGA image to program. */
-struct fpga_image_info info;
+} else {
-/* flags indicates whether to do full or partial reconfiguration */
-info.flags = 0;
+ not implemented!
-int ret;
+}
/* Get exclusive control of FPGA manager */
-struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node);
+ret = fpga_mgr_lock(mgr);
-/* Get the firmware image (path) and load it to the FPGA */
-ret = fpga_mgr_firmware_load(mgr, &info, path);
+/* Load the buffer to the FPGA */
+ret = fpga_mgr_buf_load(mgr, &info, buf, count);
/* Release the FPGA manager */
+fpga_mgr_unlock(mgr);
fpga_mgr_put(mgr);
+/* Free your image storage in some appropriate way */
+...
+
+/* Deallocate the image info if you're done with it */
+fpga_image_info_free(dev, info);
How to support a new FPGA device
================================
new file mode 100644
@@ -0,0 +1,54 @@
+FPGA Regions
+
+Alan Tull 2017
+
+An fpga-region represents a reconfigurable region of a FPGA. It could be the
+whole FPGA in the case of full reconfiguration or a partial reconfiguration area.
+
+An fpga-region will know which FPGA manager to use to do the programming as well
+as which bridges are involved. The bridges exist to prevent junk data from
+going out onto processor busses or out onto FPGA pins during programming. There
+are currently a lot of variations of how these can be implemented. Some
+implementations will include the bridge in the manager. The FPGA manager may be
+fixed hardware in some cases, while other implemenatations have managers as part
+of the static region of the FPGA to handle partial reconfiguration. Some
+bridges are fixed hardware while other bridges exist in the FPGA fabric as a
+ring surrounding the FPGA reconfiguration areas.
+
+This document is meant to be an overview of API usage. A more conceptual look
+at regions can be found in [1].
+
+===================
+The FPGA region API
+===================
+
+To register or unregister a region:
+-----------------------------------
+
+ int fpga_region_register(struct device *dev,
+ struct fpga_region *region);
+ int fpga_region_unregister(struct fpga_region *region);
+
+An example of usage can be seen in the probe function of [2]
+
+To program an FPGA:
+-------------------
+
+ int fpga_region_program_fpga(struct fpga_region *region,
+ struct fpga_image_info *image_info);
+
+image_info is described in [3]
+
+This function will attempt to:
+ * lock the region's mutex
+ * lock the region's FPGA manager
+ * build a list of FPGA bridges if a method has been specified to do so
+ * disable the bridges
+ * program the FPGA
+ * re-enable the bridges
+ * release the locks
+
+--
+[1] ../devicetree/bindings/fpga/fpga-region.txt
+[2] ../../drivers/fpga/of-fpga-region.c
+[3] ./fpga-mgr.txt
new file mode 100644
@@ -0,0 +1,23 @@
+Linux kernel FPGA support
+
+Alan Tull 2017
+
+The main point of this project has been to separate the out the upper layers
+that know when to reprogram a FPGA from the lower layers that know how to
+reprogram a specific FPGA device. The intention is to make this manufacturor
+agnostic, understanding that of course the FPGA images are very device specific
+themselves.
+
+At this point it time, the framework in the kernel includes:
+* low level FPGA manager drivers that know how to program a specific device
+* the fpga-mgr framework they are registered with
+* low level FPGA bridge drivers for hard/soft bridges which are intended to
+ be disable during FPGA programming
+* the fpga-bridge framework they are registered with
+* the fpga-region framework which associates and controls managers and bridges
+ as reconfigurable regions
+* the of-fpga-region support for reprogramming FPGAs when device tree overlays
+ are applied.
+
+I would encourage you the user to add code that creates fpga regions rather
+that trying to control managers and bridges separately.
The FPGA manager has been simplified to have a single fpga_mgr_load function which replaces the three fpga_mgr_*load* functions. The parameters presenting the FPGA image have been added to struct fpga_image_info. Additional functions have been added to alloc/free fpga_image_info. Getting a FPGA manager has been separated from locking it. So an unlocked reference can be saved and only locked when we're about to program. A document for fpga-region has been added as well. Signed-off-by: Alan Tull <atull@kernel.org> --- v1: fixed some nits v2: expanded to include other FPGA API changes besides locking --- Documentation/fpga/fpga-mgr.txt | 133 +++++++++++++++++++------------------ Documentation/fpga/fpga-region.txt | 54 +++++++++++++++ Documentation/fpga/overview.txt | 23 +++++++ 3 files changed, 147 insertions(+), 63 deletions(-) create mode 100644 Documentation/fpga/fpga-region.txt create mode 100644 Documentation/fpga/overview.txt