Simtel MSDOS 1992 June

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

/ Simtel MSDOS 1992 June / SIMTEL_0692.cdr / msdos / fossil / hzcomm31.arc / FOSSIL.DOC next >

Wrap

Text File | 1987-03-07 | 19.8 KB | 546 lines

Fundamentals of FOSSIL implementation and use Draft Version 3 March 7, 1987 Vincent E. Perriello, VEP Software IFNA Address: Network 141 Node 491 (141/491) Usenet address: ...decvax!envore!vaxine!spark!141!491!Vince_Perriello Copyright (C) 1987, VEP Software, Naugatuck, CT 06770. All rights reserved. This document may be freely used or copied by anyone interested in the data contained herein. No fees may be charged for distribution of this document. You will be held accountable for all such charges, and expected to either reimburse those persons or organizations so charged, or to make a donation in the exact amount of those fees to the International FidoNet Association, to assist them in their efforts to advance the technology of personal computer telecommunications. Fundamentals of FOSSIL implementation and use Page 1 A. Objectives of this document This document is directed at implementors or intellectuals. It is meant for use in implementing applications that can use FOSSIL drivers, or for details needed to implement a new FOSSIL. As such it won't always go out of its way to explain itself to the neophyte. This document will have served its purpose to you if you are able to use the data contained within to perform either of the above tasks. If you feel that necessary data has been omitted please contact Vince Perriello at the above listed address so that the appropriate changes can be made. B. Historical perspective For those people who were not lucky enough to have an IBM PC or a system nearly completely compatible, the world has not been very friendly. With his implementation of the Generic Fido(tm) driver, Tom Jennings made it possible for systems that had nothing in common with an IBM PC except an 808x-class processor, and the ability to run MS-DOS Version 2 and above, to run his Fido(tm) software. That was a lot to ask, and a lot of people thought it was enough. But not everyone. While Thom Henderson was debugging Version 4.0 of his SEAdog(tm) mail package, an "extended" Generic driver was designed (in cooperation with Bob Hartman) as a quick kludge to help him get past a problem with certain UART chips.The new hook was quickly pounced upon by Vince Perriello, who, with almost DAILY prodding (ouch! it still hurts) by Ken Kaplan,had been working with Henderson to get DEC Rainbow support into SEAdog. Vince then coded a driver to use this hook and - Voila! - SEAdog 4.0 started working like a champ on the Rainbow. Then something WONDERFUL happened. Wynn Wagner started having a bad time getting the Greenleaf(tm) Communication Libraries to work in exactly the way he wanted them to. Enter Bob Hartman. Having already enjoyed success in the effort with Thom Henderson, he suggested to Wynn that with a very few extensions, the driver that SEAdog(tm) 4.0 liked could drive Opus as well. Then Vince called Wynn, Wynn called Bob, Bob called Vince, and the FOSSIL driver came into existence. FOSSIL, by the way, is an acronym that Vince dreamed up. It took a while for everyone to stomach it,but it now seems to be loved by all. It is an acronym for "Fido/Opus/SEAdog Standard Interface Layer". And the concept is catching on. Henk Wevers is reportedly coding a terminal program in Turbo Pascal that uses FOSSIL services to do all the work. This should mean that the result will play elsewhere. And there are already FOSSIL implementations for the Tandy 2000, Sanyo 555, Z100 and others, so the potential of a properly coded FOSSIL application is very great. Fundamentals of FOSSIL implementation and use Page 2 C. Basic principles of a FOSSIL driver 1) Interrupt 14H. The one basic rule that the driver depends upon, is the ability for ANY target machine to allow the vector for INT 14H (absolute locations 50 to 53 in segment 0) to be "stolen" by the driver. In a system where the INT 14H vector is used already, it must be possible to replace the "builtin" functionality with that of a FOSSIL, when an application that wants the use of a FOSSIL is to be run on the target machine. 2) How to install a FOSSIL driver in a system There's no hard and fast way to do this. The FOSSIL might be implemented as part of a device driver (like Ray Gwinn's X00.SYS) and therefore gets loaded using a line in CONFIG.SYS at bootup time. It might be done as a TSR (terminate and stay resident) program, in which event you install it by running the program (DECCOMM by Vince Perriello and Opus!Comm by Bob Hartman work this way, for example). 3) How an application can detect the presence of a FOSSIL The driver has a "signature" that can be used to determine whether it is present in memory. At offset 6 in the INT 14H service routine is a word, 1954 hex, followed by a byte that specifies the maximum function number supported by the driver. This is to make it possible to determine when a driver is present and what level of functionality it provides. Also, the Init call (see below) returns a 1954 Hex in AX. SEAdog(tm) looks at the signature and Opus just goes for the Init. Fido doesn't do either. 4) How to call a FOSSIL function The FOSSIL driver is entered by issuing a software Interrupt 14 Hex from the application program. The code corresponding to the desired function should be in 8-bit register AH. For calls that relate to communications, the port number will be passed from the application in register DX. When DX contains a zero (0) it signifies use of COM1, or whatever the "first" serial port on your machine is called. A one (1) in DX points the driver at COM2, and so on. Fundamentals of FOSSIL implementation and use Page 3 D. Functions currently defined for FOSSILs AH = 0 Set baud rate Input: AL = baud rate code DX = port number This works the same as the equivalent IBM PC BIOS call, except that it ONLY selects a baud rate. This is passed in the high order 3 bits of AL as follows: 000 = 110 baud 001 = 150 '' 010 = 300 '' 011 = 600 '' 100 = 1200 '' 101 = 2400 '' 110 = 4800 '' 111 = 9600 '' The low order 3 bits can be implemented or not by the FOSSIL, but in all cases, if the low order bits of AL are 00011, the result should be that the communications device should be set to eight data bits, one stop bit and no parity. This setting is a MINIMUM REQUIREMENT of Fido, Opus and SEAdog. AH = 1 Transmit character Input: AL = character DX = port number Output: AX contains status bits (see function 3) AL contains the character to be sent. If there is room in the transmit buffer the return will be immediate, otherwise it will wait until there is room to store the character in the transmit buffer. On return, AX is set as in a status request (see function 3). AH = 2 Receive a character Input: DX = port number Output: AL = input character If there is a character available in the receive buffer, returns with the next character in AL. It will wait until a character is received if none is available. Fundamentals of FOSSIL implementation and use Page 4 AH = 3 Request status Input: DX = port number Output: AX = status bit mask (see below) Returns with the line and modem status in AX. Status bits returned are: In AH: Bit 0 = RDA - input data is available in buffer Bit 5 = THRE - room is available in output buffer Bit 6 = TSRE - output buffer is empty In AL: Bit 7 = DCD - carrier detect This can be used by the application to determine whether carrier detect (CD) is set, signifying the presence/absence of a remote connection, as well as monitoring both the input and output buffer status. AH = 4 Initialize driver Input: DX = port number ( BX = 4F50 CX = ^C flag address --- optional ) Output: AX = 1954H if successful This is used to tell the driver to begin operations, and to check that the driver is installed. This function should be called before any other communications calls are made. At this point all interrupts involved in supporting the comm port (specified in DX) should be set up for handling by the FOSSIL, then enabled. If BX contains 4F50 hex, then the address specified in DS:CX is that of a ^C flag byte in the application program, to be incremented when ^C is detected in the keyboard service routines. This is an optional service and only need be supported on machines where the keyboard service can't (or won't) perform an INT 1B or INT 23 when a Control-C is entered. AH = 5 Deinitialize driver Input: DX = port number This is used to tell the driver that comm port operations are ended. The function should be called when no more comm port functions will be used on the port specified in DX. AH = 6 Raise/lower DTR Input: DX = port number AL = DTR state to be set (1 = Raise, 0 = Lower) This function is used to control the DTR line to the modem. AL = 0 means lower DTR (disable the modem), and AL = 1 means to raise DTR (enable the modem). No other function (except Init) should alter DTR. Fundamentals of FOSSIL implementation and use Page 5 AH = 7 Return timer tick parameters Output: AL = timer tick interrupt number AH = ticks per second on interrupt number in AL DX = approximate number of milliseconds per tick This is used to determine the parameters of the timer tick on any given machine. Three numbers are returned: AL = Timer tick interrupt number AH = Ticks per second on interrupt number shown in AL DX = Milliseconds per tick (approximate) Applications can use this for critical timing (granularity of less than one second) or to set up code (such as a watchdog) that is executed on every timer tick. See function 22 (add/delete function from timer tick) for the preferred way of actually installing such code. AH = 8 Flush output buffer Input: DX = port number This is used to force any pending output. It does not return until all pending output has been sent. You should use this call with care. Flow control (documented below) can make your system hang on this call in a tight uninterruptible loop under the right circumstances. AH = 9 Purge output buffer Input: DX = port number This is used to purge any pending output. Any output data remaining in the output buffer (not transmitted yet) is discarded. AH = 10 Purge input buffer Input: DX = port number This is used to purge any pending input. Any input data which is still in the buffer is discarded. AH = 11 Transmit no wait Input: DX = port number Output: AX = 1 if character was accepted and 0 if not. This is exactly the same as the "regular" transmit call, except that if the driver is unable to buffer the character (the buffer is full), a value of zero (0) is returned in AX. If the driver accepts the character (room is available), a one (1) is returned in AX. Fundamentals of FOSSIL implementation and use Page 6 AH = 12 Read no wait Input: DX = port number Output: AX = next character or FFFF if none available Return in AX the next character in the receive buffer. If the receive buffer is empty return FFFF. AH = 13 Keyboard read no wait Output: AX = IBM-style keyboard scan code or FFFF if no keyboard character available Return in AX the next character (non-destructive read ahead) from the keyboard; if nothing there (in the type-ahead buffer), return FFFF in AX. Use IBM-style function key mapping in the high order byte. Scan codes for non-"function" keys are not specifically required, but may be included. AH = 14 Keyboard input with wait Output: AX = IBM-style keyboard scan code Return in AX the next character from the keyboard; wait if no character is available. Keyboard mapping should be the same as function 13. AH = 15 Enable or Disable flow control on transmit Input: AL = bit mask describing requested flow control DX = port number This is used to stop output when the "other end" is overwhelmed, or when a BBS user wants to stop a screen. Two kinds of flow control are supported: Bit 0 = 1 XON/XOFF Bit 1 = 1 CTS/RTS Flow control is enabled, or disabled, by setting the appropriate bits in AL for the types of flow control we want to ENABLE (value = 1), and/or DISABLE (value = 0), and calling this function. Bit 2 is reserved for DSR/DTR but is not currently supported in the DECCOMM implementation. Applications using this function should set all bits ON in the high nibble of AL as well. There is a compatible (but not identical) FOSSIL driver implementation that uses the high nibble as a control mask. If your application sets the high nibble to all ones, it will always work, regardless of the method used by any given driver. Fundamentals of FOSSIL implementation and use Page 7 AH = 16 Extended Control-C / Control-K checking and transmit on/off Input: AL = flags byte DX = port number Output: AX = status (see below) 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 The Enable (bit 0 = 1) and Disable (Bit 0 = 0) Control-C/Control-K check function is meant primarily for BBS use. When the checking is enabled, a Control-C or Control-K received from the communications port will set a flag internal to the FOSSIL driver, but will not be stored in the input buffer. The next use of the function will return the value of this flag in register AX then clear the flag for the next occurrence. The returned value is used by the BBS software to determine whether output should be halted or not. The Enable (Bit 1 = 1) and Disable (Bit 1 = 0) Transmitter function lets the application restrain the asynchronous driver from output in much the same way as XON/XOFF would. AH = 17 Set current cursor location. Input: DH = row (line) DL = column This function looks exactly like like INT 10H, subfunction 2, on the IBM PC. The cursor location is passed in DX: row in DH and column in DL. The function treats the screen as a coordinate system whose origin (0,0) is the upper left hand corner of the screen. AH = 18 Read current cursor location. Output: DH = row (line) DL = column Looks exactly like INT 10H, subfunction 3, on the IBM PC. The current cursor location (using the same coordinate system as function 17) is passed back in DX. AH = 19 Single character ANSI write to screen. Input: AL = character to display The character in AL is sent to the screen by the fastest method possible that allows ANSI processing to occur (if available). This routine should not be used in such a way that DOS output (which is not re-entrant) can not be employed by some FOSSIL driver to perform the function (in fact, on the IBM PC that is likely to be how it's done). On some systems such as the DEC Rainbow this will be a very fast method of screen writing. Fundamentals of FOSSIL implementation and use Page 8 AH = 20 Enable or disable watchdog processing Input: AL = 1 to enable or 0 to disable watchdog DX = port number When watchdog is enabled, the state of the carrier detect (CD) line on the comm port specified in DX should be constantly monitored. Should the state of that line become FALSE (carrier lost), the system should be re- booted, to enable the BBS (or other application) to start up again. AH = 21 Write character to screen using BIOS support routines Input: AL = character to display The character in AL is sent to the screen using BIOS-level Input/Output routines. This differs from function 19 in that DOS I/O CAN NOT be used, as this function might be called from driver level. AH = 22 Insert or Delete a function from the timer tick chain Input: AL = 1 to add a function or 0 to delete one DS:DX = address of function Output: AX = FFFF if unsuccessful This function is used to allow a central authority to manage the timer interrupts, so that as code is loaded and unloaded, the integrity of the "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 executing a far call to the "old" routine when yours is done, instead you call this function. It manages a list of such entry points and calls them on a timer tick (interrupt) using a FAR call. All the usual cautions about making DOS calls apply (that is, DON'T!). This makes it possible for a program to get in and out of the tick chain without having to know whether another program has also done so since it first insinuated itself. AH = 23 Reboot system Input: AL = 0 for "cold boot" or 1 for "warm boot" Perform the old 3-finger salute. Used in extreme emergency by code that can't seem to find a "clean" way out of the trouble it has gotten itself into. Hopefully it won't happen while you're computing something in the other half of a DoubleDOS system. If your machine can make a distinction between a "cold" (power-up, self-test and boot) and a "warm" (just boot) bootstrap, your FOSSIL should support the flag in AL. Otherwise just do whatever bootstrap is possible. Fundamentals of FOSSIL implementation and use Page 9 E. Validation Suite. Well, there is one, but it's involved. Run FIDO_GEN V11w on your FOSSIL for about a week with reasonable caller activity in the message areas, file uploads and downloads, and FidoNet(tm) mail. Run SEAdog for a few days, sending and receiving a reasonable number of messages. Then run Opus for the rest of your natural life. Why not? It's a good package. Anyway, some reasonable compromise with the above steps should ensure that your FOSSIL will work with most everything coded for one. F. Distribution. The good folks who distribute Opus will be more than happy to take note of your new FOSSIL driver and to add it to their distribution. And, of course, you can upload it to any system you want, but your work will get more publicity in the Opus community than anywhere else. G. Technical Discussion. A FOSSIL echomail conference is in the process of starting up. It will be coordinated by Vince Perriello at IFNA node 141/491. Contact him for details on how to join. Keep in mind though, this conference is intended SPECIFICALLY for implementors of FOSSIL software and not as a general Q&A conference, for people who think FOSSILs have something to do with paleontology.