linux/fpga/fpga-mgr.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 /*
0003  * FPGA Framework
0004  *
0005  *  Copyright (C) 2013-2016 Altera Corporation
0006  *  Copyright (C) 2017 Intel Corporation
0007  */
0008 #ifndef _LINUX_FPGA_MGR_H
0009 #define _LINUX_FPGA_MGR_H
0010
0011 #include <linux/mutex.h>
0012 #include <linux/platform_device.h>
0013
0014 struct fpga_manager;
0015 struct sg_table;
0016
0017 /**
0018  * enum fpga_mgr_states - fpga framework states
0019  * @FPGA_MGR_STATE_UNKNOWN: can't determine state
0020  * @FPGA_MGR_STATE_POWER_OFF: FPGA power is off
0021  * @FPGA_MGR_STATE_POWER_UP: FPGA reports power is up
0022  * @FPGA_MGR_STATE_RESET: FPGA in reset state
0023  * @FPGA_MGR_STATE_FIRMWARE_REQ: firmware request in progress
0024  * @FPGA_MGR_STATE_FIRMWARE_REQ_ERR: firmware request failed
0025  * @FPGA_MGR_STATE_PARSE_HEADER: parse FPGA image header
0026  * @FPGA_MGR_STATE_PARSE_HEADER_ERR: Error during PARSE_HEADER stage
0027  * @FPGA_MGR_STATE_WRITE_INIT: preparing FPGA for programming
0028  * @FPGA_MGR_STATE_WRITE_INIT_ERR: Error during WRITE_INIT stage
0029  * @FPGA_MGR_STATE_WRITE: writing image to FPGA
0030  * @FPGA_MGR_STATE_WRITE_ERR: Error while writing FPGA
0031  * @FPGA_MGR_STATE_WRITE_COMPLETE: Doing post programming steps
0032  * @FPGA_MGR_STATE_WRITE_COMPLETE_ERR: Error during WRITE_COMPLETE
0033  * @FPGA_MGR_STATE_OPERATING: FPGA is programmed and operating
0034  */
0035 enum fpga_mgr_states {
0036     /* default FPGA states */
0037     FPGA_MGR_STATE_UNKNOWN,
0038     FPGA_MGR_STATE_POWER_OFF,
0039     FPGA_MGR_STATE_POWER_UP,
0040     FPGA_MGR_STATE_RESET,
0041
0042     /* getting an image for loading */
0043     FPGA_MGR_STATE_FIRMWARE_REQ,
0044     FPGA_MGR_STATE_FIRMWARE_REQ_ERR,
0045
0046     /* write sequence: parse header, init, write, complete */
0047     FPGA_MGR_STATE_PARSE_HEADER,
0048     FPGA_MGR_STATE_PARSE_HEADER_ERR,
0049     FPGA_MGR_STATE_WRITE_INIT,
0050     FPGA_MGR_STATE_WRITE_INIT_ERR,
0051     FPGA_MGR_STATE_WRITE,
0052     FPGA_MGR_STATE_WRITE_ERR,
0053     FPGA_MGR_STATE_WRITE_COMPLETE,
0054     FPGA_MGR_STATE_WRITE_COMPLETE_ERR,
0055
0056     /* fpga is programmed and operating */
0057     FPGA_MGR_STATE_OPERATING,
0058 };
0059
0060 /**
0061  * DOC: FPGA Manager flags
0062  *
0063  * Flags used in the &fpga_image_info->flags field
0064  *
0065  * %FPGA_MGR_PARTIAL_RECONFIG: do partial reconfiguration if supported
0066  *
0067  * %FPGA_MGR_EXTERNAL_CONFIG: FPGA has been configured prior to Linux booting
0068  *
0069  * %FPGA_MGR_ENCRYPTED_BITSTREAM: indicates bitstream is encrypted
0070  *
0071  * %FPGA_MGR_BITSTREAM_LSB_FIRST: SPI bitstream bit order is LSB first
0072  *
0073  * %FPGA_MGR_COMPRESSED_BITSTREAM: FPGA bitstream is compressed
0074  */
0075 #define FPGA_MGR_PARTIAL_RECONFIG   BIT(0)
0076 #define FPGA_MGR_EXTERNAL_CONFIG    BIT(1)
0077 #define FPGA_MGR_ENCRYPTED_BITSTREAM    BIT(2)
0078 #define FPGA_MGR_BITSTREAM_LSB_FIRST    BIT(3)
0079 #define FPGA_MGR_COMPRESSED_BITSTREAM   BIT(4)
0080
0081 /**
0082  * struct fpga_image_info - information specific to an FPGA image
0083  * @flags: boolean flags as defined above
0084  * @enable_timeout_us: maximum time to enable traffic through bridge (uSec)
0085  * @disable_timeout_us: maximum time to disable traffic through bridge (uSec)
0086  * @config_complete_timeout_us: maximum time for FPGA to switch to operating
0087  *     status in the write_complete op.
0088  * @firmware_name: name of FPGA image firmware file
0089  * @sgt: scatter/gather table containing FPGA image
0090  * @buf: contiguous buffer containing FPGA image
0091  * @count: size of buf
0092  * @header_size: size of image header.
0093  * @data_size: size of image data to be sent to the device. If not specified,
0094  *  whole image will be used. Header may be skipped in either case.
0095  * @region_id: id of target region
0096  * @dev: device that owns this
0097  * @overlay: Device Tree overlay
0098  */
0099 struct fpga_image_info {
0100     u32 flags;
0101     u32 enable_timeout_us;
0102     u32 disable_timeout_us;
0103     u32 config_complete_timeout_us;
0104     char *firmware_name;
0105     struct sg_table *sgt;
0106     const char *buf;
0107     size_t count;
0108     size_t header_size;
0109     size_t data_size;
0110     int region_id;
0111     struct device *dev;
0112 #ifdef CONFIG_OF
0113     struct device_node *overlay;
0114 #endif
0115 };
0116
0117 /**
0118  * struct fpga_compat_id - id for compatibility check
0119  *
0120  * @id_h: high 64bit of the compat_id
0121  * @id_l: low 64bit of the compat_id
0122  */
0123 struct fpga_compat_id {
0124     u64 id_h;
0125     u64 id_l;
0126 };
0127
0128 /**
0129  * struct fpga_manager_info - collection of parameters for an FPGA Manager
0130  * @name: fpga manager name
0131  * @compat_id: FPGA manager id for compatibility check.
0132  * @mops: pointer to structure of fpga manager ops
0133  * @priv: fpga manager private data
0134  *
0135  * fpga_manager_info contains parameters for the register_full function.
0136  * These are separated into an info structure because they some are optional
0137  * others could be added to in the future. The info structure facilitates
0138  * maintaining a stable API.
0139  */
0140 struct fpga_manager_info {
0141     const char *name;
0142     struct fpga_compat_id *compat_id;
0143     const struct fpga_manager_ops *mops;
0144     void *priv;
0145 };
0146
0147 /**
0148  * struct fpga_manager_ops - ops for low level fpga manager drivers
0149  * @initial_header_size: minimum number of bytes that should be passed into
0150  *  parse_header and write_init.
0151  * @skip_header: bool flag to tell fpga-mgr core whether it should skip
0152  *  info->header_size part at the beginning of the image when invoking
0153  *  write callback.
0154  * @state: returns an enum value of the FPGA's state
0155  * @status: returns status of the FPGA, including reconfiguration error code
0156  * @parse_header: parse FPGA image header to set info->header_size and
0157  *  info->data_size. In case the input buffer is not large enough, set
0158  *  required size to info->header_size and return -EAGAIN.
0159  * @write_init: prepare the FPGA to receive configuration data
0160  * @write: write count bytes of configuration data to the FPGA
0161  * @write_sg: write the scatter list of configuration data to the FPGA
0162  * @write_complete: set FPGA to operating state after writing is done
0163  * @fpga_remove: optional: Set FPGA into a specific state during driver remove
0164  * @groups: optional attribute groups.
0165  *
0166  * fpga_manager_ops are the low level functions implemented by a specific
0167  * fpga manager driver.  The optional ones are tested for NULL before being
0168  * called, so leaving them out is fine.
0169  */
0170 struct fpga_manager_ops {
0171     size_t initial_header_size;
0172     bool skip_header;
0173     enum fpga_mgr_states (*state)(struct fpga_manager *mgr);
0174     u64 (*status)(struct fpga_manager *mgr);
0175     int (*parse_header)(struct fpga_manager *mgr,
0176                 struct fpga_image_info *info,
0177                 const char *buf, size_t count);
0178     int (*write_init)(struct fpga_manager *mgr,
0179               struct fpga_image_info *info,
0180               const char *buf, size_t count);
0181     int (*write)(struct fpga_manager *mgr, const char *buf, size_t count);
0182     int (*write_sg)(struct fpga_manager *mgr, struct sg_table *sgt);
0183     int (*write_complete)(struct fpga_manager *mgr,
0184                   struct fpga_image_info *info);
0185     void (*fpga_remove)(struct fpga_manager *mgr);
0186     const struct attribute_group **groups;
0187 };
0188
0189 /* FPGA manager status: Partial/Full Reconfiguration errors */
0190 #define FPGA_MGR_STATUS_OPERATION_ERR       BIT(0)
0191 #define FPGA_MGR_STATUS_CRC_ERR         BIT(1)
0192 #define FPGA_MGR_STATUS_INCOMPATIBLE_IMAGE_ERR  BIT(2)
0193 #define FPGA_MGR_STATUS_IP_PROTOCOL_ERR     BIT(3)
0194 #define FPGA_MGR_STATUS_FIFO_OVERFLOW_ERR   BIT(4)
0195
0196 /**
0197  * struct fpga_manager - fpga manager structure
0198  * @name: name of low level fpga manager
0199  * @dev: fpga manager device
0200  * @ref_mutex: only allows one reference to fpga manager
0201  * @state: state of fpga manager
0202  * @compat_id: FPGA manager id for compatibility check.
0203  * @mops: pointer to struct of fpga manager ops
0204  * @priv: low level driver private date
0205  */
0206 struct fpga_manager {
0207     const char *name;
0208     struct device dev;
0209     struct mutex ref_mutex;
0210     enum fpga_mgr_states state;
0211     struct fpga_compat_id *compat_id;
0212     const struct fpga_manager_ops *mops;
0213     void *priv;
0214 };
0215
0216 #define to_fpga_manager(d) container_of(d, struct fpga_manager, dev)
0217
0218 struct fpga_image_info *fpga_image_info_alloc(struct device *dev);
0219
0220 void fpga_image_info_free(struct fpga_image_info *info);
0221
0222 int fpga_mgr_load(struct fpga_manager *mgr, struct fpga_image_info *info);
0223
0224 int fpga_mgr_lock(struct fpga_manager *mgr);
0225 void fpga_mgr_unlock(struct fpga_manager *mgr);
0226
0227 struct fpga_manager *of_fpga_mgr_get(struct device_node *node);
0228
0229 struct fpga_manager *fpga_mgr_get(struct device *dev);
0230
0231 void fpga_mgr_put(struct fpga_manager *mgr);
0232
0233 struct fpga_manager *
0234 fpga_mgr_register_full(struct device *parent, const struct fpga_manager_info *info);
0235
0236 struct fpga_manager *
0237 fpga_mgr_register(struct device *parent, const char *name,
0238           const struct fpga_manager_ops *mops, void *priv);
0239 void fpga_mgr_unregister(struct fpga_manager *mgr);
0240
0241 struct fpga_manager *
0242 devm_fpga_mgr_register_full(struct device *parent, const struct fpga_manager_info *info);
0243 struct fpga_manager *
0244 devm_fpga_mgr_register(struct device *parent, const char *name,
0245                const struct fpga_manager_ops *mops, void *priv);
0246
0247 #endif /*_LINUX_FPGA_MGR_H */