Bila Vrana

home *** CD-ROM | disk | FTP | other *** search

/ Bila Vrana / BILA_VRANA.iso / 019A / ONEFOS09.ZIP / ONEREF.TXT < prev next >

Wrap

Text File | 1996-06-15 | 49.0 KB | 1,116 lines

Functions Reference Manual for the ONEFOSsil Developer (C) Copyright 1995-96 by Carl Morris and Morris Softronics ONEFOSsil, A low level serial communications driver for MS-DOS based FOSSIL 5 compliant applications. Introduction This document is for developers wanting to use ONEFOSsil specific features and for developers just learning about the FOSSIL specification. ONEFOSsil supports most FOSSIL 5 and X00 extended functions, and this document will help describe any differences. Portions of this document are copyright by VEP Software, Rick Moore, and Raymond Gwinn. The rest of this document is copyright by Morris Softronics and Carl Morris. This documentation is distributed as is and is provided with no guarantees. You use the information contained within at your own risk. What is ONEFOSsil and a FOSSIL driver? ONEFOSsil is a simplified serial communications driver for 8250 series UART's and MS-DOS based machines running applications requiring a simple FOSSIL 5 communications driver. ONEFOSsil only provides FOSSIL based services. FOSSIL is an acronym derived from Fido Opus Seadog Standard Interface Layer. The FOSSIL specification was intended to permit machine independent software (Fido, Opus, and Seadog at the time) to be created and ran on any MS-DOS based 8086 based computer that had a FOSSIL compatible driver. Those days are much over, and FOSSIL compatible drivers are only used as a low level communications interface for application software. A better specification is needed to keep up with today's quickly changing world, though. ONEFOSsil does not maintain total compatibility with the FOSSIL 5 specification. These differences will be noted in this document, but will seldom cause problems with most modern software. Interface ONEFOSsil's Application Program Interface is partly based on the PC BIOS communications interface. As such, the driver will be entered with an 8086 instruction INT 14h. A function number is passed in 8086 register AH and other registers are used as needed. Return codes from functions will very from function to function, and is one of the most confusing aspect of FOSSIL programming; they're not logical! Registers are not modified by ONEFOSsil unless otherwise specified. Note that this is not true about all FOSSIL drivers. While this document covers basic FOSSIL functions, some differences will be encountered from FOSSIL to FOSSIL. In most cases, functions will require a port number to operate. In all cases, port numbers are passed in register DX. Most FOSSIL's only support ports 0 - 7. FOSSIL to DigiBoard converters usually only support 0 - 15. ONEFOSsil supports ports 0 - 63. Notice that in most cases, the port number is one less than the COM port number; but, in most FOSSIL's, the port can be specified on any address/irq combination, or may not even map to a COM port at all. As a note to developers, FOSSIL functions should not be called in a way that could cause active code to be reentered. ONEFOSsil and many other FOSSIL's are re-entrant, but not to that great of a degree. Detection Detecting FOSSIL drivers vary. The FOSSIL specification states that to detect a FOSSIL, one should look at the 6th byte (3rd word) after the start of the INT 14h service routine for the word 1954h, followed by a byte, the maximum function supported by the FOSSIL driver. However, this is unreliable if other utilities and/or drivers have hooked the INT 14h interrupt vector since the FOSSIL was loaded. It is not suggested to use this method. Instead, it is better to just make the call to the "Activate" function 04h for the port you want to open and check its return codes. Almost all current applications detect the FOSSIL in this way. Another method, which only works for a few drivers, is to call the "Information" function, and check its return codes. X00 only works correctly if the FOSSIL port called is active. ONEFOSsil and BNU work all the time. Refer to function 1Bh for more information on the "Information" function; however, this method is not suggested either. Functions The following functions are supported by most FOSSIL drivers. Function 00h - Set communications baud, parity, etc. Input: AH = 00h AL = Communications parameters: 010----- = 300 baud 011----- = 600 baud 100----- = 1200 baud 101----- = 2400 baud 110----- = 4800 baud 111----- = 9600 baud 000----- = 19200 baud (replaces IBM 110 baud setting) 001----- = 38400 baud (replaces IBM 150 baud setting) ----0--- = No parity ---01--- = Odd parity ---11--- = Even parity -----0-- = 1 stop bit; -----1-- = 1½ bits for 5-bit byte length, 2 for all others ------00 = 5 bits ------01 = 6 bits ------10 = 7 bits ------11 = 8 bits DX = Port number BX = 0 (incase BNU tries to extend this function) Output: AH = Line status (see function 03h) AL = Modem status (see function 03h) This function is identical to the IBM PC INT 14h BIOS call except that 110 baud and 150 baud have been replaced by 19200 baud and 38400 baud respectively. See function 1Eh for an enhanced version of this function. In addition, once function 1Eh has been used, this function will not change the baud rate until function 04h is used to reactivate the FOSSIL driver. Note that BNU contains an extension to this function, and that if that extension is not desired you should make sure that BX and CX are not equal, or that one of them are zero. If you would like information on this extension please write the author of this document or David Nugent, author of BNU. Function 01h - Transmit character with wait. Input: AH = 01h AL = Output character DX = Port number Output: AH = Line status (see function 03h) 1------- = Time-out occurred, all other bits void 0------- = Character buffered, all bits valid AL = Modem status (see function 03h, void if time-out occurred) If there is no room in the transmit buffer, this function will wait until there is room in the buffer or until a time-out occurs. Notes: X00 executes functions with the interrupt mask set as it was when entered. That is, if X00 is called with interrupts masked, interrupts will remain masked during the processing of the function. If this function is called with interrupts masked, it may never return. ONEFOSsil always enables interrupts upon the beginning of every FOSSIL call, so unless there are severe hardware problems, ONEFOSsil should always return. It is suggested that applications use function 0Bh instead of this function in all cases. This function is slow, and X00 and BNU are prone to lock-ups. Even if the THRE bit is set in a status return, there is a chance that the buffer could be filled by another application between calls, and as such the correct application would get a long, unnecessary delay before control is returned. Many applications do not check the returned status for a time- out condition, and as such drop characters when time-outs occur. Function 02h - Get received character with wait. Input: AH = 02h DX = Port number Output: AH = Line status (see function 03h) 1------- = Time-out occurred, all other bits void 0------- = Character returned, all bits valid AL = Input character (if no time-out occurred) If no character is available from the receive buffer, this function will wait until a character is received or until a time-out occurs. Notes: X00 executes functions with the interrupt mask set as it was when entered. That is, if X00 is called with interrupts masked, interrupts will remain masked during the processing of the function. If this function is called with interrupts masked, it may never return. ONEFOSsil always enables interrupts upon the beginning of every FOSSIL call, so unless there are severe hardware problems, ONEFOSsil should always return. It is suggested that applications do not use this function. It is slow, and X00 and BNU are prone to lock-ups. Even if the RDA bit is set in a status return, it is possible that another application could steal the character, leaving the correct application to wait for the next character or a time-out. It is suggested that function 18h be used instead. Function 18h always returns immediately. Sample code for calling this block function in a single character mode can be found in the applications notes. Also, X00 and ONEFOSsil support a "get character with no wait" at function 20h, but is not supported by the FOSSIL 5 specification or most other FOSSIL's. Function 03h - Return serial port status. Input: AH = 03h DX = Port number Output: AH = Line Status (resembles the 8250 Line Status Register) 1------- = time-out, all other bits in AH and AL void* -1------ = TSRE, output buffer is empty* --1----- = THRE, room is available in output buffer* ---1---- = BRK, break detected (since last return) ----1--- = FE, framing error detected (since last return) -----1-- = PE, parity error detected (since last return) ------1- = OE, the input buffer has overrun (since last return)* -------1 = RDA, received data is available in buffer* AL = Modem Status (resembles the 8250 Modem Status Register) 1------- = Data carrier detect (DCD)* -1------ = Ring indicator (RI) --1----- = Data set ready (DSR) ---1---- = Clear to send (CTS) ----1--- = Always set to 1 upon return (dummy DCD)* ----1--- = Delta data carrier detect (since last return) -----1-- = Trailing edge ring indicator (since last return) ------1- = Delta data set ready (since last return) -------1 = Delta clear to send (since last return) * Denotes formal FOSSIL 5 specified bits. The FOSSIL specification calls for the delta data carrier detect bit to always be set to act as a dummy DCD. If an application needs a dummy DCD, it should implement it internally as described in the notes below. As such ONEFOSsil does not support it and instead uses the bit as a Delta Data Carrier Detect. ONEFOSsil instead includes a command line option to fake Data Carrier Detect. Notes: All bits without asterisks (*) will vary in meaning from FOSSIL to FOSSIL driver. X00 does not attempt to accurately return the Delta bits. ONEFOSsil should correctly return the status of the Delta bits. One way to implement a dummy DCD is to check the DCD at the start of the connection. If DCD is active, the real DCD should be watched. If DCD is inactive, it should be assumed that there might never be a DCD, and assume an internal dummy DCD. If DCD was to go active at some later time, real DCD watching should be re-enabled and used from there out. However, with ONEFOSsil supporting command line options for faking DCD, it is not suggested to follow the above practice. Function 04h - Activate Port. Input: AH = 04h BX = 0h (in case the FOSSIL supports Control-C flagging) DX = Port number Output: AX = 1954h if successful BL = Maximum function number supported BH = Revision of FOSSIL specification supported This function instructs the FOSSIL driver to initialize itself for communications on the specified port. Buffers will be cleared, interrupts activated, and DTR raised. If the port can not be supported, the call goes to the next driver or to the system BIOS. The FOSSIL specification states that the port parameters are not to be initialized at this time. However, with ONEFOSsil, if port parameters have been locked on the command line, they will be loaded during this time. The FOSSIL specification calls for an optional Control-C flag, and is not supported by X00 or ONEFOSsil. As such, BX should be cleared to prevent any possibility of this occurring. X00 incorrectly returns the maximum function number (or it isn't documented.) BNU and ONEFOSsil will only return the maximum function (currently 20h in ONEFOSsil.) BNU has an option to be compatible with the bug X00 has also. Multiple calls to this function will repeat the above process as if the port had not been open. If you want to insure the port is closed before opening, call function 05h first (many BBS's and doors do this.) Notes: At some future date, Ray Gwinn intends to make this function identical to the PS/2's function 04h. Function 1Ch is a duplicate of this function. It is my intention to create a new standard that will support this, and permit much better communications over all devices available. I do not; however, have any opinion on which call should be made. The latest X00 and VX00 still support both functions. Calling this function with an invalid port number will not return a valid reponse. Any application which calls this function with port number 255 is in error! Function 05h - Deactivate Port. Input: AH = 05h DX = Port number Output: Nothing This function instructs the FOSSIL that it should no longer process calls for specified port using the FOSSIL specification. This function is passed on to the next driver if the port is not active. Any additional calls to this driver with the specified port will also be sent on the next driver or the PC BIOS. Any function not needing a port number, or an active port, will be processed by most FOSSIL drivers. X00 will not process "Information" requests if the port requested is not active. ONEFOSsil will attempt to flush the buffers before this function will return. ONEFOSsil will return if a time-out occurs, after deactivating the port. This is to help buggy software that deactivate the port before all of their "closing" screen has been sent. It should be assumed however that what is in the transmit buffer will be lost when this function is called. NOTICE: With Revision 9, ONEFOSsil will nolonger flush the port. This created an extra long delay under some circuimstances, and if application authors can't get it right on their own, ONEFOSsil isn't going to cover up for them. NOTICE: At some future date, Ray Gwinn intends to make this function identical to the PS/2's function 05h. Function 1Dh is a duplicate of this function. It is my intention to create a new standard that will support this, and permit much better communications over all devices available. I do not; however, have any opinion on which call should be made. The latest X00 and VX00 still support both functions. 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 is defined as follows: 00h = lower DTR 01h = raise DTR With ONEFOSsil and most other FOSSILs, any even value will lower the DTR, any odd value will raise the DTR. No other function (except functions 04h, 1Ch, and 1Fh) will alter DTR. Function 07h - Return timer tick information. Input: AH = 07h Output: AL = Timer tick interrupt number (1Ch or 08h) AH = Approximate interrupts per second (18 on IBM) DX = Approximate number of milliseconds per tick (55) This function is used to determine the characteristic of the timer tick for the computer. The FOSSIL specification says this function is to return the interrupt number, not the vector. However, most FOSSIL's seem to return the vector. ONEFOSsil also returns the vector, 1Ch. This function useless today. I would instead like to see some functions that do the timing internally, including calculating the time in seconds for the application. There would need to be 5 or 6 timers in each port, to allow both BBS's and DOOR software to do separate timing. BBS and DOOR software could use a single downward counter/timer for time left on-line, but to actually see software implement this would be a miracle. Function 08h - Flush output buffer. Input: AH = 08h DX = Port number Output: Nothing This function is used to wait until all pending output has been transmitted. It does not return until all buffered output has been sent. This function should be used with care. Flow control can cause the system to hang in a tight un-interruptible 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 with interrupts masked, interrupts will remain masked during the processing of the function. If this function is called with interrupts masked, it may never return. ONEFOSsil will not wait indefinitely and always enables interrupts. ONEFOSsil will return if no output has been transmitted in the time-out period. There is no status returned to notify the application of this condition. ONEFOSsil's deactivate function literally calls this function to flush the output buffer. It is advised that this function NOT be used due to the problems that could arise. Instead developers are asked to use function 03h and wait in their own loop while the TSRE bit is clear. This would permit the application to keep an eye on local keyboard activity among other things. 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. 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 > 0000h - Character was buffered for transmission = 0000h - Character was not buffered This function performs the same operation as function 01h except control is returned even if there is no room in the buffer. It is requested that developers use this function for single character transmissions. It is asked that you also look into using function 19h which can transmit more than one character at a time. Function 0Ch - Non-destructive read-ahead (Peek). Input: AH = 0Ch DX = Port number Output: AH = 00h if a character is available > 00h if no character is available AL = Next character if available This function returns the next character from the receive buffer. The character returned remains in the receive buffer. Some programmers call this function "peek". The extended function 20h is a destructive read without wait. Function 0Dh - Keyboard peek without wait. Input: AH = 0Dh Output: AX = IBM-style scan code if available = 0FFFFh if no character is 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. This function should not be used by IBM PC software. Function 0Eh - Keyboard read with wait. Input: AH = 0Eh Output: AX = Keyboard scan code This function returns 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). This function should not be used by IBM PC software. 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 and used at the same time. The bits passed in AL are defined 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 The FOSSIL specification states that all other bits should be set to 1 for future expansion. This is insane, as it might enable options the application doesn't want. It is simpler to assume that if the bit is not used now, you wont need to use it later and leave it cleared. ONEFOSsil permits controlling and locking these options on the command line. As such, a request to enable or disable a flow control may not be honored. Some other FOSSIL drivers automatically lock RTS/CTS if the baud rate or data parameters are locked on the command line. Function 10h - Control-C/K checking and transmitter control. 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 primarily used for BBS operation. A bit mask is passed in AL with the following flags: Bit 0 = 1 Enable Control-C/K checking Bit 1 = 1 Disable the transmitter The Control-C/K status is only returned as long as Control-C/K checking is enabled. The status is cleared after each call. The transmitter disable bit lets the application program inhibit the transmitter. FIFO's of 16550's can not be stopped, and will continue to transmit until empty. The disable of the transmitter is not absolute. Several internal functions can cause the transmitter to be re-enabled, such as attempting to store another character in the buffer. Some FOSSIL's will also re-enable the transmitter when they receive an Xon, but ONEFOSsil does not. Function 11h - Set current cursor location. Input: AH = 11h DH = Row (line) DL = Column Output: Nothing This function is exactly like INT 10h, sub-function 2, on the IBM PC. The row and column are relative to zero. That is, the home position on the screen is row 0, column 0. This function should not be used by IBM PC software. Function 12h - Read current cursor location. Input: AH = 12h Output: DH = Row (line) DL = Column This function is exactly like INT 10h, sub-function 3, on the IBM PC. The current cursor location (using the same coordinate system as function 16h) is returned in DX. This function should not be used by IBM PC software. 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 the FOSSIL to execute the function. ANSI.SYS is used by most FOSSIL drivers on the IBM PC. This function should not be used on IBM PC software. 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 have no effect on the state of the DCD watchdog. This function is not supported by ONEFOSsil, and is dangerous in many multitasking environments. Function 15h - Write character to screen using BIOS. Input: AH = 15h AL = Character to display Output: Nothing The specified character 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. This function should not be used by IBM PC software. 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 < 0FFFFh if operation is successful = 0FFFFh if 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. The FOSSIL 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. 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 multitasking systems at that time. However, with the 80386 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, Ray Gwinn (who originally insisted that this function be created) RECOMMENDS THAT THIS FUNCTION NOT BE USED. ONEFOSsil returns 0FFFFh in AX at all times. Happy Ray? 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. ONEFOSsil attempts to close the task that made the call, rather than rebooting what could be a multi-user system. This function should not be called by ANY software. 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 65535 characters from the inbound circular buffer to the caller's buffer. ES and DI are not modified by this function. The number returned in AX will be the lesser of the caller's requested amount or the entire contents (if any) of the receive buffer. I request that this function be used even for reading a single character at a time. The following examples to help: In ASM push bp ;save frame pointer mov bp,sp ;set it xor ax,ax ;clear temp. value push ax ;temporary storage mov ah,18h ;function call 18h mov cx,1 ;get 1 byte mov dx,port ;port number lea di,[bp-2] ;address of temp. storage push ss pop es ;move registers (size conscious) int 14h ;make call or ax,ax ;any data moved? jnz @F ;data was moved mov [bp-1],0FFh ;write AH to 0xFF @@: pop ax ;if AH = 0, AL = character pop bp In C/C++ No real example available as I would use in-line ASM to accomplish the function very similar to the above code. Other people would use "regs" and "int86" calls. Notice that you could detect if function 20h is available, and use it when possible. FOSSILC, my C/C++ FOSSIL routines (freeware) do exactly that. This function should especially be used by file transfer protocol software. 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 65535 characters to the outbound circular buffer. ES and DI are not modified by this function. The number returned in AX will be the lesser of the caller's requested amount or the amount (if any) required to fill the transmit buffer. This function should be used whenever possible! 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. This function is useful for activating command mode on some modems. The application program is responsible for the timing of the BREAK. If ONEFOSsil has been restrained by an Xoff received from the modem, the flag will be cleared. Any port setting functions (including 04h and 1Ch) will stop an in progress break. A break must be maintained long enough for the UART to have sent a full data byte at the current settings. A break is a condition where the serial line maintains the state of a start bit for a full byte length. Function 1Bh - Return information about FOSSIL. 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 X00 returns the following: CX = '0X' First 2 bytes of 'X00 ' string DX = ' 0' Second 2 bytes of 'X00 ' string ONEFOSsil returns the following: BX = 'ON' No specific byte ordering, just the word CX = 'E ' "ONE " if you were to look at it in a register dump. This function will transfer information about the selected port and its status to the caller. This function is intended to assist "generic" applications to adjust to the current environment. Very little information should be used from the returned information. An application should NOT use the buffer size or buffer free information for anything. Use function 03h for information about the buffers. X00 returns the port status (function 03h) if this function is called for an inactive port. BNU and ONEFOSsil return useful information if they support the port. X00 does not always return the following BAUD byte correctly. ONEFOSsil contains extra fields in the following structure. The data structure (assembly language style) currently returned by ONEFOSsil 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 ;REVISION 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 ? ;BYTES OF RECV BUFFER FREE OBUFR DW OBSIZE ;BYTE SIZE OF THE XMIT BUFFER OFREE DW ? ;BYTES OF XMIT BUFFER FREE SWIDTH DB SCREEN_WIDTH ;WIDTH OF DISPLAY SCREEN SHEIGHT DB CREEN_HEIGHT ;HEIGHT OF DISPLAY SCREEN BAUD DB ? ;BAUD RATE, COMPUTER TO MODEM ;the follow are extensions NEWBAUD DB ? ;new baud rate location PORTSET DB ? ;complete port data settings OVERRUN DW ? ;number overruns this session The IDENT string is null-terminated, and does not contain a new- line. The BAUD field contains the bits that Function 00h would use to set the port speed and data format. The fields related to a particular port (buffer size, space left in the buffer, baud rate) will be undefined if the port is not active. 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, at least that's what X00REF.DOC says. It has been discovered that this is not true, and that most the time, the BAUD field contains no usable data. ONEFOSsil always sets the BAUD parameter to the closest possible value. FHSLink really likes this practice, and as such displays a baud rate without using the -B parameter. ONEFOSsil also uses the NEWBAUD and PORTSET bytes. PORTSET is the bits function 1Eh would write to the Line Control Register (minus the break bit). The NEWBAUD byte contains a value similar to what function 1Eh would use to set the baud rate. These are shown below. Values of NEWBAUD: 00h = 110 27% error factor on 8250 series 01h = 150 02h = 300 03h = 600 04h = 1200 05h = 2400 06h = 4800 07h = 9600 08h = 19200 09h = 28800 0Ah = 38400 0Bh = 57600 0Ch = 76800 does not exist on 8250 series 0Dh = 115200 Values of PORTSET: Bit 7 and 6 are always clear Bit 3 is set if parity is enabled Bits 5 - 4 define parity: 00 = Odd parity 01 = Even parity 10 = Mark parity (sticky odd) 11 = Space parity (sticky even) Bit 2 defines the number of stop bits transmitted 0 = 1 stop bit sent 1 = 1.5 stop bits for 5 bit bytes, 2 for all others Bits 1 - 0 define the number of data bits 00 = 5 data bits 01 = 6 data bits 10 = 7 data bits 11 = 8 data bits The OVERRUN word is solely for information. Extended Functions Function numbers above 1Bh and below 7Eh are X00 extended functions. These functions will only work with X00 and ONEFOSsil. It is fairly easy to see if other FOSSIL's support X00 functions by checking the maximum function supported on the "Activate" call. It is the hope of Ray Gwinn that these functions will be added by other FOSSIL authors in their implementations and become a part of the FOSSIL specification. I would personally like to see a whole new, non UART specific specification emerge. This new specification would get rid of the inefficiency FOSSIL 5 permits and clear up some of the compatibility issues with the new BIOS's. Functions 1Ch and 1Dh are exact duplicates of FOSSIL functions 04h and 05h. Functions 1Eh and 1Fh are intended to be exact duplicates of functions 04h and 05h 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. Note that function 1Eh or 1Fh are not exactly compatible with functions 04h and 05h of the PS/2 BIOS. Developers are encouraged start using functions 1Ch and 1Dh instead of functions 04h and 05h. See the application notes section for instructions on a compatible method of determining if functions 1Ch and 1Dh should be used instead of functions 04h and 05h. Function 1Ch - Activate Port. This function is identical to function 04h. Please refer to function 04h for information. Function 1Dh - Deactivate Port. This function is identical to function 05h. Please refer to function 05h for information. Function 1Eh - Extended line control initialization. This function is intended to exactly emulate the PS/2's BIOS INT 14 services, function 04h. Some or all of the functions provided here are duplicated by other FOSSIL functions. In addition, once this function is called, function 00h will not be allowed to change the baud rate. Function 00h will again be allowed to set the baud rate after the FOSSIL functions have been deactivated. 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 bit = 01h, 1.5 bits on 5 bit bytes, 2 stop bits for all others 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 = 80h, 28800 baud (these are FOSSIL only baud rates) = 81h, 38400 baud = 82h, 57600 baud = 83h, reserved (future 76800 baud) = 84h, 115200 baud DX = Port number Output: AX = Port status (see function 03h) If settings were locked at load time, the appropriate parameters are ignored. ONEFOSsil does not permit the break bit to be set by this function. The value in AL is ignored. The reason is that the PS/2 specification calls for a value of 0 to make a break and a 1 to clear a break. X00REF.DOC states the function as it appear above, but the Interrupt shows it as being an exact duplicate of the PS/2 function. I do not wish to trouble myself with programs that fail to work because their authors used the Interrupt List to write them. Function 1Fh - Extended serial port status/control. This function is intended to exactly emulate the PS/2's BIOS INT 14 services, function 05h. Some or all of the functions provided here are duplicated by other FOSSIL functions. This function has 2 sub- functions specified by AL. Sub-function 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) (always 0) Bit 4 = 1 Loopback mode Bit 3 = 1 OUT2 (interrupts) enabled Bit 2 = 1 OUT1 active Bit 1 = 1 Request to send (RTS) active Bit 0 = 1 Data terminal ready (DTR) active Sub-function 01h - Write MCR Input: AH = 1Fh AL = 01h, Write modem control register (MCR) BL = Modem control register, where: Bits 7-5 = 0 (Reserved) (forced 0) Bit 4 = 1 Set loopback mode Bit 3 = 1 Set OUT2 enable interrupts (forced 1) 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 sub-function 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 the FOSSIL. When the application program writes the MCR, the RTS bit is treated as an RTS enable bit. This means that X00 will allow the application program to signal when it wants to allow RTS on. It does not force RTS on. RTS only permits the DTR to be modified with this function. This function should not be used for any reason. It is hardware specific and such hardware may not exist in the future. Function 20h - Read with no wait (destructive). Input: AH = 20h DX = Port number Output: AH = 00h if a character is available > 00h if no character is available AL = Next character if available This function returns the next character from the receive buffer. 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 DX = Port number 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 flag is set. ONEFOSsil does not support this function as there is no known need for it. "Layered Application" services ONEFOSsil supports NO "Layered Application" services. The functions simply aren't monitored. I don't feel most people have any use for them. Application Notes Which Activate/Deactivate functions to use It is the hope of Ray Gwinn (after a period of time) to make X00's functions 04h and 05h compatible with the PS/2's INT 14h functions 04h and 05h. Currently, X00's functions 04h and 05h are duplicated at functions 1Ch and 1Dh respectively. Ray requests that application programmers start using functions 1Ch and 1Dh if those functions are available. That is, use functions 1Ch and 1Dh instead of functions 04h and 05h respectively. It is relatively simple to determine if the functions at 1Ch and 1Dh are available. When your program is ready to activate the FOSSIL 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 04h. Save the function number actually used to activate the port, then increment it by one to deactivate the port. You may also keep track of the maximum function supported by the driver, to see what other calls are available. You should; however, leave a user configured option to override all extended function calls. <EoF>