Documentation/fpga/fpga-mgr.txt

   1 FPGA Manager Core
   2
   3 Alan Tull 2015
   4
   5 Overview
   6 ========
   7
   8 The FPGA manager core exports a set of functions for programming an FPGA with
   9 an image.  The API is manufacturer agnostic.  All manufacturer specifics are
  10 hidden away in a low level driver which registers a set of ops with the core.
  11 The FPGA image data itself is very manufacturer specific, but for our purposes
  12 it's just binary data.  The FPGA manager core won't parse it.
  13
  14
  15 API Functions:
  16 ==============
  17
  18 To program the FPGA from a file or from a buffer:
  19 -------------------------------------------------
  20
  21         int fpga_mgr_buf_load(struct fpga_manager *mgr, u32 flags,
  22                               const char *buf, size_t count);
  23
  24 Load the FPGA from an image which exists as a buffer in memory.
  25
  26         int fpga_mgr_firmware_load(struct fpga_manager *mgr, u32 flags,
  27                                    const char *image_name);
  28
  29 Load the FPGA from an image which exists as a file.  The image file must be on
  30 the firmware search path (see the firmware class documentation).
  31
  32 For both these functions, flags == 0 for normal full reconfiguration or
  33 FPGA_MGR_PARTIAL_RECONFIG for partial reconfiguration.  If successful, the FPGA
  34 ends up in operating mode.  Return 0 on success or a negative error code.
  35
  36
  37 To get/put a reference to a FPGA manager:
  38 -----------------------------------------
  39
  40         struct fpga_manager *of_fpga_mgr_get(struct device_node *node);
  41
  42         void fpga_mgr_put(struct fpga_manager *mgr);
  43
  44 Given a DT node, get an exclusive reference to a FPGA manager or release
  45 the reference.
  46
  47
  48 To register or unregister the low level FPGA-specific driver:
  49 -------------------------------------------------------------
  50
  51         int fpga_mgr_register(struct device *dev, const char *name,
  52                               const struct fpga_manager_ops *mops,
  53                               void *priv);
  54
  55         void fpga_mgr_unregister(struct device *dev);
  56
  57 Use of these two functions is described below in "How To Support a new FPGA
  58 device."
  59
  60
  61 How to write an image buffer to a supported FPGA
  62 ================================================
  63 /* Include to get the API */
  64 #include <linux/fpga/fpga-mgr.h>
  65
  66 /* device node that specifies the FPGA manager to use */
  67 struct device_node *mgr_node = ...
  68
  69 /* FPGA image is in this buffer.  count is size of the buffer. */
  70 char *buf = ...
  71 int count = ...
  72
  73 /* flags indicates whether to do full or partial reconfiguration */
  74 int flags = 0;
  75
  76 int ret;
  77
  78 /* Get exclusive control of FPGA manager */
  79 struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node);
  80
  81 /* Load the buffer to the FPGA */
  82 ret = fpga_mgr_buf_load(mgr, flags, buf, count);
  83
  84 /* Release the FPGA manager */
  85 fpga_mgr_put(mgr);
  86
  87
  88 How to write an image file to a supported FPGA
  89 ==============================================
  90 /* Include to get the API */
  91 #include <linux/fpga/fpga-mgr.h>
  92
  93 /* device node that specifies the FPGA manager to use */
  94 struct device_node *mgr_node = ...
  95
  96 /* FPGA image is in this file which is in the firmware search path */
  97 const char *path = "fpga-image-9.rbf"
  98
  99 /* flags indicates whether to do full or partial reconfiguration */
 100 int flags = 0;
 101
 102 int ret;
 103
 104 /* Get exclusive control of FPGA manager */
 105 struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node);
 106
 107 /* Get the firmware image (path) and load it to the FPGA */
 108 ret = fpga_mgr_firmware_load(mgr, flags, path);
 109
 110 /* Release the FPGA manager */
 111 fpga_mgr_put(mgr);
 112
 113
 114 How to support a new FPGA device
 115 ================================
 116 To add another FPGA manager, write a driver that implements a set of ops.  The
 117 probe function calls fpga_mgr_register(), such as:
 118
 119 static const struct fpga_manager_ops socfpga_fpga_ops = {
 120        .write_init = socfpga_fpga_ops_configure_init,
 121        .write = socfpga_fpga_ops_configure_write,
 122        .write_complete = socfpga_fpga_ops_configure_complete,
 123        .state = socfpga_fpga_ops_state,
 124 };
 125
 126 static int socfpga_fpga_probe(struct platform_device *pdev)
 127 {
 128         struct device *dev = &pdev->dev;
 129         struct socfpga_fpga_priv *priv;
 130         int ret;
 131
 132         priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);
 133         if (!priv)
 134                 return -ENOMEM;
 135
 136         /* ... do ioremaps, get interrupts, etc. and save
 137            them in priv... */
 138
 139         return fpga_mgr_register(dev, "Altera SOCFPGA FPGA Manager",
 140                                  &socfpga_fpga_ops, priv);
 141 }
 142
 143 static int socfpga_fpga_remove(struct platform_device *pdev)
 144 {
 145         fpga_mgr_unregister(&pdev->dev);
 146
 147         return 0;
 148 }
 149
 150
 151 The ops will implement whatever device specific register writes are needed to
 152 do the programming sequence for this particular FPGA.  These ops return 0 for
 153 success or negative error codes otherwise.
 154
 155 The programming sequence is:
 156  1. .write_init
 157  2. .write (may be called once or multiple times)
 158  3. .write_complete
 159
 160 The .write_init function will prepare the FPGA to receive the image data.
 161
 162 The .write function writes a buffer to the FPGA. The buffer may be contain the
 163 whole FPGA image or may be a smaller chunk of an FPGA image.  In the latter
 164 case, this function is called multiple times for successive chunks.
 165
 166 The .write_complete function is called after all the image has been written
 167 to put the FPGA into operating mode.
 168
 169 The ops include a .state function which will read the hardware FPGA manager and
 170 return a code of type enum fpga_mgr_states.  It doesn't result in a change in
 171 hardware state.