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', '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