1 d) Xilinx IP cores 1 d) Xilinx IP cores
2 2
3 The Xilinx EDK toolchain ships with a set o 3 The Xilinx EDK toolchain ships with a set of IP cores (devices) for use
4 in Xilinx Spartan and Virtex FPGAs. The de 4 in Xilinx Spartan and Virtex FPGAs. The devices cover the whole range
5 of standard device types (network, serial, 5 of standard device types (network, serial, etc.) and miscellaneous
6 devices (gpio, LCD, spi, etc). Also, since 6 devices (gpio, LCD, spi, etc). Also, since these devices are
7 implemented within the fpga fabric every in 7 implemented within the fpga fabric every instance of the device can be
8 synthesised with different options that cha 8 synthesised with different options that change the behaviour.
9 9
10 Each IP-core has a set of parameters which 10 Each IP-core has a set of parameters which the FPGA designer can use to
11 control how the core is synthesized. Histo 11 control how the core is synthesized. Historically, the EDK tool would
12 extract the device parameters relevant to d 12 extract the device parameters relevant to device drivers and copy them
13 into an 'xparameters.h' in the form of #def 13 into an 'xparameters.h' in the form of #define symbols. This tells the
14 device drivers how the IP cores are configu 14 device drivers how the IP cores are configured, but it requires the kernel
15 to be recompiled every time the FPGA bitstr 15 to be recompiled every time the FPGA bitstream is resynthesized.
16 16
17 The new approach is to export the parameter 17 The new approach is to export the parameters into the device tree and
18 generate a new device tree each time the FP 18 generate a new device tree each time the FPGA bitstream changes. The
19 parameters which used to be exported as #de 19 parameters which used to be exported as #defines will now become
20 properties of the device node. In general, 20 properties of the device node. In general, device nodes for IP-cores
21 will take the following form: 21 will take the following form:
22 22
23 (name): (generic-name)@(base-address) 23 (name): (generic-name)@(base-address) {
24 compatible = "xlnx,(ip-core-na 24 compatible = "xlnx,(ip-core-name)-(HW_VER)"
25 [, (list of compa 25 [, (list of compatible devices), ...];
26 reg = <(baseaddr) (size)>; 26 reg = <(baseaddr) (size)>;
27 interrupt-parent = <&interrupt 27 interrupt-parent = <&interrupt-controller-phandle>;
28 interrupts = < ... >; 28 interrupts = < ... >;
29 xlnx,(parameter1) = "(string-v 29 xlnx,(parameter1) = "(string-value)";
30 xlnx,(parameter2) = <(int-valu 30 xlnx,(parameter2) = <(int-value)>;
31 }; 31 };
32 32
33 (generic-name): an open firmware-sty 33 (generic-name): an open firmware-style name that describes the
34 generic class of devic 34 generic class of device. Preferably, this is one word, such
35 as 'serial' or 'ethern 35 as 'serial' or 'ethernet'.
36 (ip-core-name): the name of the ip blo 36 (ip-core-name): the name of the ip block (given after the BEGIN
37 directive in system.mh 37 directive in system.mhs). Should be in lowercase
38 and all underscores '_ 38 and all underscores '_' converted to dashes '-'.
39 (name): is derived from the "P 39 (name): is derived from the "PARAMETER INSTANCE" value.
40 (parameter#): C_* parameters from sy 40 (parameter#): C_* parameters from system.mhs. The C_ prefix is
41 dropped from the param 41 dropped from the parameter name, the name is converted
42 to lowercase and all u 42 to lowercase and all underscore '_' characters are
43 converted to dashes '- 43 converted to dashes '-'.
44 (baseaddr): the baseaddr parameter 44 (baseaddr): the baseaddr parameter value (often named C_BASEADDR).
45 (HW_VER): from the HW_VER parame 45 (HW_VER): from the HW_VER parameter.
46 (size): the address range size 46 (size): the address range size (often C_HIGHADDR - C_BASEADDR + 1).
47 47
48 Typically, the compatible list will include 48 Typically, the compatible list will include the exact IP core version
49 followed by an older IP core version which 49 followed by an older IP core version which implements the same
50 interface or any other device with the same 50 interface or any other device with the same interface.
51 51
52 'reg' and 'interrupts' are all optional pro !! 52 'reg', 'interrupt-parent' and 'interrupts' are all optional properties.
53 53
54 For example, the following block from syste 54 For example, the following block from system.mhs:
55 55
56 BEGIN opb_uartlite 56 BEGIN opb_uartlite
57 PARAMETER INSTANCE = opb_uartl 57 PARAMETER INSTANCE = opb_uartlite_0
58 PARAMETER HW_VER = 1.00.b 58 PARAMETER HW_VER = 1.00.b
59 PARAMETER C_BAUDRATE = 115200 59 PARAMETER C_BAUDRATE = 115200
60 PARAMETER C_DATA_BITS = 8 60 PARAMETER C_DATA_BITS = 8
61 PARAMETER C_ODD_PARITY = 0 61 PARAMETER C_ODD_PARITY = 0
62 PARAMETER C_USE_PARITY = 0 62 PARAMETER C_USE_PARITY = 0
63 PARAMETER C_CLK_FREQ = 5000000 63 PARAMETER C_CLK_FREQ = 50000000
64 PARAMETER C_BASEADDR = 0xEC100 64 PARAMETER C_BASEADDR = 0xEC100000
65 PARAMETER C_HIGHADDR = 0xEC10F 65 PARAMETER C_HIGHADDR = 0xEC10FFFF
66 BUS_INTERFACE SOPB = opb_7 66 BUS_INTERFACE SOPB = opb_7
67 PORT OPB_Clk = CLK_50MHz 67 PORT OPB_Clk = CLK_50MHz
68 PORT Interrupt = opb_uartlite_ 68 PORT Interrupt = opb_uartlite_0_Interrupt
69 PORT RX = opb_uartlite_0_RX 69 PORT RX = opb_uartlite_0_RX
70 PORT TX = opb_uartlite_0_TX 70 PORT TX = opb_uartlite_0_TX
71 PORT OPB_Rst = sys_bus_reset_0 71 PORT OPB_Rst = sys_bus_reset_0
72 END 72 END
73 73
74 becomes the following device tree node: 74 becomes the following device tree node:
75 75
76 opb_uartlite_0: serial@ec100000 { 76 opb_uartlite_0: serial@ec100000 {
77 device_type = "serial"; 77 device_type = "serial";
78 compatible = "xlnx,opb-uartlit 78 compatible = "xlnx,opb-uartlite-1.00.b";
79 reg = <ec100000 10000>; 79 reg = <ec100000 10000>;
80 interrupt-parent = <&opb_intc_ 80 interrupt-parent = <&opb_intc_0>;
81 interrupts = <1 0>; // got thi 81 interrupts = <1 0>; // got this from the opb_intc parameters
82 current-speed = <d#115200>; 82 current-speed = <d#115200>; // standard serial device prop
83 clock-frequency = <d#50000000> 83 clock-frequency = <d#50000000>; // standard serial device prop
84 xlnx,data-bits = <8>; 84 xlnx,data-bits = <8>;
85 xlnx,odd-parity = <0>; 85 xlnx,odd-parity = <0>;
86 xlnx,use-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 };
87 }; 230 };
88 231
89 That covers the general approach to binding 232 That covers the general approach to binding xilinx IP cores into the
90 device tree. The following are bindings fo 233 device tree. The following are bindings for specific devices:
91 234
92 i) Xilinx ML300 Framebuffer 235 i) Xilinx ML300 Framebuffer
93 236
94 Simple framebuffer device from the ML300 237 Simple framebuffer device from the ML300 reference design (also on the
95 ML403 reference design as well as others 238 ML403 reference design as well as others).
96 239
97 Optional properties: 240 Optional properties:
98 - resolution = <xres yres> : pixel reso 241 - resolution = <xres yres> : pixel resolution of framebuffer. Some
99 implementa 242 implementations use a different resolution.
100 Default is 243 Default is <d#640 d#480>
101 - virt-resolution = <xvirt yvirt> : Siz 244 - virt-resolution = <xvirt yvirt> : Size of framebuffer in memory.
102 Def 245 Default is <d#1024 d#480>.
103 - rotate-display (empty) : rotate displ 246 - rotate-display (empty) : rotate display 180 degrees.
104 247
105 ii) Xilinx SystemACE 248 ii) Xilinx SystemACE
106 249
107 The Xilinx SystemACE device is used to p 250 The Xilinx SystemACE device is used to program FPGAs from an FPGA
108 bitstream stored on a CF card. It can a 251 bitstream stored on a CF card. It can also be used as a generic CF
109 interface device. 252 interface device.
110 253
111 Optional properties: 254 Optional properties:
112 - 8-bit (empty) : Set this property for 255 - 8-bit (empty) : Set this property for SystemACE in 8 bit mode
113 256
114 iii) Xilinx EMAC and Xilinx TEMAC 257 iii) Xilinx EMAC and Xilinx TEMAC
115 258
116 Xilinx Ethernet devices. In addition to 259 Xilinx Ethernet devices. In addition to general xilinx properties
117 listed above, nodes for these devices sh 260 listed above, nodes for these devices should include a phy-handle
118 property, and may include other common n 261 property, and may include other common network device properties
119 like local-mac-address. 262 like local-mac-address.
120 263
121 iv) Xilinx Uartlite 264 iv) Xilinx Uartlite
122 265
123 Xilinx uartlite devices are simple fixed 266 Xilinx uartlite devices are simple fixed speed serial ports.
124 267
125 Required properties: 268 Required properties:
126 - current-speed : Baud rate of uartlite 269 - current-speed : Baud rate of uartlite
127 270
128 v) Xilinx hwicap 271 v) Xilinx hwicap
129 272
130 Xilinx hwicap devices provide 273 Xilinx hwicap devices provide access to the configuration logic
131 of the FPGA through the Intern 274 of the FPGA through the Internal Configuration Access Port
132 (ICAP). The ICAP enables part 275 (ICAP). The ICAP enables partial reconfiguration of the FPGA,
133 readback of the configuration 276 readback of the configuration information, and some control over
134 'warm boots' of the FPGA fabri 277 'warm boots' of the FPGA fabric.
135 278
136 Required properties: 279 Required properties:
137 - xlnx,family : The family of 280 - xlnx,family : The family of the FPGA, necessary since the
138 capabilities of the unde 281 capabilities of the underlying ICAP hardware
139 differ between different 282 differ between different families. May be
140 'virtex2p', 'virtex4', o 283 'virtex2p', 'virtex4', or 'virtex5'.
141 - compatible : should contain 284 - compatible : should contain "xlnx,xps-hwicap-1.00.a" or
142 "xlnx,opb-hwic 285 "xlnx,opb-hwicap-1.00.b".
143 286
144 vi) Xilinx Uart 16550 287 vi) Xilinx Uart 16550
145 288
146 Xilinx UART 16550 devices are very simil 289 Xilinx UART 16550 devices are very similar to the NS16550 but with
147 different register spacing and an offset 290 different register spacing and an offset from the base address.
148 291
149 Required properties: 292 Required properties:
150 - clock-frequency : Frequency of the cl 293 - clock-frequency : Frequency of the clock input
151 - reg-offset : A value of 3 is required 294 - reg-offset : A value of 3 is required
152 - reg-shift : A value of 2 is required 295 - reg-shift : A value of 2 is required
153 296
154 vii) Xilinx USB Host controller 297 vii) Xilinx USB Host controller
155 298
156 The Xilinx USB host controller is EHCI c 299 The Xilinx USB host controller is EHCI compatible but with a different
157 base address for the EHCI registers, and 300 base address for the EHCI registers, and it is always a big-endian
158 USB Host controller. The hardware can be 301 USB Host controller. The hardware can be configured as high speed only,
159 or high speed/full speed hybrid. 302 or high speed/full speed hybrid.
160 303
161 Required properties: 304 Required properties:
162 - xlnx,support-usb-fs: A value 0 means t 305 - xlnx,support-usb-fs: A value 0 means the core is built as high speed
163 only. A value 1 m 306 only. A value 1 means the core also supports
164 full speed device 307 full speed devices.
165 308
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.