1 FPGA Manager
2 ============
3
4 Overview
5 --------
6
7 The FPGA manager core exports a set of functio
8 an image. The API is manufacturer agnostic.
9 hidden away in a low level driver which regist
10 The FPGA image data itself is very manufacture
11 it's just binary data. The FPGA manager core
12
13 The FPGA image to be programmed can be in a sc
14 contiguous buffer, or a firmware file. Becaus
15 memory for the buffer should be avoided, users
16 gather list instead if possible.
17
18 The particulars for programming the image are
19 fpga_image_info). This struct contains parame
20 FPGA image as well as image-specific particula
21 built for full or partial reconfiguration.
22
23 How to support a new FPGA device
24 --------------------------------
25
26 To add another FPGA manager, write a driver th
27 probe function calls ``fpga_mgr_register()`` o
28 such as::
29
30 static const struct fpga_manager_ops s
31 .write_init = socfpga_fpga_ops
32 .write = socfpga_fpga_ops_conf
33 .write_complete = socfpga_fpga
34 .state = socfpga_fpga_ops_stat
35 };
36
37 static int socfpga_fpga_probe(struct p
38 {
39 struct device *dev = &pdev->de
40 struct socfpga_fpga_priv *priv
41 struct fpga_manager *mgr;
42 int ret;
43
44 priv = devm_kzalloc(dev, sizeo
45 if (!priv)
46 return -ENOMEM;
47
48 /*
49 * do ioremaps, get interrupts
50 * them in priv
51 */
52
53 mgr = fpga_mgr_register(dev, "
54 &socfp
55 if (IS_ERR(mgr))
56 return PTR_ERR(mgr);
57
58 platform_set_drvdata(pdev, mgr
59
60 return 0;
61 }
62
63 static int socfpga_fpga_remove(struct
64 {
65 struct fpga_manager *mgr = pla
66
67 fpga_mgr_unregister(mgr);
68
69 return 0;
70 }
71
72 Alternatively, the probe function could call o
73 register functions, ``devm_fpga_mgr_register()
74 ``devm_fpga_mgr_register_full()``. When these
75 parameter syntax is the same, but the call to
76 removed. In the above example, the ``socfpga_f
77 required.
78
79 The ops will implement whatever device specifi
80 do the programming sequence for this particula
81 success or negative error codes otherwise.
82
83 The programming sequence is::
84 1. .parse_header (optional, may be called onc
85 2. .write_init
86 3. .write or .write_sg (may be called once or
87 4. .write_complete
88
89 The .parse_header function will set header_siz
90 struct fpga_image_info. Before parse_header ca
91 with initial_header_size. If flag skip_header
92 .write function will get image buffer starting
93 beginning. If data_size is set, .write functio
94 the image buffer, otherwise .write will get da
95 This will not affect .write_sg, .write_sg will
96 sg_table form. If FPGA image is already mapped
97 whole buffer will be passed into .parse_header
98 form, core code will buffer up at least .initi
99 call of .parse_header, if it is not enough, .p
100 size into info->header_size and return -EAGAIN
101 with greater part of image buffer on the input
102
103 The .write_init function will prepare the FPGA
104 buffer passed into .write_init will be at leas
105 if the whole bitstream is not immediately avai
106 buffer up at least this much before starting.
107
108 The .write function writes a buffer to the FPG
109 whole FPGA image or may be a smaller chunk of
110 case, this function is called multiple times f
111 is suitable for drivers which use PIO.
112
113 The .write_sg version behaves the same as .wri
114 scatter list. This interface is suitable for d
115
116 The .write_complete function is called after a
117 to put the FPGA into operating mode.
118
119 The ops include a .state function which will d
120 and return a code of type enum fpga_mgr_states
121 in state.
122
123 API for implementing a new FPGA Manager driver
124 ----------------------------------------------
125
126 * ``fpga_mgr_states`` - Values for :c:expr:`f
127 * struct fpga_manager - the FPGA manager stru
128 * struct fpga_manager_ops - Low level FPGA ma
129 * struct fpga_manager_info - Parameter struct
130 * __fpga_mgr_register_full() - Create and reg
131 fpga_mgr_info structure to provide the full
132 * __fpga_mgr_register() - Create and register
133 arguments
134 * __devm_fpga_mgr_register_full() - Resource
135 __fpga_mgr_register_full()
136 * __devm_fpga_mgr_register() - Resource manag
137 * fpga_mgr_unregister() - Unregister an FPGA
138
139 Helper macros ``fpga_mgr_register_full()``, ``
140 ``devm_fpga_mgr_register_full()``, and ``devm_
141 to ease the registration.
142
143 .. kernel-doc:: include/linux/fpga/fpga-mgr.h
144 :functions: fpga_mgr_states
145
146 .. kernel-doc:: include/linux/fpga/fpga-mgr.h
147 :functions: fpga_manager
148
149 .. kernel-doc:: include/linux/fpga/fpga-mgr.h
150 :functions: fpga_manager_ops
151
152 .. kernel-doc:: include/linux/fpga/fpga-mgr.h
153 :functions: fpga_manager_info
154
155 .. kernel-doc:: drivers/fpga/fpga-mgr.c
156 :functions: __fpga_mgr_register_full
157
158 .. kernel-doc:: drivers/fpga/fpga-mgr.c
159 :functions: __fpga_mgr_register
160
161 .. kernel-doc:: drivers/fpga/fpga-mgr.c
162 :functions: __devm_fpga_mgr_register_full
163
164 .. kernel-doc:: drivers/fpga/fpga-mgr.c
165 :functions: __devm_fpga_mgr_register
166
167 .. kernel-doc:: drivers/fpga/fpga-mgr.c
168 :functions: fpga_mgr_unregister
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.