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 | , |
48 | , |
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 ; |
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 ; |
172 | bool ; |
173 | enum fpga_mgr_states (*state)(struct fpga_manager *mgr); |
174 | u64 (*status)(struct fpga_manager *mgr); |
175 | int (*)(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 | * @priv: low level driver private date |
205 | */ |
206 | struct fpga_manager { |
207 | const char *name; |
208 | struct device dev; |
209 | struct mutex ref_mutex; |
210 | enum fpga_mgr_states state; |
211 | struct fpga_compat_id *compat_id; |
212 | const struct fpga_manager_ops *mops; |
213 | void *priv; |
214 | }; |
215 | |
216 | #define to_fpga_manager(d) container_of(d, struct fpga_manager, dev) |
217 | |
218 | struct fpga_image_info *fpga_image_info_alloc(struct device *dev); |
219 | |
220 | void fpga_image_info_free(struct fpga_image_info *info); |
221 | |
222 | int fpga_mgr_load(struct fpga_manager *mgr, struct fpga_image_info *info); |
223 | |
224 | int fpga_mgr_lock(struct fpga_manager *mgr); |
225 | void fpga_mgr_unlock(struct fpga_manager *mgr); |
226 | |
227 | struct fpga_manager *of_fpga_mgr_get(struct device_node *node); |
228 | |
229 | struct fpga_manager *fpga_mgr_get(struct device *dev); |
230 | |
231 | void fpga_mgr_put(struct fpga_manager *mgr); |
232 | |
233 | struct fpga_manager * |
234 | fpga_mgr_register_full(struct device *parent, const struct fpga_manager_info *info); |
235 | |
236 | struct fpga_manager * |
237 | fpga_mgr_register(struct device *parent, const char *name, |
238 | const struct fpga_manager_ops *mops, void *priv); |
239 | void fpga_mgr_unregister(struct fpga_manager *mgr); |
240 | |
241 | struct fpga_manager * |
242 | devm_fpga_mgr_register_full(struct device *parent, const struct fpga_manager_info *info); |
243 | struct fpga_manager * |
244 | devm_fpga_mgr_register(struct device *parent, const char *name, |
245 | const struct fpga_manager_ops *mops, void *priv); |
246 | |
247 | #endif /*_LINUX_FPGA_MGR_H */ |
248 | |