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
14   device drivers how the IP cores are configured, but it requires the kernel
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
52   'reg', 'interrupt-parent' and 'interrupts' are all optional properties.
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'.
284
285      vi) Xilinx Uart 16550
286
287      Xilinx UART 16550 devices are very similar to the NS16550 but with
288      different register spacing and an offset from the base address.
289
290      Required properties:
291       - clock-frequency : Frequency of the clock input
292       - reg-offset : A value of 3 is required
293       - reg-shift : A value of 2 is required
294
295      vii) Xilinx USB Host controller
296
297      The Xilinx USB host controller is EHCI compatible but with a different
298      base address for the EHCI registers, and it is always a big-endian
299      USB Host controller. The hardware can be configured as high speed only,
300      or high speed/full speed hybrid.
301
302      Required properties:
303      - xlnx,support-usb-fs: A value 0 means the core is built as high speed
304                             only. A value 1 means the core also supports
305                             full speed devices.
306
307