FPGA Manager¶
Overview¶
The FPGA manager core exports a set of functions for programming an FPGA with an image. The API is manufacturer agnostic. All manufacturer specifics are hidden away in a low level driver which registers a set of ops with the core. The FPGA image data itself is very manufacturer specific, but for our purposes it’s just binary data. The FPGA manager core won’t parse it.
The FPGA image to be programmed can be in a scatter gather list, a single contiguous buffer, or a firmware file. Because allocating contiguous kernel memory for the buffer should be avoided, users are encouraged to use a scatter gather list instead if possible.
The particulars for programming the image are presented in a structure (struct fpga_image_info). This struct contains parameters such as pointers to the FPGA image as well as image-specific particulars such as whether the image was built for full or partial reconfiguration.
How to support a new FPGA device¶
To add another FPGA manager, write a driver that implements a set of ops. The probe function calls fpga_mgr_register(), such as:
static const struct fpga_manager_ops socfpga_fpga_ops = {
.write_init = socfpga_fpga_ops_configure_init,
.write = socfpga_fpga_ops_configure_write,
.write_complete = socfpga_fpga_ops_configure_complete,
.state = socfpga_fpga_ops_state,
};
static int socfpga_fpga_probe(struct platform_device *pdev)
{
struct device *dev = &pdev->dev;
struct socfpga_fpga_priv *priv;
struct fpga_manager *mgr;
int ret;
priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);
if (!priv)
return -ENOMEM;
/*
* do ioremaps, get interrupts, etc. and save
* them in priv
*/
mgr = fpga_mgr_create(dev, "Altera SOCFPGA FPGA Manager",
&socfpga_fpga_ops, priv);
if (!mgr)
return -ENOMEM;
platform_set_drvdata(pdev, mgr);
ret = fpga_mgr_register(mgr);
if (ret)
fpga_mgr_free(mgr);
return ret;
}
static int socfpga_fpga_remove(struct platform_device *pdev)
{
struct fpga_manager *mgr = platform_get_drvdata(pdev);
fpga_mgr_unregister(mgr);
return 0;
}
The ops will implement whatever device specific register writes are needed to do the programming sequence for this particular FPGA. These ops return 0 for success or negative error codes otherwise.
- The programming sequence is::
- .write_init
- .write or .write_sg (may be called once or multiple times)
- .write_complete
The .write_init function will prepare the FPGA to receive the image data. The buffer passed into .write_init will be atmost .initial_header_size bytes long, if the whole bitstream is not immediately available then the core code will buffer up at least this much before starting.
The .write function writes a buffer to the FPGA. The buffer may be contain the whole FPGA image or may be a smaller chunk of an FPGA image. In the latter case, this function is called multiple times for successive chunks. This interface is suitable for drivers which use PIO.
The .write_sg version behaves the same as .write except the input is a sg_table scatter list. This interface is suitable for drivers which use DMA.
The .write_complete function is called after all the image has been written to put the FPGA into operating mode.
The ops include a .state function which will read the hardware FPGA manager and return a code of type enum fpga_mgr_states. It doesn’t result in a change in hardware state.
How to write an image buffer to a supported FPGA¶
Some sample code:
#include <linux/fpga/fpga-mgr.h>
struct fpga_manager *mgr;
struct fpga_image_info *info;
int ret;
/*
* Get a reference to FPGA manager. The manager is not locked, so you can
* hold onto this reference without it preventing programming.
*
* This example uses the device node of the manager. Alternatively, use
* fpga_mgr_get(dev) instead if you have the device.
*/
mgr = of_fpga_mgr_get(mgr_node);
/* struct with information about the FPGA image to program. */
info = fpga_image_info_alloc(dev);
/* flags indicates whether to do full or partial reconfiguration */
info->flags = FPGA_MGR_PARTIAL_RECONFIG;
/*
* At this point, indicate where the image is. This is pseudo-code; you're
* going to use one of these three.
*/
if (image is in a scatter gather table) {
info->sgt = [your scatter gather table]
} else if (image is in a buffer) {
info->buf = [your image buffer]
info->count = [image buffer size]
} else if (image is in a firmware file) {
info->firmware_name = devm_kstrdup(dev, firmware_name, GFP_KERNEL);
}
/* Get exclusive control of FPGA manager */
ret = fpga_mgr_lock(mgr);
/* Load the buffer to the FPGA */
ret = fpga_mgr_buf_load(mgr, &info, buf, count);
/* Release the FPGA manager */
fpga_mgr_unlock(mgr);
fpga_mgr_put(mgr);
/* Deallocate the image info if you're done with it */
fpga_image_info_free(info);
API for implementing a new FPGA Manager driver¶
-
struct
fpga_manager
¶ fpga manager structure
Definition
struct fpga_manager {
const char *name;
struct device dev;
struct mutex ref_mutex;
enum fpga_mgr_states state;
const struct fpga_manager_ops *mops;
void *priv;
};
Members
name
- name of low level fpga manager
dev
- fpga manager device
ref_mutex
- only allows one reference to fpga manager
state
- state of fpga manager
mops
- pointer to struct of fpga manager ops
priv
- low level driver private date
-
struct
fpga_manager_ops
¶ ops for low level fpga manager drivers
Definition
struct fpga_manager_ops {
size_t initial_header_size;
enum fpga_mgr_states (*state)(struct fpga_manager *mgr);
int (*write_init)(struct fpga_manager *mgr,struct fpga_image_info *info, const char *buf, size_t count);
int (*write)(struct fpga_manager *mgr, const char *buf, size_t count);
int (*write_sg)(struct fpga_manager *mgr, struct sg_table *sgt);
int (*write_complete)(struct fpga_manager *mgr, struct fpga_image_info *info);
void (*fpga_remove)(struct fpga_manager *mgr);
const struct attribute_group **groups;
};
Members
initial_header_size
- Maximum number of bytes that should be passed into write_init
state
- returns an enum value of the FPGA’s state
write_init
- prepare the FPGA to receive confuration data
write
- write count bytes of configuration data to the FPGA
write_sg
- write the scatter list of configuration data to the FPGA
write_complete
- set FPGA to operating state after writing is done
fpga_remove
- optional: Set FPGA into a specific state during driver remove
groups
- optional attribute groups.
Description
fpga_manager_ops are the low level functions implemented by a specific fpga manager driver. The optional ones are tested for NULL before being called, so leaving them out is fine.
-
struct fpga_manager *
fpga_mgr_create
(struct device * dev, const char * name, const struct fpga_manager_ops * mops, void * priv)¶ create and initialize a FPGA manager struct
Parameters
struct device * dev
- fpga manager device from pdev
const char * name
- fpga manager name
const struct fpga_manager_ops * mops
- pointer to structure of fpga manager ops
void * priv
- fpga manager private data
Return
pointer to struct fpga_manager or NULL
-
void
fpga_mgr_free
(struct fpga_manager * mgr)¶ deallocate a FPGA manager
Parameters
struct fpga_manager * mgr
- fpga manager struct created by fpga_mgr_create
-
int
fpga_mgr_register
(struct fpga_manager * mgr)¶ register a FPGA manager
Parameters
struct fpga_manager * mgr
- fpga manager struct created by fpga_mgr_create
Return
0 on success, negative error code otherwise.
-
void
fpga_mgr_unregister
(struct fpga_manager * mgr)¶ unregister and free a FPGA manager
Parameters
struct fpga_manager * mgr
- fpga manager struct
API for programming a FPGA¶
-
struct
fpga_image_info
¶ information specific to a FPGA image
Definition
struct fpga_image_info {
u32 flags;
u32 enable_timeout_us;
u32 disable_timeout_us;
u32 config_complete_timeout_us;
char *firmware_name;
struct sg_table *sgt;
const char *buf;
size_t count;
struct device *dev;
#ifdef CONFIG_OF;
struct device_node *overlay;
#endif;
};
Members
flags
- boolean flags as defined above
enable_timeout_us
- maximum time to enable traffic through bridge (uSec)
disable_timeout_us
- maximum time to disable traffic through bridge (uSec)
config_complete_timeout_us
- maximum time for FPGA to switch to operating status in the write_complete op.
firmware_name
- name of FPGA image firmware file
sgt
- scatter/gather table containing FPGA image
buf
- contiguous buffer containing FPGA image
count
- size of buf
dev
- device that owns this
overlay
- Device Tree overlay
-
enum
fpga_mgr_states
¶ fpga framework states
Constants
FPGA_MGR_STATE_UNKNOWN
- can’t determine state
FPGA_MGR_STATE_POWER_OFF
- FPGA power is off
FPGA_MGR_STATE_POWER_UP
- FPGA reports power is up
FPGA_MGR_STATE_RESET
- FPGA in reset state
FPGA_MGR_STATE_FIRMWARE_REQ
- firmware request in progress
FPGA_MGR_STATE_FIRMWARE_REQ_ERR
- firmware request failed
FPGA_MGR_STATE_WRITE_INIT
- preparing FPGA for programming
FPGA_MGR_STATE_WRITE_INIT_ERR
- Error during WRITE_INIT stage
FPGA_MGR_STATE_WRITE
- writing image to FPGA
FPGA_MGR_STATE_WRITE_ERR
- Error while writing FPGA
FPGA_MGR_STATE_WRITE_COMPLETE
- Doing post programming steps
FPGA_MGR_STATE_WRITE_COMPLETE_ERR
- Error during WRITE_COMPLETE
FPGA_MGR_STATE_OPERATING
- FPGA is programmed and operating
-
struct fpga_image_info *
fpga_image_info_alloc
(struct device * dev)¶ Allocate a FPGA image info struct
Parameters
struct device * dev
- owning device
Return
struct fpga_image_info or NULL
-
void
fpga_image_info_free
(struct fpga_image_info * info)¶ Free a FPGA image info struct
Parameters
struct fpga_image_info * info
- FPGA image info struct to free
-
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.
-
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.
-
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_mgr_lock
(struct fpga_manager * mgr)¶ Lock FPGA manager for exclusive use
Parameters
struct fpga_manager * mgr
- fpga manager
Description
Given a pointer to FPGA Manager (from fpga_mgr_get()
or
of_fpga_mgr_put()
) attempt to get the mutex. The user should call
fpga_mgr_lock()
and verify that it returns 0 before attempting to
program the FPGA. Likewise, the user should call fpga_mgr_unlock
when done programming the FPGA.
Return
0 for success or -EBUSY
-
void
fpga_mgr_unlock
(struct fpga_manager * mgr)¶ Unlock FPGA manager after done programming
Parameters
struct fpga_manager * mgr
- fpga manager
-
enum
fpga_mgr_states
fpga framework states
Constants
FPGA_MGR_STATE_UNKNOWN
- can’t determine state
FPGA_MGR_STATE_POWER_OFF
- FPGA power is off
FPGA_MGR_STATE_POWER_UP
- FPGA reports power is up
FPGA_MGR_STATE_RESET
- FPGA in reset state
FPGA_MGR_STATE_FIRMWARE_REQ
- firmware request in progress
FPGA_MGR_STATE_FIRMWARE_REQ_ERR
- firmware request failed
FPGA_MGR_STATE_WRITE_INIT
- preparing FPGA for programming
FPGA_MGR_STATE_WRITE_INIT_ERR
- Error during WRITE_INIT stage
FPGA_MGR_STATE_WRITE
- writing image to FPGA
FPGA_MGR_STATE_WRITE_ERR
- Error while writing FPGA
FPGA_MGR_STATE_WRITE_COMPLETE
- Doing post programming steps
FPGA_MGR_STATE_WRITE_COMPLETE_ERR
- Error during WRITE_COMPLETE
FPGA_MGR_STATE_OPERATING
- FPGA is programmed and operating
Note - use fpga_region_program_fpga()
instead of fpga_mgr_load()
-
int
fpga_mgr_load
(struct fpga_manager * mgr, struct fpga_image_info * info)¶ load FPGA from scatter/gather table, buffer, or firmware
Parameters
struct fpga_manager * mgr
- fpga manager
struct fpga_image_info * info
- fpga image information.
Description
Load the FPGA from an image which is indicated in info. If successful, the FPGA ends up in operating mode.
Return
0 on success, negative error code otherwise.