103 lines
2.9 KiB
ReStructuredText
103 lines
2.9 KiB
ReStructuredText
|
FPGA Region
|
||
|
|
===========
|
||
|
|
|
||
|
|
Overview
|
||
|
|
--------
|
||
|
|
|
||
|
|
This document is meant to be a brief overview of the FPGA region API usage. A
|
||
|
|
more conceptual look at regions can be found in the Device Tree binding
|
||
|
|
document [#f1]_.
|
||
|
|
|
||
|
|
For the purposes of this API document, let's just say that a region associates
|
||
|
|
an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an
|
||
|
|
FPGA or the whole FPGA. The API provides a way to register a region and to
|
||
|
|
program a region.
|
||
|
|
|
||
|
|
Currently the only layer above fpga-region.c in the kernel is the Device Tree
|
||
|
|
support (of-fpga-region.c) described in [#f1]_. The DT support layer uses regions
|
||
|
|
to program the FPGA and then DT to handle enumeration. The common region code
|
||
|
|
is intended to be used by other schemes that have other ways of accomplishing
|
||
|
|
enumeration after programming.
|
||
|
|
|
||
|
|
An fpga-region can be set up to know the following things:
|
||
|
|
|
||
|
|
* which FPGA manager to use to do the programming
|
||
|
|
|
||
|
|
* which bridges to disable before programming and enable afterwards.
|
||
|
|
|
||
|
|
Additional info needed to program the FPGA image is passed in the struct
|
||
|
|
fpga_image_info including:
|
||
|
|
|
||
|
|
* pointers to the image as either a scatter-gather buffer, a contiguous
|
||
|
|
buffer, or the name of firmware file
|
||
|
|
|
||
|
|
* flags indicating specifics such as whether the image is for partial
|
||
|
|
reconfiguration.
|
||
|
|
|
||
|
|
How to program an FPGA using a region
|
||
|
|
-------------------------------------
|
||
|
|
|
||
|
|
First, allocate the info struct::
|
||
|
|
|
||
|
|
info = fpga_image_info_alloc(dev);
|
||
|
|
if (!info)
|
||
|
|
return -ENOMEM;
|
||
|
|
|
||
|
|
Set flags as needed, i.e.::
|
||
|
|
|
||
|
|
info->flags |= FPGA_MGR_PARTIAL_RECONFIG;
|
||
|
|
|
||
|
|
Point to your FPGA image, such as::
|
||
|
|
|
||
|
|
info->sgt = &sgt;
|
||
|
|
|
||
|
|
Add info to region and do the programming::
|
||
|
|
|
||
|
|
region->info = info;
|
||
|
|
ret = fpga_region_program_fpga(region);
|
||
|
|
|
||
|
|
:c:func:`fpga_region_program_fpga()` operates on info passed in the
|
||
|
|
fpga_image_info (region->info). This function will attempt to:
|
||
|
|
|
||
|
|
* lock the region's mutex
|
||
|
|
* lock the region's FPGA manager
|
||
|
|
* build a list of FPGA bridges if a method has been specified to do so
|
||
|
|
* disable the bridges
|
||
|
|
* program the FPGA
|
||
|
|
* re-enable the bridges
|
||
|
|
* release the locks
|
||
|
|
|
||
|
|
Then you will want to enumerate whatever hardware has appeared in the FPGA.
|
||
|
|
|
||
|
|
How to add a new FPGA region
|
||
|
|
----------------------------
|
||
|
|
|
||
|
|
An example of usage can be seen in the probe function of [#f2]_.
|
||
|
|
|
||
|
|
.. [#f1] ../devicetree/bindings/fpga/fpga-region.txt
|
||
|
|
.. [#f2] ../../drivers/fpga/of-fpga-region.c
|
||
|
|
|
||
|
|
API to program an FPGA
|
||
|
|
----------------------
|
||
|
|
|
||
|
|
.. kernel-doc:: drivers/fpga/fpga-region.c
|
||
|
|
:functions: fpga_region_program_fpga
|
||
|
|
|
||
|
|
API to add a new FPGA region
|
||
|
|
----------------------------
|
||
|
|
|
||
|
|
.. kernel-doc:: include/linux/fpga/fpga-region.h
|
||
|
|
:functions: fpga_region
|
||
|
|
|
||
|
|
.. kernel-doc:: drivers/fpga/fpga-region.c
|
||
|
|
:functions: fpga_region_create
|
||
|
|
|
||
|
|
.. kernel-doc:: drivers/fpga/fpga-region.c
|
||
|
|
:functions: fpga_region_free
|
||
|
|
|
||
|
|
.. kernel-doc:: drivers/fpga/fpga-region.c
|
||
|
|
:functions: fpga_region_register
|
||
|
|
|
||
|
|
.. kernel-doc:: drivers/fpga/fpga-region.c
|
||
|
|
:functions: fpga_region_unregister
|