Documentation/powerpc/Xilinx.txt

   1 ---- Overview ----------------------------------------------------------------
   2
   3 The Xilinx Virtex-II Pro chips are unique at this time.  They are large FPGAs
   4 that can have zero to four PowerPC 405 cores on the same die.  Currently, only
   5 a single 405 core is supported by Linux.
   6
   7 Xilinx provides a variety of IP (Intellectual Property, the phrase used by
   8 hardware types to represent a ready-to-go, "canned" set of logic that can be
   9 dropped into a programmable device).  The provided IP implements a variety of
  10 useful peripherals.  When the system powers up, the IP is automatically
  11 loaded into the FPGA from a file (a.k.a. a bitstream) from the first
  12 partition (which must be a FAT partition) on a CompactFlash.  This is done by
  13 a piece of hardware known as System ACE.  The System ACE can be told which
  14 one of eight different configurations it should load into the FPGA.  System
  15 ACE also gives the 405 core access to the CompactFlash and JTAG chain during
  16 runtime.
  17
  18
  19 ---- Xilinx Access Functions and Linux Drivers -------------------------------
  20
  21 Most of the Xilinx peripherals are custom Xilinx implementations that may
  22 change over their lifetime.  To try to minimize the effort that this could
  23 cause, Xilinx provides OS independent functions that have been released under
  24 the GPL.  These OS independent functions should be called in lieu of directly
  25 accessing the hardware.  The Xilinx functions are used for multiple OSes and
  26 will be maintained by Xilinx.  A given OS utilizes these functions by writing
  27 a chunk of code that Xilinx refers to as an adapter.
  28
  29 The following Linux drivers use the Xilinx provided access functions and
  30 implement the adapter as a single source:
  31
  32   Peripheral            Driver location                 Adapter
  33   --------------------  ------------------------------  -----------------
  34   Ethernet              drivers/net/xilinx_enet/        adapter.c
  35   GPIO                  drivers/char/xilinx_gpio/       adapter.c
  36   PS/2                  drivers/char/xilinx_keyb/       x8042.c
  37   IIC                   drivers/i2c/xilinx_iic/         i2c-algo-xilinx.c
  38   System ACE            drivers/block/xilinx_sysace/    adapter.c
  39   Touch Screen          drivers/char/xilinx_ts/         adapter.c
  40
  41 The System ACE driver allows the CompactFlash to be used as a block device as
  42 well as a method of controlling which bitstream the System ACE should load at
  43 the next reset.
  44
  45 There are a few other Xilinx peripherals that Linux provides access to, but do
  46 not utilize the Xilinx access functions:
  47
  48   Peripheral            Driver location
  49   --------------------  ------------------------------
  50   TFT LCD driver        drivers/video/xilinxfb.c
  51   UART's                drivers/char/serial.c
  52   Interrupt Controller  arch/ppc/kernel/xilinx_pic.c
  53
  54 Xilinx does not provide access functions for the LCD driver, so it is
  55 implemented just as a standard Linux frame buffer driver.  Xilinx does provide
  56 access functions for the UART's and Interrupt Controller, but they are not
  57 used.  The UART's are standard 16450/16550's so by definition, serial.c "just
  58 works".  Whether or not the the Xilinx access functions should be used to
  59 access the Interrupt Controller is a decision that hasn't been finalized, but
  60 for the time being, xilinx_pic.c talks directly to the hardware.
  61
  62 The files in arch/ppc/platforms/xilinx_ocp/ are the underpinnings for the
  63 Xilinx access functions.  Most of those files are provided by Xilinx.
  64
  65
  66 ---- Peripheral Configuration ------------------------------------------------
  67
  68 A system is built by running Xilinx's System Generator.  The System Generator
  69 is told how many of each peripheral (if any) should be loaded into the FPGA.
  70 The System Generator then produces the bitstream that is put on the
  71 CompactFlash (ultimately to be loaded into the FPGA).  Linux needs to somehow
  72 know what peripherals are in the system and how to talk to them.  Currently,
  73 this is done at compile time by having the System Generator output C source.
  74 Ultimately, the hope is that Linux can determine this at run time using
  75 Xilinx's Configuration ROM (CROM), but the how/when/if of that is unknown.
  76
  77 The C sources that are output by the System Generator include the Xilinx
  78 functions previously mentioned, as well as the configuration information.  The
  79 exact format of the configuration information is evolving, but is completely
  80 functional at this time.  The System Generator outputs an include file named
  81 xparameters.h.  xparameters.h #define's information about all of the
  82 peripherals in the system. An xparameters.h for the ML300 has been placed in:
  83
  84   arch/ppc/platforms/xilinx_ocp/xparameters_ml300.h
  85
  86 This file is included based upon CONFIG_ variables from:
  87
  88   arch/ppc/platforms/xilinx_ocp/xparameters.h
  89
  90 The idea is that each Xilinx based board can put their xparameters.h under a
  91 different name and then add code to xparameters.h to include the appropriate
  92 file.
  93
  94 In addition to xparameters.h, an include file is output as part of each set of
  95 Xilinx access functions.  These files have a name of the form x*_g.h.  These
  96 files define arrays that contain values from xparameters.h to make information
  97 about each instance of each peripheral available.
  98
  99 Now for a bit of hand waving.  The System Generator isn't completed yet, so
 100 these files are currently hand-generated.  Also as mentioned above, these
 101 whole setup is evolving with the idea of a central repository for this
 102 information, much like the OCP does for the IBM on-chip peripherals.
 103 Ultimately as OCP and the Xilinx configuration strategies evolve, it would be
 104 nice for them to grow together.
 105
 106 As a note, one of the areas that is ripe for evolution is handling of the IRQ
 107 information.  Right now, it is not handled by the Xilinx functions and the
 108 values defined in xparameters.h are not the same as in the hardware
 109 documentation.  For example, what would be interrupt 0 per the hardware manual
 110 is referred to as interrupt 31 in the xparameters.h.
 111
 112
 113 ---- The Future --------------------------------------------------------------
 114
 115 There are a number of things marked by SAATODO in the code that should be
 116 addressed.  Typically, more information can be found in the source, but here
 117 is a high-level list:
 118
 119   As mentioned above, the final decision about whether or not the interrupt
 120   controller will be changed to use the Xilinx access functions has not been
 121   made.  If it is decided that the current code stays, the ACKNOWLEDGE_AFTER
 122   code in xilinx_pic.c should be revisited to ensure that it is correct.
 123
 124   The Xilinx code uses some macros to implement assert functionality to make
 125   sure that certain conditions are met.  For now, that is enabled, but before
 126   deploying, NDEBUG should probably be defined and the XAssert handling code
 127   ifdef'ed out.
 128
 129   The adapters define functions of the form *_GetConfig.  This functionality
 130   needs to be pushed into the Xilinx code, but as mentioned above, access to
 131   configuration information is evolving.
 132
 133   The GPIO adapter defines XGpio_GetDataDirection.  This function needs to be
 134   pushed into the Xilinx code.
 135
 136   The System ACE adapter defines XSysAce_GetCfgAddr.  This function needs to
 137   be pushed into the Xilinx code.
 138
 139   PS/2 issues:
 140    Keyboard/Mouse interference.
 141    Generate interrupt when OBF set.
 142    Handle disables.
 143
 144   IIC issues:
 145    Use timeout and retry?
 146    Non-experimental I2C IDs.
 147
 148   Xilinx does not yet support multicast or scatter-gather DMA for the
 149   ethernet.  Once those are supported by Xilinx, the Linux driver can
 150   be enhanced to add support for them.
 151
 152
 153 ---- Oddities ----------------------------------------------------------------
 154
 155 As I've been developing, I've noticed some things that I haven't followed up
 156 on, but have just kept a running list.  It is possible that some of these
 157 things are non-issues now.
 158
 159 1) Networking
 160  a)The network performance doesn't seem to be as good as it should be.
 161    It is believed that once scatter-gather is supported, this problem
 162    will be resolved.
 163  b)Under heavy load (e.g. recursive cksum over NFS), I've seen errors such as:
 164       eth0: device error 8, resetting device.
 165       NETDEV WATCHDOG: eth0: transmit timed out
 166       eth0: Exceeded transmit timeout of 60000 ms.  Resetting emac.
 167    Obviously, this shouldn't happen and needs to be fixed.
 168  c)It has been reported that the NFS block size needs to be lowered in some
 169    cases.  This should be investigated, but at this point, it is believed to
 170    be a problem with the NFS server instead of a problem with the ML300.
 171
 172 2) When the Xilinx drivers get made, the next time make is ran they get
 173    remade once more.  Figure out what is wrong in the Makefiles.
 174
 175 3) Not really an oddity, but devfs support should be added to the drivers.