| 1 |
FPGA Region |
| 2 |
=========== |
| 3 |
|
| 4 |
Overview |
| 5 |
-------- |
| 6 |
|
| 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 |
| 9 |
document [#f1]_. |
| 10 |
|
| 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 |
| 14 |
program a region. |
| 15 |
|
| 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. |
| 21 |
|
| 22 |
An 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 |
|
| 28 |
Additional info needed to program the FPGA image is passed in the struct |
| 29 |
fpga_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 |
|
| 37 |
How to add a new FPGA region |
| 38 |
---------------------------- |
| 39 |
|
| 40 |
An 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 |
|
| 45 |
API to add a new FPGA region |
| 46 |
---------------------------- |
| 47 |
|
| 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 |
| 53 |
arguments |
| 54 |
* fpga_region_unregister() - Unregister an FPGA region |
| 55 |
|
| 56 |
Helper macros ``fpga_region_register()`` and ``fpga_region_register_full()`` |
| 57 |
automatically set the module that registers the FPGA region as the owner. |
| 58 |
|
| 59 |
The FPGA region's probe function will need to get a reference to the FPGA |
| 60 |
Manager it will be using to do the programming. This usually would happen |
| 61 |
during the region's probe function. |
| 62 |
|
| 63 |
* fpga_mgr_get() - Get a reference to an FPGA manager, raise ref count |
| 64 |
* of_fpga_mgr_get() - Get a reference to an FPGA manager, raise ref count, |
| 65 |
given a device node. |
| 66 |
* fpga_mgr_put() - Put an FPGA manager |
| 67 |
|
| 68 |
The FPGA region will need to specify which bridges to control while programming |
| 69 |
the FPGA. The region driver can build a list of bridges during probe time |
| 70 |
(:c:expr:`fpga_region->bridge_list`) or it can have a function that creates |
| 71 |
the list of bridges to program just before programming |
| 72 |
(:c:expr:`fpga_region->get_bridges`). The FPGA bridge framework supplies the |
| 73 |
following APIs to handle building or tearing down that list. |
| 74 |
|
| 75 |
* fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a |
| 76 |
list |
| 77 |
* of_fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a |
| 78 |
list, given a device node |
| 79 |
* fpga_bridges_put() - Given a list of bridges, put them |
| 80 |
|
| 81 |
.. kernel-doc:: include/linux/fpga/fpga-region.h |
| 82 |
:functions: fpga_region |
| 83 |
|
| 84 |
.. kernel-doc:: include/linux/fpga/fpga-region.h |
| 85 |
:functions: fpga_region_info |
| 86 |
|
| 87 |
.. kernel-doc:: drivers/fpga/fpga-region.c |
| 88 |
:functions: __fpga_region_register_full |
| 89 |
|
| 90 |
.. kernel-doc:: drivers/fpga/fpga-region.c |
| 91 |
:functions: __fpga_region_register |
| 92 |
|
| 93 |
.. kernel-doc:: drivers/fpga/fpga-region.c |
| 94 |
:functions: fpga_region_unregister |
| 95 |
|
| 96 |
.. kernel-doc:: drivers/fpga/fpga-mgr.c |
| 97 |
:functions: fpga_mgr_get |
| 98 |
|
| 99 |
.. kernel-doc:: drivers/fpga/fpga-mgr.c |
| 100 |
:functions: of_fpga_mgr_get |
| 101 |
|
| 102 |
.. kernel-doc:: drivers/fpga/fpga-mgr.c |
| 103 |
:functions: fpga_mgr_put |
| 104 |
|
| 105 |
.. kernel-doc:: drivers/fpga/fpga-bridge.c |
| 106 |
:functions: fpga_bridge_get_to_list |
| 107 |
|
| 108 |
.. kernel-doc:: drivers/fpga/fpga-bridge.c |
| 109 |
:functions: of_fpga_bridge_get_to_list |
| 110 |
|
| 111 |
.. kernel-doc:: drivers/fpga/fpga-bridge.c |
| 112 |
:functions: fpga_bridges_put |