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 256a8c3be7SAlan Tull * @FPGA_MGR_STATE_WRITE_INIT: preparing FPGA for programming 266a8c3be7SAlan Tull * @FPGA_MGR_STATE_WRITE_INIT_ERR: Error during WRITE_INIT stage 276a8c3be7SAlan Tull * @FPGA_MGR_STATE_WRITE: writing image to FPGA 286a8c3be7SAlan Tull * @FPGA_MGR_STATE_WRITE_ERR: Error while writing FPGA 296a8c3be7SAlan Tull * @FPGA_MGR_STATE_WRITE_COMPLETE: Doing post programming steps 306a8c3be7SAlan Tull * @FPGA_MGR_STATE_WRITE_COMPLETE_ERR: Error during WRITE_COMPLETE 316a8c3be7SAlan Tull * @FPGA_MGR_STATE_OPERATING: FPGA is programmed and operating 326a8c3be7SAlan Tull */ 336a8c3be7SAlan Tull enum fpga_mgr_states { 346a8c3be7SAlan Tull /* default FPGA states */ 356a8c3be7SAlan Tull FPGA_MGR_STATE_UNKNOWN, 366a8c3be7SAlan Tull FPGA_MGR_STATE_POWER_OFF, 376a8c3be7SAlan Tull FPGA_MGR_STATE_POWER_UP, 386a8c3be7SAlan Tull FPGA_MGR_STATE_RESET, 396a8c3be7SAlan Tull 406a8c3be7SAlan Tull /* getting an image for loading */ 416a8c3be7SAlan Tull FPGA_MGR_STATE_FIRMWARE_REQ, 426a8c3be7SAlan Tull FPGA_MGR_STATE_FIRMWARE_REQ_ERR, 436a8c3be7SAlan Tull 446a8c3be7SAlan Tull /* write sequence: init, write, complete */ 456a8c3be7SAlan Tull FPGA_MGR_STATE_WRITE_INIT, 466a8c3be7SAlan Tull FPGA_MGR_STATE_WRITE_INIT_ERR, 476a8c3be7SAlan Tull FPGA_MGR_STATE_WRITE, 486a8c3be7SAlan Tull FPGA_MGR_STATE_WRITE_ERR, 496a8c3be7SAlan Tull FPGA_MGR_STATE_WRITE_COMPLETE, 506a8c3be7SAlan Tull FPGA_MGR_STATE_WRITE_COMPLETE_ERR, 516a8c3be7SAlan Tull 526a8c3be7SAlan Tull /* fpga is programmed and operating */ 536a8c3be7SAlan Tull FPGA_MGR_STATE_OPERATING, 546a8c3be7SAlan Tull }; 556a8c3be7SAlan Tull 56492ecf6dSAlan Tull /** 57492ecf6dSAlan Tull * DOC: FPGA Manager flags 58492ecf6dSAlan Tull * 59492ecf6dSAlan Tull * Flags used in the &fpga_image_info->flags field 60492ecf6dSAlan Tull * 61492ecf6dSAlan Tull * %FPGA_MGR_PARTIAL_RECONFIG: do partial reconfiguration if supported 62492ecf6dSAlan Tull * 63492ecf6dSAlan Tull * %FPGA_MGR_EXTERNAL_CONFIG: FPGA has been configured prior to Linux booting 64492ecf6dSAlan Tull * 65492ecf6dSAlan Tull * %FPGA_MGR_ENCRYPTED_BITSTREAM: indicates bitstream is encrypted 66492ecf6dSAlan Tull * 67492ecf6dSAlan Tull * %FPGA_MGR_BITSTREAM_LSB_FIRST: SPI bitstream bit order is LSB first 68492ecf6dSAlan Tull * 69492ecf6dSAlan Tull * %FPGA_MGR_COMPRESSED_BITSTREAM: FPGA bitstream is compressed 706a8c3be7SAlan Tull */ 716a8c3be7SAlan Tull #define FPGA_MGR_PARTIAL_RECONFIG BIT(0) 720fa20cdfSAlan Tull #define FPGA_MGR_EXTERNAL_CONFIG BIT(1) 730f4f0c8fSMoritz Fischer #define FPGA_MGR_ENCRYPTED_BITSTREAM BIT(2) 7468f6be65SAnatolij Gustschin #define FPGA_MGR_BITSTREAM_LSB_FIRST BIT(3) 75b37fa560SAnatolij Gustschin #define FPGA_MGR_COMPRESSED_BITSTREAM BIT(4) 766a8c3be7SAlan Tull 776a8c3be7SAlan Tull /** 78895ec9c0STom Rix * struct fpga_image_info - information specific to an FPGA image 791df2865fSAlan Tull * @flags: boolean flags as defined above 801df2865fSAlan Tull * @enable_timeout_us: maximum time to enable traffic through bridge (uSec) 811df2865fSAlan Tull * @disable_timeout_us: maximum time to disable traffic through bridge (uSec) 8242d5ec95SAlan Tull * @config_complete_timeout_us: maximum time for FPGA to switch to operating 8342d5ec95SAlan Tull * status in the write_complete op. 845cf0c7f6SAlan Tull * @firmware_name: name of FPGA image firmware file 855cf0c7f6SAlan Tull * @sgt: scatter/gather table containing FPGA image 865cf0c7f6SAlan Tull * @buf: contiguous buffer containing FPGA image 875cf0c7f6SAlan Tull * @count: size of buf 88571d78bdSWu Hao * @region_id: id of target region 895cf0c7f6SAlan Tull * @dev: device that owns this 9061c32102SAlan Tull * @overlay: Device Tree overlay 911df2865fSAlan Tull */ 921df2865fSAlan Tull struct fpga_image_info { 931df2865fSAlan Tull u32 flags; 941df2865fSAlan Tull u32 enable_timeout_us; 951df2865fSAlan Tull u32 disable_timeout_us; 9642d5ec95SAlan Tull u32 config_complete_timeout_us; 975cf0c7f6SAlan Tull char *firmware_name; 985cf0c7f6SAlan Tull struct sg_table *sgt; 995cf0c7f6SAlan Tull const char *buf; 1005cf0c7f6SAlan Tull size_t count; 101571d78bdSWu Hao int region_id; 1025cf0c7f6SAlan Tull struct device *dev; 10361c32102SAlan Tull #ifdef CONFIG_OF 10461c32102SAlan Tull struct device_node *overlay; 10561c32102SAlan Tull #endif 1061df2865fSAlan Tull }; 1071df2865fSAlan Tull 1081df2865fSAlan Tull /** 1096a8c3be7SAlan Tull * struct fpga_manager_ops - ops for low level fpga manager drivers 1101d7f1589SJason Gunthorpe * @initial_header_size: Maximum number of bytes that should be passed into write_init 1116a8c3be7SAlan Tull * @state: returns an enum value of the FPGA's state 112ecb5fbe2SWu Hao * @status: returns status of the FPGA, including reconfiguration error code 113*580e3137STom Rix * @write_init: prepare the FPGA to receive configuration data 1146a8c3be7SAlan Tull * @write: write count bytes of configuration data to the FPGA 115baa6d396SJason Gunthorpe * @write_sg: write the scatter list of configuration data to the FPGA 1166a8c3be7SAlan Tull * @write_complete: set FPGA to operating state after writing is done 1176a8c3be7SAlan Tull * @fpga_remove: optional: Set FPGA into a specific state during driver remove 118845089bbSAlan Tull * @groups: optional attribute groups. 1196a8c3be7SAlan Tull * 1206a8c3be7SAlan Tull * fpga_manager_ops are the low level functions implemented by a specific 1216a8c3be7SAlan Tull * fpga manager driver. The optional ones are tested for NULL before being 1226a8c3be7SAlan Tull * called, so leaving them out is fine. 1236a8c3be7SAlan Tull */ 1246a8c3be7SAlan Tull struct fpga_manager_ops { 1251d7f1589SJason Gunthorpe size_t initial_header_size; 1266a8c3be7SAlan Tull enum fpga_mgr_states (*state)(struct fpga_manager *mgr); 127ecb5fbe2SWu Hao u64 (*status)(struct fpga_manager *mgr); 1281df2865fSAlan Tull int (*write_init)(struct fpga_manager *mgr, 1291df2865fSAlan Tull struct fpga_image_info *info, 1306a8c3be7SAlan Tull const char *buf, size_t count); 1316a8c3be7SAlan Tull int (*write)(struct fpga_manager *mgr, const char *buf, size_t count); 132baa6d396SJason Gunthorpe int (*write_sg)(struct fpga_manager *mgr, struct sg_table *sgt); 1331df2865fSAlan Tull int (*write_complete)(struct fpga_manager *mgr, 1341df2865fSAlan Tull struct fpga_image_info *info); 1356a8c3be7SAlan Tull void (*fpga_remove)(struct fpga_manager *mgr); 136845089bbSAlan Tull const struct attribute_group **groups; 1376a8c3be7SAlan Tull }; 1386a8c3be7SAlan Tull 139ecb5fbe2SWu Hao /* FPGA manager status: Partial/Full Reconfiguration errors */ 140ecb5fbe2SWu Hao #define FPGA_MGR_STATUS_OPERATION_ERR BIT(0) 141ecb5fbe2SWu Hao #define FPGA_MGR_STATUS_CRC_ERR BIT(1) 142ecb5fbe2SWu Hao #define FPGA_MGR_STATUS_INCOMPATIBLE_IMAGE_ERR BIT(2) 143ecb5fbe2SWu Hao #define FPGA_MGR_STATUS_IP_PROTOCOL_ERR BIT(3) 144ecb5fbe2SWu Hao #define FPGA_MGR_STATUS_FIFO_OVERFLOW_ERR BIT(4) 145ecb5fbe2SWu Hao 1466a8c3be7SAlan Tull /** 14799a560bdSWu Hao * struct fpga_compat_id - id for compatibility check 14899a560bdSWu Hao * 14999a560bdSWu Hao * @id_h: high 64bit of the compat_id 15099a560bdSWu Hao * @id_l: low 64bit of the compat_id 15199a560bdSWu Hao */ 15299a560bdSWu Hao struct fpga_compat_id { 15399a560bdSWu Hao u64 id_h; 15499a560bdSWu Hao u64 id_l; 15599a560bdSWu Hao }; 15699a560bdSWu Hao 15799a560bdSWu Hao /** 1586a8c3be7SAlan Tull * struct fpga_manager - fpga manager structure 1596a8c3be7SAlan Tull * @name: name of low level fpga manager 1606a8c3be7SAlan Tull * @dev: fpga manager device 1616a8c3be7SAlan Tull * @ref_mutex: only allows one reference to fpga manager 1626a8c3be7SAlan Tull * @state: state of fpga manager 16399a560bdSWu Hao * @compat_id: FPGA manager id for compatibility check. 1646a8c3be7SAlan Tull * @mops: pointer to struct of fpga manager ops 1656a8c3be7SAlan Tull * @priv: low level driver private date 1666a8c3be7SAlan Tull */ 1676a8c3be7SAlan Tull struct fpga_manager { 1686a8c3be7SAlan Tull const char *name; 1696a8c3be7SAlan Tull struct device dev; 1706a8c3be7SAlan Tull struct mutex ref_mutex; 1716a8c3be7SAlan Tull enum fpga_mgr_states state; 17299a560bdSWu Hao struct fpga_compat_id *compat_id; 1736a8c3be7SAlan Tull const struct fpga_manager_ops *mops; 1746a8c3be7SAlan Tull void *priv; 1756a8c3be7SAlan Tull }; 1766a8c3be7SAlan Tull 1776a8c3be7SAlan Tull #define to_fpga_manager(d) container_of(d, struct fpga_manager, dev) 1786a8c3be7SAlan Tull 1795cf0c7f6SAlan Tull struct fpga_image_info *fpga_image_info_alloc(struct device *dev); 1806a8c3be7SAlan Tull 1815cf0c7f6SAlan Tull void fpga_image_info_free(struct fpga_image_info *info); 1825cf0c7f6SAlan Tull 1835cf0c7f6SAlan Tull int fpga_mgr_load(struct fpga_manager *mgr, struct fpga_image_info *info); 1846a8c3be7SAlan Tull 185ebf877a5SAlan Tull int fpga_mgr_lock(struct fpga_manager *mgr); 186ebf877a5SAlan Tull void fpga_mgr_unlock(struct fpga_manager *mgr); 187ebf877a5SAlan Tull 1886a8c3be7SAlan Tull struct fpga_manager *of_fpga_mgr_get(struct device_node *node); 1896a8c3be7SAlan Tull 1909dce0287SAlan Tull struct fpga_manager *fpga_mgr_get(struct device *dev); 1919dce0287SAlan Tull 1926a8c3be7SAlan Tull void fpga_mgr_put(struct fpga_manager *mgr); 1936a8c3be7SAlan Tull 1947085e2a9SAlan Tull struct fpga_manager *fpga_mgr_create(struct device *dev, const char *name, 1957085e2a9SAlan Tull const struct fpga_manager_ops *mops, 1967085e2a9SAlan Tull void *priv); 1977085e2a9SAlan Tull void fpga_mgr_free(struct fpga_manager *mgr); 1987085e2a9SAlan Tull int fpga_mgr_register(struct fpga_manager *mgr); 1997085e2a9SAlan Tull void fpga_mgr_unregister(struct fpga_manager *mgr); 2006a8c3be7SAlan Tull 20157d9352bSMoritz Fischer int devm_fpga_mgr_register(struct device *dev, struct fpga_manager *mgr); 20257d9352bSMoritz Fischer 203084181feSAlan Tull struct fpga_manager *devm_fpga_mgr_create(struct device *dev, const char *name, 204084181feSAlan Tull const struct fpga_manager_ops *mops, 205084181feSAlan Tull void *priv); 206084181feSAlan Tull 2076a8c3be7SAlan Tull #endif /*_LINUX_FPGA_MGR_H */ 208