1FPGA Regions
 2
 3Alan Tull 2017
 4
 5CONTENTS
 6 - Introduction
 7 - The FPGA region API
 8 - Usage example
 9
10Introduction
11============
12
13This document is meant to be an brief overview of the FPGA region API usage.  A
14more conceptual look at regions can be found in [1].
15
16For the purposes of this API document, let's just say that a region associates
17an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an
18FPGA or the whole FPGA.  The API provides a way to register a region and to
19program a region.
20
21Currently the only layer above fpga-region.c in the kernel is the Device Tree
22support (of-fpga-region.c) described in [1].  The DT support layer uses regions
23to program the FPGA and then DT to handle enumeration.  The common region code
24is intended to be used by other schemes that have other ways of accomplishing
25enumeration after programming.
26
27An fpga-region can be set up to know the following things:
28* which FPGA manager to use to do the programming
29* which bridges to disable before programming and enable afterwards.
30
31Additional info needed to program the FPGA image is passed in the struct
32fpga_image_info [2] including:
33* pointers to the image as either a scatter-gather buffer, a contiguous
34  buffer, or the name of firmware file
35* flags indicating specifics such as whether the image if for partial
36  reconfiguration.
37
38===================
39The FPGA region API
40===================
41
42To register or unregister a region:
43-----------------------------------
44
45	int fpga_region_register(struct device *dev,
46				 struct fpga_region *region);
47	int fpga_region_unregister(struct fpga_region *region);
48
49An example of usage can be seen in the probe function of [3]
50
51To program an FPGA:
52-------------------
53	int fpga_region_program_fpga(struct fpga_region *region);
54
55This function operates on info passed in the fpga_image_info
56(region->info).
57
58This function will attempt to:
59 * lock the region's mutex
60 * lock the region's FPGA manager
61 * build a list of FPGA bridges if a method has been specified to do so
62 * disable the bridges
63 * program the FPGA
64 * re-enable the bridges
65 * release the locks
66
67=============
68Usage example
69=============
70
71First, allocate the info struct:
72
73	info = fpga_image_info_alloc(dev);
74	if (!info)
75		return -ENOMEM;
76
77Set flags as needed, i.e.
78
79	info->flags |= FPGA_MGR_PARTIAL_RECONFIG;
80
81Point to your FPGA image, such as:
82
83	info->sgt = &sgt;
84
85Add info to region and do the programming:
86
87	region->info = info;
88	ret = fpga_region_program_fpga(region);
89
90Then enumerate whatever hardware has appeared in the FPGA.
91
92--
93[1] ../devicetree/bindings/fpga/fpga-region.txt
94[2] ./fpga-mgr.txt
95[3] ../../drivers/fpga/of-fpga-region.c