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 [1].
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 [1]. 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);
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 [2].
[1] | (1, 2) ../devicetree/bindings/fpga/fpga-region.txt |
[2] | ../../drivers/fpga/of-fpga-region.c |
API to program an FPGA¶
-
int
fpga_region_program_fpga
(struct fpga_region * region)¶ program FPGA
Parameters
struct fpga_region * region
- FPGA region
Description
Program an FPGA using fpga image info (region->info).
If the region has a get_bridges function, the exclusive reference for the
bridges will be held if programming succeeds. This is intended to prevent
reprogramming the region until the caller considers it safe to do so.
The caller will need to call fpga_bridges_put()
before attempting to
reprogram the region.
Return 0 for success or negative error code.
API to add a new FPGA region¶
-
struct
fpga_region
¶ FPGA Region structure
Definition
struct fpga_region {
struct device dev;
struct mutex mutex;
struct list_head bridge_list;
struct fpga_manager *mgr;
struct fpga_image_info *info;
struct fpga_compat_id *compat_id;
void *priv;
int (*get_bridges)(struct fpga_region *region);
};
Members
dev
- FPGA Region device
mutex
- enforces exclusive reference to region
bridge_list
- list of FPGA bridges specified in region
mgr
- FPGA manager
info
- FPGA image info
compat_id
- FPGA region id for compatibility check.
priv
- private data
get_bridges
- optional function to get bridges to a list
-
struct fpga_region *
fpga_region_create
(struct device * dev, struct fpga_manager * mgr, int (*get_bridges) (struct fpga_region *)¶ alloc and init a struct fpga_region
Parameters
struct device * dev
- device parent
struct fpga_manager * mgr
- manager that programs this region
int (*)(struct fpga_region *) get_bridges
- optional function to get bridges to a list
Return
struct fpga_region or NULL
-
void
fpga_region_free
(struct fpga_region * region)¶ free a struct fpga_region
Parameters
struct fpga_region * region
- FPGA region created by fpga_region_create
-
int
fpga_region_register
(struct fpga_region * region)¶ register a FPGA region
Parameters
struct fpga_region * region
- FPGA region created by fpga_region_create
Return
0 or -errno
-
void
fpga_region_unregister
(struct fpga_region * region)¶ unregister and free a FPGA region
Parameters
struct fpga_region * region
- FPGA region