1FPGA Manager Core 2 3Alan Tull 2015 4 5Overview 6======== 7 8The FPGA manager core exports a set of functions for programming an FPGA with 9an image. The API is manufacturer agnostic. All manufacturer specifics are 10hidden away in a low level driver which registers a set of ops with the core. 11The FPGA image data itself is very manufacturer specific, but for our purposes 12it's just binary data. The FPGA manager core won't parse it. 13 14 15API Functions: 16============== 17 18To 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 25Load the FPGA from an image which exists as a contiguous buffer in 26memory. Allocating contiguous kernel memory for the buffer should be avoided, 27users 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 33Load the FPGA from an image from non-contiguous in memory. Callers can 34construct 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 40Load the FPGA from an image which exists as a file. The image file must be on 41the firmware search path (see the firmware class documentation). If successful, 42the FPGA ends up in operating mode. Return 0 on success or a negative error 43code. 44 45A FPGA design contained in a FPGA image file will likely have particulars that 46affect how the image is programmed to the FPGA. These are contained in struct 47fpga_image_info. Currently the only such particular is a single flag bit 48indicating whether the image is for full or partial reconfiguration. 49 50To 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 56Given a DT node or device, get an exclusive reference to a FPGA manager. 57 58 void fpga_mgr_put(struct fpga_manager *mgr); 59 60Release the reference. 61 62 63To 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 72Use of these two functions is described below in "How To Support a new FPGA 73device." 74 75 76How 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 */ 82struct device_node *mgr_node = ... 83 84/* FPGA image is in this buffer. count is size of the buffer. */ 85char *buf = ... 86int count = ... 87 88/* struct with information about the FPGA image to program. */ 89struct fpga_image_info info; 90 91/* flags indicates whether to do full or partial reconfiguration */ 92info.flags = 0; 93 94int ret; 95 96/* Get exclusive control of FPGA manager */ 97struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node); 98 99/* Load the buffer to the FPGA */ 100ret = fpga_mgr_buf_load(mgr, &info, buf, count); 101 102/* Release the FPGA manager */ 103fpga_mgr_put(mgr); 104 105 106How 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 */ 112struct device_node *mgr_node = ... 113 114/* FPGA image is in this file which is in the firmware search path */ 115const char *path = "fpga-image-9.rbf" 116 117/* struct with information about the FPGA image to program. */ 118struct fpga_image_info info; 119 120/* flags indicates whether to do full or partial reconfiguration */ 121info.flags = 0; 122 123int ret; 124 125/* Get exclusive control of FPGA manager */ 126struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node); 127 128/* Get the firmware image (path) and load it to the FPGA */ 129ret = fpga_mgr_firmware_load(mgr, &info, path); 130 131/* Release the FPGA manager */ 132fpga_mgr_put(mgr); 133 134 135How to support a new FPGA device 136================================ 137To add another FPGA manager, write a driver that implements a set of ops. The 138probe function calls fpga_mgr_register(), such as: 139 140static 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 147static 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 164static int socfpga_fpga_remove(struct platform_device *pdev) 165{ 166 fpga_mgr_unregister(&pdev->dev); 167 168 return 0; 169} 170 171 172The ops will implement whatever device specific register writes are needed to 173do the programming sequence for this particular FPGA. These ops return 0 for 174success or negative error codes otherwise. 175 176The 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 181The .write_init function will prepare the FPGA to receive the image data. The 182buffer passed into .write_init will be atmost .initial_header_size bytes long, 183if the whole bitstream is not immediately available then the core code will 184buffer up at least this much before starting. 185 186The .write function writes a buffer to the FPGA. The buffer may be contain the 187whole FPGA image or may be a smaller chunk of an FPGA image. In the latter 188case, this function is called multiple times for successive chunks. This interface 189is suitable for drivers which use PIO. 190 191The .write_sg version behaves the same as .write except the input is a sg_table 192scatter list. This interface is suitable for drivers which use DMA. 193 194The .write_complete function is called after all the image has been written 195to put the FPGA into operating mode. 196 197The ops include a .state function which will read the hardware FPGA manager and 198return a code of type enum fpga_mgr_states. It doesn't result in a change in 199hardware state. 200