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