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,
  22                               struct fpga_image_info *info,
  23                               const char *buf, size_t count);
  24
  25 Load the FPGA from an image which exists as a contiguous buffer in
  26 memory. Allocating contiguous kernel memory for the buffer should be avoided,
  27 users are encouraged to use the _sg interface instead of this.
  28
  29         int fpga_mgr_buf_load_sg(struct fpga_manager *mgr,
  30                                  struct fpga_image_info *info,
  31                                  struct sg_table *sgt);
  32
  33 Load the FPGA from an image from non-contiguous in memory. Callers can
  34 construct a sg_table using alloc_page backed memory.
  35
  36         int fpga_mgr_firmware_load(struct fpga_manager *mgr,
  37                                    struct fpga_image_info *info,
  38                                    const char *image_name);
  39
  40 Load the FPGA from an image which exists as a file.  The image file must be on
  41 the firmware search path (see the firmware class documentation).  If successful,
  42 the FPGA ends up in operating mode.  Return 0 on success or a negative error
  43 code.
  44
  45 A FPGA design contained in a FPGA image file will likely have particulars that
  46 affect how the image is programmed to the FPGA.  These are contained in struct
  47 fpga_image_info.  Currently the only such particular is a single flag bit
  48 indicating whether the image is for full or partial reconfiguration.
  49
  50 To get/put a reference to a FPGA manager:
  51 -----------------------------------------
  52
  53         struct fpga_manager *of_fpga_mgr_get(struct device_node *node);
  54         struct fpga_manager *fpga_mgr_get(struct device *dev);
  55
  56 Given a DT node or device, get an exclusive reference to a FPGA manager.
  57
  58         void fpga_mgr_put(struct fpga_manager *mgr);
  59
  60 Release the reference.
  61
  62
  63 To register or unregister the low level FPGA-specific driver:
  64 -------------------------------------------------------------
  65
  66         int fpga_mgr_register(struct device *dev, const char *name,
  67                               const struct fpga_manager_ops *mops,
  68                               void *priv);
  69
  70         void fpga_mgr_unregister(struct device *dev);
  71
  72 Use of these two functions is described below in "How To Support a new FPGA
  73 device."
  74
  75
  76 How to write an image buffer to a supported FPGA
  77 ================================================
  78 /* Include to get the API */
  79 #include <linux/fpga/fpga-mgr.h>
  80
  81 /* device node that specifies the FPGA manager to use */
  82 struct device_node *mgr_node = ...
  83
  84 /* FPGA image is in this buffer.  count is size of the buffer. */
  85 char *buf = ...
  86 int count = ...
  87
  88 /* struct with information about the FPGA image to program. */
  89 struct fpga_image_info info;
  90
  91 /* flags indicates whether to do full or partial reconfiguration */
  92 info.flags = 0;
  93
  94 int ret;
  95
  96 /* Get exclusive control of FPGA manager */
  97 struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node);
  98
  99 /* Load the buffer to the FPGA */
 100 ret = fpga_mgr_buf_load(mgr, &info, buf, count);
 101
 102 /* Release the FPGA manager */
 103 fpga_mgr_put(mgr);
 104
 105
 106 How to write an image file to a supported FPGA
 107 ==============================================
 108 /* Include to get the API */
 109 #include <linux/fpga/fpga-mgr.h>
 110
 111 /* device node that specifies the FPGA manager to use */
 112 struct device_node *mgr_node = ...
 113
 114 /* FPGA image is in this file which is in the firmware search path */
 115 const char *path = "fpga-image-9.rbf"
 116
 117 /* struct with information about the FPGA image to program. */
 118 struct fpga_image_info info;
 119
 120 /* flags indicates whether to do full or partial reconfiguration */
 121 info.flags = 0;
 122
 123 int ret;
 124
 125 /* Get exclusive control of FPGA manager */
 126 struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node);
 127
 128 /* Get the firmware image (path) and load it to the FPGA */
 129 ret = fpga_mgr_firmware_load(mgr, &info, path);
 130
 131 /* Release the FPGA manager */
 132 fpga_mgr_put(mgr);
 133
 134
 135 How to support a new FPGA device
 136 ================================
 137 To add another FPGA manager, write a driver that implements a set of ops.  The
 138 probe function calls fpga_mgr_register(), such as:
 139
 140 static const struct fpga_manager_ops socfpga_fpga_ops = {
 141        .write_init = socfpga_fpga_ops_configure_init,
 142        .write = socfpga_fpga_ops_configure_write,
 143        .write_complete = socfpga_fpga_ops_configure_complete,
 144        .state = socfpga_fpga_ops_state,
 145 };
 146
 147 static int socfpga_fpga_probe(struct platform_device *pdev)
 148 {
 149         struct device *dev = &pdev->dev;
 150         struct socfpga_fpga_priv *priv;
 151         int ret;
 152
 153         priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);
 154         if (!priv)
 155                 return -ENOMEM;
 156
 157         /* ... do ioremaps, get interrupts, etc. and save
 158            them in priv... */
 159
 160         return fpga_mgr_register(dev, "Altera SOCFPGA FPGA Manager",
 161                                  &socfpga_fpga_ops, priv);
 162 }
 163
 164 static int socfpga_fpga_remove(struct platform_device *pdev)
 165 {
 166         fpga_mgr_unregister(&pdev->dev);
 167
 168         return 0;
 169 }
 170
 171
 172 The ops will implement whatever device specific register writes are needed to
 173 do the programming sequence for this particular FPGA.  These ops return 0 for
 174 success or negative error codes otherwise.
 175
 176 The programming sequence is:
 177  1. .write_init
 178  2. .write or .write_sg (may be called once or multiple times)
 179  3. .write_complete
 180
 181 The .write_init function will prepare the FPGA to receive the image data.  The
 182 buffer passed into .write_init will be atmost .initial_header_size bytes long,
 183 if the whole bitstream is not immediately available then the core code will
 184 buffer up at least this much before starting.
 185
 186 The .write function writes a buffer to the FPGA. The buffer may be contain the
 187 whole FPGA image or may be a smaller chunk of an FPGA image.  In the latter
 188 case, this function is called multiple times for successive chunks. This interface
 189 is suitable for drivers which use PIO.
 190
 191 The .write_sg version behaves the same as .write except the input is a sg_table
 192 scatter list. This interface is suitable for drivers which use DMA.
 193
 194 The .write_complete function is called after all the image has been written
 195 to put the FPGA into operating mode.
 196
 197 The ops include a .state function which will read the hardware FPGA manager and
 198 return a code of type enum fpga_mgr_states.  It doesn't result in a change in
 199 hardware state.