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 /** 109*4ba0b2c2SRuss Weight * struct fpga_compat_id - id for compatibility check 110*4ba0b2c2SRuss Weight * 111*4ba0b2c2SRuss Weight * @id_h: high 64bit of the compat_id 112*4ba0b2c2SRuss Weight * @id_l: low 64bit of the compat_id 113*4ba0b2c2SRuss Weight */ 114*4ba0b2c2SRuss Weight struct fpga_compat_id { 115*4ba0b2c2SRuss Weight u64 id_h; 116*4ba0b2c2SRuss Weight u64 id_l; 117*4ba0b2c2SRuss Weight }; 118*4ba0b2c2SRuss Weight 119*4ba0b2c2SRuss Weight /** 120*4ba0b2c2SRuss Weight * struct fpga_manager_info - collection of parameters for an FPGA Manager 121*4ba0b2c2SRuss Weight * @name: fpga manager name 122*4ba0b2c2SRuss Weight * @compat_id: FPGA manager id for compatibility check. 123*4ba0b2c2SRuss Weight * @mops: pointer to structure of fpga manager ops 124*4ba0b2c2SRuss Weight * @priv: fpga manager private data 125*4ba0b2c2SRuss Weight * 126*4ba0b2c2SRuss Weight * fpga_manager_info contains parameters for the register_full function. 127*4ba0b2c2SRuss Weight * These are separated into an info structure because they some are optional 128*4ba0b2c2SRuss Weight * others could be added to in the future. The info structure facilitates 129*4ba0b2c2SRuss Weight * maintaining a stable API. 130*4ba0b2c2SRuss Weight */ 131*4ba0b2c2SRuss Weight struct fpga_manager_info { 132*4ba0b2c2SRuss Weight const char *name; 133*4ba0b2c2SRuss Weight struct fpga_compat_id *compat_id; 134*4ba0b2c2SRuss Weight const struct fpga_manager_ops *mops; 135*4ba0b2c2SRuss Weight void *priv; 136*4ba0b2c2SRuss Weight }; 137*4ba0b2c2SRuss Weight 138*4ba0b2c2SRuss Weight /** 1396a8c3be7SAlan Tull * struct fpga_manager_ops - ops for low level fpga manager drivers 1401d7f1589SJason Gunthorpe * @initial_header_size: Maximum number of bytes that should be passed into write_init 1416a8c3be7SAlan Tull * @state: returns an enum value of the FPGA's state 142ecb5fbe2SWu Hao * @status: returns status of the FPGA, including reconfiguration error code 143580e3137STom Rix * @write_init: prepare the FPGA to receive configuration data 1446a8c3be7SAlan Tull * @write: write count bytes of configuration data to the FPGA 145baa6d396SJason Gunthorpe * @write_sg: write the scatter list of configuration data to the FPGA 1466a8c3be7SAlan Tull * @write_complete: set FPGA to operating state after writing is done 1476a8c3be7SAlan Tull * @fpga_remove: optional: Set FPGA into a specific state during driver remove 148845089bbSAlan Tull * @groups: optional attribute groups. 1496a8c3be7SAlan Tull * 1506a8c3be7SAlan Tull * fpga_manager_ops are the low level functions implemented by a specific 1516a8c3be7SAlan Tull * fpga manager driver. The optional ones are tested for NULL before being 1526a8c3be7SAlan Tull * called, so leaving them out is fine. 1536a8c3be7SAlan Tull */ 1546a8c3be7SAlan Tull struct fpga_manager_ops { 1551d7f1589SJason Gunthorpe size_t initial_header_size; 1566a8c3be7SAlan Tull enum fpga_mgr_states (*state)(struct fpga_manager *mgr); 157ecb5fbe2SWu Hao u64 (*status)(struct fpga_manager *mgr); 1581df2865fSAlan Tull int (*write_init)(struct fpga_manager *mgr, 1591df2865fSAlan Tull struct fpga_image_info *info, 1606a8c3be7SAlan Tull const char *buf, size_t count); 1616a8c3be7SAlan Tull int (*write)(struct fpga_manager *mgr, const char *buf, size_t count); 162baa6d396SJason Gunthorpe int (*write_sg)(struct fpga_manager *mgr, struct sg_table *sgt); 1631df2865fSAlan Tull int (*write_complete)(struct fpga_manager *mgr, 1641df2865fSAlan Tull struct fpga_image_info *info); 1656a8c3be7SAlan Tull void (*fpga_remove)(struct fpga_manager *mgr); 166845089bbSAlan Tull const struct attribute_group **groups; 1676a8c3be7SAlan Tull }; 1686a8c3be7SAlan Tull 169ecb5fbe2SWu Hao /* FPGA manager status: Partial/Full Reconfiguration errors */ 170ecb5fbe2SWu Hao #define FPGA_MGR_STATUS_OPERATION_ERR BIT(0) 171ecb5fbe2SWu Hao #define FPGA_MGR_STATUS_CRC_ERR BIT(1) 172ecb5fbe2SWu Hao #define FPGA_MGR_STATUS_INCOMPATIBLE_IMAGE_ERR BIT(2) 173ecb5fbe2SWu Hao #define FPGA_MGR_STATUS_IP_PROTOCOL_ERR BIT(3) 174ecb5fbe2SWu Hao #define FPGA_MGR_STATUS_FIFO_OVERFLOW_ERR BIT(4) 175ecb5fbe2SWu Hao 1766a8c3be7SAlan Tull /** 1776a8c3be7SAlan Tull * struct fpga_manager - fpga manager structure 1786a8c3be7SAlan Tull * @name: name of low level fpga manager 1796a8c3be7SAlan Tull * @dev: fpga manager device 1806a8c3be7SAlan Tull * @ref_mutex: only allows one reference to fpga manager 1816a8c3be7SAlan Tull * @state: state of fpga manager 18299a560bdSWu Hao * @compat_id: FPGA manager id for compatibility check. 1836a8c3be7SAlan Tull * @mops: pointer to struct of fpga manager ops 1846a8c3be7SAlan Tull * @priv: low level driver private date 1856a8c3be7SAlan Tull */ 1866a8c3be7SAlan Tull struct fpga_manager { 1876a8c3be7SAlan Tull const char *name; 1886a8c3be7SAlan Tull struct device dev; 1896a8c3be7SAlan Tull struct mutex ref_mutex; 1906a8c3be7SAlan Tull enum fpga_mgr_states state; 19199a560bdSWu Hao struct fpga_compat_id *compat_id; 1926a8c3be7SAlan Tull const struct fpga_manager_ops *mops; 1936a8c3be7SAlan Tull void *priv; 1946a8c3be7SAlan Tull }; 1956a8c3be7SAlan Tull 1966a8c3be7SAlan Tull #define to_fpga_manager(d) container_of(d, struct fpga_manager, dev) 1976a8c3be7SAlan Tull 1985cf0c7f6SAlan Tull struct fpga_image_info *fpga_image_info_alloc(struct device *dev); 1996a8c3be7SAlan Tull 2005cf0c7f6SAlan Tull void fpga_image_info_free(struct fpga_image_info *info); 2015cf0c7f6SAlan Tull 2025cf0c7f6SAlan Tull int fpga_mgr_load(struct fpga_manager *mgr, struct fpga_image_info *info); 2036a8c3be7SAlan Tull 204ebf877a5SAlan Tull int fpga_mgr_lock(struct fpga_manager *mgr); 205ebf877a5SAlan Tull void fpga_mgr_unlock(struct fpga_manager *mgr); 206ebf877a5SAlan Tull 2076a8c3be7SAlan Tull struct fpga_manager *of_fpga_mgr_get(struct device_node *node); 2086a8c3be7SAlan Tull 2099dce0287SAlan Tull struct fpga_manager *fpga_mgr_get(struct device *dev); 2109dce0287SAlan Tull 2116a8c3be7SAlan Tull void fpga_mgr_put(struct fpga_manager *mgr); 2126a8c3be7SAlan Tull 213*4ba0b2c2SRuss Weight struct fpga_manager * 214*4ba0b2c2SRuss Weight fpga_mgr_register_full(struct device *parent, const struct fpga_manager_info *info); 215*4ba0b2c2SRuss Weight 216*4ba0b2c2SRuss Weight struct fpga_manager * 217*4ba0b2c2SRuss Weight fpga_mgr_register(struct device *parent, const char *name, 218*4ba0b2c2SRuss Weight const struct fpga_manager_ops *mops, void *priv); 2197085e2a9SAlan Tull void fpga_mgr_unregister(struct fpga_manager *mgr); 2206a8c3be7SAlan Tull 221*4ba0b2c2SRuss Weight struct fpga_manager * 222*4ba0b2c2SRuss Weight devm_fpga_mgr_register_full(struct device *parent, const struct fpga_manager_info *info); 223*4ba0b2c2SRuss Weight struct fpga_manager * 224*4ba0b2c2SRuss Weight devm_fpga_mgr_register(struct device *parent, const char *name, 225*4ba0b2c2SRuss Weight const struct fpga_manager_ops *mops, void *priv); 226084181feSAlan Tull 2276a8c3be7SAlan Tull #endif /*_LINUX_FPGA_MGR_H */ 228