USER'S GUIDE FOR THE OS2/DOS XLN2X5 MAC DRIVER Steve Dauber Sept. 26, 1988 (version 1.2) 1. Introduction This document describes a MAC driver for the Excelan 205, 215, and 225 series Ethernet boards. Versions of the driver exist for both the OS/2 and DOS operating systems. The MAC driver provides a standard interface to the hardware for the higher levels of the protocol. Much of the functionality of the MAC driver is specified by the LAN Manager Network Driver Interface Specification Version 1.0.1. This document will not attempt to repeat the information of the specification. Unless otherwise noted, the driver will fully conform to this standard. 2. Operation 2.1. Installing the driver The driver is installed using a "device=" line in the config.sys (or config.os2) file. The syntax is: device=[d:][path]drivername [drivernum] d: is the disk on which the driver can be found. path is the path to the driver. drivername is the filename of the driver (either xln2x5.dos or xln2x5.os2). drivernum is the optional driver number. The driver number allows the user to have multiple Excelan boards in the same machine. It allows the driver to find the correct entry in the protocol.ini file. If not specified, it defaults to 1. If multiple boards are installed, each must have a different driver number and corresponding entry in protocol.ini. 1 2.2. Protocol.ini The module name of the driver is MAC2x5_drivernum, where drivernum is the driver number specified in config.sys (or 1 if no number was specified). The following parameters are recognized by the driver: DriverName: Must be "XLN2x5_$" BoardName: The type of board the being used. Must be EXOS_205, EXOS_215, or EXOS_225. All EXOS_205 series boards (eg. EXOS_205T, EXOS_205TM4) should be specified as EXOS_205. Slot: The microchannel slot number of the board. This parameter is only relevant for the EXOS_215, and only necessary if more than one 215 card is in the machine. If it is not specified, the lowest numbered slot containing a 215 board will be used. MemSize: The size of board memory in kilobytes. MemBase: The physical address of the board's window in host memory. IOBase: The base I/O address of the board. Signal: The interrupt level of the board. MaxMCast: The maximum number of multicast addresses allowed at any one time (default = 5). Loopback: Enable MAC layer loopback (see below). For the EXOS_215 board, only the DriverName and BoardName parameters are required. For the 205 and 225 boards, the DriverName, BoardName, MemSize, MemBase, IOBase, and Signal parameters all must be specified. 2.3. Errors If the driver initializes successfully, a message will be printed out to that effect. Otherwise, an error message will be displayed. These error messages are largely self-explanatory. The most common cause of error is parameters which are set incorrectly in the protocol.ini file. The driver does not obtain its interrupt vector until bind time. If it fails to obtain its vector (due to an interrupt level conflict), it will fail to bind, and an incomplete binding will result. 2 3. Functionality The following describes design decisions and features of the driver which are not specified by the LAN Manager Network Driver Interface Specification. 3.1. Interrupts The board interrupts the host to indicate reception of a packet or completion of a request. For the EXOS 215 board, interrupt level sharing is completely supported under DOS and OS/2. The PC architecture causes interrupt level 2 to be mapped to interrupt level 9. The driver takes care of this mapping, so two may be given as the interrupt level of the board in the protocol.ini file. 3.2. Packet Reception The driver passes received packets to the higher protocol layers by using the ReceiveLookahead/TransferData mechanism. The complete packet will always be available at the time ReceiveLookahead is called. 3.3. Loopback Loopback of packets which should be self-received is not supported by the hardware. By default, the MAC driver will not support this loopback in software. This loopback should be supported by higher layers of the protocol. In some cases, loopback at the MAC layer may be necessary (if a protocol stack does not support loopback, for example). MAC layer loopback may be enabled by including the Loopback flag in the protocol.ini file. Note that enabling loopback will decrease performance to some extent, and thus it should not be enabled unless it is required. 3 3.4. General Requests All general requests are executed asynchronously. RequestConfirm is called when the requests complete. The following general requests are supported. SetStationAddress OpenAdaptor CloseAdaptor SetPacketFilter AddMulticastAddress DeleteMulticastAddress UpdateStatistics ClearStatistics SetLookahead 3.5. Statistics The number of statistics kept is limited in order to improve performance. Only the following statistics are kept: Total frames received Frames with CRC error Total bytes received Frames discarded - no buffer space Frames received with errors Total frames transmitted Total bytes transmitted Frames not transmitted - timeout Frames not transmitted - hardware error Frames with alignment error Frames not sent - too many collisions Transmit error mask 4