Commit | Line | Data |
---|---|---|
b053dc5a KG |
1 | d) Xilinx IP cores |
2 | ||
3 | The Xilinx EDK toolchain ships with a set of IP cores (devices) for use | |
4 | in Xilinx Spartan and Virtex FPGAs. The devices cover the whole range | |
5 | of standard device types (network, serial, etc.) and miscellaneous | |
6 | devices (gpio, LCD, spi, etc). Also, since these devices are | |
7 | implemented within the fpga fabric every instance of the device can be | |
8 | synthesised with different options that change the behaviour. | |
9 | ||
10 | Each IP-core has a set of parameters which the FPGA designer can use to | |
11 | control how the core is synthesized. Historically, the EDK tool would | |
12 | extract the device parameters relevant to device drivers and copy them | |
13 | into an 'xparameters.h' in the form of #define symbols. This tells the | |
f77f13e2 | 14 | device drivers how the IP cores are configured, but it requires the kernel |
b053dc5a KG |
15 | to be recompiled every time the FPGA bitstream is resynthesized. |
16 | ||
17 | The new approach is to export the parameters into the device tree and | |
18 | generate a new device tree each time the FPGA bitstream changes. The | |
19 | parameters which used to be exported as #defines will now become | |
20 | properties of the device node. In general, device nodes for IP-cores | |
21 | will take the following form: | |
22 | ||
23 | (name): (generic-name)@(base-address) { | |
24 | compatible = "xlnx,(ip-core-name)-(HW_VER)" | |
25 | [, (list of compatible devices), ...]; | |
26 | reg = <(baseaddr) (size)>; | |
27 | interrupt-parent = <&interrupt-controller-phandle>; | |
28 | interrupts = < ... >; | |
29 | xlnx,(parameter1) = "(string-value)"; | |
30 | xlnx,(parameter2) = <(int-value)>; | |
31 | }; | |
32 | ||
33 | (generic-name): an open firmware-style name that describes the | |
34 | generic class of device. Preferably, this is one word, such | |
35 | as 'serial' or 'ethernet'. | |
36 | (ip-core-name): the name of the ip block (given after the BEGIN | |
37 | directive in system.mhs). Should be in lowercase | |
38 | and all underscores '_' converted to dashes '-'. | |
39 | (name): is derived from the "PARAMETER INSTANCE" value. | |
40 | (parameter#): C_* parameters from system.mhs. The C_ prefix is | |
41 | dropped from the parameter name, the name is converted | |
42 | to lowercase and all underscore '_' characters are | |
43 | converted to dashes '-'. | |
44 | (baseaddr): the baseaddr parameter value (often named C_BASEADDR). | |
45 | (HW_VER): from the HW_VER parameter. | |
46 | (size): the address range size (often C_HIGHADDR - C_BASEADDR + 1). | |
47 | ||
48 | Typically, the compatible list will include the exact IP core version | |
49 | followed by an older IP core version which implements the same | |
50 | interface or any other device with the same interface. | |
51 | ||
791d3ef2 | 52 | 'reg' and 'interrupts' are all optional properties. |
b053dc5a KG |
53 | |
54 | For example, the following block from system.mhs: | |
55 | ||
56 | BEGIN opb_uartlite | |
57 | PARAMETER INSTANCE = opb_uartlite_0 | |
58 | PARAMETER HW_VER = 1.00.b | |
59 | PARAMETER C_BAUDRATE = 115200 | |
60 | PARAMETER C_DATA_BITS = 8 | |
61 | PARAMETER C_ODD_PARITY = 0 | |
62 | PARAMETER C_USE_PARITY = 0 | |
63 | PARAMETER C_CLK_FREQ = 50000000 | |
64 | PARAMETER C_BASEADDR = 0xEC100000 | |
65 | PARAMETER C_HIGHADDR = 0xEC10FFFF | |
66 | BUS_INTERFACE SOPB = opb_7 | |
67 | PORT OPB_Clk = CLK_50MHz | |
68 | PORT Interrupt = opb_uartlite_0_Interrupt | |
69 | PORT RX = opb_uartlite_0_RX | |
70 | PORT TX = opb_uartlite_0_TX | |
71 | PORT OPB_Rst = sys_bus_reset_0 | |
72 | END | |
73 | ||
74 | becomes the following device tree node: | |
75 | ||
76 | opb_uartlite_0: serial@ec100000 { | |
77 | device_type = "serial"; | |
78 | compatible = "xlnx,opb-uartlite-1.00.b"; | |
79 | reg = <ec100000 10000>; | |
80 | interrupt-parent = <&opb_intc_0>; | |
81 | interrupts = <1 0>; // got this from the opb_intc parameters | |
82 | current-speed = <d#115200>; // standard serial device prop | |
83 | clock-frequency = <d#50000000>; // standard serial device prop | |
84 | xlnx,data-bits = <8>; | |
85 | xlnx,odd-parity = <0>; | |
86 | xlnx,use-parity = <0>; | |
87 | }; | |
88 | ||
89 | Some IP cores actually implement 2 or more logical devices. In | |
90 | this case, the device should still describe the whole IP core with | |
91 | a single node and add a child node for each logical device. The | |
92 | ranges property can be used to translate from parent IP-core to the | |
93 | registers of each device. In addition, the parent node should be | |
94 | compatible with the bus type 'xlnx,compound', and should contain | |
95 | #address-cells and #size-cells, as with any other bus. (Note: this | |
96 | makes the assumption that both logical devices have the same bus | |
97 | binding. If this is not true, then separate nodes should be used | |
98 | for each logical device). The 'cell-index' property can be used to | |
99 | enumerate logical devices within an IP core. For example, the | |
100 | following is the system.mhs entry for the dual ps2 controller found | |
101 | on the ml403 reference design. | |
102 | ||
103 | BEGIN opb_ps2_dual_ref | |
104 | PARAMETER INSTANCE = opb_ps2_dual_ref_0 | |
105 | PARAMETER HW_VER = 1.00.a | |
106 | PARAMETER C_BASEADDR = 0xA9000000 | |
107 | PARAMETER C_HIGHADDR = 0xA9001FFF | |
108 | BUS_INTERFACE SOPB = opb_v20_0 | |
109 | PORT Sys_Intr1 = ps2_1_intr | |
110 | PORT Sys_Intr2 = ps2_2_intr | |
111 | PORT Clkin1 = ps2_clk_rx_1 | |
112 | PORT Clkin2 = ps2_clk_rx_2 | |
113 | PORT Clkpd1 = ps2_clk_tx_1 | |
114 | PORT Clkpd2 = ps2_clk_tx_2 | |
115 | PORT Rx1 = ps2_d_rx_1 | |
116 | PORT Rx2 = ps2_d_rx_2 | |
117 | PORT Txpd1 = ps2_d_tx_1 | |
118 | PORT Txpd2 = ps2_d_tx_2 | |
119 | END | |
120 | ||
121 | It would result in the following device tree nodes: | |
122 | ||
123 | opb_ps2_dual_ref_0: opb-ps2-dual-ref@a9000000 { | |
124 | #address-cells = <1>; | |
125 | #size-cells = <1>; | |
126 | compatible = "xlnx,compound"; | |
127 | ranges = <0 a9000000 2000>; | |
128 | // If this device had extra parameters, then they would | |
129 | // go here. | |
130 | ps2@0 { | |
131 | compatible = "xlnx,opb-ps2-dual-ref-1.00.a"; | |
132 | reg = <0 40>; | |
133 | interrupt-parent = <&opb_intc_0>; | |
134 | interrupts = <3 0>; | |
135 | cell-index = <0>; | |
136 | }; | |
137 | ps2@1000 { | |
138 | compatible = "xlnx,opb-ps2-dual-ref-1.00.a"; | |
139 | reg = <1000 40>; | |
140 | interrupt-parent = <&opb_intc_0>; | |
141 | interrupts = <3 0>; | |
142 | cell-index = <0>; | |
143 | }; | |
144 | }; | |
145 | ||
146 | Also, the system.mhs file defines bus attachments from the processor | |
147 | to the devices. The device tree structure should reflect the bus | |
148 | attachments. Again an example; this system.mhs fragment: | |
149 | ||
150 | BEGIN ppc405_virtex4 | |
151 | PARAMETER INSTANCE = ppc405_0 | |
152 | PARAMETER HW_VER = 1.01.a | |
153 | BUS_INTERFACE DPLB = plb_v34_0 | |
154 | BUS_INTERFACE IPLB = plb_v34_0 | |
155 | END | |
156 | ||
157 | BEGIN opb_intc | |
158 | PARAMETER INSTANCE = opb_intc_0 | |
159 | PARAMETER HW_VER = 1.00.c | |
160 | PARAMETER C_BASEADDR = 0xD1000FC0 | |
161 | PARAMETER C_HIGHADDR = 0xD1000FDF | |
162 | BUS_INTERFACE SOPB = opb_v20_0 | |
163 | END | |
164 | ||
165 | BEGIN opb_uart16550 | |
166 | PARAMETER INSTANCE = opb_uart16550_0 | |
167 | PARAMETER HW_VER = 1.00.d | |
168 | PARAMETER C_BASEADDR = 0xa0000000 | |
169 | PARAMETER C_HIGHADDR = 0xa0001FFF | |
170 | BUS_INTERFACE SOPB = opb_v20_0 | |
171 | END | |
172 | ||
173 | BEGIN plb_v34 | |
174 | PARAMETER INSTANCE = plb_v34_0 | |
175 | PARAMETER HW_VER = 1.02.a | |
176 | END | |
177 | ||
178 | BEGIN plb_bram_if_cntlr | |
179 | PARAMETER INSTANCE = plb_bram_if_cntlr_0 | |
180 | PARAMETER HW_VER = 1.00.b | |
181 | PARAMETER C_BASEADDR = 0xFFFF0000 | |
182 | PARAMETER C_HIGHADDR = 0xFFFFFFFF | |
183 | BUS_INTERFACE SPLB = plb_v34_0 | |
184 | END | |
185 | ||
186 | BEGIN plb2opb_bridge | |
187 | PARAMETER INSTANCE = plb2opb_bridge_0 | |
188 | PARAMETER HW_VER = 1.01.a | |
189 | PARAMETER C_RNG0_BASEADDR = 0x20000000 | |
190 | PARAMETER C_RNG0_HIGHADDR = 0x3FFFFFFF | |
191 | PARAMETER C_RNG1_BASEADDR = 0x60000000 | |
192 | PARAMETER C_RNG1_HIGHADDR = 0x7FFFFFFF | |
193 | PARAMETER C_RNG2_BASEADDR = 0x80000000 | |
194 | PARAMETER C_RNG2_HIGHADDR = 0xBFFFFFFF | |
195 | PARAMETER C_RNG3_BASEADDR = 0xC0000000 | |
196 | PARAMETER C_RNG3_HIGHADDR = 0xDFFFFFFF | |
197 | BUS_INTERFACE SPLB = plb_v34_0 | |
198 | BUS_INTERFACE MOPB = opb_v20_0 | |
199 | END | |
200 | ||
201 | Gives this device tree (some properties removed for clarity): | |
202 | ||
203 | plb@0 { | |
204 | #address-cells = <1>; | |
205 | #size-cells = <1>; | |
206 | compatible = "xlnx,plb-v34-1.02.a"; | |
207 | device_type = "ibm,plb"; | |
208 | ranges; // 1:1 translation | |
209 | ||
210 | plb_bram_if_cntrl_0: bram@ffff0000 { | |
211 | reg = <ffff0000 10000>; | |
212 | } | |
213 | ||
214 | opb@20000000 { | |
215 | #address-cells = <1>; | |
216 | #size-cells = <1>; | |
217 | ranges = <20000000 20000000 20000000 | |
218 | 60000000 60000000 20000000 | |
219 | 80000000 80000000 40000000 | |
220 | c0000000 c0000000 20000000>; | |
221 | ||
222 | opb_uart16550_0: serial@a0000000 { | |
223 | reg = <a00000000 2000>; | |
224 | }; | |
225 | ||
226 | opb_intc_0: interrupt-controller@d1000fc0 { | |
227 | reg = <d1000fc0 20>; | |
228 | }; | |
229 | }; | |
230 | }; | |
231 | ||
232 | That covers the general approach to binding xilinx IP cores into the | |
233 | device tree. The following are bindings for specific devices: | |
234 | ||
235 | i) Xilinx ML300 Framebuffer | |
236 | ||
237 | Simple framebuffer device from the ML300 reference design (also on the | |
238 | ML403 reference design as well as others). | |
239 | ||
240 | Optional properties: | |
241 | - resolution = <xres yres> : pixel resolution of framebuffer. Some | |
242 | implementations use a different resolution. | |
243 | Default is <d#640 d#480> | |
244 | - virt-resolution = <xvirt yvirt> : Size of framebuffer in memory. | |
245 | Default is <d#1024 d#480>. | |
246 | - rotate-display (empty) : rotate display 180 degrees. | |
247 | ||
248 | ii) Xilinx SystemACE | |
249 | ||
250 | The Xilinx SystemACE device is used to program FPGAs from an FPGA | |
251 | bitstream stored on a CF card. It can also be used as a generic CF | |
252 | interface device. | |
253 | ||
254 | Optional properties: | |
255 | - 8-bit (empty) : Set this property for SystemACE in 8 bit mode | |
256 | ||
257 | iii) Xilinx EMAC and Xilinx TEMAC | |
258 | ||
259 | Xilinx Ethernet devices. In addition to general xilinx properties | |
260 | listed above, nodes for these devices should include a phy-handle | |
261 | property, and may include other common network device properties | |
262 | like local-mac-address. | |
263 | ||
264 | iv) Xilinx Uartlite | |
265 | ||
266 | Xilinx uartlite devices are simple fixed speed serial ports. | |
267 | ||
268 | Required properties: | |
269 | - current-speed : Baud rate of uartlite | |
270 | ||
271 | v) Xilinx hwicap | |
272 | ||
273 | Xilinx hwicap devices provide access to the configuration logic | |
274 | of the FPGA through the Internal Configuration Access Port | |
275 | (ICAP). The ICAP enables partial reconfiguration of the FPGA, | |
276 | readback of the configuration information, and some control over | |
277 | 'warm boots' of the FPGA fabric. | |
278 | ||
279 | Required properties: | |
280 | - xlnx,family : The family of the FPGA, necessary since the | |
281 | capabilities of the underlying ICAP hardware | |
282 | differ between different families. May be | |
283 | 'virtex2p', 'virtex4', or 'virtex5'. | |
5cb95fae NM |
284 | - compatible : should contain "xlnx,xps-hwicap-1.00.a" or |
285 | "xlnx,opb-hwicap-1.00.b". | |
b053dc5a KG |
286 | |
287 | vi) Xilinx Uart 16550 | |
288 | ||
289 | Xilinx UART 16550 devices are very similar to the NS16550 but with | |
290 | different register spacing and an offset from the base address. | |
291 | ||
292 | Required properties: | |
293 | - clock-frequency : Frequency of the clock input | |
294 | - reg-offset : A value of 3 is required | |
295 | - reg-shift : A value of 2 is required | |
296 | ||
08d3c18e JZ |
297 | vii) Xilinx USB Host controller |
298 | ||
299 | The Xilinx USB host controller is EHCI compatible but with a different | |
300 | base address for the EHCI registers, and it is always a big-endian | |
301 | USB Host controller. The hardware can be configured as high speed only, | |
302 | or high speed/full speed hybrid. | |
303 | ||
304 | Required properties: | |
305 | - xlnx,support-usb-fs: A value 0 means the core is built as high speed | |
306 | only. A value 1 means the core also supports | |
307 | full speed devices. | |
b053dc5a | 308 |