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