UNIVEL IHV LAN Driver Packaging Specification =================================================================== The purpose of this document is to describe at a detailed level, the layout of a LAN driver IHV diskette in terms of packaging along with a brief description of the NetWork Installation mechanism. 1. INTRODUCTION In the current System V Release 4.2 UnixWare v1.0 NetWork Installation product, a limited number of LAN drivers are included on the NetWork Install diskette for common adapter boards that have been certified to operate with UnixWare. If a specific LAN driver is not available on the NetWork Install Adapter Selection list that is provided on the diskette, option 12 on the list provides the installer an OTHER LAN driver option. This option is available for IHV developers who are writing LAN drivers for UnixWare and wish to take advantage of distributing an IHV diskette written for UnixWare with the hardware adapter. 2. OVERVIEW Typically, an IHV LAN diskette serves two purposes. It can be used to dynamically configure and load the driver module at network installation time in order to download the UnixWare Application Server or Personal Edition product from another Application Install Server via the IPX network protocol. Alternately, it can be used to install the driver module permanently to disk as a single package for multiple adapter installations. 3. IHV DISKETTE LAYOUT The following describes the layout and contents for the network install diskette based on a sample driver for a 3COM EtherLink III adapter that will support EISA, ISA, and MCA architectures: IHV.NETDRIVER IHV.ioaddr.isa ihv.setparms menu.el3 IHV.intv IHV.ioaddr.mca ihv.writeparms IHV.intv.esa driver/ include/ IHV.ioaddr.esa el3/ menu.cable This diskette should be made as a mountable s5 filesystem. Boot floppy 3 will mount this diskette and copy the appropriate files and configure the adapter for network installations. In addition, the Appl-n_Setup GUI will also support the mounting of this diskette and catalogue the package contained to be used for package installation. 3.1 IHV.NETDRIVER This file is a 0 length label file that is used by boot floppy 3 to ensure that an IHV diskette exists in the drive. 3.2 IHV.intv The default valid interrupts that are supported are listed in this file. If specific architectures support different interrupts, a separate file is created as shown above. The IHV.intv file is the default interrupt file for ISA and MCA architectures. The IHV.intv.esa file lists the valid interrupts for EISA based configurations. The contents of both files are shown below: IHV.intv contents: 3 5 7 9 10 11 12 15 IHV.intv.esa contents: 3 5 9 10 11 12 15 3.3 IHV.ioaddr This file contains the default valid I/O addresses for a specific architecture. If the adapter supports various I/O addresses for each type of architecture, a file is created for each as shown below: IHV.ioaddr.esa contents: 1000 1FFF 2000 2FFF 3000 3FFF 4000 4FFF 5000 5FFF 6000 6FFF 7000 7FFF 8000 8FFF IHV.ioaddr.isa contents: 200 20F 210 21F 240 24F 250 25F 260 26F 320 32F 350 35F 360 36F 370 37F 3D0 3DF 3E0 3EF 3F0 3FF IHV.ioaddr.mca contents: (Example does not list all valid addresses) 200 20F 600 60F A00 A0F E00 E0F 1200 120F 1E00 1E0F 2A00 2A0F 3600 360F 4600 460F 5200 520F 6E00 6E0F 7200 720F 9600 960F A200 A20F B200 B20F CA00 CA0F DA00 DA0F E200 E20F FE00 FE0F 3.4 driver The driver directory contains the configuration files including the driver object file as shown below: Driver.o Master Node Space.c System 3.5 el3 The el3 directory is the driver package directory that has been formatted into a package via the pkgmk command. It is used to install this driver if an add-on board has been installed in the system, or installed as a package after installation of the operating system. This package should not require the Ethernet Hardware Support package to be installed on the system at the time of this package installation. The contents of the package directory is shown below: copyright menu.param posteth3 request depend pkginfo postinstall root menu.el3 posteth1 preinstall menu.err posteth2 preremove request This file is a shell script that is used for requesting information from the installer such as the slot number, the I/O address (automatically calculated by the slot number for EISA architectures), Ram address, and cable connector type. This request script utilizes the menu tools for displaying request forms that prompt for information. A sample request script can be found in the download directory denoted as ihvnet.src on the NSE Vol 2 CDROM, or can be downloaded from CompuServe. All package script examples for this specification can be found on the above mentioned distribution mechanisms. menu.param The package menu form is used to prompt the user for the SLOT number or the I/O address depending on the adapter selection response prompted earlier using the menu.el3 form, and the cable type. An example is shown below: #ident "@(#)pkg.el3:menu.param 1.7" #ident "$Header: $" .optstring Your options are: .pageno Page %d of %d .ul Etherlink III Hardware Support .hhelp_ban Instructions .helpbanner Help: `echo $DRV` Parameter Selection .ur `echo $DRV` Parameter Selection #.ll #Please make a selection. Press F1 for Help. .lr F1=Help .top Select parameters to be configured for adapter `echo $DRV number $BNO`. .form #TYPE_ENUM `[ -f "${SLOT_FILE}" ] && echo "2 ${NSLOTS}${SLOT_CHOICES}SLOT Number://SLOTN//"` `[ -f "$SLOT_FILE" ] && echo "//Right/Left arrow keys for new choice ($NSLOTS choices)//"` #TYPE_ENUM 2 `echo ${NVECT}${INT_CHOICES}`Interrupt Vector://IRQ// //Right/Left arrow keys for new choice (`echo $NVECT` choices)// #TYPE_ENUM `[ -f "${IO_FILE}" ] && echo "2 ${NIOADDR}${IOADDR_CHOICES}I/O Address://IOADDR//"` `[ -f "$IO_FILE" ] && echo "//Right/Left arrow keys for new choice ($NIOADDR choices)//"` `[ -f "$RAM_FILE" ] && echo "2 ${NRAMADDR}${RAMADDR_CHOICES}RAM Address://RAMADDR//"` `[ -f "$RAM_FILE" ] && echo "//Right/Left arrow keys for new choice ($NRAMADDR choices)//"` `[ "${CABLETYPE}" = "AUI" ] && echo "2 2//AUI::AUI//BNC-10BaseT::BNC-10BaseT//Cable Type://CABLETYPE//"` `[ "${CABLETYPE}" = "AUI" ] && echo "//Right/Left arrow keys for new choice (2 choices)//"` `[ "${CABLETYPE}" = "BNC-10BaseT" ] && echo "2 2//BNC-10BaseT::BNC-10BaseT//AUI::AUI//Cable Type://CABLETYPE//"` `[ "${CABLETYPE}" = "BNC-10BaseT" ] && echo "//Right/Left arrow keys for new choice (2 choices)//"` .button Apply Reset .bottom Press 'TAB' to move the cursor between fields. When finished, move the cursor to "Apply" and then press 'ENTER' to continue. .help For detailed instructions, press the 'F1' (or '?') key at any time. SLOT CHOICES Following is a list of available slot addresses: `echo "$AVAIL_SLOTS"` INTERRUPT VECTOR Following is a list of available interrupt vectors: `echo "$AVAIL_INTVS"` `[ -f "$IO_FILE" ] && echo "I/O ADDRESS"` `[ -f "$IO_FILE" ] && echo "Following is a list of available I/O addresses:"` `[ -f "$IO_FILE" ] && cat $IO_FILE` `[ -f "$RAM_FILE" ] && echo "RAM ADDRESS"` `[ -f "$RAM_FILE" ] && echo "Following is a list of available RAM addresses:"` `[ -f "$RAM_FILE" ] && cat $RAM_FILE` `[ "$CABLETYPE" ] && echo "CABLE TYPE"` `[ "$CABLETYPE" ] && echo "Cable selection for $DRV adapter:"` `[ "$CABLETYPE" -a $DRV = EL3_AT ] && echo "For the cable type entry you have two options:"` `[ "$CABLETYPE" -a $DRV = EL3_AT ] && echo "BNC-10BaseT (a thin cable with a round, twist-on connector) and"` `[ "$CABLETYPE" -a $DRV = EL3_AT ] && echo "AUI (a thick cable with a flat, D-shaped connector)."` `[ "$CABLETYPE" -a $DRV = EL3_EISA ] && echo "For the cable type entry you have two options:"` `[ "$CABLETYPE" -a $DRV = EL3_EISA ] && echo "BNC-10BaseT (a thin cable with a round, twist-on connector) and"` `[ "$CABLETYPE" -a $DRV = EL3_EISA ] && echo "AUI (a thick cable with a flat, D-shaped connector)."` `[ "$CABLETYPE" -a $DRV = EL3_MCA ] && echo "For the cable type entry you have two options:"` `[ "$CABLETYPE" -a $DRV = EL3_MCA ] && echo "BNC-10BaseT (a thin cable with a round, twist-on connector) and"` `[ "$CABLETYPE" -a $DRV = EL3_MCA ] && echo "AUI (a thick cable with a flat, D-shaped connector)."` .helpinst ESC=Exit help F1=Instructions 1=Forward 2=Backward .hhelpinst ESC=Exit Instructions 1=Forward 2=Backward .working Working... .end 3.6 ihv.setparms This file is a shell script and is used by boot floppy 3 at network installation time. Its purpose is to setup the following parameters that are exported to the environment to be used later to copy, define, and configure the adapter. The following variables are listed below along with a sample script: INSTDRV - the name of the driver (required) DRV - optional - defaults to IHV DFLT_INTV - the default interrupt vector (optional) IOADDR - the default I/O address range (optional) RAMADDR - the default RAM address (optional) CAB - connector type AUI/BNC (optional) ZWS - zero wait-state, Disable/Enable (optional) mkdir -p $INSTDIR/drivers/$INSTDRV >/dev/null 2>&1 - (required where INSTDIR is /var/tmp/driver. Set by boot floppy 3) mkdir -p $INSTDIR/usr/include >/dev/null 2>&1 (required if driver contains header files to be installed) ihv.setparms contents: #This file is executed twice from boot floppy 3. We only want it to #run the menu selections once so create a file for flagging after we #finish running this the first time. if [ ! -f /tmp/el3set ] then INSTDRV=el3 mkdir -p $INSTDIR/drivers/$INSTDRV >/dev/null 2>&1 mkdir -p $INSTDIR/usr/include >/dev/null 2>&1 ihvrsp=/tmp/$$.ihvresp ihvcrsp=/tmp/ihvcresp CABLETYPE=BNC export CABLETYPE MENUDIR=${HD_MENUS} cp $FLOPMNT/menu.el3 ${MENUDIR} cp $FLOPMNT/menu.cable ${MENUDIR} menu_colors regular menu -r -f ${MENUDIR}/menu.el3 -o $ihvrsp . $ihvrsp #selection of architecture/board type requires specific #configuration options. Boot floppy 3 looks for IHV.intv #IHV.ioaddr, and IHV.ramaddr. Need to copy specific file #to default file to provide correct parameters in /tmp. case "$RETURN_VALUE" in 1) INSTDRV=el3 #if ISA, copy the ISA I/O addresses to /tmp #use the default interrupt file IHV.intv cp $FLOPMNT/IHV.ioaddr.isa /tmp/IHV.ioaddr DFLT_IOADDR="300 31F" DFLT_INTV=5 ;; 2) INSTDRV=el3 #EISA #if EISA, copy the EISA I/O valid addresses to default #file /tmp/IHV.ioaddr and copy the EISA valid interrupt #file to the default file /tmp/IHV.intv cp $FLOPMNT/IHV.ioaddr.esa /tmp/IHV.ioaddr cp $FLOPMNT/IHV.intv.esa /tmp/IHV.intv DFLT_INTV=5 DFLT_IOADDR="1000 1FFF" ;; 3) INSTDRV=el3_mca #if MCA, copy the MCA I/O valid addresses to default #file /tmp/IHV.ioaddr cp $FLOPMNT/IHV.ioaddr.mca /tmp/IHV.ioaddr DFLT_INTV=5 DFLT_IOADDR="1000 102F" ;; esac DRV=el3 export INSTDRV DRV menu -c cp $FLOPMNT/driver/* $INSTDIR/drivers/$INSTDRV menu_colors regular menu -r -f ${MENUDIR}/menu.cable -o $ihvcrsp menu -c > /tmp/el3set #boot #3 has the responses from the menus so set the flag fi DFLT_INTV=5 IOADDR=$DFLT_IOADDR export DFLT_INTV IOADDR 3.7 ihv.writeparms This file is optional. It is a shell script used to modify the driver system file and/or space.c file. A write function is already contained on boot floppy 3 for default drivers. This driver however, requires a specific write function due to modifications made in the space.c file for multiple cable connector types. The boot floppy write function will not accommodate the changes needed for this driver. The contents of this file is shown below: Write_parameters() { [ "$UPDEBUG" = YES ] && set -x DRV=$1 BNO=$2 OFS=$IFS IFS=" " #tab # change the Interrupt Vector, Start and End I/O addresses # to the values provided by the user via the request script. grep "^${DRV}" $INSTDIR/drivers/$DRV/System > /tmp/$$.system read Dev Config Unit Ipl Itype Vector Sioa Eioa Scma Ecma Dma < /tmp/$$.system . $RSPDIR/parameters rm -f $RSPDIR/parameters N=`expr $BNO - 1` [ "$UPDEBUG" = YES ] && goany if [ $N -eq 0 ] then ed - $DRV/System <>$DRV/System fi [ $N -gt 0 ] && echo "clone\t${DRV}_$N\tc:$N\t${DRV}" >>$DRV/Node #$NETINFO -a -d ${DRV}_$N [ "$UPDEBUG" = YES ] && goany # Set the ethernet cable type NUMB=`expr $BNO - 1` . /tmp/ihvcresp case "$CABLETYPE" in BNC) CABLE=0 ;; AUI) CABLE=1 ;; esac [ "$CABLE" ] && { CABLINE="#define CABLE_TYPE_$NUMB $CABLE" # cat $DRV/Space.c | \ # sed -e "s/#define.*CABLE_TYPE_${NUMB}.*/${CABLINE}/" >Space.new ed - $DRV/Space.c </dev/null 2>&1 rm -f /tmp/ihvcresp > /dev/null 2>&1 exit 0 3.8 include The include directory contains the header files to be installed on the disk: sys dlpi_ether.h el3.h 3.9 menu.el3 The menu form is optional, but used in this example to provide a list of adapter type to select from for configuring the appropriate board. .optstring Your options are: .pageno Page %d of %d .ul Network Installation Support .hhelp_ban Instructions .helpbanner Help: EtherLink III Adaptor Selection Menu .ur EtherLink III Adaptor Selection Menu .lr F1=Help .top Following is a list of the EtherLink III adaptor bus type boards. You need to configure a board to install the product. .form 3Com 3C509 AT 3Com 3C579 EISA 3Com 3C509 MCA .button Apply Reset .selection Please select the number of the appropriate board .help For detailed instructions, press or at any time. 3COM EtherLink III ETHERNET NETWORK ADAPTOR BOARDS 3Com EtherLink III (3C509) for AT architectures 3Com EtherLink III (3C579) for EISA architectures 3Com EtherLink III (3C509) for MCA architectures If you are not sure which kind of adaptor you have, refer to the hardware documentation that came with your adaptor. MULTIPLE ADAPTOR BOARD SETUPS You must designate only one of your network adaptor boards for use in installation of the product over the network. If you have multiple network adapters in your system, they can be configured at a later point in the installation process. Refer to the Installation Handbook for more information. .helpinst ESC=Exit help F1=Instructions 1=Forward 2=Backward .hhelpinst ESC=Exit instructions 1=Forward 2=Backward .working Working... .end 3.10 menu.cable This menu form is also optional and needed for this driver due to changes made in the space.c file for this driver for configuring cable types. .optstring Your options are: .pageno Page %d of %d .ul Network Installation Support .hhelp_ban Instructions .helpbanner Help: Cable Selection .ur Cable Parameter Selection .lr F1=Help .top Select parameters to be configured for el3. .form `[ BNC ] && echo "2 2//BNC::BNC//AUI::AUI//Cable Type://CABLETYPE//"` `[ BNC ] && echo "//Right/Left arrow keys for new choice (2 choices)//"` .button Apply Reset .bottom Press 'TAB' to move the cursor between fields. When finished, move the cursor to "Apply" and then press 'ENTER' to continue. .help For detailed instructions, press or ? at any time. `[ "$CABLETYPE" ] && echo "CABLE TYPE"` `[ "$CABLETYPE" ] && echo "Cable selection for $DRV adaptor:"` `[ "$CABLETYPE" -a $DRV = el3 ] && echo "For the cable type entry you have two options:"` `[ "$CABLETYPE" -a $DRV = IHV ] && echo "BNC (a thin cable with a round, twist-on connector,"` `[ "$CABLETYPE" -a $DRV = el3 ] && echo "or a telephone-like connector)"` `[ "$CABLETYPE" -a $DRV = el3 ] && echo "and AUI (a thick cable with a flat, D-shaped connector)."` .helpinst ESC=Exit help F1=Instructions 1=Forward 2=Backward .hhelpinst ESC=Exit Instructions 1=Forward 2=Backward .working Working... .end 4. PACKAGING an ETHERNET DRIVER FOR BULLETIN BOARD DISTRIBUTION To standardize the method used for packaging an IHV driver for bulletin board distribution, the standard conventions should be followed to prevent a customer from confusion when trying to install the update, or trying to figure out what to do with the file once it has been downloaded from a bulletin board. The process used by Univel for distributing IHV drivers for CompuServe is outlined below using the example provided in this document: Step 1. Once the package has been created via the pkgmk command for the driver and the network install files have been completed, the first step is to create a cpio archive of the entire directory layout shown in section 3: #find . -print | cpio -ocvuB > ihvel3 Step 2. The next step is to compress the cpio archive: #compress ihvel3 This step creates a cpio compressed archive denoted as ihvel3.Z Step 3. Create a mkfloppy script that will uncompress the archive, provide the user to create either a 5 1/4" diskette, or a 3 1/2 diskette. This script should also format the floppy, make mountable s5 filesystem on it, and then use the cpio command to unpack the archive, and move the contents to the diskette. Step 4. Provide an electronic set of release notes that are associated with the driver. Step 5. Create a self extracting DOS executable using the PKZIP command that contains the cpio compressed archive, the mkfloppy script, and a set of release notes as shown below: >C: PKZIP IHVEL3.ZIP ihvel3.Z, mkfloppy, EL3.TXT >C: ZIP2EXE IHVEL3.ZIP Step 6. Distribute the IHVEL3.EXE file on the bulletin board. The user can download the file, execute IHVEL3 from a DOS window to unzip the files contained. From a desktop terminal window, or from the standard desktop, the mkfloppy script can be executed to provide the user an automated method for creating an IHV floppy diskette. A sample mkfloppy script is provided on the NSE and CompuServe denoted as ihvnet.src. NOTE: This mechanism can also be used for packaging IHV HBA diskettes using the IHV HBA diskette layout discussed in the ihvsrc directory of the Driver Development Tools Package for UnixWare. 5. INSTALLATION and CONFIGURATION INSTALLATION INSTRUCTIONS FOR UNIXWARE ETHERNET ADAPTER UPDATE This section provides step-by-step procedures for installing a UnixWare Ethernet Adapter Update. In addition, pre-installation requirements have been provided: INSTALLING AN ETHERNET ADAPTER UPDATE FROM THE UNIXWARE DESKTOP NOTE: If an adapter has previously been configured for a different board, and you are installing a new board to be used as the first lan card, then you will need to remove the Ethernet Hardware Support Package using the pkgrm command before attempting to install a new driver. 1. Double-click on the Disks-etc folder inside the UnixWare Desktop window. 2. Place the driver update media into the appropriate drive, and double-click on the device icon that you are installing from. 3. Double-click on the Application Setup icon. (See "Using Application Setup" in Chapter 11 of the User Handbook for more information.) 4. After the system has finished cataloging the contents of the media, a list of packages is displayed in icon format. In this example the el3 package is the only icon that is displayed. 5a. Click on the el3 adapter package icon. 5b. Click on the Application option in the menu bar. 5c. Click on the Install menu item. The Add Application: screen is displayed, and the installation is in progress. 6. A brief message is displayed providing you with instructions for reading and exiting the UnixWare Ethernet Adapter Update Release Notes screen. The release notes will be displayed next. At this time either press the key to continue paging through the release notes or enter "q" at the colon prompt to exit the view. After one of these two steps have been taken, the installation process will continue. 7. The next screen displayed will prompt you to place the media into the drive. The installation process will detect if media has been inserted, and will continue to display the appropriate menu screens to aid you through the installation process. On-line help is also available throughout the installation process. 8. The Adapter Selection Menu screen will prompt for the number of boards to be configured of the selected bus type. 9. The Parameter Selection Menu screen will prompt for the interrupt vector by providing a list of available interrupt vectors. This screen is displayed on a per-board basis. The next field will prompt for either the I/O address for ISA and MCA systems, or the slot # for EISA based architectures. For EISA based systems, the I/O address is automatically configured from the slot number where the board has been installed. If the adapter supports multiple connectors such as AUI, BNC, or TP, the cable type selection field is then displayed. 10. Once the adapter selections have been responded, the installation of the driver software will continue. Once the files have been installed, the installation process will send notice to the installer the shut the system down, and execute a reboot in order to rebuild the kernel, and incorporate the new changes. INSTALLING AN ETHERNET ADAPTER UPDATE FROM THE COMMAND LINE 1. Double-click on the Accessories icon located in the Desktop folder. 2. Double-click on the Terminal icon in the Accessories folder. A Terminal window is displayed. 3. Insert the Ethernet Adapter diskette into a 3.5-inch floppy or 5.25-inch floppy drive. You need to be superuser (id=0) to execute the following command: 4. Mount the diskette as shown below: # mount -r /dev/dsk/f03ht /Disk_A (1st 3.5-inch floppy drive) # mount -r /dev/dsk/f13ht /Disk_B (2nd 3.5-inch floppy drive) # mount -r /dev/dsk/f0hht /Disk_A (1st 5.25-inch floppy drive) # mount -r /dev/dsk/f15ht /Disk_B (2nd 5.25-inch floppy drive) 5. Execute the package installation command: # pkgadd -d /Disk_[A or B] The terminal window will display a list of packages located on the diskette available for installation. 6. Follow steps 6 through 11 of the installation instructions to complete the installation process. INSTALLING AN ETHERNET ADAPTER UPDATE FOR NETWORK INSTALLATIONS 1. Follow the network installation instructions outlined in the UnixWare Installation Guide. 2. Select option 12 "Other" from the Ethernet Adapter Board menu. You will be prompted to insert an IHV diskette. Insert the UnixWare Ethernet Adapter Update diskette into the floppy drive. 3. Respond to the selections presented. The system will configure the adapter board to the options selected from the installation menus. REMOVING AN ETHERNET ADAPTER UPDATE FROM THE UNIXWARE DESKTOP 1. Double-click on the System_Setup icon located in the desktop folder. 2. Double-click on the Appl-n_Setup icon in the System_Setup folder. 3. The system will catalog the installed applications, and display them in icon format. 4. Click on the wd package icon, and click on the Application Remove option of the Application Setup: Installed - All menu bar. REMOVING AN ETHERNET ADAPTER UPDATE FROM THE COMMAND LINE 1. Double-click on the Accessories icon located in the Desktop folder. 2. Double-click on the Terminal icon in the Accessories folder. A terminal window is displayed. 3. You need to be superuser (id=0) to execute the following command: # pkgrm 4. Follow steps 6 through 9 of the removal instructions to complete the package removal process.