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() or fpga_mgr_register_full(),
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_register(dev, "Altera SOCFPGA FPGA Manager",
                                &socfpga_fpga_ops, priv);
        if (IS_ERR(mgr))
                return PTR_ERR(mgr);
        platform_set_drvdata(pdev, mgr);
        return 0;
}
static int socfpga_fpga_remove(struct platform_device *pdev)
{
        struct fpga_manager *mgr = platform_get_drvdata(pdev);
        fpga_mgr_unregister(mgr);
        return 0;
}
Alternatively, the probe function could call one of the resource managed
register functions, devm_fpga_mgr_register() or
devm_fpga_mgr_register_full().  When these functions are used, the
parameter syntax is the same, but the call to fpga_mgr_unregister() should be
removed. In the above example, the socfpga_fpga_remove() function would not be
required.
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::
- .parse_header (optional, may be called once or multiple times) 
- .write_init 
- .write or .write_sg (may be called once or multiple times) 
- .write_complete 
 
The .parse_header function will set header_size and data_size to
struct fpga_image_info. Before parse_header call, header_size is initialized
with initial_header_size. If flag skip_header of fpga_manager_ops is true,
.write function will get image buffer starting at header_size offset from the
beginning. If data_size is set, .write function will get data_size bytes of
the image buffer, otherwise .write will get data up to the end of image buffer.
This will not affect .write_sg, .write_sg will still get whole image in
sg_table form. If FPGA image is already mapped as a single contiguous buffer,
whole buffer will be passed into .parse_header. If image is in scatter-gather
form, core code will buffer up at least .initial_header_size before the first
call of .parse_header, if it is not enough, .parse_header should set desired
size into info->header_size and return -EAGAIN, then it will be called again
with greater part of image buffer on the input.
The .write_init function will prepare the FPGA to receive the image data. The buffer passed into .write_init will be at least info->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 for fpga_manager->state.
- struct fpga_manager- the FPGA manager struct
- struct fpga_manager_ops- Low level FPGA manager driver ops
- struct fpga_manager_info- Parameter structure for fpga_mgr_register_full()
- __fpga_mgr_register_full()- Create and register an FPGA manager using the fpga_mgr_info structure to provide the full flexibility of options
- __fpga_mgr_register()- Create and register an FPGA manager using standard arguments
- __devm_fpga_mgr_register_full()- Resource managed version of- __fpga_mgr_register_full()
- __devm_fpga_mgr_register()- Resource managed version of- __fpga_mgr_register()
- fpga_mgr_unregister()- Unregister an FPGA manager
Helper macros fpga_mgr_register_full(), fpga_mgr_register(),
devm_fpga_mgr_register_full(), and devm_fpga_mgr_register() are available
to ease the registration.
- 
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_PARSE_HEADER
- parse FPGA image header 
- FPGA_MGR_STATE_PARSE_HEADER_ERR
- Error during PARSE_HEADER stage 
- 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_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;
    struct module *mops_owner;
    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 
- compat_id
- FPGA manager id for compatibility check. 
- mops
- pointer to struct of fpga manager ops 
- mops_owner
- module containing the mops 
- 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;
    bool skip_header;
    enum fpga_mgr_states (*state)(struct fpga_manager *mgr);
    u64 (*status)(struct fpga_manager *mgr);
    int (*parse_header)(struct fpga_manager *mgr,struct fpga_image_info *info, const char *buf, size_t count);
    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
- minimum number of bytes that should be passed into parse_header and write_init. 
- skip_header
- bool flag to tell fpga-mgr core whether it should skip info->header_size part at the beginning of the image when invoking write callback. 
- state
- returns an enum value of the FPGA’s state 
- status
- returns status of the FPGA, including reconfiguration error code 
- parse_header
- parse FPGA image header to set info->header_size and info->data_size. In case the input buffer is not large enough, set required size to info->header_size and return -EAGAIN. 
- write_init
- prepare the FPGA to receive configuration 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_info¶
- collection of parameters for an FPGA Manager 
Definition:
struct fpga_manager_info {
    const char *name;
    struct fpga_compat_id *compat_id;
    const struct fpga_manager_ops *mops;
    void *priv;
};
Members
- name
- fpga manager name 
- compat_id
- FPGA manager id for compatibility check. 
- mops
- pointer to structure of fpga manager ops 
- priv
- fpga manager private data 
Description
fpga_manager_info contains parameters for the register_full function. These are separated into an info structure because they some are optional others could be added to in the future. The info structure facilitates maintaining a stable API.
- 
struct fpga_manager *__fpga_mgr_register_full(struct device *parent, const struct fpga_manager_info *info, struct module *owner)¶
- create and register an FPGA Manager device 
Parameters
- struct device *parent
- fpga manager device from pdev 
- const struct fpga_manager_info *info
- parameters for fpga manager 
- struct module *owner
- owner module containing the ops 
Description
The caller of this function is responsible for calling fpga_mgr_unregister().
Using devm_fpga_mgr_register_full() instead is recommended.
Return
pointer to struct fpga_manager pointer or ERR_PTR()
- 
struct fpga_manager *__fpga_mgr_register(struct device *parent, const char *name, const struct fpga_manager_ops *mops, void *priv, struct module *owner)¶
- create and register an FPGA Manager device 
Parameters
- struct device *parent
- 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 
- struct module *owner
- owner module containing the ops 
Description
The caller of this function is responsible for calling fpga_mgr_unregister().
Using devm_fpga_mgr_register() instead is recommended. This simple
version of the register function should be sufficient for most users. The
fpga_mgr_register_full() function is available for users that need to pass
additional, optional parameters.
Return
pointer to struct fpga_manager pointer or ERR_PTR()
- 
struct fpga_manager *__devm_fpga_mgr_register_full(struct device *parent, const struct fpga_manager_info *info, struct module *owner)¶
- resource managed variant of fpga_mgr_register() 
Parameters
- struct device *parent
- fpga manager device from pdev 
- const struct fpga_manager_info *info
- parameters for fpga manager 
- struct module *owner
- owner module containing the ops 
Return
fpga manager pointer on success, negative error code otherwise.
Description
This is the devres variant of fpga_mgr_register_full() for which the unregister function will be called automatically when the managing device is detached.
- 
struct fpga_manager *__devm_fpga_mgr_register(struct device *parent, const char *name, const struct fpga_manager_ops *mops, void *priv, struct module *owner)¶
- resource managed variant of fpga_mgr_register() 
Parameters
- struct device *parent
- 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 
- struct module *owner
- owner module containing the ops 
Return
fpga manager pointer on success, negative error code otherwise.
Description
This is the devres variant of fpga_mgr_register() for which the unregister function will be called automatically when the managing device is detached.
- 
void fpga_mgr_unregister(struct fpga_manager *mgr)¶
- unregister an FPGA manager 
Parameters
- struct fpga_manager *mgr
- fpga manager struct 
Description
This function is intended for use in an FPGA manager driver’s remove function.