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