

			   [ XALL.DOC ]


	Version 1.4.7[a3] of XALL.SYS is an OS/2 device driver for the 
     following DigiBoard intelligent multichannel cards:

	PC/Xi,e         PC/Xem          PC/2e       EPC/X (ISA)
	MC/Xi           MC/Xem          MC/2e       EPC/X (EISA)
	COM/Xi          COM/Xi-422                  EPC/X (MCA)
	C/X (ISA)       C/X (EISA)      C/X (MCA)   AccelePort

    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, MCXem and Acceleport
    xxbios xxfep                -- for the PC/Xi,e and MC/Xi(fep only)
    mxfep                       -- for the COM/Xi
    cxbios cxfep cxconc         -- for the C/X series
    fxbios fxfep fcconc         -- for the EPC/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 only accounts for the data that is on the actual host 
	adapter and not on C/X and EPC/X concentrators.

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");
	...
