1473f01f7SAlan Tull /* SPDX-License-Identifier: GPL-2.0 */ 26a8c3be7SAlan Tull /* 36a8c3be7SAlan Tull * FPGA Framework 46a8c3be7SAlan Tull * 55cf0c7f6SAlan Tull * Copyright (C) 2013-2016 Altera Corporation 65cf0c7f6SAlan Tull * Copyright (C) 2017 Intel Corporation 76a8c3be7SAlan Tull */ 86a8c3be7SAlan Tull #ifndef _LINUX_FPGA_MGR_H 96a8c3be7SAlan Tull #define _LINUX_FPGA_MGR_H 106a8c3be7SAlan Tull 115cf0c7f6SAlan Tull #include <linux/mutex.h> 125cf0c7f6SAlan Tull #include <linux/platform_device.h> 135cf0c7f6SAlan Tull 146a8c3be7SAlan Tull struct fpga_manager; 15baa6d396SJason Gunthorpe struct sg_table; 166a8c3be7SAlan Tull 176a8c3be7SAlan Tull /** 186a8c3be7SAlan Tull * enum fpga_mgr_states - fpga framework states 196a8c3be7SAlan Tull * @FPGA_MGR_STATE_UNKNOWN: can't determine state 206a8c3be7SAlan Tull * @FPGA_MGR_STATE_POWER_OFF: FPGA power is off 216a8c3be7SAlan Tull * @FPGA_MGR_STATE_POWER_UP: FPGA reports power is up 226a8c3be7SAlan Tull * @FPGA_MGR_STATE_RESET: FPGA in reset state 236a8c3be7SAlan Tull * @FPGA_MGR_STATE_FIRMWARE_REQ: firmware request in progress 246a8c3be7SAlan Tull * @FPGA_MGR_STATE_FIRMWARE_REQ_ERR: firmware request failed 25*3cc624beSIvan Bornyakov * @FPGA_MGR_STATE_PARSE_HEADER: parse FPGA image header 26*3cc624beSIvan Bornyakov * @FPGA_MGR_STATE_PARSE_HEADER_ERR: Error during PARSE_HEADER stage 276a8c3be7SAlan Tull * @FPGA_MGR_STATE_WRITE_INIT: preparing FPGA for programming 286a8c3be7SAlan Tull * @FPGA_MGR_STATE_WRITE_INIT_ERR: Error during WRITE_INIT stage 296a8c3be7SAlan Tull * @FPGA_MGR_STATE_WRITE: writing image to FPGA 306a8c3be7SAlan Tull * @FPGA_MGR_STATE_WRITE_ERR: Error while writing FPGA 316a8c3be7SAlan Tull * @FPGA_MGR_STATE_WRITE_COMPLETE: Doing post programming steps 326a8c3be7SAlan Tull * @FPGA_MGR_STATE_WRITE_COMPLETE_ERR: Error during WRITE_COMPLETE 336a8c3be7SAlan Tull * @FPGA_MGR_STATE_OPERATING: FPGA is programmed and operating 346a8c3be7SAlan Tull */ 356a8c3be7SAlan Tull enum fpga_mgr_states { 366a8c3be7SAlan Tull /* default FPGA states */ 376a8c3be7SAlan Tull FPGA_MGR_STATE_UNKNOWN, 386a8c3be7SAlan Tull FPGA_MGR_STATE_POWER_OFF, 396a8c3be7SAlan Tull FPGA_MGR_STATE_POWER_UP, 406a8c3be7SAlan Tull FPGA_MGR_STATE_RESET, 416a8c3be7SAlan Tull 426a8c3be7SAlan Tull /* getting an image for loading */ 436a8c3be7SAlan Tull FPGA_MGR_STATE_FIRMWARE_REQ, 446a8c3be7SAlan Tull FPGA_MGR_STATE_FIRMWARE_REQ_ERR, 456a8c3be7SAlan Tull 46*3cc624beSIvan Bornyakov /* write sequence: parse header, init, write, complete */ 47*3cc624beSIvan Bornyakov FPGA_MGR_STATE_PARSE_HEADER, 48*3cc624beSIvan Bornyakov FPGA_MGR_STATE_PARSE_HEADER_ERR, 496a8c3be7SAlan Tull FPGA_MGR_STATE_WRITE_INIT, 506a8c3be7SAlan Tull FPGA_MGR_STATE_WRITE_INIT_ERR, 516a8c3be7SAlan Tull FPGA_MGR_STATE_WRITE, 526a8c3be7SAlan Tull FPGA_MGR_STATE_WRITE_ERR, 536a8c3be7SAlan Tull FPGA_MGR_STATE_WRITE_COMPLETE, 546a8c3be7SAlan Tull FPGA_MGR_STATE_WRITE_COMPLETE_ERR, 556a8c3be7SAlan Tull 566a8c3be7SAlan Tull /* fpga is programmed and operating */ 576a8c3be7SAlan Tull FPGA_MGR_STATE_OPERATING, 586a8c3be7SAlan Tull }; 596a8c3be7SAlan Tull 60492ecf6dSAlan Tull /** 61492ecf6dSAlan Tull * DOC: FPGA Manager flags 62492ecf6dSAlan Tull * 63492ecf6dSAlan Tull * Flags used in the &fpga_image_info->flags field 64492ecf6dSAlan Tull * 65492ecf6dSAlan Tull * %FPGA_MGR_PARTIAL_RECONFIG: do partial reconfiguration if supported 66492ecf6dSAlan Tull * 67492ecf6dSAlan Tull * %FPGA_MGR_EXTERNAL_CONFIG: FPGA has been configured prior to Linux booting 68492ecf6dSAlan Tull * 69492ecf6dSAlan Tull * %FPGA_MGR_ENCRYPTED_BITSTREAM: indicates bitstream is encrypted 70492ecf6dSAlan Tull * 71492ecf6dSAlan Tull * %FPGA_MGR_BITSTREAM_LSB_FIRST: SPI bitstream bit order is LSB first 72492ecf6dSAlan Tull * 73492ecf6dSAlan Tull * %FPGA_MGR_COMPRESSED_BITSTREAM: FPGA bitstream is compressed 746a8c3be7SAlan Tull */ 756a8c3be7SAlan Tull #define FPGA_MGR_PARTIAL_RECONFIG BIT(0) 760fa20cdfSAlan Tull #define FPGA_MGR_EXTERNAL_CONFIG BIT(1) 770f4f0c8fSMoritz Fischer #define FPGA_MGR_ENCRYPTED_BITSTREAM BIT(2) 7868f6be65SAnatolij Gustschin #define FPGA_MGR_BITSTREAM_LSB_FIRST BIT(3) 79b37fa560SAnatolij Gustschin #define FPGA_MGR_COMPRESSED_BITSTREAM BIT(4) 806a8c3be7SAlan Tull 816a8c3be7SAlan Tull /** 82895ec9c0STom Rix * struct fpga_image_info - information specific to an FPGA image 831df2865fSAlan Tull * @flags: boolean flags as defined above 841df2865fSAlan Tull * @enable_timeout_us: maximum time to enable traffic through bridge (uSec) 851df2865fSAlan Tull * @disable_timeout_us: maximum time to disable traffic through bridge (uSec) 8642d5ec95SAlan Tull * @config_complete_timeout_us: maximum time for FPGA to switch to operating 8742d5ec95SAlan Tull * status in the write_complete op. 885cf0c7f6SAlan Tull * @firmware_name: name of FPGA image firmware file 895cf0c7f6SAlan Tull * @sgt: scatter/gather table containing FPGA image 905cf0c7f6SAlan Tull * @buf: contiguous buffer containing FPGA image 915cf0c7f6SAlan Tull * @count: size of buf 92*3cc624beSIvan Bornyakov * @header_size: size of image header. 93*3cc624beSIvan Bornyakov * @data_size: size of image data to be sent to the device. If not specified, 94*3cc624beSIvan Bornyakov * whole image will be used. Header may be skipped in either case. 95571d78bdSWu Hao * @region_id: id of target region 965cf0c7f6SAlan Tull * @dev: device that owns this 9761c32102SAlan Tull * @overlay: Device Tree overlay 981df2865fSAlan Tull */ 991df2865fSAlan Tull struct fpga_image_info { 1001df2865fSAlan Tull u32 flags; 1011df2865fSAlan Tull u32 enable_timeout_us; 1021df2865fSAlan Tull u32 disable_timeout_us; 10342d5ec95SAlan Tull u32 config_complete_timeout_us; 1045cf0c7f6SAlan Tull char *firmware_name; 1055cf0c7f6SAlan Tull struct sg_table *sgt; 1065cf0c7f6SAlan Tull const char *buf; 1075cf0c7f6SAlan Tull size_t count; 108*3cc624beSIvan Bornyakov size_t header_size; 109*3cc624beSIvan Bornyakov size_t data_size; 110571d78bdSWu Hao int region_id; 1115cf0c7f6SAlan Tull struct device *dev; 11261c32102SAlan Tull #ifdef CONFIG_OF 11361c32102SAlan Tull struct device_node *overlay; 11461c32102SAlan Tull #endif 1151df2865fSAlan Tull }; 1161df2865fSAlan Tull 1171df2865fSAlan Tull /** 1184ba0b2c2SRuss Weight * struct fpga_compat_id - id for compatibility check 1194ba0b2c2SRuss Weight * 1204ba0b2c2SRuss Weight * @id_h: high 64bit of the compat_id 1214ba0b2c2SRuss Weight * @id_l: low 64bit of the compat_id 1224ba0b2c2SRuss Weight */ 1234ba0b2c2SRuss Weight struct fpga_compat_id { 1244ba0b2c2SRuss Weight u64 id_h; 1254ba0b2c2SRuss Weight u64 id_l; 1264ba0b2c2SRuss Weight }; 1274ba0b2c2SRuss Weight 1284ba0b2c2SRuss Weight /** 1294ba0b2c2SRuss Weight * struct fpga_manager_info - collection of parameters for an FPGA Manager 1304ba0b2c2SRuss Weight * @name: fpga manager name 1314ba0b2c2SRuss Weight * @compat_id: FPGA manager id for compatibility check. 1324ba0b2c2SRuss Weight * @mops: pointer to structure of fpga manager ops 1334ba0b2c2SRuss Weight * @priv: fpga manager private data 1344ba0b2c2SRuss Weight * 1354ba0b2c2SRuss Weight * fpga_manager_info contains parameters for the register_full function. 1364ba0b2c2SRuss Weight * These are separated into an info structure because they some are optional 1374ba0b2c2SRuss Weight * others could be added to in the future. The info structure facilitates 1384ba0b2c2SRuss Weight * maintaining a stable API. 1394ba0b2c2SRuss Weight */ 1404ba0b2c2SRuss Weight struct fpga_manager_info { 1414ba0b2c2SRuss Weight const char *name; 1424ba0b2c2SRuss Weight struct fpga_compat_id *compat_id; 1434ba0b2c2SRuss Weight const struct fpga_manager_ops *mops; 1444ba0b2c2SRuss Weight void *priv; 1454ba0b2c2SRuss Weight }; 1464ba0b2c2SRuss Weight 1474ba0b2c2SRuss Weight /** 1486a8c3be7SAlan Tull * struct fpga_manager_ops - ops for low level fpga manager drivers 149*3cc624beSIvan Bornyakov * @initial_header_size: minimum number of bytes that should be passed into 150*3cc624beSIvan Bornyakov * parse_header and write_init. 151*3cc624beSIvan Bornyakov * @skip_header: bool flag to tell fpga-mgr core whether it should skip 152*3cc624beSIvan Bornyakov * info->header_size part at the beginning of the image when invoking 153*3cc624beSIvan Bornyakov * write callback. 1546a8c3be7SAlan Tull * @state: returns an enum value of the FPGA's state 155ecb5fbe2SWu Hao * @status: returns status of the FPGA, including reconfiguration error code 156*3cc624beSIvan Bornyakov * @parse_header: parse FPGA image header to set info->header_size and 157*3cc624beSIvan Bornyakov * info->data_size. In case the input buffer is not large enough, set 158*3cc624beSIvan Bornyakov * required size to info->header_size and return -EAGAIN. 159580e3137STom Rix * @write_init: prepare the FPGA to receive configuration data 1606a8c3be7SAlan Tull * @write: write count bytes of configuration data to the FPGA 161baa6d396SJason Gunthorpe * @write_sg: write the scatter list of configuration data to the FPGA 1626a8c3be7SAlan Tull * @write_complete: set FPGA to operating state after writing is done 1636a8c3be7SAlan Tull * @fpga_remove: optional: Set FPGA into a specific state during driver remove 164845089bbSAlan Tull * @groups: optional attribute groups. 1656a8c3be7SAlan Tull * 1666a8c3be7SAlan Tull * fpga_manager_ops are the low level functions implemented by a specific 1676a8c3be7SAlan Tull * fpga manager driver. The optional ones are tested for NULL before being 1686a8c3be7SAlan Tull * called, so leaving them out is fine. 1696a8c3be7SAlan Tull */ 1706a8c3be7SAlan Tull struct fpga_manager_ops { 1711d7f1589SJason Gunthorpe size_t initial_header_size; 172*3cc624beSIvan Bornyakov bool skip_header; 1736a8c3be7SAlan Tull enum fpga_mgr_states (*state)(struct fpga_manager *mgr); 174ecb5fbe2SWu Hao u64 (*status)(struct fpga_manager *mgr); 175*3cc624beSIvan Bornyakov int (*parse_header)(struct fpga_manager *mgr, 176*3cc624beSIvan Bornyakov struct fpga_image_info *info, 177*3cc624beSIvan Bornyakov const char *buf, size_t count); 1781df2865fSAlan Tull int (*write_init)(struct fpga_manager *mgr, 1791df2865fSAlan Tull struct fpga_image_info *info, 1806a8c3be7SAlan Tull const char *buf, size_t count); 1816a8c3be7SAlan Tull int (*write)(struct fpga_manager *mgr, const char *buf, size_t count); 182baa6d396SJason Gunthorpe int (*write_sg)(struct fpga_manager *mgr, struct sg_table *sgt); 1831df2865fSAlan Tull int (*write_complete)(struct fpga_manager *mgr, 1841df2865fSAlan Tull struct fpga_image_info *info); 1856a8c3be7SAlan Tull void (*fpga_remove)(struct fpga_manager *mgr); 186845089bbSAlan Tull const struct attribute_group **groups; 1876a8c3be7SAlan Tull }; 1886a8c3be7SAlan Tull 189ecb5fbe2SWu Hao /* FPGA manager status: Partial/Full Reconfiguration errors */ 190ecb5fbe2SWu Hao #define FPGA_MGR_STATUS_OPERATION_ERR BIT(0) 191ecb5fbe2SWu Hao #define FPGA_MGR_STATUS_CRC_ERR BIT(1) 192ecb5fbe2SWu Hao #define FPGA_MGR_STATUS_INCOMPATIBLE_IMAGE_ERR BIT(2) 193ecb5fbe2SWu Hao #define FPGA_MGR_STATUS_IP_PROTOCOL_ERR BIT(3) 194ecb5fbe2SWu Hao #define FPGA_MGR_STATUS_FIFO_OVERFLOW_ERR BIT(4) 195ecb5fbe2SWu Hao 1966a8c3be7SAlan Tull /** 1976a8c3be7SAlan Tull * struct fpga_manager - fpga manager structure 1986a8c3be7SAlan Tull * @name: name of low level fpga manager 1996a8c3be7SAlan Tull * @dev: fpga manager device 2006a8c3be7SAlan Tull * @ref_mutex: only allows one reference to fpga manager 2016a8c3be7SAlan Tull * @state: state of fpga manager 20299a560bdSWu Hao * @compat_id: FPGA manager id for compatibility check. 2036a8c3be7SAlan Tull * @mops: pointer to struct of fpga manager ops 2046a8c3be7SAlan Tull * @priv: low level driver private date 2056a8c3be7SAlan Tull */ 2066a8c3be7SAlan Tull struct fpga_manager { 2076a8c3be7SAlan Tull const char *name; 2086a8c3be7SAlan Tull struct device dev; 2096a8c3be7SAlan Tull struct mutex ref_mutex; 2106a8c3be7SAlan Tull enum fpga_mgr_states state; 21199a560bdSWu Hao struct fpga_compat_id *compat_id; 2126a8c3be7SAlan Tull const struct fpga_manager_ops *mops; 2136a8c3be7SAlan Tull void *priv; 2146a8c3be7SAlan Tull }; 2156a8c3be7SAlan Tull 2166a8c3be7SAlan Tull #define to_fpga_manager(d) container_of(d, struct fpga_manager, dev) 2176a8c3be7SAlan Tull 2185cf0c7f6SAlan Tull struct fpga_image_info *fpga_image_info_alloc(struct device *dev); 2196a8c3be7SAlan Tull 2205cf0c7f6SAlan Tull void fpga_image_info_free(struct fpga_image_info *info); 2215cf0c7f6SAlan Tull 2225cf0c7f6SAlan Tull int fpga_mgr_load(struct fpga_manager *mgr, struct fpga_image_info *info); 2236a8c3be7SAlan Tull 224ebf877a5SAlan Tull int fpga_mgr_lock(struct fpga_manager *mgr); 225ebf877a5SAlan Tull void fpga_mgr_unlock(struct fpga_manager *mgr); 226ebf877a5SAlan Tull 2276a8c3be7SAlan Tull struct fpga_manager *of_fpga_mgr_get(struct device_node *node); 2286a8c3be7SAlan Tull 2299dce0287SAlan Tull struct fpga_manager *fpga_mgr_get(struct device *dev); 2309dce0287SAlan Tull 2316a8c3be7SAlan Tull void fpga_mgr_put(struct fpga_manager *mgr); 2326a8c3be7SAlan Tull 2334ba0b2c2SRuss Weight struct fpga_manager * 2344ba0b2c2SRuss Weight fpga_mgr_register_full(struct device *parent, const struct fpga_manager_info *info); 2354ba0b2c2SRuss Weight 2364ba0b2c2SRuss Weight struct fpga_manager * 2374ba0b2c2SRuss Weight fpga_mgr_register(struct device *parent, const char *name, 2384ba0b2c2SRuss Weight const struct fpga_manager_ops *mops, void *priv); 2397085e2a9SAlan Tull void fpga_mgr_unregister(struct fpga_manager *mgr); 2406a8c3be7SAlan Tull 2414ba0b2c2SRuss Weight struct fpga_manager * 2424ba0b2c2SRuss Weight devm_fpga_mgr_register_full(struct device *parent, const struct fpga_manager_info *info); 2434ba0b2c2SRuss Weight struct fpga_manager * 2444ba0b2c2SRuss Weight devm_fpga_mgr_register(struct device *parent, const char *name, 2454ba0b2c2SRuss Weight const struct fpga_manager_ops *mops, void *priv); 246084181feSAlan Tull 2476a8c3be7SAlan Tull #endif /*_LINUX_FPGA_MGR_H */ 248