| 1 |
FPGA Manager |
| 2 |
============ |
| 3 |
|
| 4 |
Overview |
| 5 |
-------- |
| 6 |
|
| 7 |
The FPGA manager core exports a set of functions for programming an FPGA with |
| 8 |
an image. The API is manufacturer agnostic. All manufacturer specifics are |
| 9 |
hidden away in a low level driver which registers a set of ops with the core. |
| 10 |
The FPGA image data itself is very manufacturer specific, but for our purposes |
| 11 |
it's just binary data. The FPGA manager core won't parse it. |
| 12 |
|
| 13 |
The FPGA image to be programmed can be in a scatter gather list, a single |
| 14 |
contiguous buffer, or a firmware file. Because allocating contiguous kernel |
| 15 |
memory for the buffer should be avoided, users are encouraged to use a scatter |
| 16 |
gather list instead if possible. |
| 17 |
|
| 18 |
The particulars for programming the image are presented in a structure (struct |
| 19 |
fpga_image_info). This struct contains parameters such as pointers to the |
| 20 |
FPGA image as well as image-specific particulars such as whether the image was |
| 21 |
built for full or partial reconfiguration. |
| 22 |
|
| 23 |
How to support a new FPGA device |
| 24 |
-------------------------------- |
| 25 |
|
| 26 |
To add another FPGA manager, write a driver that implements a set of ops. The |
| 27 |
probe function calls ``fpga_mgr_register()`` or ``fpga_mgr_register_full()``, |
| 28 |
such as:: |
| 29 |
|
| 30 |
static const struct fpga_manager_ops socfpga_fpga_ops = { |
| 31 |
.write_init = socfpga_fpga_ops_configure_init, |
| 32 |
.write = socfpga_fpga_ops_configure_write, |
| 33 |
.write_complete = socfpga_fpga_ops_configure_complete, |
| 34 |
.state = socfpga_fpga_ops_state, |
| 35 |
}; |
| 36 |
|
| 37 |
static int socfpga_fpga_probe(struct platform_device *pdev) |
| 38 |
{ |
| 39 |
struct device *dev = &pdev->dev; |
| 40 |
struct socfpga_fpga_priv *priv; |
| 41 |
struct fpga_manager *mgr; |
| 42 |
int ret; |
| 43 |
|
| 44 |
priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL); |
| 45 |
if (!priv) |
| 46 |
return -ENOMEM; |
| 47 |
|
| 48 |
/* |
| 49 |
* do ioremaps, get interrupts, etc. and save |
| 50 |
* them in priv |
| 51 |
*/ |
| 52 |
|
| 53 |
mgr = fpga_mgr_register(dev, "Altera SOCFPGA FPGA Manager", |
| 54 |
&socfpga_fpga_ops, priv); |
| 55 |
if (IS_ERR(mgr)) |
| 56 |
return PTR_ERR(mgr); |
| 57 |
|
| 58 |
platform_set_drvdata(pdev, mgr); |
| 59 |
|
| 60 |
return 0; |
| 61 |
} |
| 62 |
|
| 63 |
static int socfpga_fpga_remove(struct platform_device *pdev) |
| 64 |
{ |
| 65 |
struct fpga_manager *mgr = platform_get_drvdata(pdev); |
| 66 |
|
| 67 |
fpga_mgr_unregister(mgr); |
| 68 |
|
| 69 |
return 0; |
| 70 |
} |
| 71 |
|
| 72 |
Alternatively, the probe function could call one of the resource managed |
| 73 |
register functions, ``devm_fpga_mgr_register()`` or |
| 74 |
``devm_fpga_mgr_register_full()``. When these functions are used, the |
| 75 |
parameter syntax is the same, but the call to ``fpga_mgr_unregister()`` should be |
| 76 |
removed. In the above example, the ``socfpga_fpga_remove()`` function would not be |
| 77 |
required. |
| 78 |
|
| 79 |
The ops will implement whatever device specific register writes are needed to |
| 80 |
do the programming sequence for this particular FPGA. These ops return 0 for |
| 81 |
success or negative error codes otherwise. |
| 82 |
|
| 83 |
The programming sequence is:: |
| 84 |
1. .parse_header (optional, may be called once or multiple times) |
| 85 |
2. .write_init |
| 86 |
3. .write or .write_sg (may be called once or multiple times) |
| 87 |
4. .write_complete |
| 88 |
|
| 89 |
The .parse_header function will set header_size and data_size to |
| 90 |
struct fpga_image_info. Before parse_header call, header_size is initialized |
| 91 |
with initial_header_size. If flag skip_header of fpga_manager_ops is true, |
| 92 |
.write function will get image buffer starting at header_size offset from the |
| 93 |
beginning. If data_size is set, .write function will get data_size bytes of |
| 94 |
the image buffer, otherwise .write will get data up to the end of image buffer. |
| 95 |
This will not affect .write_sg, .write_sg will still get whole image in |
| 96 |
sg_table form. If FPGA image is already mapped as a single contiguous buffer, |
| 97 |
whole buffer will be passed into .parse_header. If image is in scatter-gather |
| 98 |
form, core code will buffer up at least .initial_header_size before the first |
| 99 |
call of .parse_header, if it is not enough, .parse_header should set desired |
| 100 |
size into info->header_size and return -EAGAIN, then it will be called again |
| 101 |
with greater part of image buffer on the input. |
| 102 |
|
| 103 |
The .write_init function will prepare the FPGA to receive the image data. The |
| 104 |
buffer passed into .write_init will be at least info->header_size bytes long; |
| 105 |
if the whole bitstream is not immediately available then the core code will |
| 106 |
buffer up at least this much before starting. |
| 107 |
|
| 108 |
The .write function writes a buffer to the FPGA. The buffer may be contain the |
| 109 |
whole FPGA image or may be a smaller chunk of an FPGA image. In the latter |
| 110 |
case, this function is called multiple times for successive chunks. This interface |
| 111 |
is suitable for drivers which use PIO. |
| 112 |
|
| 113 |
The .write_sg version behaves the same as .write except the input is a sg_table |
| 114 |
scatter list. This interface is suitable for drivers which use DMA. |
| 115 |
|
| 116 |
The .write_complete function is called after all the image has been written |
| 117 |
to put the FPGA into operating mode. |
| 118 |
|
| 119 |
The ops include a .state function which will determine the state the FPGA is in |
| 120 |
and return a code of type enum fpga_mgr_states. It doesn't result in a change |
| 121 |
in state. |
| 122 |
|
| 123 |
API for implementing a new FPGA Manager driver |
| 124 |
---------------------------------------------- |
| 125 |
|
| 126 |
* ``fpga_mgr_states`` - Values for :c:expr:`fpga_manager->state`. |
| 127 |
* struct fpga_manager - the FPGA manager struct |
| 128 |
* struct fpga_manager_ops - Low level FPGA manager driver ops |
| 129 |
* struct fpga_manager_info - Parameter structure for fpga_mgr_register_full() |
| 130 |
* __fpga_mgr_register_full() - Create and register an FPGA manager using the |
| 131 |
fpga_mgr_info structure to provide the full flexibility of options |
| 132 |
* __fpga_mgr_register() - Create and register an FPGA manager using standard |
| 133 |
arguments |
| 134 |
* __devm_fpga_mgr_register_full() - Resource managed version of |
| 135 |
__fpga_mgr_register_full() |
| 136 |
* __devm_fpga_mgr_register() - Resource managed version of __fpga_mgr_register() |
| 137 |
* fpga_mgr_unregister() - Unregister an FPGA manager |
| 138 |
|
| 139 |
Helper macros ``fpga_mgr_register_full()``, ``fpga_mgr_register()``, |
| 140 |
``devm_fpga_mgr_register_full()``, and ``devm_fpga_mgr_register()`` are available |
| 141 |
to ease the registration. |
| 142 |
|
| 143 |
.. kernel-doc:: include/linux/fpga/fpga-mgr.h |
| 144 |
:functions: fpga_mgr_states |
| 145 |
|
| 146 |
.. kernel-doc:: include/linux/fpga/fpga-mgr.h |
| 147 |
:functions: fpga_manager |
| 148 |
|
| 149 |
.. kernel-doc:: include/linux/fpga/fpga-mgr.h |
| 150 |
:functions: fpga_manager_ops |
| 151 |
|
| 152 |
.. kernel-doc:: include/linux/fpga/fpga-mgr.h |
| 153 |
:functions: fpga_manager_info |
| 154 |
|
| 155 |
.. kernel-doc:: drivers/fpga/fpga-mgr.c |
| 156 |
:functions: __fpga_mgr_register_full |
| 157 |
|
| 158 |
.. kernel-doc:: drivers/fpga/fpga-mgr.c |
| 159 |
:functions: __fpga_mgr_register |
| 160 |
|
| 161 |
.. kernel-doc:: drivers/fpga/fpga-mgr.c |
| 162 |
:functions: __devm_fpga_mgr_register_full |
| 163 |
|
| 164 |
.. kernel-doc:: drivers/fpga/fpga-mgr.c |
| 165 |
:functions: __devm_fpga_mgr_register |
| 166 |
|
| 167 |
.. kernel-doc:: drivers/fpga/fpga-mgr.c |
| 168 |
:functions: fpga_mgr_unregister |