xilinx.txt

  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' 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   That covers the general approach to binding xilinx IP cores into the
 90   device tree.  The following are bindings for specific devices:
 91
 92      i) Xilinx ML300 Framebuffer
 93
 94      Simple framebuffer device from the ML300 reference design (also on the
 95      ML403 reference design as well as others).
 96
 97      Optional properties:
 98       - resolution = <xres yres> : pixel resolution of framebuffer.  Some
 99                                    implementations use a different resolution.
100                                    Default is <d#640 d#480>
101       - virt-resolution = <xvirt yvirt> : Size of framebuffer in memory.
102                                           Default is <d#1024 d#480>.
103       - rotate-display (empty) : rotate display 180 degrees.
104
105      iii) Xilinx EMAC and Xilinx TEMAC
106
107      Xilinx Ethernet devices.  In addition to general xilinx properties
108      listed above, nodes for these devices should include a phy-handle
109      property, and may include other common network device properties
110      like local-mac-address.
111
112      v) Xilinx hwicap
113
114		Xilinx hwicap devices provide access to the configuration logic
115		of the FPGA through the Internal Configuration Access Port
116		(ICAP).  The ICAP enables partial reconfiguration of the FPGA,
117		readback of the configuration information, and some control over
118		'warm boots' of the FPGA fabric.
119
120		Required properties:
121		- xlnx,family : The family of the FPGA, necessary since the
122                      capabilities of the underlying ICAP hardware
123                      differ between different families.  May be
124                      'virtex2p', 'virtex4', or 'virtex5'.
125		- compatible : should contain "xlnx,xps-hwicap-1.00.a" or
126				"xlnx,opb-hwicap-1.00.b".
127
128      vii) Xilinx USB Host controller
129
130      The Xilinx USB host controller is EHCI compatible but with a different
131      base address for the EHCI registers, and it is always a big-endian
132      USB Host controller. The hardware can be configured as high speed only,
133      or high speed/full speed hybrid.
134
135      Required properties:
136      - xlnx,support-usb-fs: A value 0 means the core is built as high speed
137                             only. A value 1 means the core also supports
138                             full speed devices.
139