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
108