About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / devicetree / bindings / xilinx.txt




Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 09:02 EST.

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.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.