FPGA Region¶
Overview¶
This document is meant to be a brief overview of the FPGA region API usage. Amore conceptual look at regions can be found in the Device Tree bindingdocument[1].
For the purposes of this API document, let’s just say that a region associatesan FPGA Manager and a bridge (or bridges) with a reprogrammable region of anFPGA or the whole FPGA. The API provides a way to register a region and toprogram a region.
Currently the only layer above fpga-region.c in the kernel is the Device Treesupport (of-fpga-region.c) described in[1]. The DT support layer uses regionsto program the FPGA and then DT to handle enumeration. The common region codeis intended to be used by other schemes that have other ways of accomplishingenumeration 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 structfpga_image_info including:
- pointers to the image as either a scatter-gather buffer, a contiguousbuffer, or the name of firmware file
- flags indicating specifics such as whether the image is for partialreconfiguration.
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 add a new FPGA region¶
- struct
fpga_region— The FPGA region struct devm_fpga_region_create()— Allocate and init a region structfpga_region_register()— Register an FPGA regionfpga_region_unregister()— Unregister an FPGA region
The FPGA region’s probe function will need to get a reference to the FPGAManager it will be using to do the programming. This usually would happenduring the region’s probe function.
fpga_mgr_get()— Get a reference to an FPGA manager, raise ref countof_fpga_mgr_get()— Get a reference to an FPGA manager, raise ref count,given a device node.fpga_mgr_put()— Put an FPGA manager
The FPGA region will need to specify which bridges to control while programmingthe FPGA. The region driver can build a list of bridges during probe time(fpga_region->bridge_list) or it can have a function that createsthe list of bridges to program just before programming(fpga_region->get_bridges). The FPGA bridge framework supplies thefollowing APIs to handle building or tearing down that list.
fpga_bridge_get_to_list()— Get a ref of an FPGA bridge, add it to alistof_fpga_bridge_get_to_list()— Get a ref of an FPGA bridge, add it to alist, given a device nodefpga_bridges_put()— Given a list of bridges, put them
- 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
- structfpga_region *
devm_fpga_region_create(structdevice * dev, structfpga_manager * mgr, int (*get_bridges)(structfpga_region *))¶ create and initialize a managed FPGA region struct
Parameters
structdevice*dev- device parent
structfpga_manager*mgr- manager that programs this region
int(*)(structfpga_region*)get_bridges- optional function to get bridges to a list
Description
This function is intended for use in a FPGA region driver’s probe function.After the region driver creates the region struct withdevm_fpga_region_create(), it should register it withfpga_region_register().The region driver’s remove function should callfpga_region_unregister().The region struct allocated with this function will be freed automatically ondriver detach. This includes the case of a probe function returning errorbefore callingfpga_region_register(), the struct will still get cleaned up.
Return
struct fpga_region or NULL
- int
fpga_region_register(structfpga_region * region)¶ register a FPGA region
Parameters
structfpga_region*region- FPGA region
Return
0 or -errno
- void
fpga_region_unregister(structfpga_region * region)¶ unregister a FPGA region
Parameters
structfpga_region*region- FPGA region
Description
This function is intended for use in a FPGA region driver’s remove function.
- structfpga_manager *
fpga_mgr_get(structdevice * dev)¶ Given a device, get a reference to a fpga mgr.
Parameters
structdevice*dev- parent device that fpga mgr was registered with
Return
fpga manager struct or IS_ERR() condition containing error code.
- structfpga_manager *
of_fpga_mgr_get(struct device_node * node)¶ Given a device node, get a reference to a fpga mgr.
Parameters
structdevice_node*node- device node
Return
fpga manager struct or IS_ERR() condition containing error code.
- void
fpga_mgr_put(structfpga_manager * mgr)¶ release a reference to a fpga manager
Parameters
structfpga_manager*mgr- fpga manager structure
- int
fpga_bridge_get_to_list(structdevice * dev, structfpga_image_info * info, struct list_head * bridge_list)¶ given device, get a bridge, add it to a list
Parameters
structdevice*dev- FPGA bridge device
structfpga_image_info*info- fpga image specific information
structlist_head*bridge_list- list of FPGA bridges
Description
Get an exclusive reference to the bridge and and it to the list.
Return 0 for success, error code from fpga_bridge_get() othewise.
- int
of_fpga_bridge_get_to_list(struct device_node * np, structfpga_image_info * info, struct list_head * bridge_list)¶ get a bridge, add it to a list
Parameters
structdevice_node*np- node pointer of a FPGA bridge
structfpga_image_info*info- fpga image specific information
structlist_head*bridge_list- list of FPGA bridges
Description
Get an exclusive reference to the bridge and and it to the list.
Return 0 for success, error code from of_fpga_bridge_get() othewise.
- void
fpga_bridges_put(struct list_head * bridge_list)¶ put bridges
Parameters
structlist_head*bridge_list- list of FPGA bridges
Description
For each bridge in the list, put the bridge and remove it from the list.If list is empty, do nothing.