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 | ||
14 | ||
15 | API Functions: | |
16 | ============== | |
17 | ||
18 | To program the FPGA from a file or from a buffer: | |
19 | ------------------------------------------------- | |
20 | ||
40e83578 AT |
21 | int fpga_mgr_buf_load(struct fpga_manager *mgr, |
22 | struct fpga_image_info *info, | |
e8f5fda1 AT |
23 | const char *buf, size_t count); |
24 | ||
baa6d396 JG |
25 | Load the FPGA from an image which exists as a contiguous buffer in |
26 | memory. Allocating contiguous kernel memory for the buffer should be avoided, | |
27 | users are encouraged to use the _sg interface instead of this. | |
28 | ||
29 | int fpga_mgr_buf_load_sg(struct fpga_manager *mgr, | |
30 | struct fpga_image_info *info, | |
31 | struct sg_table *sgt); | |
32 | ||
33 | Load the FPGA from an image from non-contiguous in memory. Callers can | |
34 | construct a sg_table using alloc_page backed memory. | |
e8f5fda1 | 35 | |
40e83578 AT |
36 | int fpga_mgr_firmware_load(struct fpga_manager *mgr, |
37 | struct fpga_image_info *info, | |
e8f5fda1 AT |
38 | const char *image_name); |
39 | ||
40 | Load the FPGA from an image which exists as a file. The image file must be on | |
40e83578 AT |
41 | the firmware search path (see the firmware class documentation). If successful, |
42 | the FPGA ends up in operating mode. Return 0 on success or a negative error | |
43 | code. | |
e8f5fda1 | 44 | |
40e83578 AT |
45 | A FPGA design contained in a FPGA image file will likely have particulars that |
46 | affect how the image is programmed to the FPGA. These are contained in struct | |
47 | fpga_image_info. Currently the only such particular is a single flag bit | |
48 | indicating whether the image is for full or partial reconfiguration. | |
e8f5fda1 AT |
49 | |
50 | To get/put a reference to a FPGA manager: | |
51 | ----------------------------------------- | |
52 | ||
53 | struct fpga_manager *of_fpga_mgr_get(struct device_node *node); | |
9dce0287 AT |
54 | struct fpga_manager *fpga_mgr_get(struct device *dev); |
55 | ||
56 | Given a DT node or device, get an exclusive reference to a FPGA manager. | |
e8f5fda1 AT |
57 | |
58 | void fpga_mgr_put(struct fpga_manager *mgr); | |
59 | ||
9dce0287 | 60 | Release the reference. |
e8f5fda1 AT |
61 | |
62 | ||
63 | To register or unregister the low level FPGA-specific driver: | |
64 | ------------------------------------------------------------- | |
65 | ||
66 | int fpga_mgr_register(struct device *dev, const char *name, | |
67 | const struct fpga_manager_ops *mops, | |
68 | void *priv); | |
69 | ||
70 | void fpga_mgr_unregister(struct device *dev); | |
71 | ||
72 | Use of these two functions is described below in "How To Support a new FPGA | |
73 | device." | |
74 | ||
75 | ||
76 | How to write an image buffer to a supported FPGA | |
77 | ================================================ | |
78 | /* Include to get the API */ | |
79 | #include <linux/fpga/fpga-mgr.h> | |
80 | ||
81 | /* device node that specifies the FPGA manager to use */ | |
82 | struct device_node *mgr_node = ... | |
83 | ||
84 | /* FPGA image is in this buffer. count is size of the buffer. */ | |
85 | char *buf = ... | |
86 | int count = ... | |
87 | ||
40e83578 AT |
88 | /* struct with information about the FPGA image to program. */ |
89 | struct fpga_image_info info; | |
90 | ||
e8f5fda1 | 91 | /* flags indicates whether to do full or partial reconfiguration */ |
40e83578 | 92 | info.flags = 0; |
e8f5fda1 AT |
93 | |
94 | int ret; | |
95 | ||
96 | /* Get exclusive control of FPGA manager */ | |
97 | struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node); | |
98 | ||
99 | /* Load the buffer to the FPGA */ | |
40e83578 | 100 | ret = fpga_mgr_buf_load(mgr, &info, buf, count); |
e8f5fda1 AT |
101 | |
102 | /* Release the FPGA manager */ | |
103 | fpga_mgr_put(mgr); | |
104 | ||
105 | ||
106 | How to write an image file to a supported FPGA | |
107 | ============================================== | |
108 | /* Include to get the API */ | |
109 | #include <linux/fpga/fpga-mgr.h> | |
110 | ||
111 | /* device node that specifies the FPGA manager to use */ | |
112 | struct device_node *mgr_node = ... | |
113 | ||
114 | /* FPGA image is in this file which is in the firmware search path */ | |
115 | const char *path = "fpga-image-9.rbf" | |
116 | ||
40e83578 AT |
117 | /* struct with information about the FPGA image to program. */ |
118 | struct fpga_image_info info; | |
119 | ||
e8f5fda1 | 120 | /* flags indicates whether to do full or partial reconfiguration */ |
40e83578 | 121 | info.flags = 0; |
e8f5fda1 AT |
122 | |
123 | int ret; | |
124 | ||
125 | /* Get exclusive control of FPGA manager */ | |
126 | struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node); | |
127 | ||
128 | /* Get the firmware image (path) and load it to the FPGA */ | |
40e83578 | 129 | ret = fpga_mgr_firmware_load(mgr, &info, path); |
e8f5fda1 AT |
130 | |
131 | /* Release the FPGA manager */ | |
132 | fpga_mgr_put(mgr); | |
133 | ||
134 | ||
135 | How to support a new FPGA device | |
136 | ================================ | |
137 | To add another FPGA manager, write a driver that implements a set of ops. The | |
138 | probe function calls fpga_mgr_register(), such as: | |
139 | ||
140 | static const struct fpga_manager_ops socfpga_fpga_ops = { | |
141 | .write_init = socfpga_fpga_ops_configure_init, | |
142 | .write = socfpga_fpga_ops_configure_write, | |
143 | .write_complete = socfpga_fpga_ops_configure_complete, | |
144 | .state = socfpga_fpga_ops_state, | |
145 | }; | |
146 | ||
147 | static int socfpga_fpga_probe(struct platform_device *pdev) | |
148 | { | |
149 | struct device *dev = &pdev->dev; | |
150 | struct socfpga_fpga_priv *priv; | |
151 | int ret; | |
152 | ||
153 | priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL); | |
154 | if (!priv) | |
155 | return -ENOMEM; | |
156 | ||
157 | /* ... do ioremaps, get interrupts, etc. and save | |
158 | them in priv... */ | |
159 | ||
160 | return fpga_mgr_register(dev, "Altera SOCFPGA FPGA Manager", | |
161 | &socfpga_fpga_ops, priv); | |
162 | } | |
163 | ||
164 | static int socfpga_fpga_remove(struct platform_device *pdev) | |
165 | { | |
166 | fpga_mgr_unregister(&pdev->dev); | |
167 | ||
168 | return 0; | |
169 | } | |
170 | ||
171 | ||
172 | The ops will implement whatever device specific register writes are needed to | |
173 | do the programming sequence for this particular FPGA. These ops return 0 for | |
174 | success or negative error codes otherwise. | |
175 | ||
176 | The programming sequence is: | |
177 | 1. .write_init | |
baa6d396 | 178 | 2. .write or .write_sg (may be called once or multiple times) |
e8f5fda1 AT |
179 | 3. .write_complete |
180 | ||
1d7f1589 JG |
181 | The .write_init function will prepare the FPGA to receive the image data. The |
182 | buffer passed into .write_init will be atmost .initial_header_size bytes long, | |
183 | if the whole bitstream is not immediately available then the core code will | |
184 | buffer up at least this much before starting. | |
e8f5fda1 AT |
185 | |
186 | The .write function writes a buffer to the FPGA. The buffer may be contain the | |
187 | whole FPGA image or may be a smaller chunk of an FPGA image. In the latter | |
baa6d396 JG |
188 | case, this function is called multiple times for successive chunks. This interface |
189 | is suitable for drivers which use PIO. | |
190 | ||
191 | The .write_sg version behaves the same as .write except the input is a sg_table | |
192 | scatter list. This interface is suitable for drivers which use DMA. | |
e8f5fda1 AT |
193 | |
194 | The .write_complete function is called after all the image has been written | |
195 | to put the FPGA into operating mode. | |
196 | ||
197 | The ops include a .state function which will read the hardware FPGA manager and | |
198 | return a code of type enum fpga_mgr_states. It doesn't result in a change in | |
199 | hardware state. |