Sample MDI network drivers for OpenServer 5

The O5ndsaml package includes the following sample MDI network drivers for OpenServer 5:

e3B
3Com 3C503 Etherlink II ISA series (for Ethernet adapters)

e3D
3Com 3C507 EtherLink 16 ISA series (for Ethernet adapters)

tok
IBM Token-Ring Network Adapter series (for Token Ring adapters)

shrk
Matrox NS100 series and Osicom 2300 (for PCI Ethernet adapters)

A sample MDI driver (shrk) was added to the OpenServer NIC Driver Samples package in version 5.0.5a. The shrk driver is a multithreaded driver for PCI adapters. There have been some improvements and bugfixes made to the shrk driver in this release.

For current information about the entire UnixWare/OpenServer Hardware Developers Kit (HDK) release, see the HDK Release Notes.

Note: Documentation references on this page link to the Product Documentation.

System requirements

This package has no installation dependencies. The samples can be installed on either UnixWare 7 or OpenServer 5.0.5 although they can only be built and installed on OpenServer systems. The ndsample package contains sample MDI drivers for UnixWare 7.

Installation

To install the package from:

downloaded files

  1. Log in as root.
  2. Download the package to an installation directory; for example, /tmp.
  3. Use the pkgadd(ADM) command to install it by entering:
    pkgadd  -d  /tmp/O5ndsampl

media distribution

  1. Log in as root.
  2. Insert the CD-ROM in the drive.
  3. Create a cdrom directory if it does not already exist:
    mkdir  /cdrom
  4. Mount the CD-ROM by typing:
    mount  -r  /dev/cd0  /cdrom
  5. Use the pkgadd(ADM) command to install it by entering:
    pkgadd  -d  /cdrom  O5ndsampl

Configuration

No specific configuration is required. The sample drivers can be found under /usr/src/O5hdk/net/drv/mdi.

Known limitations

There are no upgrade scripts included for custom+ packages that are cut from the ndsample source. Upgrade scripts should update the network driver if it has been configured in the link-kit, and schedule a kernel relink and reboot. Without such a script, customers must use the Network Configuration Manager to remove, then add their network adapter and protocol stacks to update the MDI driver. This means they must also reconfigure any protocol stacks they wish to run over the network driver.

For more information

More information concerning MDI drivers may be found in Developing MDI network adapter drivers.

See also OpenServer NIC Driver Testsuite for information about testing and debugging your driver.

A README file may be included with the sample drivers in /usr/src/O5hdk/net/README to provide more information:

This README will cover the following topics:

    * Building Sample MAC (Media Access Control) Driver Interface (MDI) Drivers
    * Network Driver Directory Source Contents
    * Network Driver Software Package (NDSP) extensions - copy and pkg scripts
    * Installing your driver into the network driver source tree


Building Sample MAC (Media Access Control) Driver Interface (MDI) Drivers
-------------------------------------------------------------------------

This directory contains a buildable sample source tree that contains code
for three MDI drivers:

    * 3Com 3c503 EtherLink II - "network/mdi/src/drv/mdi/e3B"	(ISA)
    * 3Com 3c507 EtherLink 16 - "network/mdi/src/drv/mdi/e3D"	(ISA)
    * IBM Token-Ring Network  - "network/mdi/src/drv/mdi/tok"	(ISA and MCA)
    * Matrox/Osicom D21140A   - "network/mdi/src/drv/mdi/shrk"	(PCI)

Also included in these sub-directories are working AOF files, lkcfg scripts, and
"acfg" configuration utility code.

The purpose of this tree is to build a custom installable product that contains
your MDI driver.  


Network Driver Directory Source Contents
----------------------------------------

The sample source code tree is structured as a build tree that creates a
sample Network Drivers disk with a sample MDI drivers on it.  This serves
as an example and facilitates the production of a finished diskette that
includes your driver for testing purposes.  The following diagram describes
the layout of the Network Drivers source tree on the build machine,
where "driver" is replaced by your driver code in the drv/mdi directory below:

                            /usr/src/O5hdk/net/drv/mdi/
                                         |
           --------------------------------------------------------------
           |                  |               |                         |
          cmd/               drv/           scripts/                  tools/
     (provided                |            (provided                (utilities
    utility source)           |          installation and           used during
                             mdi/        configuration scripts)     build)
                              |
   ---------------------------------------------------------------------------
   |                    |                    |                    |          |
  ahdk/                shrk/                e3D/                 tok/     driver
(example AHDK    (example DEC D21140A  (example 3Com         (example IBM    |
stub driver      multithreaded PCI     EtherLink/16          Token-Ring      |
source)          driver source)        driver source)        driver source)  |
                                                                             |
                                                                             |
                                                                             |
       -----------------------------------------------------------------------
       |            |         |        |          |        |       |        |
    Makefile   driver src  AOF/   Driver.o   Space.c   acfg/   lkcfg   driver.h


Each individual MDI driver has its own self contained directory (driver in
the diagram above).  This directory contains the following:

	Makefile
	Driver source
        Include files   (driver.h gets placed in driver package file
                        and copied into the linkkit /etc/pack.d/driver
                        when it's configured)
	AOF/
	Space.c
	lkcfg
	Master           (Optional - override default Master generated by
	                 tools/genmaster)
	Node             (Optional - override default Node generated by
	                 tools/gennode)
	System           (Optional - override default System generated by
	                 tools/gensystem)
	acfg/Makefile, acfg/      (Optional - ISA only)
	"pkg" and "copy" (Optional - adds files to driver package file)

Note the custom(ADM) and netconfig(ADM) product scripts are no longer
provided.  Your self-contained mdi driver directory should be capable
of producing a Driver.o.


NDSP extensions - copy and pkg scripts
--------------------------------------

The examples below show how to get an include file (ne3200.h) placed into the
distribution in "ID/ne/ne3200.h".  If you need files placed under directories
in your driver directory, please refer to the cdmtInput(CDMT) man page.  More
information on CDMT can be found in the "CDMT - Custom Distribution Mastering
Toolkit" reference pages in the "Development System Documentation" set.

Copy scripts are called as "copy driver_src_directory dist_dir dist_dir".
Example copy script:

	# our copy script
	cp $1/ne3200.h $3/ID/ne/ne3200.h

The pkg file contains file and directory definitions used by CDMT to add files
to your package other than those defined in the Network Driver Software Package.
Example pkg script:

	FILE:ne:SERVER:./ID/ne/ne3200.h:


Installing your driver into the network driver source tree
----------------------------------------------------------

Follow the instructions below to install your driver into the Network Driver
Source tree:
	1.  Choose a 3 or 4 letter code for your driver.  Codes currently in
	    use are:
	    btok	IBM Busmaster Token Ring Adapter/A
	    ctr		Compaq Token Ring
	    e3A		3Com EtherLink (3C501)
	    e3B		3Com EtherLink II (3C503)
	    e3C		3Com EtherLink MC (3C523)
	    e3D		3Com EtherLink 16 (3C507)
	    e3E		3Com EtherLink III (3C5X9)
	    eeA		Intel EtherExpress 16
	    eeB		Intel EtherExpress Flash 32
	    eeC		Intel EtherExpress PRO
	    eeD		Intel EtherExpress PRO/100
	    exos	Excelan 205T
	    hfs		Hewlett Packard ISA/EISA/PCI 10/100VG adapters
	    hfm		Hewlett Packard ISA/EISA/PCI 10/100VG adapters
	    hvm		Hewlett Packard ISA/EISA/PCI 10/100VG adapters
	    hvs		Hewlett Packard ISA/EISA/PCI 10/100VG adapters
	    hpe		Hewlett Packard EISA adapters
	    hpi		Hewlett Packard ISA adapters
	    i3B		Racal Interlan EISA
	    i6E		Racal Interlan NI6510
	    nat		Novell NE2000/NSC InfoMover NE2000+
	    ne		Novell NE3200 EISA
	    pnt		AMD Am2100/1500 PCNet-ISA, PCNet-ISA+, PCNet-PCI
	    shrk	Osicom 2300, Matrox Shark NS-100/1 and NS-100/4
	    sebm	SMC 82M32 EtherCard Elite 32C Ultra
	    sme		SMC EtherCard Elite 16C Ultra
	    smpw	SMC EtherPower PCI (8432 series)
	    spwr	SMC EtherPower 10/100 (9432)
	    tok		IBM Token Ring Network Adapter
	    wdn		Western Digital/SMC 8003,8013 series
	    wwdu	IBM Ether, LAN and Auto LANStreamer MC 32

	Note: It is important that driver writers ensure that
	all external function names begin with your driver code.
	A symbol checking tool is now part of the OpenServer NIC Driver
	Testsuite to verify this requirement.

	2.  Copy the source tree onto your build machine.
	3.  Edit the file "Make.inc" and change the following macros:
	    PRODDESC=
	    PRODVENDOR=
	    PRODPRD=
	    PRODREL=
	    DLIST=
	4.  Type "cd drv/mdi" and create a new directory for your driver;
	    this directory must be the same name as your driver code.
	5. Place your driver source into this directory.  You should not need
	   to modify anything outside of this directory other than the Make.inc
	   file mentioned above.
	6. Set up a Makefile in the directory, such that
		make		Builds the driver and any utility source
		make clean	Removes any .o's, tags files etc.
		make clobber	Removes everything built by make
	   The cc line in the Makefile should include at least optimization,
	   and the CFLAGS macro should specify "-w3 -O -I../../.." so the
	   correct MDI include files are used.  Use a Makefile from one of
	   the sample drivers as a model.  When the driver is compiled,
	   there should be no warnings.  It is strongly recommended that you
	   run "lint" on your sources.
	7. Run "make" from the top level directory (e.g., /usr/src/O5hdk/net) 
       followed by "make floppy".  Then cd to archives/FLOPPY and run the 
       command "dd if=VOL.000.000 of=/dev/rfd0135ds18" to copy the image 
       onto a floppy disk.  Then use custom to install from this floppy on 
       the target machine.
	8. You may also run "make sampledist" to make a distribution for
	   the sample drivers provided in this developers kit followed by
	   "make floppy" to create the custom installable archive.

	  NOTE:	Before installing this media image, make sure you remove
		the driver packages that will be replaced.  These can be
		found under the custom "OpenServer Enterprise Connectivity"
		parcel in the "Network Drivers" component.  The packages
		are named "3Com EtherLink II Adapter series", "3Com EtherLink
		16/16TP Adapter", and "IBM Token-Ring Network ISA Series
		(Shared RAM".

	9. OpenServer Release 5.0 Custom is able to install images from
	   DOS floppies from the image "\SCO\CUSTOM.DST".  To install the
	   images on a DOS floppy diskette for inclusion on a floppy that
	   you ship with your adapters, you may run "make dosdd135" with a
	   1.4 Meg. DOS format floppy in the drive.



Document version 7.1.0a
08 July 1999