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 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

The FPGA region’s probe function will need to get a reference to the FPGA Manager it will be using to do the programming. This usually would happen during the region’s probe function.

The FPGA region will need to specify which bridges to control while programming the FPGA. The region driver can build a list of bridges during probe time (fpga_region->bridge_list) or it can have a function that creates the list of bridges to program just before programming (fpga_region->get_bridges). The FPGA bridge framework supplies the following APIs to handle building or tearing down that list.

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 * devm_fpga_region_create(struct device * dev, struct fpga_manager * mgr, int (*get_bridges)(struct fpga_region *))

create and initialize a managed FPGA region struct

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

Description

This function is intended for use in a FPGA region driver’s probe function. After the region driver creates the region struct with devm_fpga_region_create(), it should register it with fpga_region_register(). The region driver’s remove function should call fpga_region_unregister(). The region struct allocated with this function will be freed automatically on driver detach. This includes the case of a probe function returning error before calling fpga_region_register(), the struct will still get cleaned up.

Return

struct fpga_region or NULL

int fpga_region_register(struct fpga_region * region)

register a FPGA region

Parameters

struct fpga_region * region
FPGA region

Return

0 or -errno

void fpga_region_unregister(struct fpga_region * region)

unregister a FPGA region

Parameters

struct fpga_region * region
FPGA region

Description

This function is intended for use in a FPGA region driver’s remove function.

struct fpga_manager * fpga_mgr_get(struct device * dev)

Given a device, get a reference to a fpga mgr.

Parameters

struct device * dev
parent device that fpga mgr was registered with

Return

fpga manager struct or IS_ERR() condition containing error code.

struct fpga_manager * of_fpga_mgr_get(struct device_node * node)

Given a device node, get a reference to a fpga mgr.

Parameters

struct device_node * node
device node

Return

fpga manager struct or IS_ERR() condition containing error code.

void fpga_mgr_put(struct fpga_manager * mgr)

release a reference to a fpga manager

Parameters

struct fpga_manager * mgr
fpga manager structure
int fpga_bridge_get_to_list(struct device * dev, struct fpga_image_info * info, struct list_head * bridge_list)

given device, get a bridge, add it to a list

Parameters

struct device * dev
FPGA bridge device
struct fpga_image_info * info
fpga image specific information
struct list_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, struct fpga_image_info * info, struct list_head * bridge_list)

get a bridge, add it to a list

Parameters

struct device_node * np
node pointer of a FPGA bridge
struct fpga_image_info * info
fpga image specific information
struct list_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

struct list_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.