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 add a new FPGA region
38----------------------------
39
40An example of usage can be seen in the probe function of [#f2]_.
41
42.. [#f1] ../devicetree/bindings/fpga/fpga-region.txt
43.. [#f2] ../../drivers/fpga/of-fpga-region.c
44
45API to add a new FPGA region
46----------------------------
47
48* struct fpga_region — The FPGA region struct
49* devm_fpga_region_create() — Allocate and init a region struct
50* fpga_region_register() —  Register an FPGA region
51* fpga_region_unregister() —  Unregister an FPGA region
52
53The FPGA region's probe function will need to get a reference to the FPGA
54Manager it will be using to do the programming.  This usually would happen
55during the region's probe function.
56
57* fpga_mgr_get() — Get a reference to an FPGA manager, raise ref count
58* of_fpga_mgr_get() —  Get a reference to an FPGA manager, raise ref count,
59  given a device node.
60* fpga_mgr_put() — Put an FPGA manager
61
62The FPGA region will need to specify which bridges to control while programming
63the FPGA.  The region driver can build a list of bridges during probe time
64(:c:expr:`fpga_region->bridge_list`) or it can have a function that creates
65the list of bridges to program just before programming
66(:c:expr:`fpga_region->get_bridges`).  The FPGA bridge framework supplies the
67following APIs to handle building or tearing down that list.
68
69* fpga_bridge_get_to_list() — Get a ref of an FPGA bridge, add it to a
70  list
71* of_fpga_bridge_get_to_list() — Get a ref of an FPGA bridge, add it to a
72  list, given a device node
73* fpga_bridges_put() — Given a list of bridges, put them
74
75.. kernel-doc:: include/linux/fpga/fpga-region.h
76   :functions: fpga_region
77
78.. kernel-doc:: drivers/fpga/fpga-region.c
79   :functions: devm_fpga_region_create
80
81.. kernel-doc:: drivers/fpga/fpga-region.c
82   :functions: fpga_region_register
83
84.. kernel-doc:: drivers/fpga/fpga-region.c
85   :functions: fpga_region_unregister
86
87.. kernel-doc:: drivers/fpga/fpga-mgr.c
88   :functions: fpga_mgr_get
89
90.. kernel-doc:: drivers/fpga/fpga-mgr.c
91   :functions: of_fpga_mgr_get
92
93.. kernel-doc:: drivers/fpga/fpga-mgr.c
94   :functions: fpga_mgr_put
95
96.. kernel-doc:: drivers/fpga/fpga-bridge.c
97   :functions: fpga_bridge_get_to_list
98
99.. kernel-doc:: drivers/fpga/fpga-bridge.c
100   :functions: of_fpga_bridge_get_to_list
101
102.. kernel-doc:: drivers/fpga/fpga-bridge.c
103   :functions: fpga_bridges_put
104