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 = devm_fpga_mgr_create(dev, "Altera SOCFPGA FPGA Manager",
&socfpga_fpga_ops, priv);
if (!mgr)
return -ENOMEM;
platform_set_drvdata(pdev, mgr);
return fpga_mgr_register(mgr);
}
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 at most .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 determine the state the FPGA is in
and return a code of type enum fpga_mgr_states. It doesn’t result in a change
in state.
API for implementing a new FPGA Manager driver¶
fpga_mgr_states— Values forfpga_manager->state.struct fpga_manager— the FPGA manager structstruct fpga_manager_ops— Low level FPGA manager driver opsdevm_fpga_mgr_create()— Allocate and init a manager structfpga_mgr_register()— Register an FPGA managerfpga_mgr_unregister()— Unregister an FPGA manager
-
enum
fpga_mgr_states¶ fpga framework states
Constants
FPGA_MGR_STATE_UNKNOWNcan’t determine state
FPGA_MGR_STATE_POWER_OFFFPGA power is off
FPGA_MGR_STATE_POWER_UPFPGA reports power is up
FPGA_MGR_STATE_RESETFPGA in reset state
FPGA_MGR_STATE_FIRMWARE_REQfirmware request in progress
FPGA_MGR_STATE_FIRMWARE_REQ_ERRfirmware request failed
FPGA_MGR_STATE_WRITE_INITpreparing FPGA for programming
FPGA_MGR_STATE_WRITE_INIT_ERRError during WRITE_INIT stage
FPGA_MGR_STATE_WRITEwriting image to FPGA
FPGA_MGR_STATE_WRITE_ERRError while writing FPGA
FPGA_MGR_STATE_WRITE_COMPLETEDoing post programming steps
FPGA_MGR_STATE_WRITE_COMPLETE_ERRError during WRITE_COMPLETE
FPGA_MGR_STATE_OPERATINGFPGA is programmed and operating
-
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;
struct fpga_compat_id *compat_id;
const struct fpga_manager_ops *mops;
void *priv;
};
Members
namename of low level fpga manager
devfpga manager device
ref_mutexonly allows one reference to fpga manager
statestate of fpga manager
compat_idFPGA manager id for compatibility check.
mopspointer to struct of fpga manager ops
privlow 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);
u64 (*status)(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_sizeMaximum number of bytes that should be passed into write_init
statereturns an enum value of the FPGA’s state
statusreturns status of the FPGA, including reconfiguration error code
write_initprepare the FPGA to receive confuration data
writewrite count bytes of configuration data to the FPGA
write_sgwrite the scatter list of configuration data to the FPGA
write_completeset FPGA to operating state after writing is done
fpga_removeoptional: Set FPGA into a specific state during driver remove
groupsoptional 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 *
devm_fpga_mgr_create(struct device *dev, const char *name, const struct fpga_manager_ops *mops, void *priv)¶ create and initialize a managed FPGA manager struct
Parameters
struct device *devfpga manager device from pdev
const char *namefpga manager name
const struct fpga_manager_ops *mopspointer to structure of fpga manager ops
void *privfpga manager private data
Description
This function is intended for use in a FPGA manager driver’s probe function.
After the manager driver creates the manager struct with
devm_fpga_mgr_create(), it should register it with fpga_mgr_register(). The
manager driver’s remove function should call fpga_mgr_unregister(). The
manager 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_mgr_register(), the struct will still get cleaned up.
Return
pointer to struct fpga_manager or NULL
-
int
fpga_mgr_register(struct fpga_manager *mgr)¶ register a FPGA manager
Parameters
struct fpga_manager *mgrfpga manager struct
Return
0 on success, negative error code otherwise.
-
void
fpga_mgr_unregister(struct fpga_manager *mgr)¶ unregister a FPGA manager
Parameters
struct fpga_manager *mgrfpga manager struct
Description
This function is intended for use in a FPGA manager driver’s remove function.