

KSZ884X Ethernet Driver Installation Guide


01/21/2008


A. Introduction

This installation guide explains how to build the KSZ884X device drivers for
use in a Linux system.  They are provided in source code format so that they
can be used in different systems.  The drivers support two versions of the
KSZ884X hardware: PCI and generic bus.

The PCI drivers can be run anywhere as PCI configuration is standard.

The generic bus drivers were tested in a Renesas Solution Engine 7751R system
running Linux 2.4.18 and ST7100 systems running Linux 2.6.  They expect the
system is properly configured to expose the I/O address space of the KSZ884X
devices and their hardware interrupts can be passed to the drivers.  In the
case of Renesas 7751R system this requires modification to the kernel code
specific to the 7751R to use the KSZ884X devices successfully.


B. Driver Features

The drivers are designed to operate the KSZ884X devices and demonstrate their
hardware capabilities.  They share some common code that is called the KSZ884X
library, which is located under the common subdirectory.  This library
provides an application programming interface to program the KSZ884X hardware.
Please consult the KSZ884X Programmer's Guide to understand how to use the
APIs.  Because the library code is shared in several platforms, the drivers
may not run very efficiently.  To increase performance, the conditional INLINE
is used to put some functions inline.

There are two versions of drivers, one for generic bus and the other for PCI
bus.

The generic bus version of the KSZ884X driver is used for generic bus such as
the SH bus used in the Renesas 7751R board.  It uses a list of banks to access
registers.  It supports early-transmit and early-receive features.  The code
is stored under the LinuxISA subdirectory.

The PCI version of the KSZ884X driver is used for PCI bus.  It uses a flat
address space to access registers.  It uses descriptors to send and receive
packets.  The code is stored under the LinuxPCI subdirectory.

The KSZ8841 has one PHY port to send and receive packets, while the KSZ8842
has two.  It is possible to create two network devices in the KSZ8842 driver so
that the operating system can control which port to send packets.  This is
enabled by the TWO_NETWORK_INTERFACE conditional.


C. Building Driver for Linux 2.6

The driver can be built outside or inside the kernel source tree.  For drivers
loaded as modules it is better to build outside the kernel as it does not
require setting up the code.  For better driver configuration it is necessary
to build it inside the kernel.

To build outside the kernel just first go to the proper subdirectory:

    cd LinuxPCI
or
    cd LinuxISA

and use the kernel module build command:

    make -C /kerneldir M=$PWD modules

The KSZ8842 device driver is built by default.  If KSZ8841 device driver is
desired define CONFIG_KS8841 before building the driver.  Use this command to
build KSZ8841 driver:

    CONFIG_KS8841=y make -C /kerneldir M=$PWD modules

To build inside the kernel source tree the driver code need to be copied to it.
Create a subdirectory KSZ884X under network driver directory drivers/net.
Copy the driver source files to that directory.

    mkdir /kerneldir/drivers/net/KSZ884X
    cp -rp source/* /kerneldir/drivers/net/KSZ884X/

Modify the network driver configuration file Kconfig to include the KSZ884X
configuration by adding the line inside the Ethernet (10 or 100Mbit) menu:

    source "drivers/net/KSZ884X/Kconfig"

Modify the network driver Makefile to build KSZ884X drivers by adding the
lines:

    obj-$(CONFIG_KS8842_ISA) += KSZ884X/LinuxISA/
    obj-$(CONFIG_KS8842_PCI) += KSZ884X/LinuxPCI/

Run "make menuconfig" in the Linux base directory to bring up Linux kernel
configuration.  Select Networking support.  Select Network device support.
Select Ethernet (10 or 100Mbit).  Select KS8841/2 Ethernet controller support.
There will be 5 submenus.  The default is to build KSZ8842 driver.  Select
KS8841 only to build KSZ8841 driver, or select KS8842 with 2 devices to add 2
network interfaces support.  Select SH support to build driver for SH bus, or
select ISA support.  Select PCI support to build driver for PCI bus.  The SH
support, ISA support, and PCI support can indicate module if dynamic module
loading is supported.


D. Building Driver for Linux 2.4

The driver can be built outside or inside the kernel source tree.  For drivers
loaded as modules it is better to build outside the kernel as it does not
require setting up the code.  For better driver configuration it is necessary
to build it inside the kernel.

To build outside the kernel just first go to the proper subdirectory:

    cd LinuxPCI
or
    cd LinuxISA

and use the kernel module build command:

    make -C /kerneldir SUBDIRS=$PWD modules

The KSZ8842 device driver is built by default.  If KSZ8841 device driver is
desired define CONFIG_KS8841 before building the driver.  Use this command to
build KSZ8841 driver:

    CONFIG_KS8841=y make -C /kerneldir SUBDIRS=$PWD modules

To build inside the kernel source tree the driver code need to be copied to it.
Create a subdirectory KSZ884X under network driver directory drivers/net.
Copy the driver source files to that directory.

    mkdir /kerneldir/drivers/net/KSZ884X
    cp -rp source/* /kerneldir/drivers/net/KSZ884X/

Modify the network driver configuration file Config.in to include the KSZ884X
configuration by adding the line inside the Ethernet (10 or 100Mbit) menu:

    source drivers/net/KSZ884X/Config.in

Modify the network driver Makefile to build KSZ884X drivers by adding the
lines:

    subdir-$(CONFIG_KS8842_ISA) += KSZ884X/LinuxISA
    subdir-$(CONFIG_KS8842_PCI) += KSZ884X/LinuxPCI

    ifeq ($(CONFIG_KS8842_ISA),y)
    ifeq ($(CONFIG_KS8841),y)
        obj-y += KSZ884X/LinuxISA/ks8841_isa.o
    else
        obj-y += KSZ884X/LinuxISA/ks8842_isa.o
    endif
    endif
    ifeq ($(CONFIG_KS8842_PCI),y)
    ifeq ($(CONFIG_KS8841),y)
        obj-y += KSZ884X/LinuxPCI/ks8841_pci.o
    else
        obj-y += KSZ884X/LinuxPCI/ks8842_pci.o
    endif
    endif

Run "make menuconfig" in the Linux base directory to bring up Linux kernel
configuration.  Select Network device support.  Select Ethernet
(10 or 100Mbit).  Select KS8841/2 Ethernet controller support.  There will be
5 submenus.  The default is to build KSZ8842 driver.  Select KS8841 only to
build KSZ8841 driver, or select KS8842 with 2 devices to add 2 network
interfaces support.  Select SH support to build driver for SH bus, or select
ISA support.  Select PCI support to build driver for PCI bus.  The SH support,
ISA support, and PCI support can indicate module if dynamic module loading is
supported.

For very old kernel systems that do not have complete kernel development
headers setup the kernel module build does not work, but it is still possible
to build the drivers.  In RedHat 9.0 the kernel header files are located under
/usr/src/linux-2.4/include.  If other locations are used please modify the
Makefile appropriately.  The KERNELDIR in the Makefile specifies this location.
Type a simple "make" to build the default KSZ8842 driver.  For KSZ8841 driver
define CONFIG_KS8841 first and use this command:

    CONFIG_KS8841=y make


E. Additional Information

The driver source files are organized for minimal modification when
customizing.  In most situations only 3 files need to be modified to run the
driver successfully.

The file target.h contains macros for use in different platforms.  For Linux
the conditional DEF_LINUX tells which macros to use.  Some of the conditionals
defined there need to be changed for generic bus drivers as generic bus
hardware has many variations.  Refer to section Building Generic Bus Drivers
for more details.

The file hardware.h contains macros independent from system platforms.  It
also contains conditionals that affect hardware operation and conditionals
for debugging.  The debug conditionals are all prefixed with DEBUG_.

The file device.h contains conditionals that affect driver operation.


F. Turning on Debug Information of Drivers

To build a driver with debug statements to help debugging define DEBUG when
building the driver as loadable module:

    DEBUG=1 CONFIG_KS8841=y make -C /kerneldir SUBDIRS=$PWD modules

When conditional DEBUG is defined the conditional INLINE is not defined.  To
use inline functions in debug version of driver define INLINE manually:

    DEBUG=1 INLINE=1 CONFIG_KS8841=y make -C /kerneldir SUBDIRS=$PWD modules

Driver built inside the kernel source tree do not provide this flexibility
yet.  To build debug version the conditional DBG need to be manually defined
in the file hardware.h.


G. Building Generic Bus Drivers

Changing conditionals defined in target.h:

The generic bus KSZ884X chips have two versions: 16-bit and 32-bit.  The
default is to build 32-bit version.  For 16-bit define the conditional
SH_16BIT.

Only generic bus is supported for now, so conditional SH_BUS is always
defined.

For 32-bit CPU system it is best to define conditional SH_32BIT_ALIGNED for
best performance.  Undefine it if the driver runs faster in the other case.

Some hardware platforms cannot write a byte successfully.  In this case define
the conditional SH_16BIT_WRITE.

Some hardware platforms can only do 32-bit access.  In this case define the
conditional SH_32BIT_ACCESS_ONLY.  The KSZ8695 Load Board uses such access.

The macros HW_READ_BYTE, HW_WRITE_BYTE, HW_READ_WORD, HW_WRITE_WORD,
HW_READ_DWORD, and HW_WRITE_DWORD are used to access hardware I/O registers.
Modify them appropriately for target hardware platform.


Changing conditionals defined in hardware.h:

Define conditional DBG if debug version of driver is desired.  Other debug
conditionals then can be defined to display certain debug messages.

The A6 revision chip has a feature called Receive Turbo Mode.  Define
conditional RCV_TURBO_MODE to use this feature for better performance.

The conditional AVOID_OVERRUN provides a workaround for a receive problem.  In
newer revision chips where this problem does not occur the conditional can be
undefined.


Changing conditionals defined in device.h:

In ST7100 systems DMA operation is required for faster operation of the
KSZ884X chips.  Define SH_BUS_DMA to use DMA operation.

Some hardware platforms require the global interrupts be disabled when the
KSZ884X hardware interrupt is handled.  Change DEV_INTERRUPT_FLAG from 0 to
SA_INTERRUPT for this behavior.


H. Building PCI drivers for running in the PC

If the target PC has the necessary GCC compiler and kernel development header
files it can be very easy to build the PCI drivers.  The kernel development
header files are mostly located at the directory /usr/src.  For Fedora system
the directory is /usr/src/kernels.  The exact final directory name can be
found by using the command "uname -r."  So the command to use is

     CONFIG_KS8841=y make -C /usr/src/kernels/`uname -r`-`uname -m` \
         M=$PWD modules

After then copy the driver file ks8841_pci.ko to the directory
/lib/modules/`uname -r`/kernel/drivers/net.  Run the command "/sbin/depmod" so
that the PCI driver can be loaded at startup automatically.

To build the driver automatically in RedHat systems a RPM source packet can be
created.  The RPM specification file ksz884x_net.spec is provided to build
this package.  To use it the RPM development tool needs to be installed.

Copy the source file ksz884x-%version.tar.gz to the RPM SOURCE directory.  The
RPM base directory can be the default /usr/src/redhat or the rpmbuild
subdirectory in the user home directory.

Extract the file ksz884x_net.spec from the source file and copy it to the RPM
SPECS directory.  Go to the SPECS directory and type
"rpmbuild -bs ksz884x_net.spec" to build the RPM source package which is
located in the RPM SRPMS directory.  You can continue building the RPM binary
package by using the command
"rpmbuild -bb --target=`uname -m` ksz884x_net.spec."

To build the driver using the RPM source package first install the package:

    rpm -i ksz884x-%version-%release.src.rpm

Go to the RPM SPECS directory and type "rpmbuild --rebuild ksz884x_net.spec."

