home *** CD-ROM | disk | FTP | other *** search
/ Troubleshooting Netware Systems / CSTRIAL0196.BIN / attach / pcc / v08n03 / netwrk.exe / WDPOST.ZIP / WDPOST.TAR / wdpost.dir / sample.drv / readme.doc < prev    next >
Text File  |  1988-06-21  |  10KB  |  283 lines
  1.                          WESTERN DIGITAL
  2.  
  3.                            WD8003-DRV
  4.                    Sample Software Driver For
  5.                 WD8003-Family LAN Adapter Boards
  6.  
  7.                            Version 3.0 
  8.                           6 April 1988
  9.  
  10.  
  11. This driver shows examples of programming the Western Digital
  12. WD8003 family of LAN adapter boards:
  13.  
  14.      Ethernet    WD8003E    EtherCard PLUS
  15.                  WD8003EBT  EtherCard PLUS With Boot ROM Socket
  16.                  WD8003ET/A EtherCard PLUS For Micro Channel (*)
  17.  
  18.      StarLAN     WD8003S    StarCard PLUS
  19.                  WD8003SH   StarLink PLUS
  20.                  WD8003ST/A StarCard PLUS For Micro Channel
  21.  
  22. This sample driver is part of an actual operating software
  23. system.  You may use it as is, modify it to suit your particular
  24. environment, or simply use it as an example.
  25.  
  26. This driver also applies to new boards being developed in the
  27. WD8003 family, such as 10 Mbps/Twisted Pair products, because
  28. these all have the same software interface.
  29.  
  30.  
  31. DISK CONTENTS
  32.  
  33. There is 1 .C file and 1 .ASM file in the MAC layer, with 2 .EQU
  34. files and 5 .H files for definitions of variables, constants and
  35. stucture:
  36.  
  37.      MACMOD.C
  38.      WD8STAR2.ASM
  39.      FRAMEBLK.EQU
  40.      WD8STAR2.EQU
  41.      MAC.H
  42.      LANCONS.H
  43.      MACDEFS.H
  44.      MACCONS.H
  45.      VERSION.H
  46.  
  47. Files @6FC0.ADF (for WD8003ET/A) and @6FC1.ADF (for WD8003ST/A)
  48. are sample .ADF files for use with Micro Channel adapter boards.
  49.  
  50. This document is contained in the file named README.DOC.
  51.  
  52. The MACMOD.C file contains routines written for the Microsoft
  53. C compiler, Version 4.0.
  54.  
  55.  
  56. DESCRIPTION OF FILES
  57.  
  58.  MACMOD.C
  59.  
  60.     This file contains the interface routines to the LLC 
  61.     sublayer and to the LAN adapter board.
  62.  
  63.     There are six routines in this C file:
  64.  
  65.     1.  init_lanc       One time LAN controller set up routine
  66.     2.  stop_mac        Reset 8390, take it off line
  67.     3a. init_mac        MAC sublayer initialization routine
  68.     3b. start_mac       MAC sublayer start routine
  69.     4.  M_DATArequest   Handle a msdu from LLC layer
  70.     5.  do_mac_queue    Process rx_queue until it is empty
  71.  
  72.  WD8STAR2.ASM
  73.  
  74.     This asm file and the MACMOD.C file will handle the interface
  75.     between upper layer modules and the Western Digital WD8003 
  76.     family adapter boards.
  77.  
  78.     Since the Microsoft compiler is used, the public varibles
  79.     and routines must be named with a leading underscore.
  80.  
  81.     There are six routines in this asm file:
  82.  
  83.     1.  _starlan_wait   Initiate transmit wait loop count for
  84.                         StarLAN to avoid transmitting back-to-
  85.                         back packets from AT-class machines to
  86.                         slower machines
  87.     2.  _init_8390      Initiate 8390 Network Interface Controller
  88.                         Initiate the LAN controller registers
  89.     3.  _hdw_isr        Services all LAN hardware interrupts
  90.     4.  _cp_frm         Copy a frame in system memory to tx buff
  91.                         of shared memory
  92.                         (argument: ptr to the frame buffheader)
  93.     5.  _xmt_frm        Initiate a tx of frame in shared memory
  94.     6.  _rcv_frm        Copy a rx frame from rx buff ring of 
  95.                         shared memory to system memory and put 
  96.                         it into rx_queue
  97.                         (argument: ptr to the frame in ring)
  98.  
  99.  FRAMEBLK.EQU
  100.  
  101.     Defines the structure that is used to pass arguments to 
  102.     public routines.
  103.  
  104.  WD8STAR2.EQU
  105.  
  106.     Provides constants and data definitions for WD8STAR2.ASM file
  107.     for WD8003 family adapter boards.
  108.  
  109.     Contents:   external definition
  110.                 I/O port offset definition
  111.                 I/O register mask definition
  112.                 miscellaneous constants definition
  113.                 structure definition
  114.  
  115.  MAC.H
  116.  
  117.     General header file for Media Access Control module for the 
  118.     WD8003 family of adapter boards.
  119.  
  120.  LANCONS.H
  121.  
  122.     Machine-specific MAC module constants for the 8390-based 
  123.     WD8003 adapter board family:
  124.  
  125.     These constants are for a generic IBM PC (*).
  126.  
  127.  MACDEFS.H
  128.  
  129.     Media Access Control Sublayer module data structure
  130.     definitions for 8390-based WD8003 adapter board family.
  131.  
  132.  MACCONS.H
  133.  
  134.     MAC module constants for the 8390-based WD8003 
  135.     adapter board family.
  136.  
  137.  VERSION.H
  138.  
  139.     Contains version level definitions.
  140.  
  141.  
  142. MICRO CHANNEL ADAPTER INFORMATION
  143.  
  144. Earlier versions of the Sample Driver, up through Version 2.1, 
  145. did not provide for Micro Channel access.  The following changes 
  146. were made for Micro Channel access; the same changes must be
  147. made in any driver written for Western Digital WD8003-family LAN 
  148. adapter boards to ensure proper operation with Micro Channel
  149. adapters:
  150.  
  151. 1) Even Boundary Word Mode Access To Shared Memory
  152.     Western Digital Micro Channel boards support only word mode
  153.     access to their shared buffer memory, and the word access 
  154.     must be on even boundaries.  Routines using byte-mode access 
  155.     to shared memory must be changed.  Furthermore, the memory
  156.     enable bit pattern for the Micro Channel boards is
  157.     different (refer to the init_lanc routine in the MACMOD.C
  158.     module).
  159.  
  160. 2) NIC 8390 Programming
  161.     Since the Micro Channel boards support only word-mode access,
  162.     the 8390 has to be programmed for word-wide DMA transfer.
  163.     This can be done by programming a "1" to the D0 bit of the
  164.     8390 Data Configuration Register (DCR).
  165.  
  166. 3) Size Of Shared Memory
  167.     Instead of 8 Kbytes, the size of the shared memory on 
  168.     Micro Channel adapter boards is 16 Kbytes.  Therefore, the
  169.     size of the receive ring buffer must be adjusted.
  170.  
  171. 4) Level-Sensitive Interrupt
  172.     To support the level-sensitive interrupt mechanism used
  173.     on all Micro Channel machines, the interrupt service routine
  174.     must not attempt to end the interrupt sequence (EOI command)
  175.     until it has reset the interrupt line of the 8390.  The
  176.     8390 interrupt line can be reset by writing 0xFF to its
  177.     Interrupt Status Register (ISR).
  178.  
  179.     Note also that WD8003-family adapter boards for conventional
  180.     PC busses support interrupt levels 2-7;  Micro Channel
  181.     adapter boards support interrupt levels 3, 4, 10 and 15.
  182.  
  183. 5) Machine Identification
  184.     The BIOS call
  185.                    INT 15H,  (AH) = C0H
  186.     can be used at a higher level to decide if the machine on
  187.     which the driver is running has a Micro Channel 
  188.     implementation or not.  The programmer must make this call
  189.     and set the _m_channel flag in WD8STAR2.ASM:
  190.  
  191.            Micro Channel      _m_channel = 1
  192.            PC/XT/AT           _m_channel = 0
  193.  
  194.     The Sample Driver tests this flag and adjusts its operation
  195.     accordingly.
  196.  
  197. To help programmers make the above changes (1-5) in other
  198. drivers, each change has been marked in this Sample Driver as
  199. follows:
  200.  
  201.       /* %%1%%+ */     Beginning of change 1
  202.          - - -
  203.       /* %%1%%- */     End of change 1
  204.  
  205. Changes 2, 3, 4 and 5 are marked in a similar way.  These
  206. markings begin in column 1 of each line to make them easy to
  207. find with a text editor.
  208.  
  209. To read the configuation of the Micro Channel adapter board
  210. from the POS registers, please refer to the following two
  211. documents:
  212.  
  213.         "POS Implementation Procedure" on page 2-33
  214.         of the IBM Personal System/2 Model 50 And 60
  215.         Technical Reference (*)
  216.  
  217.         Western Digital WD8003ET/A High Performance
  218.         Ethernet Adapter Board For Micro Channel
  219.         (Engineering Specification)
  220.  
  221. Western Digital supplies an ADF file with each Micro Channel
  222. adapter board.  Sample ADF files are located on the Sample 
  223. Driver disk:
  224.  
  225.         @6FC0.ADF     For WD8003ET/A (Ethernet)
  226.         @6FC1.ADF     For WD8003ST/A (StarLAN)
  227.  
  228.  
  229. WD8003 DIAGNOSTIC PROGRAM
  230.  
  231. The Western Digital WD8003 Diagnostic Program is available to
  232. verify correct operation of WD8003-family adapter boards in a
  233. network and to serve as a tool for testing software.  It can be
  234. used to generate test data as well as to echo data sent to it.
  235.  
  236.  
  237. VERSION HISTORY
  238.  
  239. Following is information about changes that have been made
  240. in this Sample Driver:
  241.  
  242. Version 3.0  (6 April 1988)
  243.   a) The compiler was changed from LATTICE C (Version 3.0)
  244.      to Microsoft C (Version 4.0).  The major change was
  245.      the use of register variables for higher-speed
  246.      execution.
  247.   b) The _starlan_wait routine was added.
  248.   c) The provisions described above for Micro Channel 
  249.      adapters were added.
  250.  
  251.                            NOTE
  252.      This Sample Driver Version 3.0 only addresses 8 Kbtye
  253.      shared RAM buffers on PC/XT/AT adapter boards.  The
  254.      WD8003EBT Ethernet adapter contains 32 Kbytes of
  255.      buffer RAM, and can operate in either 8K or 32K mode.
  256.      The next version of this Sample Driver (Version 3.1,
  257.      approximately 1 May 1988) will adapt to both
  258.      sizes of RAM buffers automatically.
  259.  
  260. Version 2.1  (6 October 1987)
  261.   Widely distributed version that supported adapter boards
  262.   for conventional PC bus machines.
  263.  
  264.  
  265. FACTORY TECHNICAL SUPPORT
  266.  
  267. For technical support on Western Digital LAN products, call:
  268.  
  269.      (800) 638-5323 or
  270.      (714) 474-2033    ext. 4900
  271.  
  272.      Fax:  (714) 660-4909
  273.  
  274.  
  275. TRADEMARKS
  276.  
  277. EtherCard PLUS, StarCard PLUS and StarLink PLUS are trademarks
  278. of Western Digital Corporation.
  279.  
  280. (*) IBM and PC AT are registered trademarks, and PC XT, Micro
  281. Channel and Personal System/2 are trademarks of International
  282. Business Machines Corporation.
  283.