packages/devs/eth/rltk/8139/v2_0/doc/README

   1 Some notes on the RealTek 8139 driver
   2
   3
   4 1. Using the driver
   5
   6 This driver follows the customization model used by many other drivers
   7 to separate those parts of the code that are device specific from those
   8 that are platform specific by requiring two packages to actually use the
   9 driver -- the driver itself and a platform glue package that contains
  10 only a .cdl and an .inl file (see the devs/i386/pc/rltk8139 package for
  11 an example).
  12
  13 Both the driver and the glue packages must be added to the package
  14 database before you can use them. My entries look like this:
  15
  16 package CYGPKG_DEVS_ETH_RLTK_8139 {
  17   alias     { "RealTek 8139 ethernet driver"
  18               devs_eth_rltk_8139 8139_eth_driver }
  19   hardware
  20   directory devs/eth/rltk/8139
  21   script    rltk_8139_eth_drivers.cdl
  22         description     "Ethernet driver for RealTek 8139 NIC."
  23 }
  24
  25 and
  26
  27 package CYGPKG_DEVS_ETH_I386_RLTK8139 {
  28   alias     { "Standard PC with RealTek 8139 ethernet device"
  29               devs_eth_i386_pc_rltk8139 }
  30   hardware
  31   directory devs/eth/i386/pc/rltk8139
  32   script    i386_pc_rltk8139_eth_drivers.cdl
  33   description "Ethernet driver for the RealTek 8139 family of chips."
  34 }
  35
  36 Finally, you will need to create a new target that includes the RealTek
  37 driver. The easiest way to this is copy an existing target and add the
  38 two packages defined above (and removing the Intel 82259 packages in case
  39 of an i386 pc target).
  40
  41
  42 2. Cache Coherency
  43
  44 Since the 8139 reads data directly from memory via the PCI bus, you may
  45 have to worry about data cache coherency. For eCos, there are basically
  46 three cases (turning the data cache off is not considered a serious solution):
  47
  48 a. Either the CPU has no data cache, or the CPU has cache snooping logic
  49 that will detect memory accesses by PCI bus master devices and flush the cache
  50 when necessary. In this case, nothing special needs to be done.
  51
  52 b. The MMU is configured to access memory uncached in a certain address space.
  53 In this case, the macro CYGARC_UNCACHED_ADDRESS() can be used to convert
  54 normal (cached) into uncached accesses. The driver always uses this macro for
  55 accessing the transmit and receive buffers, since if the HAL doesn't
  56 support this mechanism, the macro does nothing and no harm is done.
  57
  58 c. The data cache needs to be flushed/invalidated by the driver. In this case,
  59 you must define CYGPKG_DEVS_ETH_RLTK_8139_SOFTWARE_CACHE_COHERENCY in the
  60 platform specific .inl file. Furthermore, the HAL macros HAL_DCACHE_INVALIDATE
  61 and HAL_DCACHE_FLUSH must be defined. Next, you must ensure that the buffers
  62 are aligned to cache line boundaries; otherwise, the code could fail in
  63 mysterious ways.
  64
  65 One way to do this is to define the following in the .inl file:
  66
  67 #define CACHE_ALIGNED __attribute__ ((aligned (HAL_DCACHE_LINE_SIZE)))
  68
  69 Then, use this attribute on the transmit and receive buffer definitions:
  70
  71 static cyg_uint8 rltk8139_eth0_rx_ring[RX_BUF_TOT_LEN] CACHE_ALIGNED;
  72
  73 Note that this may fail for long cache lines, since the 'aligned' attribute
  74 does not allow arbitrarily large alignment parameters. Unfortunately, the gcc
  75 documentation does not say what the maximum alignment that can be specified
  76 is. Additionally, the linker may also be limited in the maximum alignment that
  77 can be used. In such cases, you'll have to bite the bullet and define more
  78 space than would be strictly necessary, and ensure the necessary alignment
  79 like this:
  80
  81 static cyg_uint8 rltk8139_eth0_rx_ring[RX_BUF_TOT_LEN + HAL_DCACHE_LINE_SIZE];
  82
  83 Then, reference the buffers in the Rltk8139 definition like this:
  84
  85 (cyg_uint8 *)((int)(&rltk8139_eth0_rx_ring[0] + HAL_DCACHE_LINE_SIZE)
  86                     & ~(HAL_DCACHE_LINE_SIZE - 1))
  87
  88 This assumes the cache line size is a power of 2; this is the case for all
  89 CPUs I know of. It also assumes an int can hold a pointer; if this is
  90 not true for your platform, use an integral type that can.
  91
  92 Another thing to watch out for is that the buffers should also end on
  93 a cache line boundary. If your linker places the buffers sequentially in
  94 memory, you will only have to do this for the last buffer defined (since
  95 all buffers will start on cache line boundaries):
  96
  97 static cyg_uint8
  98 rltk8139_eth0_tx_buffer[(TX_BUF_TOT_LEN + HAL_DCACHE_LINE_SIZE - 1)
  99                         & ~(HAL_DCACHE_LINE_SIZE - 1)] CACHE_ALIGNED;
 100
 101
 102 3. Interrupt sharing
 103
 104 If the 8139 must share it's interrupt request line with other devices, the
 105 HAL option 'chained interrupts' must be enabled. The 8139 driver does not
 106 support IRQ muxing like the Intel 82559 driver does (see also *Limitations*).
 107
 108 The driver's ISR does not clear the interrupt status bits since I believe this
 109 should only be done after the conditions that caused those bits to be set
 110 have been handled by the '_deliver' routine. Instead, the interrupt is masked.
 111 There are two ways to do this (configurable with a CDL option):
 112
 113 a. The interrupt vector is masked. Personally I think this is a bad idea
 114    because this will also block interrupts from all other devices sharing
 115    this interrupt until the network thread gets around to calling the
 116    '_deliver' routine.
 117
 118 b. Mask the interrupt request using the 8139's interrupt mask register. This
 119    way, other devices' interrupt requests can still be serviced. Enable the
 120    CYGPKG_DEVS_ETH_RLTK_8139_MASK_INTERRUPTS_IN_8139 option to use this.
 121
 122
 123 4. Limitations
 124
 125 There are a number of limitations associated with this driver:
 126
 127 a. The configuration of the NIC (MAC address, media selection, etc.) is
 128    loaded from the serial EEPROM (which is assumed to exist) and cannot be
 129    changed either at compile or run time.
 130
 131 b. The 'twister' cannot be tuned. As far as I can make out, the 'twister'
 132    can be tuned to improve signal quality over long lines. The RealTek
 133    data sheet does not document the twister; and the code in the Linux
 134    driver that does this is totally incomprehensible to me.
 135
 136 c. If multiple 8139s share the same interrupt, chained interrupts have to
 137    be used. No IRQ MUXing (like the Intel 82559 driver has) is supported.
 138
 139 d. Programming the multicast acceptance filter is now implemented, but not
 140    tested because eCos doesn't have such a test program (or at least I
 141    couldn't find any). Since I have never used multicasting myself, I don't
 142    feel competent to write one. Someone suggested setting up an IPv6 network
 143    for testing, since it seems IPv6 makes use of multicasting in normal
 144    operation, but I haven't got around to doing that.
 145
 146 e. It's fairly slow. This is not really the driver's fault - the 8139 requires
 147    a fast CPU to get anything approaching decent speed because all messages
 148    have to be copied around in memory.
 149
 150
 151 5. Credits
 152
 153 The 8139's data sheet is not really all that helpful, since it contains
 154 a lot of omissions and some data that is simply incorrect. As such, I am
 155 indebted to Bill Paul for his well-documented OpenBSD driver, which was
 156 invaluable for figuring out how the chip is supposed to work. The idea of
 157 using 'enum' instead of '#define' came from the Linux 8139 driver, which I
 158 initially wanted to port to eCos, but didn't because I found it extremely
 159 hard to read and understand. (Note that I didn't copy any code from those
 160 drivers to avoid tainting eCos' license). The basic structure of the driver
 161 and .cdl files was taken from the eCos i82559 driver.
 162
 163 I'd also like all the people who have downloaded and tested the driver, and
 164 contributed bug reports and fixes.