1 /* SPDX-License-Identifier: GPL-2.0 */ 2 /* 3 * FPGA Framework 4 * 5 * Copyright (C) 2013-2016 Altera Corporation 6 * Copyright (C) 2017 Intel Corporation 7 */ 8 #ifndef _LINUX_FPGA_MGR_H 9 #define _LINUX_FPGA_MGR_H 10 11 #include <linux/mutex.h> 12 #include <linux/platform_device.h> 13 14 struct fpga_manager; 15 struct sg_table; 16 17 /** 18 * enum fpga_mgr_states - fpga framework states 19 * @FPGA_MGR_STATE_UNKNOWN: can't determine state 20 * @FPGA_MGR_STATE_POWER_OFF: FPGA power is off 21 * @FPGA_MGR_STATE_POWER_UP: FPGA reports power is up 22 * @FPGA_MGR_STATE_RESET: FPGA in reset state 23 * @FPGA_MGR_STATE_FIRMWARE_REQ: firmware request in progress 24 * @FPGA_MGR_STATE_FIRMWARE_REQ_ERR: firmware request failed 25 * @FPGA_MGR_STATE_PARSE_HEADER: parse FPGA image header 26 * @FPGA_MGR_STATE_PARSE_HEADER_ERR: Error during PARSE_HEADER stage 27 * @FPGA_MGR_STATE_WRITE_INIT: preparing FPGA for programming 28 * @FPGA_MGR_STATE_WRITE_INIT_ERR: Error during WRITE_INIT stage 29 * @FPGA_MGR_STATE_WRITE: writing image to FPGA 30 * @FPGA_MGR_STATE_WRITE_ERR: Error while writing FPGA 31 * @FPGA_MGR_STATE_WRITE_COMPLETE: Doing post programming steps 32 * @FPGA_MGR_STATE_WRITE_COMPLETE_ERR: Error during WRITE_COMPLETE 33 * @FPGA_MGR_STATE_OPERATING: FPGA is programmed and operating 34 */ 35 enum fpga_mgr_states { 36 /* default FPGA states */ 37 FPGA_MGR_STATE_UNKNOWN, 38 FPGA_MGR_STATE_POWER_OFF, 39 FPGA_MGR_STATE_POWER_UP, 40 FPGA_MGR_STATE_RESET, 41 42 /* getting an image for loading */ 43 FPGA_MGR_STATE_FIRMWARE_REQ, 44 FPGA_MGR_STATE_FIRMWARE_REQ_ERR, 45 46 /* write sequence: parse header, init, write, complete */ 47 FPGA_MGR_STATE_PARSE_HEADER, 48 FPGA_MGR_STATE_PARSE_HEADER_ERR, 49 FPGA_MGR_STATE_WRITE_INIT, 50 FPGA_MGR_STATE_WRITE_INIT_ERR, 51 FPGA_MGR_STATE_WRITE, 52 FPGA_MGR_STATE_WRITE_ERR, 53 FPGA_MGR_STATE_WRITE_COMPLETE, 54 FPGA_MGR_STATE_WRITE_COMPLETE_ERR, 55 56 /* fpga is programmed and operating */ 57 FPGA_MGR_STATE_OPERATING, 58 }; 59 60 /** 61 * DOC: FPGA Manager flags 62 * 63 * Flags used in the &fpga_image_info->flags field 64 * 65 * %FPGA_MGR_PARTIAL_RECONFIG: do partial reconfiguration if supported 66 * 67 * %FPGA_MGR_EXTERNAL_CONFIG: FPGA has been configured prior to Linux booting 68 * 69 * %FPGA_MGR_ENCRYPTED_BITSTREAM: indicates bitstream is encrypted 70 * 71 * %FPGA_MGR_BITSTREAM_LSB_FIRST: SPI bitstream bit order is LSB first 72 * 73 * %FPGA_MGR_COMPRESSED_BITSTREAM: FPGA bitstream is compressed 74 */ 75 #define FPGA_MGR_PARTIAL_RECONFIG BIT(0) 76 #define FPGA_MGR_EXTERNAL_CONFIG BIT(1) 77 #define FPGA_MGR_ENCRYPTED_BITSTREAM BIT(2) 78 #define FPGA_MGR_BITSTREAM_LSB_FIRST BIT(3) 79 #define FPGA_MGR_COMPRESSED_BITSTREAM BIT(4) 80 81 /** 82 * struct fpga_image_info - information specific to an FPGA image 83 * @flags: boolean flags as defined above 84 * @enable_timeout_us: maximum time to enable traffic through bridge (uSec) 85 * @disable_timeout_us: maximum time to disable traffic through bridge (uSec) 86 * @config_complete_timeout_us: maximum time for FPGA to switch to operating 87 * status in the write_complete op. 88 * @firmware_name: name of FPGA image firmware file 89 * @sgt: scatter/gather table containing FPGA image 90 * @buf: contiguous buffer containing FPGA image 91 * @count: size of buf 92 * @header_size: size of image header. 93 * @data_size: size of image data to be sent to the device. If not specified, 94 * whole image will be used. Header may be skipped in either case. 95 * @region_id: id of target region 96 * @dev: device that owns this 97 * @overlay: Device Tree overlay 98 */ 99 struct fpga_image_info { 100 u32 flags; 101 u32 enable_timeout_us; 102 u32 disable_timeout_us; 103 u32 config_complete_timeout_us; 104 char *firmware_name; 105 struct sg_table *sgt; 106 const char *buf; 107 size_t count; 108 size_t header_size; 109 size_t data_size; 110 int region_id; 111 struct device *dev; 112 #ifdef CONFIG_OF 113 struct device_node *overlay; 114 #endif 115 }; 116 117 /** 118 * struct fpga_compat_id - id for compatibility check 119 * 120 * @id_h: high 64bit of the compat_id 121 * @id_l: low 64bit of the compat_id 122 */ 123 struct fpga_compat_id { 124 u64 id_h; 125 u64 id_l; 126 }; 127 128 /** 129 * struct fpga_manager_info - collection of parameters for an FPGA Manager 130 * @name: fpga manager name 131 * @compat_id: FPGA manager id for compatibility check. 132 * @mops: pointer to structure of fpga manager ops 133 * @priv: fpga manager private data 134 * 135 * fpga_manager_info contains parameters for the register_full function. 136 * These are separated into an info structure because they some are optional 137 * others could be added to in the future. The info structure facilitates 138 * maintaining a stable API. 139 */ 140 struct fpga_manager_info { 141 const char *name; 142 struct fpga_compat_id *compat_id; 143 const struct fpga_manager_ops *mops; 144 void *priv; 145 }; 146 147 /** 148 * struct fpga_manager_ops - ops for low level fpga manager drivers 149 * @initial_header_size: minimum number of bytes that should be passed into 150 * parse_header and write_init. 151 * @skip_header: bool flag to tell fpga-mgr core whether it should skip 152 * info->header_size part at the beginning of the image when invoking 153 * write callback. 154 * @state: returns an enum value of the FPGA's state 155 * @status: returns status of the FPGA, including reconfiguration error code 156 * @parse_header: parse FPGA image header to set info->header_size and 157 * info->data_size. In case the input buffer is not large enough, set 158 * required size to info->header_size and return -EAGAIN. 159 * @write_init: prepare the FPGA to receive configuration data 160 * @write: write count bytes of configuration data to the FPGA 161 * @write_sg: write the scatter list of configuration data to the FPGA 162 * @write_complete: set FPGA to operating state after writing is done 163 * @fpga_remove: optional: Set FPGA into a specific state during driver remove 164 * @groups: optional attribute groups. 165 * 166 * fpga_manager_ops are the low level functions implemented by a specific 167 * fpga manager driver. The optional ones are tested for NULL before being 168 * called, so leaving them out is fine. 169 */ 170 struct fpga_manager_ops { 171 size_t initial_header_size; 172 bool skip_header; 173 enum fpga_mgr_states (*state)(struct fpga_manager *mgr); 174 u64 (*status)(struct fpga_manager *mgr); 175 int (*parse_header)(struct fpga_manager *mgr, 176 struct fpga_image_info *info, 177 const char *buf, size_t count); 178 int (*write_init)(struct fpga_manager *mgr, 179 struct fpga_image_info *info, 180 const char *buf, size_t count); 181 int (*write)(struct fpga_manager *mgr, const char *buf, size_t count); 182 int (*write_sg)(struct fpga_manager *mgr, struct sg_table *sgt); 183 int (*write_complete)(struct fpga_manager *mgr, 184 struct fpga_image_info *info); 185 void (*fpga_remove)(struct fpga_manager *mgr); 186 const struct attribute_group **groups; 187 }; 188 189 /* FPGA manager status: Partial/Full Reconfiguration errors */ 190 #define FPGA_MGR_STATUS_OPERATION_ERR BIT(0) 191 #define FPGA_MGR_STATUS_CRC_ERR BIT(1) 192 #define FPGA_MGR_STATUS_INCOMPATIBLE_IMAGE_ERR BIT(2) 193 #define FPGA_MGR_STATUS_IP_PROTOCOL_ERR BIT(3) 194 #define FPGA_MGR_STATUS_FIFO_OVERFLOW_ERR BIT(4) 195 196 /** 197 * struct fpga_manager - fpga manager structure 198 * @name: name of low level fpga manager 199 * @dev: fpga manager device 200 * @ref_mutex: only allows one reference to fpga manager 201 * @state: state of fpga manager 202 * @compat_id: FPGA manager id for compatibility check. 203 * @mops: pointer to struct of fpga manager ops 204 * @mops_owner: module containing the mops 205 * @priv: low level driver private date 206 */ 207 struct fpga_manager { 208 const char *name; 209 struct device dev; 210 struct mutex ref_mutex; 211 enum fpga_mgr_states state; 212 struct fpga_compat_id *compat_id; 213 const struct fpga_manager_ops *mops; 214 struct module *mops_owner; 215 void *priv; 216 }; 217 218 #define to_fpga_manager(d) container_of(d, struct fpga_manager, dev) 219 220 struct fpga_image_info *fpga_image_info_alloc(struct device *dev); 221 222 void fpga_image_info_free(struct fpga_image_info *info); 223 224 int fpga_mgr_load(struct fpga_manager *mgr, struct fpga_image_info *info); 225 226 int fpga_mgr_lock(struct fpga_manager *mgr); 227 void fpga_mgr_unlock(struct fpga_manager *mgr); 228 229 struct fpga_manager *of_fpga_mgr_get(struct device_node *node); 230 231 struct fpga_manager *fpga_mgr_get(struct device *dev); 232 233 void fpga_mgr_put(struct fpga_manager *mgr); 234 235 #define fpga_mgr_register_full(parent, info) \ 236 __fpga_mgr_register_full(parent, info, THIS_MODULE) 237 struct fpga_manager * 238 __fpga_mgr_register_full(struct device *parent, const struct fpga_manager_info *info, 239 struct module *owner); 240 241 #define fpga_mgr_register(parent, name, mops, priv) \ 242 __fpga_mgr_register(parent, name, mops, priv, THIS_MODULE) 243 struct fpga_manager * 244 __fpga_mgr_register(struct device *parent, const char *name, 245 const struct fpga_manager_ops *mops, void *priv, struct module *owner); 246 247 void fpga_mgr_unregister(struct fpga_manager *mgr); 248 249 #define devm_fpga_mgr_register_full(parent, info) \ 250 __devm_fpga_mgr_register_full(parent, info, THIS_MODULE) 251 struct fpga_manager * 252 __devm_fpga_mgr_register_full(struct device *parent, const struct fpga_manager_info *info, 253 struct module *owner); 254 #define devm_fpga_mgr_register(parent, name, mops, priv) \ 255 __devm_fpga_mgr_register(parent, name, mops, priv, THIS_MODULE) 256 struct fpga_manager * 257 __devm_fpga_mgr_register(struct device *parent, const char *name, 258 const struct fpga_manager_ops *mops, void *priv, 259 struct module *owner); 260 261 #endif /*_LINUX_FPGA_MGR_H */ 262