USING THE XLN2X5 MAC DRIVER WITHOUT THE PROTOCOL MANAGER Steve Dauber Excelan, Inc. November 29,1988 1. Introduction The Excelan XLN2x5 MAC driver may be used in two modes. The first mode, in which the driver is used with Microsoft Lan Manager, is described in the XLN2x5 MAC Driver User Guide. The MAC driver (versions 1.4 and greater) may also be used as a standalone link level interface to the Excelan board. In this mode, the MAC does not require the protocol manager. It implements separate mechanisms for obtaining its parameters and for binding to the higher level protocols. 2. Driver Installation The driver is installed using a "device=" line in the config.sys (or config.os2) file. The syntax is: device=[d:][path]drivername [drivernum] [parameter...] 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. parameters are used only when the driver is to be used in standalone mode. They are described more fully below. Note that the "device=" line for the XLN2x5 driver must appear before the "device=" line for any driver which will use it in standalone mode. 1 2.1. Driver Number The driver number allows the user to have multiple Excelan boards in the same machine. If not specified, it defaults to 1. If multiple boards are installed, each must have a different driver number. 2.2. Parameters If the driver is to be used in standalone mode, its hardware parameters must be specified on the command line. If no parameters are specified, the driver will assume it is being used with the protocol manager. If any parameter is specified, the driver will assume it is in standalone mode. The order in which the parameters are given is irrelevant. The following sections describe the parameters used by the driver. To designate numerical parameters, xxx will be used. The user may specify either a decimal integer or a hexadecimal integer starting with the characters 0x (eg. 0xCC000). 2.2.1. Parameters used for all boards BoardName: This gives the type of board being used. This should be specified as EXOS_205, EXOS_215, or EXOS_225. This parameter is mandatory for all boards. MaxMCast: This gives the maximum number of multicast addresses allowed at any one time. It is specified as Cxxx. This parameter is optional, and defaults to 5 if not given. Loopback: This enables software loopback of packets which should be self received (see below). It is specified by placing the parameter L on the command line. 2.2.2. Parameters used by the EXOS 205 and EXOS 225 Boards The following parameters are mandatory when the EXOS205 or EXOS225 board is to be used. For information on parameter values, the hardware manual for your board should be consulted. IOBase: This gives the base I/O address of the board. It is specified as Ixxx. MemBase: This gives the physical address of the board's window in host memory. It is specified as Mxxx. MemSize: This gives the size of board memory in kilobytes. It is specified as Zxxx. Signal: This gives the interrupt level of the board. It is specified as Sxxx. 2 2.2.3. Parameters used by the EXOS 215 Board Slot: This gives the microchannel slot number of the board. It is specified as Txxx. This parameter is only mandatory if more than one EXOS 215 board is to be used in the computer. If it is not given, the driver will scan the microchannel slots until it finds an EXOS 215 board. 2.3. Example config.sys line The following is an example config.sys line for the EXOS 205T board. The parameters used are for the default jumper settings of the board. Items in bold face are optional and were included just for the completeness of the example. device=c:\xln\xln2x5.dos 1 EXOS_205 I0x310 M0xCC000 Z256 S2 L C5 3. Binding to the XLN2x5 MAC Driver 3.1. Introduction Under Lan Manager, binding is accomplished with the aid of the protocol manager. At initialization time, each module registers itself with the protocol manager, passing a far pointer to its Common Characteristics table and a list of modules to which it wishes to bind. At bind time, the protocol manager calls each module in turn, passing the address of the Common Characteristics table of the module to which it should bind. The binding module then extracts the vector of the System routine from the characteristics table, and makes a bind call to the other module. In order to bind without the aid of the protocol manager, the XLN2x5 MAC driver implements an IOCTL call which returns the address of its Common Characteristics table. The binding driver can then use this address to complete the bind in the same way as it would if running under Lan Manager. The binding driver must first open the MAC driver in order to obtain the handle required by the IOCTL call. The device name of the MAC driver is "XLN2X5?$", where ? is the driver number specified on the command line in config.sys. If no number was given, 1 should be used. 3 3.2. Binding under DOS The address of the Common Characteristics table may be obtained using the Device Read IOCTL call. This IOCTL should be requested using Interrupt 21 with the registers loaded with the following values: AH = 44H for IOCTL request AL = 02H for device read DS:DX = Pointer to 4 byte buffer CX = 4 for the size of the buffer BX = Handle from the DOS open of "XLN2X5?$" Upon successful return, the buffer will contain a far pointer to the Common Characteristics table of the XLN2x5 MAC driver. The binding driver may then make the bind call to the MAC whenever it is ready. Note that if the binding entity is an installed device driver, the IOCTL call is only available at initialization time. 4 3.2.1. Example of DOS binding .DATA macdev db 'XLN2X51$',0 ;name of MAC driver filehandle dw ? ;handle for opening driver MacCommChar dd ? ;address of MAC's table .CODE GetCommChar PROC NEAR ;open the MAC driver mov ah,3dh ;command code mov al,40h ;Deny None, Read Only mov dx, OFFSET macdev ;device name int 21h jnc @F ;check for error jmp error @@: mov filehandle,ax ;get pointer to common characteristics table mov ah,44h ;IOCTL req mov al,02h ;device input mov dx,OFFSET MacCommChar ;pointer to buffer mov cx,4 ;size of buffer mov bx,filehandle int 21h ;call DOS jnc @F ;check for error jmp error @@: ret GetCommChar ENDP 5 3.3. Binding under OS/2 The address of the Common Characteristics table may be obtained using the OS/2 IOCTL function. This IOCTL has the following IOCTL request packet parameters: 1. Block Device Unit Code: Undefined since the MAC driver is a character device. 2. Command Code: 16 for Generic IOCTL 3. Status: This field will contain the status of the request upon return. 4. Category code: 82h 5. Function code: 41h 6. Parameter buffer: Unused. Should be set to NULL. 7. Data buffer: Pointer to 4 byte buffer. Upon successful return, the data buffer will contain a far pointer to the Common Characteristics table of the XLN2x5 MAC driver. Under OS/2, the IOCTL call must be made at driver initialization time. However, the driver can only bind to the MAC when it is running at Ring 0 ie. after initialization has completed. The binding driver must thus have some external mechanism by which it regains control after initialization time in order to make the bind call to the MAC. 6 3.3.1. Example of OS/2 Binding .DATA MacCommChar dd ? ;address of MAC's table filehandle dw ? ;handle for opening driver action dw ? ;used by DOSOPEN macdev db 'XLN2X51$',0 ;name of MAC driver .CODE EXTRN DOSOPEN:FAR, DOSDEVIOCTL:FAR, DOSPUTMESSAGE:FAR GetCommChar PROC NEAR ;open the MAC driver push ds ;pointer to device name push OFFSET macdev push ds ;pointer to file handle push OFFSET filehandle push ds ;pointer to action push OFFSET action push WORD PTR 0 ;size push WORD PTR 0 push WORD PTR READONLY_FILE ;file attribute push WORD PTR (NOTEXIST_FAIL OR EXIST_OPEN) ;open flag push WORD PTR (DENY_NONE OR READ_ONLY) ;open mode push WORD PTR 0 ;reserved push WORD PTR 0 call DOSOPEN cmp ax,0 ;open ok? je @F jmp error @@: push ds ;pointer to data buffer push OFFSET MacCommChar push WORD PTR 0 ;pointer to param area push WORD PTR 0 push 41h ;function push 82h ;category push filehandle ;device handle call DOSDEVIOCTL cmp ax,0 ;IOCTL ok? je @F jmp error @@: ret GetCommChar ENDP 7 4. Driver Description The XLN2x5 MAC driver fully conforms to the Lan Manager Network Driver Interface Specification, Version 1.0.1 (NDIS). This document will not duplicate the information of the NDIS. The following sections document design decisions and additional features of the XLN2x5 driver which may be useful to those designing software which use it. 4.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 specified as the interrupt level of the board. 4.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. 4.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 on the command line. Note that enabling loopback will decrease performance to some extent, and thus it should not be enabled unless it is required. 8 4.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 4.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 9