7 This document is meant to be a brief overview of the FPGA region API usage. A
8 more conceptual look at regions can be found in the Device Tree binding
11 For the purposes of this API document, let's just say that a region associates
12 an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an
13 FPGA or the whole FPGA. The API provides a way to register a region and to
16 Currently the only layer above fpga-region.c in the kernel is the Device Tree
17 support (of-fpga-region.c) described in [#f1]_. The DT support layer uses regions
18 to program the FPGA and then DT to handle enumeration. The common region code
19 is intended to be used by other schemes that have other ways of accomplishing
20 enumeration after programming.
22 An fpga-region can be set up to know the following things:
24 * which FPGA manager to use to do the programming
26 * which bridges to disable before programming and enable afterwards.
28 Additional info needed to program the FPGA image is passed in the struct
29 fpga_image_info including:
31 * pointers to the image as either a scatter-gather buffer, a contiguous
32 buffer, or the name of firmware file
34 * flags indicating specifics such as whether the image is for partial
37 How to add a new FPGA region
38 ----------------------------
40 An example of usage can be seen in the probe function of [#f2]_.
42 .. [#f1] ../devicetree/bindings/fpga/fpga-region.txt
43 .. [#f2] ../../drivers/fpga/of-fpga-region.c
45 API to add a new FPGA region
46 ----------------------------
48 * struct fpga_region - The FPGA region struct
49 * struct fpga_region_info - Parameter structure for fpga_region_register_full()
50 * fpga_region_register_full() - Create and register an FPGA region using the
51 fpga_region_info structure to provide the full flexibility of options
52 * fpga_region_register() - Create and register an FPGA region using standard
54 * fpga_region_unregister() - Unregister an FPGA region
56 The FPGA region's probe function will need to get a reference to the FPGA
57 Manager it will be using to do the programming. This usually would happen
58 during the region's probe function.
60 * fpga_mgr_get() - Get a reference to an FPGA manager, raise ref count
61 * of_fpga_mgr_get() - Get a reference to an FPGA manager, raise ref count,
63 * fpga_mgr_put() - Put an FPGA manager
65 The FPGA region will need to specify which bridges to control while programming
66 the FPGA. The region driver can build a list of bridges during probe time
67 (:c:expr:`fpga_region->bridge_list`) or it can have a function that creates
68 the list of bridges to program just before programming
69 (:c:expr:`fpga_region->get_bridges`). The FPGA bridge framework supplies the
70 following APIs to handle building or tearing down that list.
72 * fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a
74 * of_fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a
75 list, given a device node
76 * fpga_bridges_put() - Given a list of bridges, put them
78 .. kernel-doc:: include/linux/fpga/fpga-region.h
79 :functions: fpga_region
81 .. kernel-doc:: include/linux/fpga/fpga-region.h
82 :functions: fpga_region_info
84 .. kernel-doc:: drivers/fpga/fpga-region.c
85 :functions: fpga_region_register_full
87 .. kernel-doc:: drivers/fpga/fpga-region.c
88 :functions: fpga_region_register
90 .. kernel-doc:: drivers/fpga/fpga-region.c
91 :functions: fpga_region_unregister
93 .. kernel-doc:: drivers/fpga/fpga-mgr.c
94 :functions: fpga_mgr_get
96 .. kernel-doc:: drivers/fpga/fpga-mgr.c
97 :functions: of_fpga_mgr_get
99 .. kernel-doc:: drivers/fpga/fpga-mgr.c
100 :functions: fpga_mgr_put
102 .. kernel-doc:: drivers/fpga/fpga-bridge.c
103 :functions: fpga_bridge_get_to_list
105 .. kernel-doc:: drivers/fpga/fpga-bridge.c
106 :functions: of_fpga_bridge_get_to_list
108 .. kernel-doc:: drivers/fpga/fpga-bridge.c
109 :functions: fpga_bridges_put