Commit | Line | Data |
---|---|---|
473f01f7 | 1 | /* SPDX-License-Identifier: GPL-2.0 */ |
6a8c3be7 AT |
2 | /* |
3 | * FPGA Framework | |
4 | * | |
5cf0c7f6 AT |
5 | * Copyright (C) 2013-2016 Altera Corporation |
6 | * Copyright (C) 2017 Intel Corporation | |
6a8c3be7 | 7 | */ |
6a8c3be7 AT |
8 | #ifndef _LINUX_FPGA_MGR_H |
9 | #define _LINUX_FPGA_MGR_H | |
10 | ||
5cf0c7f6 AT |
11 | #include <linux/mutex.h> |
12 | #include <linux/platform_device.h> | |
13 | ||
6a8c3be7 | 14 | struct fpga_manager; |
baa6d396 | 15 | struct sg_table; |
6a8c3be7 AT |
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 | |
3cc624be IB |
25 | * @FPGA_MGR_STATE_PARSE_HEADER: parse FPGA image header |
26 | * @FPGA_MGR_STATE_PARSE_HEADER_ERR: Error during PARSE_HEADER stage | |
6a8c3be7 AT |
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 | ||
3cc624be IB |
46 | /* write sequence: parse header, init, write, complete */ |
47 | FPGA_MGR_STATE_PARSE_HEADER, | |
48 | FPGA_MGR_STATE_PARSE_HEADER_ERR, | |
6a8c3be7 AT |
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 | ||
492ecf6d AT |
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 | |
6a8c3be7 AT |
74 | */ |
75 | #define FPGA_MGR_PARTIAL_RECONFIG BIT(0) | |
0fa20cdf | 76 | #define FPGA_MGR_EXTERNAL_CONFIG BIT(1) |
0f4f0c8f | 77 | #define FPGA_MGR_ENCRYPTED_BITSTREAM BIT(2) |
68f6be65 | 78 | #define FPGA_MGR_BITSTREAM_LSB_FIRST BIT(3) |
b37fa560 | 79 | #define FPGA_MGR_COMPRESSED_BITSTREAM BIT(4) |
6a8c3be7 | 80 | |
1df2865f | 81 | /** |
895ec9c0 | 82 | * struct fpga_image_info - information specific to an FPGA image |
1df2865f AT |
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) | |
42d5ec95 AT |
86 | * @config_complete_timeout_us: maximum time for FPGA to switch to operating |
87 | * status in the write_complete op. | |
5cf0c7f6 AT |
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 | |
3cc624be IB |
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. | |
571d78bd | 95 | * @region_id: id of target region |
5cf0c7f6 | 96 | * @dev: device that owns this |
61c32102 | 97 | * @overlay: Device Tree overlay |
1df2865f AT |
98 | */ |
99 | struct fpga_image_info { | |
100 | u32 flags; | |
101 | u32 enable_timeout_us; | |
102 | u32 disable_timeout_us; | |
42d5ec95 | 103 | u32 config_complete_timeout_us; |
5cf0c7f6 AT |
104 | char *firmware_name; |
105 | struct sg_table *sgt; | |
106 | const char *buf; | |
107 | size_t count; | |
3cc624be IB |
108 | size_t header_size; |
109 | size_t data_size; | |
571d78bd | 110 | int region_id; |
5cf0c7f6 | 111 | struct device *dev; |
61c32102 AT |
112 | #ifdef CONFIG_OF |
113 | struct device_node *overlay; | |
114 | #endif | |
1df2865f AT |
115 | }; |
116 | ||
4ba0b2c2 RW |
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 | ||
6a8c3be7 AT |
147 | /** |
148 | * struct fpga_manager_ops - ops for low level fpga manager drivers | |
3cc624be IB |
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. | |
6a8c3be7 | 154 | * @state: returns an enum value of the FPGA's state |
ecb5fbe2 | 155 | * @status: returns status of the FPGA, including reconfiguration error code |
3cc624be IB |
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. | |
580e3137 | 159 | * @write_init: prepare the FPGA to receive configuration data |
6a8c3be7 | 160 | * @write: write count bytes of configuration data to the FPGA |
baa6d396 | 161 | * @write_sg: write the scatter list of configuration data to the FPGA |
6a8c3be7 AT |
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 | |
845089bb | 164 | * @groups: optional attribute groups. |
6a8c3be7 AT |
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 { | |
1d7f1589 | 171 | size_t initial_header_size; |
3cc624be | 172 | bool skip_header; |
6a8c3be7 | 173 | enum fpga_mgr_states (*state)(struct fpga_manager *mgr); |
ecb5fbe2 | 174 | u64 (*status)(struct fpga_manager *mgr); |
3cc624be IB |
175 | int (*parse_header)(struct fpga_manager *mgr, |
176 | struct fpga_image_info *info, | |
177 | const char *buf, size_t count); | |
1df2865f AT |
178 | int (*write_init)(struct fpga_manager *mgr, |
179 | struct fpga_image_info *info, | |
6a8c3be7 AT |
180 | const char *buf, size_t count); |
181 | int (*write)(struct fpga_manager *mgr, const char *buf, size_t count); | |
baa6d396 | 182 | int (*write_sg)(struct fpga_manager *mgr, struct sg_table *sgt); |
1df2865f AT |
183 | int (*write_complete)(struct fpga_manager *mgr, |
184 | struct fpga_image_info *info); | |
6a8c3be7 | 185 | void (*fpga_remove)(struct fpga_manager *mgr); |
845089bb | 186 | const struct attribute_group **groups; |
6a8c3be7 AT |
187 | }; |
188 | ||
ecb5fbe2 WH |
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 | ||
6a8c3be7 AT |
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 | |
99a560bd | 202 | * @compat_id: FPGA manager id for compatibility check. |
6a8c3be7 | 203 | * @mops: pointer to struct of fpga manager ops |
4d4d2d43 | 204 | * @mops_owner: module containing the mops |
6a8c3be7 AT |
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; | |
99a560bd | 212 | struct fpga_compat_id *compat_id; |
6a8c3be7 | 213 | const struct fpga_manager_ops *mops; |
4d4d2d43 | 214 | struct module *mops_owner; |
6a8c3be7 AT |
215 | void *priv; |
216 | }; | |
217 | ||
218 | #define to_fpga_manager(d) container_of(d, struct fpga_manager, dev) | |
219 | ||
5cf0c7f6 AT |
220 | struct fpga_image_info *fpga_image_info_alloc(struct device *dev); |
221 | ||
222 | void fpga_image_info_free(struct fpga_image_info *info); | |
6a8c3be7 | 223 | |
5cf0c7f6 | 224 | int fpga_mgr_load(struct fpga_manager *mgr, struct fpga_image_info *info); |
6a8c3be7 | 225 | |
ebf877a5 AT |
226 | int fpga_mgr_lock(struct fpga_manager *mgr); |
227 | void fpga_mgr_unlock(struct fpga_manager *mgr); | |
228 | ||
6a8c3be7 AT |
229 | struct fpga_manager *of_fpga_mgr_get(struct device_node *node); |
230 | ||
9dce0287 AT |
231 | struct fpga_manager *fpga_mgr_get(struct device *dev); |
232 | ||
6a8c3be7 AT |
233 | void fpga_mgr_put(struct fpga_manager *mgr); |
234 | ||
4d4d2d43 MP |
235 | #define fpga_mgr_register_full(parent, info) \ |
236 | __fpga_mgr_register_full(parent, info, THIS_MODULE) | |
4ba0b2c2 | 237 | struct fpga_manager * |
4d4d2d43 MP |
238 | __fpga_mgr_register_full(struct device *parent, const struct fpga_manager_info *info, |
239 | struct module *owner); | |
6a8c3be7 | 240 | |
4d4d2d43 MP |
241 | #define fpga_mgr_register(parent, name, mops, priv) \ |
242 | __fpga_mgr_register(parent, name, mops, priv, THIS_MODULE) | |
4ba0b2c2 | 243 | struct fpga_manager * |
4d4d2d43 MP |
244 | __fpga_mgr_register(struct device *parent, const char *name, |
245 | const struct fpga_manager_ops *mops, void *priv, struct module *owner); | |
246 | ||
4ba0b2c2 | 247 | void fpga_mgr_unregister(struct fpga_manager *mgr); |
57d9352b | 248 | |
4d4d2d43 MP |
249 | #define devm_fpga_mgr_register_full(parent, info) \ |
250 | __devm_fpga_mgr_register_full(parent, info, THIS_MODULE) | |
4ba0b2c2 | 251 | struct fpga_manager * |
4d4d2d43 MP |
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) | |
4ba0b2c2 | 256 | struct fpga_manager * |
4d4d2d43 MP |
257 | __devm_fpga_mgr_register(struct device *parent, const char *name, |
258 | const struct fpga_manager_ops *mops, void *priv, | |
259 | struct module *owner); | |
084181fe | 260 | |
6a8c3be7 | 261 | #endif /*_LINUX_FPGA_MGR_H */ |