home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 4 Drivers
/
04-Drivers.zip
/
594p.zip
/
XALL.DOC
< prev
next >
Wrap
Text File
|
1994-11-21
|
14KB
|
351 lines
[ 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");
...