/* dp83815.c -- National DP83815 PCI Ethernet Controller Driver */

static const char *version =
    "dp83815.c:v1.52C National DP83815 Fast Ethernet Driver\n";

/*    
1. INTRODUCTION
---------------

The DP83815 is a PCI bus based single chip 10/100 Mbps ethernet
controller targeted for PC mother boards, adapter cards, and embedded
systems. It fully implements the V2.2 33MHz PCI bus interface for host
communications with power management support. Packet descriptors and
data are transferred via bus-mastering, reducing the burden on the
host CPU. The DP83815 can support full duplex 10/100 Mbps transmission
and reception.

The DP83815 driver is developed for use on Linux v2.0.36. It can be
configured either as a static driver into the kernel or as a loadable
module. The driver is capable of 10/100 Mbps Full/Half duplex mode
operation via an internal PHY. Detailed features are given below.

2.1 Chip Features

o The chip is bus-master capable and transfers packet descriptors
and data using DMA with burst sizes upto 128 words.

o It supports 10 Mbps Ethernet and 100 Mbps Fast Ethernet via
an internal PHY and emerging 1-2 Mbps home networking
solutions via external PHY.

o Flexible Rx packet filtration including: perfect match, broadcast, 
multicast/unicast hash table, deep packet pattern matching.

o Internal Tx and Rx data FIFOs of 2KB each

o 802.3u Auto-Negotiation - advertised features configurable via
EEPROM

o Full duplex support for 10 and 100Mb/s data rates


2.2 Driver Features

2.2.1 Supported Features

o 10 Mbps full duplex and half duplex
o 100 Mbps full duplex and half duplex
o Auto Negotiation
o Broadcast and perfect match transmit and receive
o ARP transmit and receive
o Promiscuous mode
o Multicast support
o Loadable Kernel Module
o PCI bus probe for auto-configuration when configured as a static
  driver or a loadable kernel module
o Endian, and CPU architecture neutral
o Driver now supports insmod params.

2.2.2 Unsupported Features

o ACPI
o Multiple ethernet addresses 
o Wake on LAN and OnNow support for PC98/99, and other power-management
  features.
o Magic packets with SecureON, VLAN
o Programming EEPROM/Flash
o Old Linux kernels 1.xx.xx
o Newer MP kernels 2.2.xx 
o Remote boot           


3. DRIVER OPERATION
-------------------

Buffer management used in this version of the driver sets up the
transmit and receive buffer descriptors in a ring. The rings, shared
between the driver and the device, are located in memory buffers 
allocated in the kernel. The device accesses these buffers via DMA.

Each device will be allocated two similar queues of descriptors, one
for transmit and the other for receive. These queues are linked
together into a ring. For the default size of the transmit rings is
10, while the size of the receive ring is 30. These values can be
changed via macros in the driver source file.

The driver implements no copy transmit and receive operation. All
receive descriptors are created with no associated buffers, but the
descriptor uses the sk_buff passed to it via the transmit routine. The
sk_buff is held by the driver until the next transmit operation that
follows the actual transmit of the packet.

Each receive descriptor is initialized, at creation time, with an
sk_buff. Each sk_buff has a data buffer that can hold a max ethernet
packet. When a packet is suceesfully received, the skb is directly
sent to the stack with no copy, and it is replaced with a newly
allocated sk_buff. But if the packet less than 128 bytes
was received, the data is instead copied into a new skb. 

The driver makes of appropriate macros to adjust for endian-ness of
the host CPU, PCI bus, Ethernet, and the DP device. It also performs
appropriate translations of addresses for device use. These builtin
features makes the driver extremely portable to run on Linux systems
with non-Intel CPUs with minimum changes.


4. FILES IN THIS RELEASE
------------------------

The following files are included in a tar ball, dp83815.tar.gz

README.Linux   - This file
dp83815.c      - Driver source file
dp83815.h      - Driver header file
dp83815.o      - Driver object module
Makefile       - Rules to compile and install the driver.


5. MODIFICATION HISTORY
-----------------------
version 1.52c:

o This version of driver supports Linux kernel version large than 2.4.18 
and has bee tested on Red Hat 8.0 9.0  distribution .

version 1.51:

o fixes for short cable attenuation.

version 1.50:

o merged dp83815.c driver, to support link aggregration
o added function dp83815_rx_control function for fail over only support.

version 1.40:

o upgraded the driver to support linux kernel version 2.4.x.
o fixed duplex support.
o added bytes count support to ethernet MIB.
o fixed MAC address read routine to read from eeprom.
o implemented support for load-time parameters.

version 1.30:

o Driver release supporting Redhat Linux ver 5.2 and 
  linux kernel version 2.0.36.
 
6. INSTALLATION
---------------

6.1 Kernel Requirements:

This version of the driver supports Linux kernel version 2.4.x and
has been tested on Red Hat 7.0 distribution.

6.2 Installation Procedure:

To install the driver, login as root, and extract the files into an 
appropriate directory.

     # mkdir <path>/dp83815 
     # cp dp83815.c dp83815.h makefile  <path>/dp83815/
     # cd <path>/dp83815/
     # make

To install the current driver object module in the filesystem run,

     # make install

You'll need to edit the following files to configure the driver as a
valid ethernet device in the system

  o /etc/hosts
  o /etc/sysconfig/network-scripts/ifcfg-eth?
  o /etc/conf.modules

6.3 Load Parameters:

This version of the driver supports to specify parameters via insmod
while loading the driver dynamically in to the running
kernel. Parameter are specified as list of string inside double quotes
seprated by commas.  This does not apply to "debug" parameter which is
a integer value. For example

     fullduplex="1,0,1,0,0,0" debug=7

Using these parameters, except "debug", maximum MAX_DEV dp83815
devices can be configured to user specified configuartion. If there
more than MAX_DEV dp83815 devices first MAX_DEV devices will be
configured using these parameters if they are defined otherwise they
will use defaults, and other devices beyond MAX_DEV will be configured
for autonegotiation advertising for 10/100 Mb/s and full/half duplex.

Following is the list parameters supported:

  o fullduplex: This parameter can be assigned values 0, 1, or 2.

    0: Device in half duplex mode. 
    1: Device in full duplex mode.
    2: full/half duplex (used during autonegotiation to advertise 
       that device is capable of doing both full and half duplex 
       mode of operation.)

  If no value is defined for full-duplex parameter, in case of
  autonegotiation, driver will use full/half duplex capability to advertise,
  otherwise it will put device in half duplex mode. If no autonegotiation is
  being done, then value of 2 for fullduplex will put the device in half
  duplex mode.

  o speed100: This parameter can be assigned value 0, 1, or 2.

    0: Device in 10 Mb/s mode.
    1: Device in 100 Mb/s mode.
    2: Device either in 10 or 100 Mb/s mode. (used during auto 
       negotiation to advertise the capability of the device.)
  
  If no value is defined for this parameter, in case of
  autonegotiation device capability of 10/100 Mb/s will be advertised,
  otherwise in case of no autonegotiation it will put device in 100
  Mb/s mode. If no autonegoatiation is done then value of 2 for
  speed100 will put the device in 100 Mb/s mode.

  o autoneg: This parameter can be assigned 0 or 1.
    
    0: no autonegotiation.
    1: do autonegotiation.
      
  If no value is defined for this parameter, driver will do the
  autonegotiation for the device capability defined by fullduplex and
  speed100 parameter.
  
  Autonegotiation can be done for the following capabilities:
  a) 10 Mb/s full/half duplex.
  b) 10/100 Mb/s half duplex.
  c) 100 Mb/s half duplex.
  d) 10/100 Mbs/s hfull/half duplex.

 o txdesc: This parameter specify number of desriptor used for
           tranmit, it can be assigned any interger value. By default
           driver uses 32 descriptors for transmit.

 o rxdesc: This parameter specify number of receive desriptor, and can
           be assigned any interger value. By default driver uses 30
           desriptors.
 
 o debug: This parameter can be assigned any or sum of the following values.
 
   1:   debug enabled at device probe level.
   2:   debug enabled at device open level.
   4:   debug enabled at device close level.
   8:   debug enabled at device ioctl level.
   16:  debug enabled at device transmit level.
   32:  debug enabled at device receive level.
   64:  debug enabled at device rxfilter setup level.
   128: debug enabled at device autonegotiation level.
   256: debug enabled at device interrupt level.
   
   By defualt none of the debug level will be enabled.

 
The driver can be dynamically loaded and unloaded from a running kernel 
using insmod/rmmod.

	# insmod dp83815
        # rmmod dp83815

Load time parameters can be specified while  running insmod. The example below
shows parameters for   3   dp83815   cards.

  - Card 0 is configured with full-duplex/100/no-autoneg/64 txDesc/32 rxDesc

  - Card 1 is configured with half-duplex/10/no-autoneg/32 txdesc/default
  rxdesc

  - Card 2 is configured with full-or-half-duplex/10-or-100/autoneg/default
  tx-and-rx desc

  - Driver debug level is set to 6 (open & close debug level enabled).


	# insmod dp83815 fullduplex="1,0,2" speed100="1,0,2" \
          autoneg="0,0,1" txdesc="64,32" rxdec="32" debug=6

To install and test the driver, shutdown the network stack, install
the driver, and re-start the startup the stack again.

	# sh /etc/rc.d/init.d/network stop
	# insmod dp83815
	# sh /etc/rc.d/init.d/network start
	

7. FUNCTIONALITY TESTING
------------------------

When the driver is loaded into the system via `insmod' it probes the
PCI bus to locate all DP83815 devices, and creates control structures
for each. The driver logs a couple of messages available in
`/var/log/messages' for each device with information about its PCI
geographic location, IRQ, IO address, and some basic debug information 
(addresses of some important structures).

All the devices on the PCI bus can be listed by,

# cat /proc/pci

IRQ and IO address information from this can be correlated with the 
information displayed by the driver in `/var/log/messages'.

When the TCP/IP stack is initialized, it opens all configured ethernet 
devices, and initializes them for use. At this time, the driver will
perform autonegotiation and log information about the link status.
The driver can then be tested by running ping, telnet, ftp, NFS etc.


8. KNOWN DRIVER PROBLEMS
------------------------

o  Since the device requires that the receive buffer be aligned on a
4-byte (word) boundary, it is not possible to align the IP header
on a word boundary unless the received packet is copied. Since this
version of the driver support a no-copy receive operation, the IP
header will not be aligned. This is not a problem for Intel CPUs,
but will cause exceptions on RISC CPUs (PowerPC, Alpha, ...). While
porting the driver to these platforms, the no-copy receive can be
turned off, but setting the DP_RX_COPY_THRESHOLD to ETH_MAX_PKT_SIZE,
whereby forcing all receive buffers to be copied.

The driver ensures that the IP headers in a copied buffer is aligned
on a word-boundary.


9. DOCUMENTATION REFERENCES
---------------------------

1. National DP83815 10/100 Mb/s Integrated PCI Ethernet
   Media Access Controller and Physical Layer, 1998.

2. Linux Device Drivers, Alessandro Rubini, 1998.

10. BUG REPORTS
--------------

Bug reports and enhancement requests should be directed to
National. Please include the driver version number, hardware
information, and Linux kernel version number along with the bug
report.

mailto: support@nsc.com

*/

/* to convert Linux kernel version into hexadecimal number */
#define DP_KERNEL_VERSION(a,b,c)	(((a) << 16) + ((b) <<8 ) +(c))

/* Generic Kernel Module/Driver Headers */

#include <linux/module.h>
#include <linux/kernel.h>

#include <linux/pci.h>

#include <linux/ioport.h>
#include <asm/io.h>         /* IO stuff */
#include <asm/byteorder.h>
#include <linux/delay.h>

/* Ethernet Driver Specific Headers */

#include <linux/netdevice.h>
#include <linux/etherdevice.h>
#include <linux/skbuff.h>

#if ((LINUX_VERSION_CODE >= DP_KERNEL_VERSION(2,4,18) ) )
#include <linux/slab.h>
MODULE_LICENSE("GPL");
#else
#include <linux/malloc.h>
#endif
#include <linux/if_ether.h>

#include "dp83815.h"

#ifdef LINK_AGGR
#include "adapter.h"
#endif