Commit | Line | Data |
---|---|---|
e8f5fda1 AT |
1 | FPGA Manager Core |
2 | ||
3 | Alan Tull 2015 | |
4 | ||
5 | Overview | |
6 | ======== | |
7 | ||
8 | The FPGA manager core exports a set of functions for programming an FPGA with | |
9 | an image. The API is manufacturer agnostic. All manufacturer specifics are | |
10 | hidden away in a low level driver which registers a set of ops with the core. | |
11 | The FPGA image data itself is very manufacturer specific, but for our purposes | |
12 | it's just binary data. The FPGA manager core won't parse it. | |
13 | ||
5cf0c7f6 AT |
14 | The FPGA image to be programmed can be in a scatter gather list, a single |
15 | contiguous buffer, or a firmware file. Because allocating contiguous kernel | |
16 | memory for the buffer should be avoided, users are encouraged to use a scatter | |
17 | gather list instead if possible. | |
18 | ||
19 | The particulars for programming the image are presented in a structure (struct | |
20 | fpga_image_info). This struct contains parameters such as pointers to the | |
21 | FPGA image as well as image-specific particulars such as whether the image was | |
22 | built for full or partial reconfiguration. | |
e8f5fda1 AT |
23 | |
24 | API Functions: | |
25 | ============== | |
26 | ||
5cf0c7f6 AT |
27 | To program the FPGA: |
28 | -------------------- | |
baa6d396 | 29 | |
5cf0c7f6 AT |
30 | int fpga_mgr_load(struct fpga_manager *mgr, |
31 | struct fpga_image_info *info); | |
e8f5fda1 | 32 | |
5cf0c7f6 | 33 | Load the FPGA from an image which is indicated in the info. If successful, |
40e83578 AT |
34 | the FPGA ends up in operating mode. Return 0 on success or a negative error |
35 | code. | |
e8f5fda1 | 36 | |
5cf0c7f6 AT |
37 | To allocate or free a struct fpga_image_info: |
38 | --------------------------------------------- | |
39 | ||
40 | struct fpga_image_info *fpga_image_info_alloc(struct device *dev); | |
41 | ||
42 | void fpga_image_info_free(struct fpga_image_info *info); | |
e8f5fda1 AT |
43 | |
44 | To get/put a reference to a FPGA manager: | |
45 | ----------------------------------------- | |
46 | ||
47 | struct fpga_manager *of_fpga_mgr_get(struct device_node *node); | |
9dce0287 | 48 | struct fpga_manager *fpga_mgr_get(struct device *dev); |
e8f5fda1 AT |
49 | void fpga_mgr_put(struct fpga_manager *mgr); |
50 | ||
ebf877a5 AT |
51 | Given a DT node or device, get a reference to a FPGA manager. This pointer |
52 | can be saved until you are ready to program the FPGA. fpga_mgr_put releases | |
53 | the reference. | |
54 | ||
55 | ||
56 | To get exclusive control of a FPGA manager: | |
57 | ------------------------------------------- | |
58 | ||
59 | int fpga_mgr_lock(struct fpga_manager *mgr); | |
60 | void fpga_mgr_unlock(struct fpga_manager *mgr); | |
61 | ||
62 | The user should call fpga_mgr_lock and verify that it returns 0 before | |
63 | attempting to program the FPGA. Likewise, the user should call | |
64 | fpga_mgr_unlock when done programming the FPGA. | |
e8f5fda1 | 65 | |
7085e2a9 AT |
66 | To alloc/free a FPGA manager struct: |
67 | ------------------------------------ | |
68 | ||
69 | struct fpga_manager *fpga_mgr_create(struct device *dev, | |
70 | const char *name, | |
71 | const struct fpga_manager_ops *mops, | |
72 | void *priv); | |
73 | void fpga_mgr_free(struct fpga_manager *mgr); | |
e8f5fda1 AT |
74 | |
75 | To register or unregister the low level FPGA-specific driver: | |
76 | ------------------------------------------------------------- | |
77 | ||
7085e2a9 | 78 | int fpga_mgr_register(struct fpga_manager *mgr); |
e8f5fda1 | 79 | |
7085e2a9 | 80 | void fpga_mgr_unregister(struct fpga_manager *mgr); |
e8f5fda1 | 81 | |
7085e2a9 | 82 | Use of these functions is described below in "How To Support a new FPGA |
e8f5fda1 AT |
83 | device." |
84 | ||
85 | ||
86 | How to write an image buffer to a supported FPGA | |
87 | ================================================ | |
e8f5fda1 AT |
88 | #include <linux/fpga/fpga-mgr.h> |
89 | ||
5cf0c7f6 AT |
90 | struct fpga_manager *mgr; |
91 | struct fpga_image_info *info; | |
92 | int ret; | |
e8f5fda1 | 93 | |
ebf877a5 AT |
94 | /* |
95 | * Get a reference to FPGA manager. The manager is not locked, so you can | |
96 | * hold onto this reference without it preventing programming. | |
97 | * | |
98 | * This example uses the device node of the manager. Alternatively, use | |
99 | * fpga_mgr_get(dev) instead if you have the device. | |
100 | */ | |
101 | mgr = of_fpga_mgr_get(mgr_node); | |
102 | ||
40e83578 | 103 | /* struct with information about the FPGA image to program. */ |
5cf0c7f6 | 104 | info = fpga_image_info_alloc(dev); |
40e83578 | 105 | |
e8f5fda1 | 106 | /* flags indicates whether to do full or partial reconfiguration */ |
5cf0c7f6 | 107 | info->flags = FPGA_MGR_PARTIAL_RECONFIG; |
e8f5fda1 | 108 | |
5cf0c7f6 AT |
109 | /* |
110 | * At this point, indicate where the image is. This is pseudo-code; you're | |
111 | * going to use one of these three. | |
112 | */ | |
113 | if (image is in a scatter gather table) { | |
e8f5fda1 | 114 | |
5cf0c7f6 | 115 | info->sgt = [your scatter gather table] |
e8f5fda1 | 116 | |
5cf0c7f6 | 117 | } else if (image is in a buffer) { |
e8f5fda1 | 118 | |
5cf0c7f6 AT |
119 | info->buf = [your image buffer] |
120 | info->count = [image buffer size] | |
e8f5fda1 | 121 | |
5cf0c7f6 | 122 | } else if (image is in a firmware file) { |
e8f5fda1 | 123 | |
5cf0c7f6 | 124 | info->firmware_name = devm_kstrdup(dev, firmware_name, GFP_KERNEL); |
40e83578 | 125 | |
5cf0c7f6 | 126 | } |
e8f5fda1 | 127 | |
ebf877a5 AT |
128 | /* Get exclusive control of FPGA manager */ |
129 | ret = fpga_mgr_lock(mgr); | |
e8f5fda1 | 130 | |
5cf0c7f6 AT |
131 | /* Load the buffer to the FPGA */ |
132 | ret = fpga_mgr_buf_load(mgr, &info, buf, count); | |
e8f5fda1 AT |
133 | |
134 | /* Release the FPGA manager */ | |
ebf877a5 | 135 | fpga_mgr_unlock(mgr); |
e8f5fda1 AT |
136 | fpga_mgr_put(mgr); |
137 | ||
5cf0c7f6 AT |
138 | /* Deallocate the image info if you're done with it */ |
139 | fpga_image_info_free(info); | |
e8f5fda1 AT |
140 | |
141 | How to support a new FPGA device | |
142 | ================================ | |
143 | To add another FPGA manager, write a driver that implements a set of ops. The | |
144 | probe function calls fpga_mgr_register(), such as: | |
145 | ||
146 | static const struct fpga_manager_ops socfpga_fpga_ops = { | |
147 | .write_init = socfpga_fpga_ops_configure_init, | |
148 | .write = socfpga_fpga_ops_configure_write, | |
149 | .write_complete = socfpga_fpga_ops_configure_complete, | |
150 | .state = socfpga_fpga_ops_state, | |
151 | }; | |
152 | ||
153 | static int socfpga_fpga_probe(struct platform_device *pdev) | |
154 | { | |
155 | struct device *dev = &pdev->dev; | |
156 | struct socfpga_fpga_priv *priv; | |
7085e2a9 | 157 | struct fpga_manager *mgr; |
e8f5fda1 AT |
158 | int ret; |
159 | ||
160 | priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL); | |
161 | if (!priv) | |
162 | return -ENOMEM; | |
163 | ||
164 | /* ... do ioremaps, get interrupts, etc. and save | |
165 | them in priv... */ | |
166 | ||
7085e2a9 AT |
167 | mgr = fpga_mgr_create(dev, "Altera SOCFPGA FPGA Manager", |
168 | &socfpga_fpga_ops, priv); | |
169 | if (!mgr) | |
170 | return -ENOMEM; | |
171 | ||
172 | platform_set_drvdata(pdev, mgr); | |
173 | ||
174 | ret = fpga_mgr_register(mgr); | |
175 | if (ret) | |
176 | fpga_mgr_free(mgr); | |
177 | ||
178 | return ret; | |
e8f5fda1 AT |
179 | } |
180 | ||
181 | static int socfpga_fpga_remove(struct platform_device *pdev) | |
182 | { | |
7085e2a9 AT |
183 | struct fpga_manager *mgr = platform_get_drvdata(pdev); |
184 | ||
185 | fpga_mgr_unregister(mgr); | |
e8f5fda1 AT |
186 | |
187 | return 0; | |
188 | } | |
189 | ||
190 | ||
191 | The ops will implement whatever device specific register writes are needed to | |
192 | do the programming sequence for this particular FPGA. These ops return 0 for | |
193 | success or negative error codes otherwise. | |
194 | ||
195 | The programming sequence is: | |
196 | 1. .write_init | |
baa6d396 | 197 | 2. .write or .write_sg (may be called once or multiple times) |
e8f5fda1 AT |
198 | 3. .write_complete |
199 | ||
1d7f1589 JG |
200 | The .write_init function will prepare the FPGA to receive the image data. The |
201 | buffer passed into .write_init will be atmost .initial_header_size bytes long, | |
202 | if the whole bitstream is not immediately available then the core code will | |
203 | buffer up at least this much before starting. | |
e8f5fda1 AT |
204 | |
205 | The .write function writes a buffer to the FPGA. The buffer may be contain the | |
206 | whole FPGA image or may be a smaller chunk of an FPGA image. In the latter | |
baa6d396 JG |
207 | case, this function is called multiple times for successive chunks. This interface |
208 | is suitable for drivers which use PIO. | |
209 | ||
210 | The .write_sg version behaves the same as .write except the input is a sg_table | |
211 | scatter list. This interface is suitable for drivers which use DMA. | |
e8f5fda1 AT |
212 | |
213 | The .write_complete function is called after all the image has been written | |
214 | to put the FPGA into operating mode. | |
215 | ||
216 | The ops include a .state function which will read the hardware FPGA manager and | |
217 | return a code of type enum fpga_mgr_states. It doesn't result in a change in | |
218 | hardware state. |