********************************************************************* * THE USE BY YOU OF THIS SOFTWARE IS GOVERNED IN ALL * RESPECTS BY THE MADGE LTD OPEN SOURCE LICENSE. * WE ADVISE YOU TO READ THE TERMS OF THE OPEN SOURCE LICENSE * WHICH CAN BE FOUND WITHIN THE LICENSE.TXT FILE WHICH IS PART * OF THIS SOFTWARE OR BY VISITING THE MADGE LTD WEBSITE * http://www.madge.com/ * MADGE LTD RESERVES THE RIGHT TO SEEK REDRESS FOR * ANY VIOLATION OF THE LICENSE'S TERMS ********************************************************************* Madge Token Ring Open-Source Driver For Linux - September 2003 ========================================================== Contents ======== 1. Introduction 2. Contents of this Distribution 3. Building the Driver 4. Installation 5. Command Line Parameters 6. Installing a kernel patch 7. Kernel Improvements for Cardbus Support 8. Madge Support and Contact Information 1. Introduction =============== This driver software supports the following Madge Token Ring adapter cards: * 51-05 Smart Mk4 100/16/4 PCI Adapter * 53-05 Smart Mk4 100/16/4 PCI Adapter (Low Profile) * 3140 2010 RapidFire 3140V2 16/4 TR PCI Adapter * 31-04 RapidFire 3140V2 16/4 TR PCI Adapter (Low Profile) * 20-03 Smart 16/4 CardBus Mk2 The compiled software has been tested on the following uniprocessor Linux kernel versions:- * 2.0.36 * 2.2.5-15 * 2.2.10 * 2.2.12-20 * 2.4.2-2 * 2.4.7-10 * 2.4.18-3 * 2.4.18-14 * 2.4.20-8 This includes support for Redhat Linux 9.0 Note: This Driver software cannot be installed on symmetric multiprocessing (smp) kernel versions. 2. Contents of the Distribution =============================== ./ README - This file. Makefile - The 'Makefile'. config.in - Default configuration options for the driver. driver.h - Configuration file for the Universal Driver Toolkit (UDT). madgetr.c - Main driver source. madgetr.h - Main driver header. ver.h - Some macro definitions to try to make the driver source as compatible as possible over different kernel versions. madgecb.c - Source for the CardBus helper. madgecb.h - Header for the CardBus helper. ./udt - UDT source and header files. ./utils trconfig.c - A command line utility to display information about Madge Token Ring Adapters currently running. Demonstrates how to use the IOCTL interface. Also used to turn on/off MAC frame reception. mver.c - A command line utility to extract Madge product information strings from files. llcping.c - A command line utility to send a TEST or XID frame to another node and wait for the response. 3. Building the driver ====================== Prerequisites You must have at least the kernel headers installed, and if you want to build the CardBus helper modules, you must have unpacked the pcmcia-cs source tree somewhere. Under RedHat the pcmcia source files can normally be found under /usr/src/linux/pcmcia-cs-*. The location varies on other distributions. Things to be noted in RedHat Linux 7.3 and upwards: 1. Remove "custom" string from Extraversion in /usr/src/linux-2.4/Makefile (optional) 2. Run "make menuconfig". Do not edit anything, save the kernel configuration and exit. This will generate ".config" file needed for compilation of driver. 3. Run "make dep". This will resolve all the dependancy and make the driver compatible with the currently running kernel. If you are removing the "custom" string from Extraversion, then the module installation directory will be /lib/modules/ otherwise it will be /lib/modules/custom. Note: RedHat release 7 and upwards have the pcmcia/CardBus files bundled along with the kernel. The release does not provide the k_compat.h file, which has been provided in this distribution, and will be using this file during compilation. If you would like to use any of the pcmcia-cs-* releases, then you will have to compile the release with the kernel. For instructions on compiling the release, please refer to the readme files with the release. Step 1: Run make The first time you run make on a clean distribution a configuration script will run. It asks for the location of a kernel source tree. This source tree must have been configured and make dep run. It is best if the source tree has been configured and a kernel made from it and that kernel is running when the Madge Token Ring driver is built. The kernel configuration options can either be taken from the running kernel or from the kernel source tree. If the driver is to be used with the running kernel select that option. If you are building a driver to be used on a kernel version that is different from the kernel version that is currently running you will not be allowed to take configuration options from the currently running kernel. For the vast majority of cases it is fine to accept the default driver options. The Cardbus Helper driver module should not be opted to be built if the driver configuration is for PCI adapters. Step 2: Run make After configuring various locations make must be run again to build the driver. The driver file is called mtok.o. The PCMCIA and CardBus helpers are called mtok_cs.o and mtok_cb.o respectively. These modules will be found in the root of the distribution directory. Please read Section 7 below for more information on using Madge Cardbus Token Ring adapters. 4. Installation =============== The mtok.o driver is intended to be used as a loadable module. It must be copied to the /lib/modules directory. The following command can be used to copy the modules into the appropriate places:- "make install" The kernel must be told which device drivers should be used for which network interfaces. This is done by adding lines to the file /etc/modules.conf (called conf.modules on some systems). Add a line as follows:- alias tr0 mtok This tells the system that the first Token Ring interface will be controlled by the Madge driver. If you will be using the module to control a PCMCIA adapter you must include in your options line the following:- options mtok pcmcia=1 Having done this a command depmod must be executed as follows:- depmod -a This rebuilds the database of module dependancies to include the Madge module. The command "ifconfig tr0" or "/sbin/insmod mtok" should automatically load the Madge module now and display its MAC address. For LAA support in 2.4.x kernels, 1. Install net-tools sources from Redhat Linux source CDs. 2. Dowmload net-tools.1_60.patch from www.linuxtr.net/download.html in /usr/src/redhat/SOURCES directory 3. Apply this patch to it through "patch -p0 The ring speed to which the adapter has been programmed. N=4 -> 4 MBit/s N=16 -> 16 MBit/s N=100 -> 100 MBit/s dtr=N Specifies in which mode the adapter should open. N=0 -> Either DTR or Classic Mode (DTR on a switch port and classic on a shared hub). N=1 -> DTR mode only. N=2 -> Classic mode only. pcmcia=1 Normally the driver will only stay loaded in memory if it successfully finds and configures an adapter. However if a PCMCIA/CardBus adapter is to be used the driver must always be resident. Using the parameter pcmcia=1 ensures that the driver stays resident. txslots=N Specifies the number of transmit slots to be used. The default depends on the adapter type. Increasing this number uses more memory but allows more frames to be queued on the adapter for transmission. It is not advisable to queue too many transmits as this may interfere with higher layer flow control and queueing algorithms. rxslots=N Specifies the number of receive slots to be used. If this parameter is increased then more memory will be used by the driver but more frames can be queued for reception. maxframesize=N Specifies the maximum frame size the adapter will be able to receive. This parameter has a maximum value of 4486 for an adapter running at 4MBps and 17814 for adapters running at 16 and 100MBps. The default value is 2040. Performance improvements may be obtained by increasing this parameter if other machines on the network are also capable of sending and receiving large frames. 6. Installing a kernel patch ============================= If you are using a Madge Token Ring adapter in a remote boot setup or for some other reason require the driver to be included into the kernel rather than built as a module you will need to patch the kernel source tree. This procedure makes all Madge Token Ring interfaces available before the root partition is mounted. This allows the root partition to be an NFS mounted directory for example. Procedure:- 1. Ensure that the kernel source tree you wish to patch is downloaded and unpacked. 2. From in the directory you installed the Madge Token Ring Linux driver source code run:- "make patch" 3. Enter the directory name of where the Linux source tree to be patched is located. e.g. /usr/src/linux 4. Use one of the kernel configuration mechanisms to reconfigure the kernel:- "make config" OR "make menuconfig" OR "make xconfig" 5. Under menu item "Network Device Support" select YES to "Token Ring driver support" and YES to "Madge Token Ring adapter support" 6. Recompile the kernel as follows:- "make dep ; make clean ; make bzImage" 7. Copy the new kernel (arch/i386/boot/bzImage) to an appropriate place edit /etc/lilo.conf and rerun /sbin/lilo. (See your distribution documentation for more information on this stage). Beware that compiling the Madge driver into the kernel will increase the kernel size significantly. It may be necessary to compile other non essential devices for booting as modules in order to decrease the kernel size sufficiently to make space for the Madge driver. Kernel patches are supplied for 2.0.36 and 2.2.10. These patches will generally apply successfully to similar kernel versions too. They have not been tested for any other kernel versions and we cannot guarantee they will work for other versions. 7. Kernel Improvements for Cardbus Support ========================================== The Madge Linux Token Ring driver supports the Madge Cardbus Mk2 Token Ring adapter. However, the driver is dependent upon a card services implementation for Linux. There are known problems with some PCMCIA and Cardbus controllers with the Linux card services implementation. Please see http://pcmcia-cs.sourceforge.net for more information. If problems are experienced when using the standard card services installed with the kernel then it is recommended that you update to the latest card services software. This can be obtained from http://pcmcia-cs.sourceforge.net. Then look in the foundries for pcmcia card services. Use of CardBus cards with 2.0.* kernels is discouraged. It may work on some systems, but not on others, due to PCI BIOS limitations. Also, it is harder to diagnose problems, because /proc/bus/pccard is not available with these kernels. Note that from Redhat Linux 7.3(kernel version 2.4.18-3) the kernel pcmcia-cs source tree does not have "cb_enabler.c" file which is needed to register the client driver to the driver services. In this case you will need to download the latest pcmcia-cs source tree from sourceforge as indicated above. To make CardBus adpater working in 2.4.18 series/2.4.20 kernels, you need to take care of the following: 1. Compile the kernel without "CONFIG_PCMCIA" support. 2. Compile the latest pcmcia-cs source tree (At the time of testing, pcmcia-cs-3.2.4 was used) Please go through the PCMCIA-HOWTO and README-2.4 in the pcmcia-cs source tree for compilation help. 3. Configure the Driver to select the option to build the Cardbus Helper module and then compile the driver source. During compilation, if you get "CONFIG_X86_L1_CACHE_SHIFT" undeclared problem in /usr/src/linux-2.4/include/asm/processor.h try copying /usr/include/asm/processor.h to /usr/src/linux-2.4/include/asm/processor.h but keep a copy of /usr/src/linux-2.4/include/asm/processor.h. If you get conflicting types error from the processor.h and sched.h system files, for the return type of kernel_thread function, comment the line in sched.h file for compilation of the driver. If you get "unresolved symbol: register_pccard_driver_R1c442d6c unregister_pccard_driver_Rdb348cd2 WARNING: cb_enabler is not loaded" then in /etc/sysconfig/pcmcia file, please change PCIC_OPTS=yenta_socket to PCIC_OPTS=i82365 Then reboot the machine or stop & start the pcmcia service by issuing the command "service pcmcia stop" - "service pcmcia start" for the new setting to take effect.This will automatically load the modules (pcmcia_core, i82365, ds) needed by mtok_cb. 8. Madge Support and Contact Information ======================================== Visit Madge at http://www.madge.com For technical support go to the website to find the appropriate telephone number or email contact: http://www.madge.com/support.asp **** End of README ****