1In-kernel API for FPGA Programming 2================================== 3 4Overview 5-------- 6 7The in-kernel API for FPGA programming is a combination of APIs from 8FPGA manager, bridge, and regions. The actual function used to 9trigger FPGA programming is :c:func:`fpga_region_program_fpga()`. 10 11:c:func:`fpga_region_program_fpga()` uses functionality supplied by 12the FPGA manager and bridges. It will: 13 14 * lock the region's mutex 15 * lock the mutex of the region's FPGA manager 16 * build a list of FPGA bridges if a method has been specified to do so 17 * disable the bridges 18 * program the FPGA using info passed in :c:member:`fpga_region->info`. 19 * re-enable the bridges 20 * release the locks 21 22The struct fpga_image_info specifies what FPGA image to program. It is 23allocated/freed by :c:func:`fpga_image_info_alloc()` and freed with 24:c:func:`fpga_image_info_free()` 25 26How to program an FPGA using a region 27------------------------------------- 28 29When the FPGA region driver probed, it was given a pointer to an FPGA manager 30driver so it knows which manager to use. The region also either has a list of 31bridges to control during programming or it has a pointer to a function that 32will generate that list. Here's some sample code of what to do next:: 33 34 #include <linux/fpga/fpga-mgr.h> 35 #include <linux/fpga/fpga-region.h> 36 37 struct fpga_image_info *info; 38 int ret; 39 40 /* 41 * First, alloc the struct with information about the FPGA image to 42 * program. 43 */ 44 info = fpga_image_info_alloc(dev); 45 if (!info) 46 return -ENOMEM; 47 48 /* Set flags as needed, such as: */ 49 info->flags = FPGA_MGR_PARTIAL_RECONFIG; 50 51 /* 52 * Indicate where the FPGA image is. This is pseudo-code; you're 53 * going to use one of these three. 54 */ 55 if (image is in a scatter gather table) { 56 57 info->sgt = [your scatter gather table] 58 59 } else if (image is in a buffer) { 60 61 info->buf = [your image buffer] 62 info->count = [image buffer size] 63 64 } else if (image is in a firmware file) { 65 66 info->firmware_name = devm_kstrdup(dev, firmware_name, 67 GFP_KERNEL); 68 69 } 70 71 /* Add info to region and do the programming */ 72 region->info = info; 73 ret = fpga_region_program_fpga(region); 74 75 /* Deallocate the image info if you're done with it */ 76 region->info = NULL; 77 fpga_image_info_free(info); 78 79 if (ret) 80 return ret; 81 82 /* Now enumerate whatever hardware has appeared in the FPGA. */ 83 84API for programming an FPGA 85--------------------------- 86 87* :c:func:`fpga_region_program_fpga` — Program an FPGA 88* :c:type:`fpga_image_info` — Specifies what FPGA image to program 89* :c:func:`fpga_image_info_alloc()` — Allocate an FPGA image info struct 90* :c:func:`fpga_image_info_free()` — Free an FPGA image info struct 91 92.. kernel-doc:: drivers/fpga/fpga-region.c 93 :functions: fpga_region_program_fpga 94 95FPGA Manager flags 96 97.. kernel-doc:: include/linux/fpga/fpga-mgr.h 98 :doc: FPGA Manager flags 99 100.. kernel-doc:: include/linux/fpga/fpga-mgr.h 101 :functions: fpga_image_info 102 103.. kernel-doc:: drivers/fpga/fpga-mgr.c 104 :functions: fpga_image_info_alloc 105 106.. kernel-doc:: drivers/fpga/fpga-mgr.c 107 :functions: fpga_image_info_free 108