home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Collection of Hack-Phreak Scene Programs
/
cleanhpvac.zip
/
cleanhpvac
/
X00-202.ZIP
/
X00-DOC.EXE
/
X00REF.DOC
< prev
next >
Wrap
Text File
|
1994-07-09
|
68KB
|
1,719 lines
Functions reference manual for the X00 developer
X.00 A Low Level Serial I/O Communications Driver
for MS DOS and like Operating Systems.
Copyright (c) 1990 by Raymond L. Gwinn
12469 Cavalier Drive
Woodbridge, Virginia 22192
All Rights Reserved
July 15, 1990
Fidonet address 1:265/1
Data 703-494-8331
i
INTRODUCTION
Previously, the documentation for X00 was little more than a
collection of notes. The notes were added to as the development
process continued and enhancements were made. I honestly did not
suspect that X00 would become as widely used as it is. This
manual is an attempt at some decent documentation for X00.
But who do I document for? The user that is setting up a BBS
just wants to get X00 installed and to move on to more important
things. The user that is having problems needs information about
serial I/O communications in general and the PC specifically.
The application developer (programmer) needs detailed information
about each individual function and the information generated.
This manual is intended as a reference for use by application
programmers who desires to use X00. A separate Users manual is
included in the distribution file(s).
This manual and the software distributed with it is provided with
no guarantees. Use at your own risk.
ii
WHAT IS X00 . . . . . . . . . . . . . . . . . . . . . . . . . 1
Warranty . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Licensing Information . . . . . . . . . . . . . . . . . . . . 2
Non-Commercial License . . . . . . . . . . . . . . . . . 2
Commercial License . . . . . . . . . . . . . . . . . . . 2
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Function 00h - Set communications parameters . . . . . . 5
Function 01h - Transmit character and wait . . . . . . . 6
Function 02h - Get received character with wait . . . . 6
Function 03h - Return Serial Port Status . . . . . . . . 7
Function 04h - Activate Port . . . . . . . . . . . . . . 8
Function 05h - Deactivate Port . . . . . . . . . . . . . 9
Function 06h - Raise/lower DTR . . . . . . . . . . . . . 9
Function 07h - Return timer tick information . . . . . 10
Function 08h - Flush output buffer . . . . . . . . . . 10
Function 09h - Purge output buffer . . . . . . . . . . 10
Function 0Ah - Purge input buffer . . . . . . . . . . 11
Function 0Bh - Transmit no wait . . . . . . . . . . . 11
Function 0Ch - Non-destructive read-ahead (Peek) . . . 11
Function 0Dh - Keyboard read without wait . . . . . . 12
Function 0Eh - Keyboard read with wait . . . . . . . . 12
Function 0Fh - Flow Control for serial I/O . . . . . . 13
Xon/Xoff flow control . . . . . . . . . . . . . . 13
RTS/CTS flow control . . . . . . . . . . . . . . 13
Function 10h - Control-C / Control-K checking . . . . 14
Function 11h - Set current cursor location . . . . . . 14
Function 12h - Read current cursor location . . . . . 15
Function 13h - Single character ANSI write to screen . 15
Function 14h - Enable or disable the DCD watchdog . . 15
Function 15h - Write character to screen using BIOS . 16
Function 16h - Add or delete a routine from the timer
tick . . . . . . . . . . . . . . . . . . . . . . 16
Function 17h - Reboot system . . . . . . . . . . . . . 17
Function 18h - Block Read . . . . . . . . . . . . . . 17
Function 19h - Block Write . . . . . . . . . . . . . . 17
Function 1Ah - Break begin or end . . . . . . . . . . 18
Function 1Bh - Return information about X00 . . . . . 19
Superset Functions . . . . . . . . . . . . . . . . . . . . 20
Function 1Ch - Activate Port . . . . . . . . . . . . . 21
Function 1Dh - Deactivate Port . . . . . . . . . . . . 22
Function 1Eh - Extended line control initialization . 23
Function 1Fh - Extended serial port status/control . . 24
Function 20h - Read with no wait (destructive) . . . . 25
Function 21h - Stuff/Poke the receive buffer . . . . . 25
iii
"Layered Application" services . . . . . . . . . . . . . . 26
Function 7Eh - Install an "external application"
function . . . . . . . . . . . . . . . . . . . . 26
Function 7Fh - Remove an "external application"
function . . . . . . . . . . . . . . . . . . . . 27
Application Notes . . . . . . . . . . . . . . . . . . . . . 28
Which Activate/Deactivate functions to use . . . . . . 28
Watch out for disk I/O . . . . . . . . . . . . . . . . 28
Successive timer tick calls . . . . . . . . . . . . . 29
1
WHAT IS X00
X00 is a Serial Input/Output (SIO) communications driver. It
provides an interface between an application program and the
serial communications hardware.
X00 was originally designed as a FOSSIL driver. FOSSIL is an
acronym containing the first character of several communications
programs. The FOSSIL specification is basically an extension of
the PC's BIOS services for serial communications.
Except as noted in the this Manual, X00 meets the FOSSIL level 5
specification. X00 provides additional functions that are not
contained in the FOSSIL level 5 specification.
X00 only works with 8250 (TYPE) serial I/O devices. Such devices
include the 8250A, 16450, 16550, 16550A and the 82510. If you
have a PC that is an IBM or near compatible which has a serial
communication port, it is likely that it contains one of these
devices. XU, a utility distributed with X00, will identify the
existence of compatible SIO devices.
Like other Device Drivers, X00 will do very little standing
alone. There must be an application(s) program to use X00 before
you will gain benefit.
Since the introduction of the FOSSILs, a great number of new
communications programs have come into existence. I like to
think that the FOSSILs are largely responsible for this. Many
programs that contain their own communications drivers have added
FOSSIL support. One notable example is RBBS.
Many programs written to use BIOS's serial communications
services will also work with X00. This gives those programs the
benefits of buffered interrupt driven I/O.
Warranty
There is none. Use X00 your own risk.
2
Licensing Information
Non-Commercial License:
A non-commercial license for use of X00 is included in the
distribution file called LICENSE.TXT.
I have received several unsolicited checks from users of X00.
All of the checks have been returned or uncashed. To date, I
have not accepted any payments for X00. If you feel that X00 is
useful enough that some sort of payment is justified then read
on.
Our local (public) High School desperately needs funds. The
school officials work at keeping the students off the streets and
away from drugs. The local School Board is unable to provide
needed funds for non-academic activities. I suggest a $10.00
contribution be sent to:
Woodbridge Senior High School
3001 Old Bridge Road
Woodbridge, Virginia, 22192
You can make the check payable to "WSHS, Ballfield Improvement
Fund". Please make a note "X00 contribution" somewhere on the
check.
Many of you have used X00 for years. I believe $10.00 is easily
affordable to most X00 users. Please take the time to sit down,
make out the check, address the envelope and mail a contribution.
Shareware authors that wish to distribute X00 with their product
should contact me. Permission will usually be granted.
Commercial License:
Commercial Licenses will be liberally granted in return for a
donation (usually tax deductible). Each commercial license will
be individually granted. That is, there is no single policy that
can be stated here. Some generally uniform commercial license
policies follow.
1 - X00 is usually licensed by product.
2 - All commercial licensees of X00 will receive a special copy
of X00 that will identify, at boot time, the commercial product.
3 - I may require a fully licensed, fully featured, copy of your
product for personal use on multiple computers.
3
4 - The required contribution, which is never to me personally,
will usually be a one time contribution of $100.00.
5 - Proof of licensing belongs to you. That is, I am not going
to be responsible for keeping records. I suggest that you keep a
copy of the donation check so that you can send me a copy if a
question arises. Otherwise you may have to make another
contribution.
6 - You may only distribute versions of X00 that contain your
product name in the X00 banner (at boot time).
7 - If you wish to have the latest version of X00 automatically
sent to you with your product name in the X00 banner, then do the
following: Send me a check for $10.00, in advance, along with a
pre-addressed mailing label. If you require a 3.5 inch diskette,
then write "3.5 inch" on the pre-addressed mailing label and send
$15.00 (instead of $10.00). For updates, the check should be
made out to Raymond L. Gwinn. The checks will be cashed when
received. Individuals that wish to receive a mailed copy of the
latest X00 version may also use this procedure. Once you have
received an update, you will need to resend the update fee and
pre-addressed mailing label if you desire to receive the next
update.
8 - Your contribution check should state "X00 Licensing
contribution" in the Memo or comment field.
If you write me about a commercial license, please include a
voice phone number. You may not receive a response if the voice
phone number is omitted. Correspondence should be sent to:
Raymond L. Gwinn
12469 Cavalier Dr.
Woodbridge, Va. 22192
Prior to making the special version of X00 available, I may wait
for the check to clear the bank. If the check bounces, I will,
most likely, not give any further consideration to a commercial
license.
4
Functions
X00 functions are designed to be called by assembly language
programs. Some rudimentary High Level access routines are
provided in the X00 distribution files. These rudimentary
routines are the so called HLLAPI files.
Parameters for all X00 functions are passed in the basic 808x
registers. In most cases the results of the function are
returned in registers. If no parameter is returned in a
register, X00 will return the register unchanged except for the
AX register. If no information is returned in the AX register,
then its contents upon return from a function is undefined.
Many (most) of the X00 functions require a port number be passed
in the DX register. Port numbers start at 0 (zero). Port 0 and
COM1 are normally the same. However, this relationship must not
be assumed. It is possible for the X00 user to re-map the ports
on their systems. Please refer to the Users Manual for more
information.
I have noted that some application programs are calling X00
functions from the timer tick. This should be done with care.
If the X00 DV option is enabled at load time, X00 could issue a
DESQview Pause command as a result of your call. I am not sure
what the results of this would be, but it points out the type of
consideration that should be done before issuing function calls
from the timer tick.
5
Function 00h - Set communications parameters, baud, parity etc.
Input: AH = 00h
AL = Communications parameters (defined below)
DX = Port number
Output: AX = Port status (see function 03h)
This function is identical to the IBM PC BIOS call except that
110 baud and 150 baud have been replaced by 19200 baud and 38400
baud respectively. The high order 3 bits of AL specify the baud
rate as follows: See functions 1Eh and 1Fh for an enhanced
version of this function.
010 = 300 baud
011 = 600 ''
100 = 1200 ''
101 = 2400 ''
110 = 4800 ''
111 = 9600 ''
000 = 19200 '' (Replaces IBM 110 baud setting)
001 = 38400 '' (Replaces IBM 150 baud setting)
The low order 5 of AL specify the following:
Bits 4-3 define parity: 0 0 no parity
1 0 no parity
0 1 odd parity
1 1 even parity
Bit 2 defines stop bits: 0 1 stop bit;
1 1.5 bits for 5-bit codes,
2 for others
Bits 1-0 character length: 0 0 5 bits
0 1 6 bits
1 0 7 bits
1 1 8 bits
6
Function 01h - Transmit character and wait.
Input: AH = 01h
AL = Character
DX = Port number
Output: AX = Port status (see function 03h)
Upon entry to this function, AL must contain a character that is
to be transmitted. If there is room in the transmit buffer, the
character buffered. Otherwise, this function will loop until
their is room in the buffer or until a timeout occurs. If set,
the high order bit of the returned status indicates a time out
occurred. See function 03h. At the time of this writing, the
timeout is set to 30 seconds.
Note: X00 executes functions with the interrupt mask set as it
was when entered. That is, if X00 is called will interrupts
masked, interrupts will remain masked during the processing of
the function. If this function is called with interrupts masked,
it may never return.
-----------------------------------------------------------------
Function 02h - Get received character with wait.
Receive character with wait
Input: AH = 02h
DX = Port number
Output: AH = Line status (same AH returned by function 3)
AL = Input character
If a character available in the receive buffer, this function
returns the next character from the receive buffer in AL. If no
receive character is available, this function will wait until a
character is received or until a timeout occurs. If a timeout
occurs, the high order bit of AH will be set upon return. See
function 03h. At the time of this writing, the timeout value is
set to 30 seconds.
Note: X00 executes functions with the interrupt mask set as it
was when entered. That is, if X00 is called will interrupts
masked, interrupts will remain masked during the processing of
the function. If this function is called with interrupts masked,
it may never return.
Function 20h is a get character with no wait.
7
Function 03h - Return Serial Port Status.
Input: AH = 03h
DX = Port number
Output: AX = Status bits as follows:
AH = Line Status, where:
Bit 0 = RDA - input data is available in buffer
Bit 1 = OVRN - the input buffer has been overrun
Bit 2 = Reserved (Parity error in BIOS INT 14h)
Bit 3 = Reserved (Framing error in BIOS INT 14h)
Bit 4 = Reserved (Break detect in BIOS INT 14h)
Bit 5 = THRE - room is available in output buffer
Bit 6 = TSRE - output buffer is empty
Bit 7 = Timeout (set by functions 1 and 2 only)
Bit 7 of AH IS ALWAYS ZERO WHEN RETURNED BY FUNCTION 3. Bit 7 of
AH may be set to one by other functions (like 1 and 2) that also
return status. When bit 7 of AH is set to one, none of the other
15 bits returned in AX are valid.
AL = Modem status, where:
Bit 0 = Delta clear to send (not reliable)
Bit 1 = Delta data set ready (not reliable)
Bit 2 = Delta data carrier detect (not reliable)
Bit 3 = Always set to 1 upon return (DUMMY DCD)
Bit 4 = Clear to send (CTS)
Bit 5 = Data set ready (DSR)
Bit 6 = Ring indicator (RI)
Bit 7 = Data carrier detect (DCD)
Bit 3 of AL is always returned set to 1. This enables
application programs to use bit 3 as a carrier detect bit on
hardwired (null modem) links.
8
Function 04h - Activate Port.
Input: AH = 04h
DX = port number
Output: AX = 1954h if successful
BL = maximum function number supported (not
counting functions 7Eh and above)
BH = rev of FOSSIL specification supported
This function instructs X00 to use the FOSSIL specification for
the specified port. Prior to issuing this function, any function
that requires a port number in DX be will passed on to BIOS or
X00's INT 14h BIOS emulator. When this function is called, all
interrupts involved in supporting the communications port
(specified in DX) are set up for support by X00. DTR is turned
on by this function. The baud rate is NOT set or changed by this
function.
If an additional call to this function occurs (2 Inits or Init,
Function nn, Init, etc.) X00 will reset (clear) all buffers and
all flow control is turned off. Values returned in the registers
upon a re-init are the same as an initial init (defined above).
NOTICE: At a future date (July 1991 or later), the author intends
to make this function identical to the PS/2's function 4.
Function 1Ch is a duplicate of this function. New or modified
application programs should discontinue use of this function and
use the duplicate (1Ch) function.
A section is the application notes describes a simple method of
determining which Activate/Deactivate function numbers to use.
The described method should work on all FOSSIL implementations.
9
Function 05h - Deactivate Port.
Input: AH = 05h
DX = Port number
Output: Nothing
This function instructs X00 that it should no longer process
calls for specified port (in DX) using the FOSSIL specification.
If the port was never activated by function 4, then this function
is ignored. Any subsequent function calls, that require a port
number in DX, will be passed to BIOS or the BIOS INT 14h
emulator.
NOTICE: At a future date (July 1991 or later), the author intends
to make this function identical to the PS/2's function 5.
Function 1Dh is a duplicate of this function. New or modified
application programs should discontinue use of this function and
use the duplicate (1Dh) function.
A section is the application notes describes a simple method of
determining which Activate/Deactivate function numbers to use.
The described method should work on all FOSSIL implementations.
-----------------------------------------------------------------
Function 06h - Raise/lower DTR.
Input: AH = 06h
AL = DTR state to set
DX = Port number
Output: Nothing
This function is used to control the DTR signal. AL = 00h means
lower DTR (turn it off), and AL = 01h means to raise DTR (turn it
on). No other function (except functions 04h and 1Ch) will alter
DTR.
10
Function 07h - Return timer tick information.
Input: AH = 07h
Output: AL = Timer tick interrupt number
AH = Approximate interrupts per second (18 on IBM)
DX = Approximate number of milliseconds per tick
This function is used to determine the characteristic of the
timer tick for the computer.
Application programs can use information returned by this
function to dynamically set up code that is executed on every
timer tick.
-----------------------------------------------------------------
Function 08h - Flush output buffer.
Input: AH = 08h
DX = Port number
Output: Nothing
This function is used to wait until any pending output is
transmitted. It does not return until all buffered output has
been sent. This function should be used with care. Flow control
(documented below) can cause your system hang in a tight un-
interruptable loop given the right circumstances.
Note: X00 executes functions with the interrupt mask set as it
was when entered. That is, if X00 is called will interrupts
masked, interrupts will remain masked during the processing of
the function. If this function is called with interrupts masked,
it may never return.
-----------------------------------------------------------------
Function 09h - Purge output buffer.
Input: AH = 09h
DX = Port number
Output: Nothing
This function is used to remove any buffered output (transmit)
data. Any output data remaining in the output buffer (not
transmitted yet) is discarded.
11
Function 0Ah - Purge input buffer.
Input: AH = 0Ah
DX = Port number
Output: Nothing
This function is used to remove any buffered input (received)
data. Any input data which is in the receive buffer is
discarded.
-----------------------------------------------------------------
Function 0Bh - Transmit no wait.
Input: AH = 0Bh
AL = Character
DX = Port number
Output: AX = 0001h - Character was buffered for xmit
AX = 0000h - Character was not buffered
This is exactly the same as function 01h, except that it will
always return immediately. If X00 is unable to buffer the
character (the transmit buffer is full), a value of 0000h is
returned in AX. If X00 accepts the character (room is available),
0001h is returned in AX.
-----------------------------------------------------------------
Function 0Ch - Non-destructive read-ahead (Peek).
Input: AH = 0Ch
DX = Port number
Output: AH = 00h if character is available
AL = Next character if available
AX = 0FFFFh = If no character is available
This function returns the next character from the receive buffer.
If the receive buffer is empty, 0FFFFh is returned in AX. The
character returned remains in the receive buffer. Some
programmers call this function "peek".
Function 20h is a destructive read with no wait.
12
Function 0Dh - Keyboard read without wait.
Input: AH = 0Dh
Output: AX = IBM-style scan code if available
= 0FFFFh if no character not available
This function returns the keyboard scan code of the next
character from the keyboard. This is a non-destructive (peek)
read of the keyboard. If no keyboard data is available, 0FFFFh
is returned in AX.
-----------------------------------------------------------------
Function 0Eh - Keyboard read with wait.
Input: AH = 0Eh
Output: AX = Keyboard scan code
This function return the next character available from the
keyboard. If no keyboard input is available, this function waits
until a keyboard character is available. Returned character
codes are the same as function 0Dh (IBM style scan codes).
13
Function 0Fh - Flow Control for serial I/O.
Input: AH = 0Fh
AL = Bit defining the flow control to use
DX = Port number
Output: Nothing
Two kinds of basic flow control are supported. One is software,
called Xon/Xoff flow control. The other is hardware, called
RTS/CTS flow control. Both software and hardware flow control
may be enabled at the same time.
The bits in the parameter passed in AL are as follows:
Bit 0 = 1 Enable receiving of Xon/Xoff
Bit 1 = 1 Enable RTS/CTS flow control
Bit 2 Reserved (should be zero)
Bit 3 = 1 Enable transmitting of Xon/Xoff
Setting an appropriate bit to zero will cause the flow control
associated with that bit to be disabled.
Enabling the receiving of Xon/Xoff will cause X00 to stop
transmitting upon receiving an Xoff. X00 will resume
transmitting when an Xon is received.
Enabling the sending of Xon/Xoff will cause X00 to send an Xoff
when its buffers are 3/4 full. When the buffers are emptied to
1/4 full, X00 will send an Xon.
X00 WILL ALWAYS CEASE TRANSMITTING WHEN CTS IS LOWERED (TURNED
OFF). TRANSMISSION WILL RESUME WHEN CTS IS RAISED (TURNED ON).
When RTS/CTS flow control is enabled, X00 will drop (turn off)
RTS when the receive buffer is 3/4 full. X00 will raise (turn
on) RTS when the receive buffer empties to 1/4 full. RTS/CTS
flow control is almost always used by modems that operate above
2400 baud. Some 2400 baud modems also use/allow RTS/CTS
handshaking
If the baud rate is locked in the command line that loads X00,
RTS/CTS handshaking is forced. In this case, the application
program can not disable RTS/CTS handshaking.
14
Function 10h - Control-C / Control-K checking and transmitter
disable/enable.
Input: AH = 10h
AL = Control bits (defined below)
DX = Port number
Output: AX = 0001h - A Control-C/K has been received
= 0000h - A Control-C/K has not been received
This is used for BBS operation, primarily. A bit mask is passed
in AL with the following flags:
Bit 0 Enable/disable Control-C / Control-K checking
Bit 1 Disable/enable the transmitter
To enable Control C/K checking set bit 0 = 1, to disable set bit
0 = 0. When checking is enabled, a received Control-C or
Control-K will set a flag (internal to X00). The Control-C/K
character will not be stored in the input buffer. The state of
the internal Control-C/K flag will be returned (then reset) the
next time this function is called. The returned value may be
used by the BBS software as it wishes.
The transmitter disable (bit 1 = 1) and Enable (bit 1 = 0)
function lets the application program to inhibit the transmitter.
The disable of the transmitter is not absolute. Several internal
functions can cause the transmitter to be re-enabled, such as
receiving an Xon when receiving of Xon/Xoff is enabled.
-----------------------------------------------------------------
Function 11h - Set current cursor location.
Input: AH = 11h
DH = Row (line)
DL = Column
Output: Nothing
This function is exactly like INT 10h, subfunction 2, on the IBM
PC. The desired cursor location is passed in DX, row in DH and
column in DL. The row and column are relative to zero. That is,
the home position on the screen is row 0, column 0.
15
Function 12h - Read current cursor location.
Input: AH = 12h
Output: DH = Row (line)
DL = Column
This function is exactly like INT 10h, subfunction 3, on the IBM
PC. The current cursor location (using the same coordinate
system as function 16h) is returned in DX.
-----------------------------------------------------------------
Function 13h - Single character ANSI write to screen.
Input: AH = 13h
AL = Character to display
Output: Nothing
The character passed in AL is sent displayed on the screen at the
current cursor location. ANSI.SYS type processing is performed.
This routine should not be used in such a way that DOS output
(which is not re-entrant) can not be employed by X00 to execute
the function.
-----------------------------------------------------------------
Function 14h - Enable or disable the DCD watchdog.
Input: AH = 14h
AL = 01h - Enable watchdog
= 00h - Disable watchdog
DX = Port number
Output: Nothing
This function enables and disables the monitoring of carrier
detect. When enabled, the state of the carrier detect (DCD) is
constantly monitored during timer tick processing. Should
carrier detect be lost (turned off), the system will be
re-booted. Activate/Deactivate etc have no effect on the state
of the DCD watchdog.
16
Function 15h - Write character to screen using BIOS.
Input: AH = 15h
AL = Character to display
Output: Nothing
The character passed in AL is sent to the screen using BIOS-level
Input/Output routines. This differs from function 13h in that
DOS I/O will not be used.
-----------------------------------------------------------------
Function 16h - Add or delete a routine from the timer tick chain.
Input: AH = 16h
AL = 01h - Add a function
= 00h - Delete a function
ES = Segment of function
DX = Offset of function
Output: AX = 0000h - Operation successful
= 0FFFFh - Operation unsuccessful
This function is used to allow a central authority to manage the
timer interrupts, so that the integrity of the "timer tick chain"
is not compromised. Rather than using the traditional method of
saving the old contents of the timer vector, storing the address
of your routine there, and calling the "old" routine, instead you
call this function. X00 manages a list of such entry points and
calls them on a timer tick (interrupt) using a FAR call.
X00 will allow up to 4 programs to hook into the timer tick
processing. Interrupts are enabled when the hooked routines are
called.
CAUTION, when this FOSSIL function was implemented, it provided
the best means to hook into the timer tick on multi-tasking
systems at that time. However, with the 386 and virtual 8086
mode of operation used by DESQview, Windows V3.0 etc, this
function can crash the system. The reason is the virtual 8086
application (task/window) that hooked in, may not be the active
virtual 8086 (task/window) when the timer tick interrupt occurs.
Due to popularity of the virtual 8086 type multi-tasking systems,
the author (who originally insisted that this function be
created) RECOMMENDS THAT THIS FUNCTION NOT BE USED.
17
Function 17h - Reboot system.
Input: AH = 17h
AL = 00h - "Cold boot"
= 01h - "Warm boot"
Output: Nothing
This function is intended primarily as a security feature. It
provides the application with a last resort escape from a
situation that could allow a security breach.
-----------------------------------------------------------------
Function 18h - Block Read.
Input: AH = 18h
CX = Requested number of characters to transfer
DX = Port number
ES = Segment of the caller's buffer
DI = Offset of the caller's buffer
Output: AX = Number of characters actually transferred
This function will transfer from 0 to 65534 characters from X00's
inbound circular buffer to the caller's buffer. ES:DI are not
changed by this function. The number of bytes placed in the
caller's buffer is returned in AX. The number returned in AX
will be the lesser of the caller's requested amount or the entire
contents (if any) of X00's receive buffer.
-----------------------------------------------------------------
Function 19h - Block Write.
Input: AH = 19h
CX = Requested number of characters to transfer
DX = Port number
ES = Segment of the caller's buffer
DI = Offset of the caller's buffer
Output: AX = Number of characters actually transferred
This function will transfer from 0 to 65534 characters to X00's
outbound circular buffer. ES:DI are not changed by this
function. The number of bytes placed in X00's buffer is returned
in AX. The number returned in AX will be the lesser of the
caller's requested amount or the amount (if any) required to fill
X00's transmit buffer.
18
Function 1Ah - Break begin or end.
Input: AH = 1Ah
AL = 01h - Start sending 'break'
= 00h - Stop sending 'break'
DX = port number
Output: Nothing
This function will start or terminate a break signal. If AL=01h
X00 will start the transmission of a break. If AL=00h X00 will
terminate any break signal. This function is useful for
activating command mode on some modems. The application program
is responsible for the timing of the BREAK. If X00 has been
restrained by an Xoff received from the modem, the flag will be
cleared. An Activate or Deavtivate will stop an in-progress
BREAK.
It is the experience of the author that the duration of a break
should be less than 0.1 seconds.
19
Function 1Bh - Return information about X00.
Input: AH = 1Bh
CX = Size of caller's info buffer in bytes
DX = Port number
ES = Segment of caller's info buffer
DI = Offset of caller's info buffer
Output: AX = Number of bytes actually transferred
CX = '0X' First 2 bytes of 'X00 ' string
DX = ' 0' Second 2 bytes of 'X00 ' string
Note that the values returned in CX and DX can be stored in
memory to form a space terminated string 'X00 '. Additionally,
the values returned in CX and DX can be used to determine if X00
is installed.
This function will transfer information about X00 and its current
status to the caller. This function is intended to assist
"generic" applications to adjust to the current environment.
The data structure (assembly language style) currently returned
by X00 is as follows:
INFO EQU $ ;DEFINE BEGIN OF STRUCTURE
STRSIZ DW INFO_SIZE ;SIZE OF THIS STRUC IN BYTES
MAJVER DB CURR_FOSSIL ;FOSSIL SPECIFICATION REV
MINVER DB CURR_REV ;REV OF THIS DRIVER.
IDENT DD ID_STRING ;"FAR" POINTER TO ASCIIZ
; DRIVER DESCRIPTION STRING.
IBUFR DW IBSIZE ;BYTE SIZE OF THE INPUT BUFFER
IFREE DW ? ;NUMBER OF BUFFERED RECV BYTES
OBUFR DW OBSIZE ;BYTE SIZE OF THE XMIT BUFFER
OFREE DW ? ;NUMBER OF BUFFERED XMIT BYTES
SWIDTH DB SCREEN_WIDTH ;WIDTH OF DISPLAY SCREEN
SHEIGHT DB SCREEN_HEIGHT ;HEIGHT OF DISPLAY SCREEN
BAUD DB ? ;BAUD RATE, COMPUTER TO MODEM
The IDENT string is null-terminated, and does not contain a
newline. The baud rate byte contains the bits that Function 00h
would use to set the port to that speed.
The fields related to a particular port (buffer size, space left
in the buffer, baud rate) will be undefined if port 0FFh or an
invalid port is contained in DX.
In some cases X00 can not accurately return information. For
example, the user can lock the baud rate at 115200 when loading
X00. There is no correct FOSSIL value that X00 can return in the
BAUD field. X00 will set the BAUD field equal to the last baud
rate that the application attempted to set.
20
Superset Functions.
Function numbers above 1Bh and below 7Eh are X00 only functions.
These functions will only work with X00. It is the hope of the
author that these functions will be added by other FOSSIL authors
in their implementations and become a part of the FOSSIL
specification.
Functions 1Ch and 1Dh are exact duplicated of FOSSIL functions 4
and 5.
Functions 1Eh and 1Fh are intended to be exact duplicates of
functions 4 and 5 of the PS/2's BIOS INT 14h.
Function 20h is a destructive read with no wait.
Function 21h is a Stuff/Poke character into the receive buffer.
21
Function 1Ch is a duplicate of function 4. The function is
duplicated so that at a future date, X00 functions 4 and 5 can be
made compatible to the PS/2's function 4 and 5.
Developers are encouraged by the author to start using functions
1Ch and 1Dh instead of functions 4 and 5. See the application
notes section for instructions on a compatible method of
determining if functions 1Ch and 1Dh should be used instead of
functions 4 and 5.
Function 1Ch - Activate Port.
Input: AH = 1Ch
DX = port number
Output: AX = 1954h if successful
BL = maximum function number supported (not
counting functions 7Eh and above)
BH = rev of FOSSIL specification supported
This function instructs X00 to use the FOSSIL specification for
the specified port. Prior to issuing this function, any function
that requires a port number in DX will be passed on to BIOS or
X00's INT 14h BIOS emulator. When this function is called, all
interrupts involved in supporting the communications port
(specified in DX) are set up for support by X00. DTR is turned
on by this function. The baud rate is NOT set or changed by this
function.
If an additional call to this function occurs (2 Inits or Init,
Read, Init, etc.) X00 will reset (clear) all buffers and all flow
control is turned off. Values returned in the registers upon a
re-init are the same as an initial init (defined above).
22
Function 1Dh is a duplicate of function 5. The function is
duplicated so that at a future date, X00 functions 4 and 5 can be
made compatible to the PS/2's functions 4 and 5.
Developers are encouraged by the author to start using functions
1Ch and 1Dh instead of functions 4 and 5. See the application
notes section for instructions on a compatible method of
determining if functions 1Ch and 1Dh should be used instead of
functions 4 and 5.
Function 1Dh - Deactivate Port.
Input: AH = 1Dh
DX = Port number
Output: Nothing
This function instructs X00 that it should no longer to process
calls for specified port (in DX) using the FOSSIL specification.
If the port was never activated by function 4, then this function
is ignored. Any subsequent function calls, that require a port
number in DX, will be passed to BIOS or the BIOS INT 14h
emulator.
23
Function 1Eh - Extended line control initialization.
This function is intended to exactly emulate the PS/2's BIOS INT
14 services, function 4. Some or all of the functions provided
here are duplicated by other X00 functions.
Input: AH = 1Eh
AL = Break, Where:
= 00h, No break and/or turn off break
= 01h, Start send of break.
BH = Parity, where:
= 00h, No parity
= 01h, Odd parity
= 02h, Even parity
= 03h, Mark parity (always 1)
= 04h, Space parity (always 0)
BL = Stop bits, where:
= 00h, One stop bit
= 01h, Two stop bits for 6, 7 and 8 bit word
length, 1 and 1/2 stop bits for 5 bit
word length.
CH = Word length, where:
= 00h, 5 bits
= 01h, 6 bits
= 02h, 7 bits
= 03h, 8 bits
CL = Baud rate, where:
= 00h, 110 baud
= 01h, 150 baud
= 02h, 300 baud
= 03h, 600 baud
= 04h, 1200 baud
= 05h, 2400 baud
= 06h, 4800 baud
= 07h, 9600 baud
= 08h, 19200 baud
DX = Port number
Output: AX = Port status (see function 03h)
If locked at X00 load time, the appropriate parameters of this
function are ignored.
24
Function 1Fh - Extended serial port status/control.
This function is intended to exactly emulate the PS/2's BIOS INT
14 services, function 5. Some or all of the functions provided
here are duplicated by other X00 functions. This function has 2
subfunctions specified by AL.
Subfunction 00h - Read MCR
Input: AH = 1Fh
AL = 00h, Read modem control register (MCR)
DX = Port number
Output: AX = Port status (see function 03h)
BL = Modem control register, where:
Bits 7-5 = 0 (Reserved)
Bit 4 = 1 Loopback mode
Bit 3 = 1 OUT2 (interrupts) enabled
Bit 2 = 1 OUT1 active
Bit 1 = 1 Request to send active
Bit 0 = 1 Data terminal ready (DTR) active
Subfunction 01h - Write MCR
Input: AH = 1Fh
AL = 01h, Write modem control register (MCR)
BL = Modem control register, where:
Bits 7-5 = 0 (Reserved)
Bit 4 = 1 Set loopback mode
Bit 3 = 1 Set OUT2 enable interrupts
Bit 2 = 1 Set OUT1 active (on)
Bit 1 = 1 Set Request to send active (on)
Bit 0 = 1 Set DTR active (on)
DX = Port number
Output: AX = Port status (see function 03h)
In subfunction 01h (write MCR) X00 will force bit 3 to 1. That
is, X00 will not allow the communications interrupts to be
disabled.
RTS may be used as a flow control signal by X00. When the
application program writes the MCR, the RTS bit is treated as an
RTS enable bit. This means that X00 will always allow the
application program to turn RTS off. However, X00 will not turn
on RTS unless it is safe to do so.
25
Function 20h - Read with no wait (destructive).
Input: AH = 20h
DX = Port number
Output: AH = 00h if character is available
AL = Next character if available
AX = 0FFFFh If no character is available
This function returns the next character from the receive buffer.
If the receive buffer is empty, 0FFFFh is returned in AX. This
function is the same as function 0Ch except that any character
returned is removed from the receive buffer.
----------------------------------------------------------------
Function 21h - Stuff/Poke the receive buffer.
Input: AH = 20h
AL = Character to place in the receive buffer
Output: Nothing
This function will insert the passed character into the receive
buffer (at the end). Subsequent reading of the serial input will
read the character. The character is inserted at the end of the
buffer (as though it were just received).
The character is inserted into the receive buffer by calling the
receive interrupt routine. All normal receive checking is
preformed on the character. Some things to note are:
If receiving of Xon/Xoff is enabled and an Xoff is
stuffed/poked into the buffer, the transmitter will stop
until a an Xon is received or stuffed/poked.
If Control C/K checking is enabled and a Control C/K is
stuffed/poked, then the character is not put in the buffer
and the internal flags is set.
The above should give you a little to think about when using this
function.
This function is intended to be fully re-entrant. Thus, it
should be callable from timer tick processing etc.
26
"Layered Application" services.
The functions below are provided to meet the FOSSIL
specification. The following functions in effect make X00 a
dispatcher for other programs.
To operate properly on a multi-port system, any "Layered
Application" must be re-entrant. The only "Layered Application"
know to the author is called a Video FOSSIL. The one Video
Fossil known to the author is not re-entrant and can not be used
on a multi-port system.
Function 7Eh - Install an "external application" function.
Input: AH = 7Eh
AL = Code assigned to external application
DX = Offset of application entry point
ES = Segment of application entry point
Output: AX = 1954h
BL = Code given to application (same as input AL)
BH = 01h - Installation was successful
= 00h - Installation failed
This function may be used by external application code (special
screen drivers, modem code, database code, etc) to link into the
INT 14h service for use by multiple applications. The "error
return" (BH=0 with AX=1954h) should mean that another
application layer has already been installed at that particular
code. Codes 80h through 0BFh are be supported.
External application codes 80h-83h are reserved by FOSSIL
developers for re-organizing FOSSIL services by type (comm,
screen, keyboard, system).
Installed application code will be entered, via a FAR call, from
the INT 14H dispatcher whenever it is entered (with AH =
application code).
If the value returned in AX from this function is not 1954h, the
service code that is trying to be installed should bring up its
own INT 14h code that can service INT 14h functions 7h-0BFh
(80h-0BFh are "applications").
27
Function 7Fh - Remove an "external application" function.
Input: AH = 7Fh
AL = Code assigned to external application
DX = Offset of application entry point
ES = Segment of application entry point
Output: AX = 1954h
BL = Code given to application (same as input AL)
BH = 01h - Removal was successful
= 00h - Removal failed
This function removes an application's entry from the table. If
an error is returned, this means ES:DX did not match any entry at
the slot described by AL. An application that wants to remove
itself from memory can issue the 7F function to remove itself
from the table, then, if it is successful, un-install. If
installed with an INT 14h dispatcher it may un-install provided
no other application(s) have been installed on top of it (using
its dispatcher).
28
Application Notes.
Which Activate/Deactivate functions to use
It is the hope of the author (after a period of time) to make
X00's functions 4 and 5 compatible with the PS/2's INT 14h
functions 4 and 5. Currently, X00's functions 4 and 5 are
duplicated at functions 1Ch and 1Dh respectively. I request that
application programmers start using functions 1Ch and 1Dh if
those functions are available. That is, use functions 1Ch and
1Dh instead of functions 4 and 5 respectively.
It is relatively simple to determine if the functions at 1Ch and
1Dh are available. When your program is ready to activate X00
for a given port, issue function 1Ch. If 1954h is returned, then
the port is activated. If 1954h is not returned, reissue the
request to function 4. Save the function number actually used to
activate the port, then increment it by one to deactivate the
port.
Watch out for disk I/O
Chris Irwin deserves credit for discovering and informing me of
the following: On some (if not all) IBM/Clones, interrupts are
masked for a long period of time during DOS disk I/O. As a
result, data characters were being lost during receive. The
problem is most noticeable on slower (4.77 meg) systems with 8250
or 16450 type SIO chips installed using high speed modems.
Remembering that all high speed modems (that I know of) use
RTS/CTS handshaking, I implemented a back door hook in some Beta
X00s that allowed Chris to turn RTS off prior to any disk I/O.
Turning off RTS while a disk write is taking place fixed the
problem. Also, turning off RTS during disk I/O had no adverse
effect on the transfer speed due to the modems internal buffers.
While RTS is off, the modem simply buffers the data internally.
When RTS is again turned on, the modems internal buffer is
emptied because the transfer rate from the modem to the computer
is faster than the line receive rate.
X00 now has a front door (documented) function (1Fh) that allows
application programs to disable RTS. Note that X00 function 1Fh
is not a FOSSIL function. I hope that it will eventually become
a FOSSIL function. X00s function 1Fh is close to a duplicate of
the PS/2's BIOS INT 14h, function 5.
I strongly suggest that application programmers consider turning
off (disabling) RTS prior to any disk I/O. Even if the modem is
not using RTS/CTS handshaking, turning off RTS will not do any
harm (that I know of).
29
Successive timer tick calls
In some environments, the timer tick chain is called several
times in succession with no delay between the calls. I believe
that one such environment is DESQview. If a task has been asleep
for 10 timer ticks, the timer tick chain will be called 10 times
when the task is activated.
X00 checks the DWORD at 46Ch. If the value at that location has
not changed, X00 ignores the timer tick. Any hooked in
application programs are not called.
This means that the timer tick is not reliable for accurate
timing. All programs (that I know of) that alter the normal
timer tick processing keeps the DWORD at 46Ch (time of day)
updated. If not, your time of day will be off. If you need to
know elapsed time, do not count timer ticks. Use the DWORD at
46Ch to calculate elapsed time. The value stored in the DWORD at
46Ch is the number of timer ticks since the computer was booted
or the number of timer ticks past midnight.
30
Application Notes . . . . . . . . . . . . . . . . . . . . . . 28
FOSSIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Function 00h . . . . . . . . . . . . . . . . . . . . . . . . . 5
Function 01h . . . . . . . . . . . . . . . . . . . . . . . . . 6
Function 02h . . . . . . . . . . . . . . . . . . . . . . . . . 6
Function 03h . . . . . . . . . . . . . . . . . . . . . . . . . 7
Function 04h . . . . . . . . . . . . . . . . . . . . . . . . . 8
Function 05h . . . . . . . . . . . . . . . . . . . . . . . . . 9
Function 06h . . . . . . . . . . . . . . . . . . . . . . . . . 9
Function 07h . . . . . . . . . . . . . . . . . . . . . . . . 10
Function 08h . . . . . . . . . . . . . . . . . . . . . . . . 10
Function 09h . . . . . . . . . . . . . . . . . . . . . . . . 10
Function 0Ah . . . . . . . . . . . . . . . . . . . . . . . . 11
Function 0Bh . . . . . . . . . . . . . . . . . . . . . . . . 11
Function 0Ch . . . . . . . . . . . . . . . . . . . . . . . . 11
Function 0Dh . . . . . . . . . . . . . . . . . . . . . . . . 12
Function 0Eh . . . . . . . . . . . . . . . . . . . . . . . . 12
Function 0Fh . . . . . . . . . . . . . . . . . . . . . . . . 13
Function 10h . . . . . . . . . . . . . . . . . . . . . . . . 14
Function 11h . . . . . . . . . . . . . . . . . . . . . . . . 14
Function 12h . . . . . . . . . . . . . . . . . . . . . . . . 15
Function 13h . . . . . . . . . . . . . . . . . . . . . . . . 15
Function 14h . . . . . . . . . . . . . . . . . . . . . . . . 15
Function 15h . . . . . . . . . . . . . . . . . . . . . . . . 16
Function 16h . . . . . . . . . . . . . . . . . . . . . . . . 16
Function 17h . . . . . . . . . . . . . . . . . . . . . . . . 17
Function 18h . . . . . . . . . . . . . . . . . . . . . . . . 17
Function 19h . . . . . . . . . . . . . . . . . . . . . . . . 17
Function 1Ah . . . . . . . . . . . . . . . . . . . . . . . . 18
Function 1Bh . . . . . . . . . . . . . . . . . . . . . . . . 19
Function 1Ch . . . . . . . . . . . . . . . . . . . . . . . . 21
Function 1Dh . . . . . . . . . . . . . . . . . . . . . . . . 22
Function 1Eh . . . . . . . . . . . . . . . . . . . . . . . . 23
Function 1Fh . . . . . . . . . . . . . . . . . . . . . . . . 24
Function 20h . . . . . . . . . . . . . . . . . . . . . . . . 25
Function 21h . . . . . . . . . . . . . . . . . . . . . . . . 25
Function 7Eh . . . . . . . . . . . . . . . . . . . . . . . . 26
Function 7Fh . . . . . . . . . . . . . . . . . . . . . . . . 27
Licensing Information . . . . . . . . . . . . . . . . . . . . . 2
Commercial License . . . . . . . . . . . . . . . . . . . . 2
Non-Commercial License . . . . . . . . . . . . . . . . . . 2
RTS/CTS flow control . . . . . . . . . . . . . . . . . . . . 13
SIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Warranty . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
WHAT IS X00 . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Xon/Xoff flow control . . . . . . . . . . . . . . . . . . . . 13
