linux/Documentation/devicetree/bindings/xilinx.txt
<<
>>
Prefs
   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      ii) Xilinx SystemACE
 106
 107      The Xilinx SystemACE device is used to program FPGAs from an FPGA
 108      bitstream stored on a CF card.  It can also be used as a generic CF
 109      interface device.
 110
 111      Optional properties:
 112       - 8-bit (empty) : Set this property for SystemACE in 8 bit mode
 113
 114      iii) Xilinx EMAC and Xilinx TEMAC
 115
 116      Xilinx Ethernet devices.  In addition to general xilinx properties
 117      listed above, nodes for these devices should include a phy-handle
 118      property, and may include other common network device properties
 119      like local-mac-address.
 120
 121      iv) Xilinx Uartlite
 122
 123      Xilinx uartlite devices are simple fixed speed serial ports.
 124
 125      Required properties:
 126       - current-speed : Baud rate of uartlite
 127
 128      v) Xilinx hwicap
 129
 130                Xilinx hwicap devices provide access to the configuration logic
 131                of the FPGA through the Internal Configuration Access Port
 132                (ICAP).  The ICAP enables partial reconfiguration of the FPGA,
 133                readback of the configuration information, and some control over
 134                'warm boots' of the FPGA fabric.
 135
 136                Required properties:
 137                - xlnx,family : The family of the FPGA, necessary since the
 138                      capabilities of the underlying ICAP hardware
 139                      differ between different families.  May be
 140                      'virtex2p', 'virtex4', or 'virtex5'.
 141                - compatible : should contain "xlnx,xps-hwicap-1.00.a" or
 142                                "xlnx,opb-hwicap-1.00.b".
 143
 144      vi) Xilinx Uart 16550
 145
 146      Xilinx UART 16550 devices are very similar to the NS16550 but with
 147      different register spacing and an offset from the base address.
 148
 149      Required properties:
 150       - clock-frequency : Frequency of the clock input
 151       - reg-offset : A value of 3 is required
 152       - reg-shift : A value of 2 is required
 153
 154      vii) Xilinx USB Host controller
 155
 156      The Xilinx USB host controller is EHCI compatible but with a different
 157      base address for the EHCI registers, and it is always a big-endian
 158      USB Host controller. The hardware can be configured as high speed only,
 159      or high speed/full speed hybrid.
 160
 161      Required properties:
 162      - xlnx,support-usb-fs: A value 0 means the core is built as high speed
 163                             only. A value 1 means the core also supports
 164                             full speed devices.
 165
 166