[ XALL.DOC ] Version 1.4.5 of XALL.SYS is an OS/2 device driver for the following DigiBoard intelligent multichannel cards: PC/Xi,e PC/Xem PC/2e MC/Xi MC/Xem MC/2e COM/Xi COM/Xi-422 C/X (ISA) C/X (EISA) C/X (MCA) This document is intended for programmers developing software who need to be aware of the advantages and possible problems of using DigiBoard hardware and this provided device driver. Included in the release are several binary data files. They are the BIOS and On-Board Operating system (Front End Processor; i.e. FEP) code for the different boards. sxbios sxfep -- for the PC/Xem and MCXem xxbios xxfep -- for the PC/Xi,e and MC/Xi(fep only) mxfep -- for the COM/Xi cxbios cxfep cxrmt -- for the C/X series fxbios fxfep -- for the HP C/X series Almost all of the standard Device IO commands are supported in full and behave exactly as the standard OS/2 COM01.SYS driver. There are however a few expections as well as undefined or undocumented pieces of how a 'well behaved' serial driver is to behave. Programmers should in general be aware that these are INTELLIGENT cards with large on-board memory buffers for data. Calls to the driver that expect information related to byte-by-byte activity of the driver are at best going to return approximations and at worst will be simply missing some information. Please read the sections below on the setting in the Device Control Block, and GETCOMMSTATUS, GETLINESTATUS, GETCOMMERROR. FILES: xall.sys -- the executable device driver file. xall.doc -- this document. install.doc -- some installation notes for PC bus boards relnotes.doc -- upgrade notes. dmode.exe -- a MODE workalike with extended DEVICE capabilities. The device driver requires a number of command-line arguments described in the installation guide (INSTALL.DOC). STANDARD OS/2 DEVICE DRIVER COMMANDS READ (4) Fully Supported NDREAD (5) Fully Supported WRITE (8) Fully Supported Writes will return to the caller AS SOON as the data has cleared the card -- unless the request size indicates that the transmission should take less than a few seconds -- in which case it will return immediately. If it is important to wait until the data has actually ALL been transmitted be sure to check with GETOUTQUEUECOUNT (see IOCtls below) to see how many bytes remain in the transmit queue. WRITEVFY(9) Supported. We have discovered that even though undocumented in the Programmers Reference, this call gets generated by some implementations of OS/2 if DISKVERIFY is set to ON in the 'config.sys' file EVERY TIME an application program calls DosWrite. Hence this will be treated like a DosWrite. INSTAT (6) Fully Supported OUTSTAT (10) Fully Supported OPEN (13) Fully Supported Shared opens are supported and permissions enforced by the system. Device Baud rates, data types, DCB information, etc. are set per system defaults if this is the first 'open' since system initialization. NOTE: This means that before the first open, the channel is NOT enabled and will NOT accept any data into the receive buffer. CLOSE (14) Fully Supported CLOSE will decrement the number of opens on this port. If this is the final close, CLOSE will flush any outstanding READ requests. If there are still some outstanding WRITEs AND some form of output handshaking is enabled then CLOSE will block until they complete or time out. NOTE: If the process that currently owns the port dies or is killed (eg. Cntl-C/Brk), CLOSE will NOT wait for data to clear before dropping the lines. However, note that OS/2 does NOT pass on signals to the threads within a process; thus if a spawned thread is ALSO blocked on IO when the process tries to die the process will hang for whatever timeout is in effect on the IO block in question. *GEN_IOCTL -- See subsequent part of this document. *PRT_ACS(21) UNSUPPORTED. The IO port associated with the card is not used by application programs for communications, but by the driver for control of the card as a whole. Will return Error. STANDARD OS/2 ioctl COMMANDS Below are the functions defined in the Programmers Ref. manual. Where behavior might not be exactly what you would expect, the function name is preceded by an asterisk. Category 01: SETBAUDRATE (41) Supported in Full Additionally, in order to support higher baud rates within the limitations of a 16-bit word, the following non-standard values will be interpreted thus: value passed: 768 will set 76.8Kbaud 1152 will set 115.2Kbaud SETLINECTRL (42) Supported in Full SETXBAUDRATE (43) Supported in Full The baud rate is passed as a 4-byte long and if supported then is set. Note that the CX cards only support up to 57Kbaud. TRANSMITIMM (44) Supported Since commands must be issued to the card to temporarily suspend software flow control if such is in effect it is possible that if other data is in the Transmit queue that a byte or so of that may also be transmitted. In general this function is NOT recommended if any software flow control is in effect as results on the receiving end may be unpredictable. SETMODEMCTRL (46) Supported in Full Attempts to set/clear modem lines that are currenly invloved in flow control as per DCB.fbCtlHndShake (flag1) will fail. SETBREAKON (4b) Supported The length of time of the transmitted break is 1 min. max ! SETBREAKOFF (45) Supported in Full STOPTRANSMIT (47) (4c) Supported in Full STARTTRANSMIT (48) (4d) Supported SETDCBINFO (53) Supported Setting Flag2.bit6 AND Flag2.bit7 is supposed to enable the RTS-toggle mode on Transmit. This is not supported. Setting BOTH of these bits will be interpreted simply as RTS handshake on Input. DCB.fbTimeout bits 3-7 are documented in IBM's Device Driver guide as relating to Extended Hardware Buffering. Since the settings are so tightly related to the particular hardware used by IBM on their MCA machines and since setting these bits may have caused application programs to assume the presence of a raw 8530 UART, this driver will always clear these bits. Character Replacement/Stripping: NULL-stripping and BREAK- and ERR-char-replacement are supported in this version of the driver but it is important to note that this is done by the driver code, not the on-board FEPOS. Turning these options ON will thus slow things down. Also, if NULL-stripping is enabled, there can be discrepancies between how many bytes GET_INQUEUE_COUNT says are in the buffer and how many bytes are returned to the user by a read call. GETBAUDRATE (61) Supported in Full Beyond the normal limits of 19200 (IBM) or 38400 (MS), this driver supports settings of 57600. Settings beyond 19200 are NOT recommended on the COM/Xi. GETLINECTRL (62) Supported in Full GETXBAUDRATE (43) Supported in Full The fractional bit rates returned are always zero since the rates are quantized by the FEPOS on the card and not calculated by the driver GETCOMMSTATUS (64) (6b) Supported The information in this byte about hardware signal REASONS for Rx or Tx being paused is extracted from comparing the current line signals with the handshake ones requested in DCB.fbCtlHndShake (flag1). No explicit information is available from the DigiCHANNEL hardware concerning those pauses/reasons but the above analysis will result in accurate information barring strange cabling or severely ill on-board operating system. If Tx is paused for reasons of Software Flow control (i.e. an XOFF was received), that condition is accurately reflected in the COMMSTATUS byte. The TX_WAITING_TO_SEND_XON will never be set since the time between the transmitter sending an XON and proceeding (i.e. no longer paused) to subsequent data is not trappable by the Device Driver. Other bits are all set as per the MS OS/2 documentation. Note that on the C/X, information about the transmitter being paused can be inaccurate if all the data in the TX buffer is small enough to have LEFT the host adapter but is still paused on the remote Concentrator. In such instances the above analysys ofcourse fails. Likewise on the GETLINESTATUS call. GETLINESTATUS (65) Supported The HARDWARE_TRANSMITTING bit is set by cheating. The call actually pauses for the time increment to transmit 1 byte at the current baud rate then checks to see if the transmit buffer head pointer has moved. The WAITING_TO_SEND_XON and WAITING_TO_SEND_XOFF bits will never be set as the batch nature of the intelligent card does not permit that information to be reliable. GETMODEMOUTPUT (66) Supported in Full GETMODEMINPUT (67) Supported in Full GETINQUECOUNT (68) Mostly Supported This count can be mistakenly large in certain circumstances. Since the FEPOS encodes line-errors and certain data bytes as multi-byte sequences in the data stream, if such have occured then the count returned will be a few bytes high. The errors will only be quantitative and not logical; the count will never be non-zero when it should be zero or vice-versa. GETOUTQUECOUNT (69) Supported in Full On the C/X there can be up to 2K of data out on the remote box that the driver is [almost] oblivious of. If the buffer on the host adapter is empty, then the driver checks a boolean to see if there is still activity on the remote box -- returning a character count of 1 of there is. GETCOMMERR (6d) Supported Errors in the input data are only detected as the data is read from the card into user space. Thus the COMMERROR byte will accurately indicate Parity, framing, and hardware-overrun errors on data that has been read off the card into user-space. We remain oblivious of COM errors in the data out on the as yet un-read (i.e. un-requested) buffers of the card. GETCOMMEVENT (72) Supported in Full *GETDCBINFO (73) Again, note quirks in SETDCBINFO Category 0x0b FLUSHINPUT (01) Not Supported at this time FLUSHOUTPUT (02) Not Supported at this time ******************************************** Category 0xD1 ******************************************** This is a non-standard category of IOCtl custom for the XALL driver. This section of code will ENABLE altpin processing on the given device. The _QUICKWRITE bit permits the writing of data to the card to happen much more efficently -- utilizing ALL the buffer space on the card before resorting to BLOCKING the process. Without this bit set (default=0), the driver will mimick the Standard MS/IBM COM driver and wait for EACH write request to clear the card before continuing with the next or returning to the user program. /* Enable-Disable reversed interpretations of DSR and CD for RJ45, and * method of waiting for WRITE requests. */ #define IOCTL_CATEGORY_DIGI 0xd1 #define DIGI_CUSTOM 0x07 #define DIGI_QUERY 0x00 /* non-destructively READ settings */ #define QUICKWRITE_ENABLE 0x10 /* if set, wait only on last close */ #define ALTPIN_ENABLE 0x01 #define ALTPIN_DISABLE 0x02 /* default Value */ #define DIGI_BLOCK_EVENT 0x08 unsigned char Current, Want; ... Want = DIGI_QUERY ; ... /* Query current status without change */ if ( DosDevIOCtl ( &Current, &Want, DIGI_CUSTOM, IOCTL_CATEGORY_DIGI, handle) ) { printf ("This driver isn't XALL, won't do DIGI processing"); } else { /* If need CD on 8-wire RJ45 and not already set up */ if ( 8_WIRE_RJ45 && ((Current & ALTPIN_ENABLE) == 0)) { Want = (Current & (~ALTPIN_DISABLE)) | ALTPIN_ENABLE; if ( DosDevIOCtl ( &Current, &Want, DIGI_CUSTOM, IOCTL_CATEGORY_DIGI, handle) ) printf ("Something ill in State of DIGI"); ... ... /* If I want to have QuickWrite processing on this port */ if ( (Current & QUICKWRITE_ENABLE) == 0)) { Want = Current | QUICKWRITE_ENABLE; if ( DosDevIOCtl ( &Current, &Want, DIGI_CUSTOM, IOCTL_CATEGORY_DIGI, handle) ) RETURN VALUE: The call will always return 0. Current Status (0x1,0x2,0x11,0x12) returned in 'Current' byte. A new function has been added to the Digi custom IOCTL's. This function provides a mechanism by which a user program can block until a specific DigiBoard event occurs. These events are defined below. The driver will only block on one event and will return an error if more than one event is specified. #define DIGI_BLOCK_EVENT 0x08 // IOCTL Function Number #define DeltaCTS 0x0008 // Change in CTS #define DeltaDSR 0x0010 // Change in DSR #define DeltaDCD 0x0020 // Change in DCD #define StartRXBreak 0x0040 // Start of a received BREAK #define DeltaRI 0x0100 // Change in RI unsigned char Want; ... Want = DeltaCTS; ... /* Query current status without change */ if ( DosDevIOCtl ( NULL, &Want, DIGI_BLOCK_EVENT, IOCTL_CATEGORY_DIGI, handle) ) { printf ("Error In Call To XALL, Check Parameter\n"); return(ERROR) } printf("Thread Done Blocking on CTS Event\n"); ...