Loading...
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
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 fpga_region_program_fpga().
10
11fpga_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:expr:`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 fpga_image_info_alloc() and freed with
24fpga_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* fpga_region_program_fpga() - Program an FPGA
88* fpga_image_info() - Specifies what FPGA image to program
89* fpga_image_info_alloc() - Allocate an FPGA image info struct
90* 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