Installation Instructions for sk98lin Driver

This file contains
 1  Overview
 2  Required Files and Tools
 3  Prerequisites
 4  Preparing the Driver Installation Package
 5  Driver Installation
    5.1  User Installation Mode
    5.2  Expert Installation Mode
    5.3  Patch Generation Mode
 6  Patch Generation and Recompilation of the Kernel
    6.1  Downloading and Unpacking the Linux Kernel
    6.2  Generating the Driver Patch
    6.3  Applying the Driver Patch
    6.4  Configuring the Linux Kernel
    6.5  Compiling the Linux Kernel
    6.6  Installing the Compiled Linux Kernel
 7  Manual Module Loading
 8  Unloading the Module
 9  Driver Parameters
10  Troubleshooting
================================================================================


1  Overview
===========

This document describes the installation of the sk98lin driver 
on your Linux system. It describes how the installation script works
and how it can be used to either install the sk98lin driver or to 
create a Linux kernel patch. The installation script can be used on
any Linux kernel version from 2.4.13 or higher.

Applying the Linux kernel patch requires an installed Linux kernel 
which can be compiled and which is used along with the applied 
sk98lin driver. Therefore, unpacking, patching, configuring
and compiling a Linux kernel is also explained in this document.

This document does not describe the sk98lin driver and its 
parameters. For more information refer to 'sk98lin.txt' or 
the sk98lin.4 man page.
***


2  Required Files and Tools
===========================

To install the sk98lin driver the following files
and tools on your Linux system are required:

- Linux kernel source available in directory /usr/src/linux

- Compiler tools (e.g. gcc)
***


3  Prerequisites
================

The prerequisites for compilation, loading and patch creation of the
sk98lin driver are:

- Any device using the sk98lin kernel module needs to be closed.

- The old sk98lin kernel module needs to be unloaded.
  Per default the installation script will do this automatically
  (if "user mode" installation is selected). 
  If you want to shutdown and unload the old sk98lin kernel module
  manually, run the script in "expert installation" mode.

- Your system has to be equipped with a supported network card. 
  Without a card the full driver functionality cannot be checked.

- The kernel source and kernel version have to be consistent. 
  For instance, it might be, that you run kernel version 2.4.20, but 
  the header files the kernel module will be compiled with refer to 
  kernel version 2.4.21. If you don't have the same kernel version, 
  install the sources and compile a new kernel. It's not possible to 
  mix different kernel versions!
***


4  Preparing the Driver Installation Package
============================================

Before the sk98lin driver installation script can be invoked, the 
installation package needs to be unpacked:

1.  Login as 'root'.
2.  Unpack the driver installation package using the command

    # tar xfvj install-???.tar.bz2
    or
    # bunzip2 -c install-???.tar.bz2 | tar xfv -
***

5  Driver Installation
======================

1. After the driver installation package is unpacked, type the following
   commands to start the sk98lin driver build process:

   # cd DriverInstall
   # ./install.sh

2. Select the driver installation mode (see following subchapters).
3. Wait for the driver build process to finish.
   Depending on the installation mode you selected, the driver is either 
   compiled and installed or a kernel patch is generated.
***

5.1  User Installation Mode
---------------------------

Selecting this installation mode the driver sources shipped
with the install package are compiled and the resulting driver 
module object file is installed to a suitable location (usually somewhere
below directory /lib/modules/...).

No source files of the driver are installed into a kernel directory.
Only the driver module object file and the man page of the driver are 
installed onto your system permanently. 
            
The term "user installation" reflects the fact that the build
process runs automatically without any user interaction. In case
of installation problems, the driver installation script autonomously
tries to solve the problem (if this is possible). 

After compilation has finished, the initial system state and 
configuration is recovered and all (possibly) backed-up system 
files are restored from the initial configuration.
***

5.2  Expert Installation Mode
-----------------------------

Selecting this installation mode the driver sources are also compiled 
and the resulting driver module object file is installed to a suitable 
location (Similiar to the "user installation" mode).

No source files of the driver are installed into a kernel directory.
Only the driver module object file and the man page of the driver are 
installed onto your system permanently.

In contrast to the "user installation" it is the user's responsiblity
to provide a consistent Linux system with correctly installed Linux 
kernel sources. In case of problems at installation time, no attempts
to solve the problem are performed.

In case of problems or warnings, the installation stops and an error 
message is displayed. Then it is up to the user to correct the
error and to restart the installation.
***

5.3  Patch Generation Mode
--------------------------

Selecting this installation mode, a driver patch is created which can 
be applied to your Linux kernel (instead of compiling and installing
the driver on your machine).

Usually, a patch is applied when a recompilation of the Linux
kernel is intended and the latest driver sources need to be
installed permanently in the appropriate driver directory of 
the Linux kernel.

NOTE: You still have to compile your patched Linux kernel in
      order to effectively use the latest driver sources shipped 
      with this installation package! 
***


6  Patch Generation and Recompilation of the Kernel
===================================================

If a new patch has been created using the sk98lin driver installation 
script, 
- it needs to be applied against the Linux kernel sources 
and 
- the Linux kernel has to be recompiled in order to use the 
  sk98lin driver.
***

6.1  Downloading and Unpacking the Linux Kernel
-----------------------------------------------

Before the sk98lin driver installation script is used to generate
a driver patch, a Linux kernel needs to be installed. If you already have 
installed a Linux kernel in the directory /usr/src, you can skip this
paragraph and immediately continue with the paragraph describing
how to apply the patch against the Linux kernel.

To patch the Linux Kernel, proceed as follows:

1.  Login as 'root'.

2.  Download the original Linux source code named linux-a.b.c.tar.bz
    from ftp.kernel.org into the directory /usr/src

3.  Go to the directory /usr/src and remove all symbolic links to old 
    Linux sources using the commands:

    # cd /usr/src
    # rm linux

4.  Unpack the original Linux source code using the command:

    # tar xvjf linux-a.b.c.tar.bz

    After the sources have been installed, they can be found in a
    directory named /usr/src/linux-a.b.c or /usr/src/linux.

5.  If the symbolic link to the target kernel source directory 
    (/usr/src/linux) does not exist, create it manually with the 
    following commands:

    # cd /usr/src
    # ln -s linux.a.b.c linux
***

6.2  Generating the Driver Patch
--------------------------------

1. Run the the sk98lin driver installation script.
2. Choose "gererate patch".
3. Follow the instructions of the install script.
***

6.3  Applying the Driver Patch
------------------------------

To apply the generated Patch into the kernel use the following
commands:
    
# cd /usr/src/linux
# cat /patch-location/sk98lin__vX.XX_a_b_c_patch | patch -p1
***

6.4  Configuring the Linux Kernel
---------------------------------

1.  Go to the directory /usr/src/linux:

    # cd /usr/src/linux

2.  Depending on your current environment mode (console or graphical),
    you have to invoke different Kernel configuration commands:

    - In the console mode, execute the command: 

      # make menuconfig

    - In the graphical mode, execute the command:

      # make xconfig

    - In the graphical mode with kernel 2.6, execute the command: 

      # make gconfig

      This builds a few programs and displays the kernel 
      configuration menu. In this menu you can modify several options 
      of the kernel configuration.

3.  Select the options you want to compile into the new kernel.

    - For kernel 2.4.x family:
      a. Select the menu "Network Device Support".
      b. Select "Ethernet (1000 Mbit)".

    - For kernel 2.6.x family:
      a. Select the menu "device drivers"
      b. Select the menu "Network Device Support".
      c. Select "Ethernet (1000 Mbit)".

4.  Select how to use the driver in the Linux kernel.

    - To compile the driver as a module, mark 
      "Marvell Yukon Chipset/SysKonnect SK-98xx Support" with (M).

    - To integrate the driver permanently into the kernel, mark 
      "Marvell Yukon Chipset/SysKonnect SK-98xx Support" with (*).

5.  Select if you want to use Rx polling (NAPI).

    - To enable Rx polling of the driver, mark
      "Use Rx polling (NAPI)" with (*).

    - To disable Rx polling of the driver, do not mark
      "Use Rx polling (NAPI)".

6.  Select "Exit".

7.  Select the menu "Loadable module support".

8.  Select "Enable loadable module support".

9.  Select "Kernel module loader".

10.  Configure other options depending on your needs (e.g. SCSI).

11. To quit the configuration, select "Exit".

12. When the message "Do you wish to save your new kernel configuration"
    is displayed, select "Yes".
***

6.5  Compiling the Linux Kernel
-------------------------------

After the Linux configuration has been finished, it can be compiled. 

1.  Create all dependencies (unnecessary for kernel 2.6.x):

    # make dep

2.  Build the Linux kernel binary:

    # make clean bzImage.

3.  Build all modules and install them below /lib/modules:

    # make modules
    # make modules_install
***

6.6  Installing the Compiled Linux Kernel
-----------------------------------------

When the compilation of the Linux kernel has been finished it needs
to be installed to the boot directory. In addition to this, the boot 
loader (LILO, GRUB etc.) needs to be notified about the new Linux kernel.

1.  Install the new kernel by copying it into your boot directory 
    by executing the commands (e.g. on Intel/x86 machines):

    # cp arch/i386/boot/bzImage /boot/vmlinuz-new 
    # cp System.map /boot/System.map-new.

2.  Edit the boot loader configuration file to boot the new kernel.
    For details refer to man page and documentation of your boot loader
    (LILO, GRUB).

3.  Reboot your system with the new kernel.
***


7  Manual Module Loading
========================

After booting the Linux kernel and compiling the driver as a loadable 
kernel module (LKM), the driver needs to be loaded.

1. Enter "modprobe sk98lin".

2. If any Marvell Yukon(TM) based adapter is installed in your computer 
   and you have a mounted /proc file system, execute the command:

   # ls /proc/net/sk98lin/ 

   This should produce an output line of the following format:
   eth0   eth1  ...
   which indicates that your adapter(s) has/have been found and initialized.
   
NOTE: For further information (e.g. the driver parameters) refer to 
      the sk98lin.txt file.
***


8  Unloading the Module
=======================

Unloading of the sk98lin driver is only possible if it has been 
compiled as loadable kernel module. Before the driver module can be unloaded,
all interfaces of the driver module need to be stopped using the following 
sequence of commands:

1. Execute the command "ifconfig YOUR_DEVICE down":

  # ifconfig eth0 down
  # ifconfig eth1 down
  # ifconfig ... down

2. Execute the command "rmmod sk98lin".
***


9  Driver Parameters
====================

When loading the driver as a kernel module, additional parameters
can be passed to the driver for configuration.

Those parameters can be passed in two ways: You can either

- state them on the modprobe command line
or
- set them in the file /etc/modules.conf (old name: 
  /etc/conf.modules), in order to force the kernel module loader
  to pass them to the driver at load-time.

NOTE: For further information about the driver parameters and their
      possible values refer to the sk98lin.txt file.
***


10  Troubleshooting
===================

If any problems occur during the installation process, check the 
following list:


Problem:  The SK-98xx adapter cannot be found by the driver.
Solution: In /proc/pci search for the following entry:
             'Ethernet controller: SysKonnect SK-98xx ...'
          If this entry exists, the SK-98xx or SK-98xx V2.0 adapter has 
          been found by the system and should be operational.
          If this entry does not exist or if the file '/proc/pci' is not 
          found, there may be a hardware problem or the PCI support may 
          not be enabled in your kernel.
          The adapter can be checked using the diagnostics program which 
          is available on the SysKonnect web site:
          www.syskonnect.com


Problem:  Programs such as 'ifconfig' or 'route' cannot be found or the 
          error message 'Operation not permitted' is displayed.
Reason:   You are not logged in as user 'root'.
Solution: Logout and login as 'root' or change to 'root' via 'su'.


Problem:  The driver can be started, but if an ip address is assigned
          to an adapter no link up indication appears although it is
          connected to the network. It is also not possible to receive
          or transmit any packets; e.g. 'ping' does not work.
Reason:   The adapter does not receive any interrupts from the Linux 
          system. This can happen when using the APIC (Advanced 
          Programmable Interrupt Controller) of an SMP compiled kernel
          on a UP envrionment. 
Solution: Use the Linux kernel parameters 'noapic' or 'nolapic' when
          booting your kernel. This can be done by adding those kernel
          parameters to the boot manager kernel selection menu (either
          /boot/grub/menu.lst (GRUB) or /etc/lilo.conf (LILO)).
          When you build a kernel, deselect option CONFIG_X86_LOCAL_APIC.


Problem:  The driver can be started, the adapter is connected to the 
          network and a link up indication is displayed, but you cannot 
          receive or transmit any packets; e.g. 'ping' does not work.
Reason:   There is an incorrect route in your routing table or the
          remote host is unreachable.
Solution: Check the routing table with the command 'route' and read the 
          manual help pages dealing with routes (enter 'man route').
          Check the connection to the remote host system.


Problem:  At driver start, the following error message is displayed:
          "eth0: -- ERROR --
          Class: internal Software error
          Nr:    0xcc
          Msg:   SkGeInitPort() cannot init running ports"
Reason:   You are using a driver compiled for single processor machines 
          on a multiprocessor machine with SMP (Symmetric MultiProcessor) 
          kernel.
Solution: Configure your kernel appropriately and recompile the kernel.
***


***End of Readme File***
