home *** CD-ROM | disk | FTP | other *** search
/ Beijing Paradise BBS Backup / PARADISE.ISO / software / BBSDOORW / X00150.ZIP / X00REF.DOC < prev    next >
Text File  |  1993-05-22  |  63KB  |  1,634 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.                    Functions reference manual for the X00 developer
  28.  
  29.                   X.00 A Low Level Serial I/O Communications Driver
  30.                         for MS DOS and like Operating Systems.
  31.  
  32.                         Copyright (c) 1993 by Raymond L. Gwinn
  33.                                  12469 Cavalier Drive
  34.                               Woodbridge, Virginia 22192
  35.                                  All Rights Reserved
  36.  
  37.                                      May 22, 1993
  38.  
  39.  
  40.                    Fidonet address 1:265/104 (Routed Netmail only)
  41.                                  Compuserve 72570,157
  42.                           Internet 72570.157@Compuserve.com
  43.                                    FAX 703-494-0595
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.                                                                           i
  52.  
  53.  
  54.                                      INTRODUCTION
  55.  
  56.           Previously,  the documentation  for X00  was  little more  than a
  57.           collection  of notes.  The notes were added to as the development
  58.           process continued and enhancements were made.  I honestly did not
  59.           suspect that  X00 would become  as widely  used as it  is.   This
  60.           manual is an attempt at some decent documentation for X00.
  61.  
  62.           But who do  I document for?   The user that  is setting up a  BBS
  63.           just wants to get X00 installed and to move on  to more important
  64.           things.  The user that is having problems needs information about
  65.           serial  I/O communications  in general  and the  PC specifically.
  66.           The application developer (programmer) needs detailed information
  67.           about each individual function and the information generated.
  68.  
  69.           This manual is  intended as  a reference for  use by  application
  70.           programmers who desires  to use X00.  A separate  Users manual is
  71.           included in the distribution file(s).
  72.  
  73.           This manual and the software distributed with it is provided with
  74.           no guarantees.  Use at your own risk.
  75.  
  76.  
  77.  
  78.  
  79.  
  80.  
  81.  
  82.                                                                          ii
  83.  
  84.  
  85.           WHAT IS X00 . . . . . . . . . . . . . . . . . . . . . . . . .   1
  86.  
  87.           Warranty  . . . . . . . . . . . . . . . . . . . . . . . . . .   1
  88.  
  89.           Licensing Information . . . . . . . . . . . . . . . . . . . .   2
  90.                Non-Commercial License . . . . . . . . . . . . . . . . .   2
  91.                Commercial License . . . . . . . . . . . . . . . . . . .   2
  92.  
  93.           Functions . . . . . . . . . . . . . . . . . . . . . . . . . .   3
  94.                Function 00h - Set communications parameters . . . . . .   4
  95.                Function 01h - Transmit character and wait . . . . . . .   5
  96.                Function 02h - Get received character with wait  . . . .   5
  97.                Function 03h - Return Serial Port Status . . . . . . . .   6
  98.                Function 04h - Activate Port . . . . . . . . . . . . . .   7
  99.                Function 05h - Deactivate Port . . . . . . . . . . . . .   8
  100.                Function 06h - Raise/lower DTR . . . . . . . . . . . . .   8
  101.                Function 07h - Return timer tick information . . . . . .   9
  102.                Function 08h - Flush output buffer . . . . . . . . . . .   9
  103.                Function 09h - Purge output buffer . . . . . . . . . . .   9
  104.                Function 0Ah - Purge input buffer  . . . . . . . . . .    10
  105.                Function 0Bh - Transmit no wait  . . . . . . . . . . .    10
  106.                Function 0Ch - Non-destructive read-ahead (Peek) . . .    10
  107.                Function 0Dh - Keyboard read without wait  . . . . . .    11
  108.                Function 0Eh - Keyboard read with wait . . . . . . . .    11
  109.                Function 0Fh - Flow Control for serial I/O . . . . . .    12
  110.                     Xon/Xoff flow control . . . . . . . . . . . . . .    12
  111.                     RTS/CTS flow control  . . . . . . . . . . . . . .    12
  112.                Function 10h - Control-C / Control-K checking  . . . .    13
  113.                Function 11h - Set current cursor location . . . . . .    13
  114.                Function 12h - Read current cursor location  . . . . .    14
  115.                Function 13h - Single character ANSI write to screen .    14
  116.                Function 14h - Enable or disable the DCD watchdog  . .    14
  117.                Function 15h - Write character to screen using BIOS  .    15
  118.                Function 16h - Add  or delete a routine from  the timer
  119.                     tick  . . . . . . . . . . . . . . . . . . . . . .    15
  120.                Function 17h - Reboot system . . . . . . . . . . . . .    16
  121.                Function 18h - Block Read  . . . . . . . . . . . . . .    16
  122.                Function 19h - Block Write . . . . . . . . . . . . . .    16
  123.                Function 1Ah - Break begin or end  . . . . . . . . . .    17
  124.                Function 1Bh - Return information about X00  . . . . .    18
  125.  
  126.           Superset Functions  . . . . . . . . . . . . . . . . . . . .    19
  127.                Function 1Ch - Activate Port . . . . . . . . . . . . .    20
  128.                Function 1Dh - Deactivate Port . . . . . . . . . . . .    21
  129.                Function 1Eh - Extended line control initialization  .    22
  130.                Function 1Fh - Extended serial port status/control . .    23
  131.                Function 20h - Read with no wait (destructive) . . . .    24
  132.                Function 21h - Stuff/Poke the receive buffer . . . . .    24
  133.  
  134.           "Layered Application" services  . . . . . . . . . . . . . .    25
  135.                Function  7Eh  -  Install  an   "external  application"
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.                                                                         iii
  144.  
  145.                     function  . . . . . . . . . . . . . . . . . . . .    25
  146.                Function  7Fh  -   Remove  an  "external   application"
  147.                     function  . . . . . . . . . . . . . . . . . . . .    26
  148.  
  149.           Application Notes . . . . . . . . . . . . . . . . . . . . .    27
  150.                Which Activate/Deactivate functions to use . . . . . .    27
  151.                Watch out for disk I/O . . . . . . . . . . . . . . . .    27
  152.                Successive timer tick calls  . . . . . . . . . . . . .    28
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.                                                                           1
  161.  
  162.  
  163.                                      WHAT IS X00
  164.  
  165.           X00 is  a Serial  Input/Output (SIO) communications  driver.   It
  166.           provides  an interface  between  an application  program and  the
  167.           serial communications hardware.
  168.  
  169.           X00 was originally  designed as a  FOSSIL driver.   FOSSIL is  an
  170.           acronym  containing the first character of several communications
  171.           programs.  The FOSSIL specification  is basically an extension of
  172.           the PC's BIOS services for serial communications.
  173.  
  174.           Except as  noted in the this Manual, X00 meets the FOSSIL level 5
  175.           specification.   X00 provides  additional functions that  are not
  176.           contained in the FOSSIL level 5 specification.
  177.  
  178.           X00 only works with 8250 (TYPE) serial I/O devices.  Such devices
  179.           include the  8250A, 16450, 16550, 16550A  and the 82510.   If you
  180.           have a PC that  is an IBM or near  compatible which has a  serial
  181.           communication  port, it is likely  that it contains  one of these
  182.           devices.  XU, a  utility distributed with X00, will  identify the
  183.           existence of compatible SIO devices.
  184.  
  185.           Like  other Device  Drivers,  X00 will  do  very little  standing
  186.           alone.  There must be an application(s) program to use X00 before
  187.           you will gain benefit.
  188.  
  189.           Since  the introduction  of the  FOSSILs, a  great number  of new
  190.           communications  programs  have come  into existence.   I  like to
  191.           think  that the FOSSILs are  largely responsible for  this.  Many
  192.           programs that contain their own communications drivers have added
  193.           FOSSIL support.  One notable example is RBBS.
  194.  
  195.           Many  programs  written  to   use  BIOS's  serial  communications
  196.           services will also work with X00.   This gives those programs the
  197.           benefits of buffered interrupt driven I/O.
  198.  
  199.           Warranty
  200.  
  201.           There is none.  Use X00 your own risk.
  202.  
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.                                                                           2
  210.  
  211.  
  212.                                 Licensing Information
  213.  
  214.           Non-Commercial License:
  215.  
  216.           A  non-commercial license  for  use of  X00  is included  in  the
  217.           distribution file called LICENSE.TXT.
  218.  
  219.           Commercial License:
  220.  
  221.           See Users Reference manual.
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.                                                                           3
  230.  
  231.  
  232.                                       Functions
  233.  
  234.           X00  functions are  designed to  be  called by  assembly language
  235.           programs.    Some  rudimentary  High Level  access  routines  are
  236.           provided  in  the  X00  distribution files.    These  rudimentary
  237.           routines are the so called HLLAPI files.
  238.  
  239.           Parameters for all  X00 functions  are passed in  the basic  808x
  240.           registers.    In  most cases  the  results  of  the function  are
  241.           returned  in registers.    If  no  parameter  is  returned  in  a
  242.           register,  X00 will return the register  unchanged except for the
  243.           AX register.   If no information is returned in  the AX register,
  244.           then its contents upon return from a function is undefined.
  245.  
  246.           Many  (most) of the X00 functions require a port number be passed
  247.           in  the DX register.  Port numbers start at 0 (zero).  Port 0 and
  248.           COM1  are normally the same.  However, this relationship must not
  249.           be assumed.  It is possible for the X00 user to re-map the  ports
  250.           on their  systems.  Please  refer to  the Users  Manual for  more
  251.           information.
  252.  
  253.           I  have  noted that  some  application programs  are  calling X00
  254.           functions from  the timer tick.   This should be done  with care.
  255.           If  the X00 DV option is enabled  at load time, X00 could issue a
  256.           DESQview Pause command as a result  of your call.  I am  not sure
  257.           what  the results of this would be, but it points out the type of
  258.           consideration that  should be done before  issuing function calls
  259.           from the timer tick.
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.                                                                           4
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.           Function 00h - Set communications parameters, baud, parity etc.
  277.  
  278.                Input:    AH = 00h
  279.                          AL = Communications parameters (defined below)
  280.                          DX = Port number
  281.  
  282.                Output:   AX = Port status (see function 03h)
  283.  
  284.           This function is identical to the IBM PC INT 14h BIOS call except
  285.           that  110 baud and 150 baud have  been replaced by 19200 baud and
  286.           38400 baud respectively.  The high order 3 bits of AL specify the
  287.           baud rate  as follows:  See functions 1Eh and 1Fh for an enhanced
  288.           version of this function.
  289.  
  290.                          010 =   300 baud
  291.                          011 =   600  ''
  292.                          100 =  1200  ''
  293.                          101 =  2400  ''
  294.                          110 =  4800  ''
  295.                          111 =  9600  ''
  296.                          000 = 19200  '' (Replaces IBM 110 baud setting)
  297.                          001 = 38400  '' (Replaces IBM 150 baud setting)
  298.  
  299.           The low order 5 of AL specify the following:
  300.  
  301.                Bits 4-3 define parity:       0 0  no parity
  302.                                              1 0  no parity
  303.                                              0 1  odd parity
  304.                                              1 1  even parity
  305.  
  306.                Bit 2 defines stop bits:      0    1 stop bit;
  307.                                              1    1.5 bits for 5-bit codes,
  308.                                                   2 for others
  309.  
  310.                Bits 1-0 character length:    0 0  5 bits
  311.                                              0 1  6 bits
  312.                                              1 0  7 bits
  313.                                              1 1  8 bits
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.                                                                           5
  322.  
  323.  
  324.           Function 01h - Transmit character and wait.
  325.  
  326.                Input:    AH = 01h
  327.                          AL = Character
  328.                          DX = Port number
  329.  
  330.                Output:   AX = Port status (see function 03h)
  331.  
  332.           Upon  entry to this function, AL must contain a character that is
  333.           to be transmitted.   If there is room in the transmit buffer, the
  334.           character  buffered.   Otherwise, this  function will  loop until
  335.           their is  room in the buffer or until  a timeout occurs.  If set,
  336.           the high  order bit of  the returned status indicates  a time out
  337.           occurred.   See function 03h.   At the time of  this writing, the
  338.           timeout is set to 30 seconds.
  339.  
  340.           Note:  X00 executes functions with  the interrupt mask  set as it
  341.           was  when entered.   That is,  if X00  is called  will interrupts
  342.           masked, interrupts will  remain masked during  the processing  of
  343.           the function.  If this function is called with interrupts masked,
  344.           it may never return.
  345.  
  346.           -----------------------------------------------------------------
  347.  
  348.           Function 02h - Get received character with wait.
  349.  
  350.               Receive character with wait
  351.  
  352.                Input:    AH = 02h
  353.                          DX = Port number
  354.  
  355.                Output:   AH = Line status (same AH returned by function 3)
  356.                          AL = Input character
  357.  
  358.           If  a character is available in the receive buffer, this function
  359.           returns the next character from the  receive buffer in AL.  If no
  360.           receive character is available, this  function will wait until  a
  361.           character is received or  until a timeout occurs.   If a  timeout
  362.           occurs,  the high order bit of  AH will be set  upon return.  See
  363.           function 03h.   At the time of this writing, the timeout value is
  364.           set to 30 seconds.
  365.  
  366.           Note:  X00 executes functions with  the interrupt mask  set as it
  367.           was when  entered.   That is,  if X00  is called  will interrupts
  368.           masked, interrupts will  remain masked during  the processing  of
  369.           the function.  If this function is called with interrupts masked,
  370.           it may never return.
  371.  
  372.           Function 20h is a get character with no wait.
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.                                                                           6
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.           Function 03h - Return Serial Port Status.
  388.  
  389.                Input:    AH = 03h
  390.                          DX = Port number
  391.  
  392.                Output:   AX = Status bits as follows:
  393.  
  394.                     AH = Line Status, where:
  395.                          Bit 0 = RDA  - input data is available in buffer
  396.                          Bit 1 = OVRN - the input buffer has been overrun
  397.                          Bit 2 = Reserved (Parity error in BIOS INT 14h)
  398.                          Bit 3 = Reserved (Framing error in BIOS INT 14h)
  399.                          Bit 4 = Reserved (Break detect in BIOS INT 14h)
  400.                          Bit 5 = THRE - room is available in output buffer
  401.                          Bit 6 = TSRE - output buffer is empty
  402.                          Bit 7 = Timeout (set by functions 1 and 2 only)
  403.  
  404.           Bit 7 of AH IS ALWAYS ZERO WHEN RETURNED BY FUNCTION 3.  Bit 7 of
  405.           AH may be  set to one by other functions (like 1 and 2) that also
  406.           return status.  When bit 7 of AH is set to one, none of the other
  407.           15 bits returned in AX are valid.
  408.  
  409.                     AL = Modem status, where:
  410.                          Bit 0 = Delta clear to send (not reliable)
  411.                          Bit 1 = Delta data set ready (not reliable)
  412.                          Bit 2 = Delta data carrier detect (not reliable)
  413.                          Bit 3 = Always set to 1 upon return (DUMMY DCD)
  414.                          Bit 4 = Clear to send (CTS)
  415.                          Bit 5 = Data set ready (DSR)
  416.                          Bit 6 = Ring indicator (RI)
  417.                          Bit 7 = Data carrier detect (DCD)
  418.  
  419.           Bit  3  of AL  is  always  returned  set  to  1.    This  enables
  420.           application programs  to use  bit 3  as a  carrier detect bit  on
  421.           hardwired (null modem) links.
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.                                                                           7
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.           Function 04h - Activate Port.
  439.  
  440.                Input:    AH = 04h
  441.                          DX = port number
  442.  
  443.                Output:   AX = 1954h if successful
  444.                          BL   =  maximum  function  number  supported  (not
  445.                          counting functions 7Eh and above)
  446.                          BH = rev of FOSSIL specification supported
  447.  
  448.           This function instructs X00  to use the FOSSIL specification  for
  449.           the specified port.  Prior to issuing this function, any function
  450.           that  requires a port number  in DX be will  passed on to BIOS or
  451.           X00's  INT 14h BIOS emulator.  When this function  is called, all
  452.           interrupts   involved  in  supporting   the  communications  port
  453.           (specified in DX) are  set up for support by X00.   DTR is turned
  454.           on by this function.  The baud rate is NOT set or changed by this
  455.           function.
  456.  
  457.           If an additional call  to this function occurs (2  Inits or Init,
  458.           Function nn, Init, etc.)  X00 will reset (clear) all  buffers and
  459.           all flow control is turned off.  Values returned in the registers
  460.           upon a re-init are the same as an initial init (defined above).
  461.  
  462.           NOTICE:  At some  future date,  the author  intends to  make this
  463.           function identical to the PS/2's  function 4.  Function 1Ch  is a
  464.           duplicate of this function.  New or modified application programs
  465.           should  discontinue use  of this function  and use  the duplicate
  466.           (1Ch) function.
  467.  
  468.           A section is the  application notes describes a simple  method of
  469.           determining  which Activate/Deactivate  function numbers  to use.
  470.           The described method should work on all FOSSIL implementations.
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.                                                                           8
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.           Function 05h - Deactivate Port.
  486.  
  487.                Input:    AH = 05h
  488.                          DX = Port number
  489.  
  490.                Output:   Nothing
  491.  
  492.           This function  instructs X00  that it  should  no longer  process
  493.           calls for specified port (in  DX) using the FOSSIL specification.
  494.           If the port was never activated by function 4, then this function
  495.           is ignored.  Any  subsequent function calls, that require  a port
  496.           number  in  DX, will  be  passed  to BIOS  or  the  BIOS INT  14h
  497.           emulator.
  498.  
  499.           NOTICE:  At some  future date  (July 1991  or later),  the author
  500.           intends to make this function identical to the PS/2's function 5.
  501.           Function 1Dh is  a duplicate of this  function.  New  or modified
  502.           application programs should discontinue use of this function  and
  503.           use the duplicate (1Dh) function.
  504.  
  505.           A section is the  application notes describes a simple  method of
  506.           determining  which Activate/Deactivate  function numbers  to use.
  507.           The described method should work on all FOSSIL implementations.
  508.  
  509.           -----------------------------------------------------------------
  510.  
  511.           Function 06h - Raise/lower DTR.
  512.  
  513.                Input:    AH = 06h
  514.                          AL = DTR state to set
  515.                          DX = Port number
  516.  
  517.                Output:   Nothing
  518.  
  519.           This function is used to control the DTR signal.   AL = 00h means
  520.           lower DTR (turn it off), and AL = 01h means to raise DTR (turn it
  521.           on).  No other function (except functions 04h and 1Ch) will alter
  522.           DTR.
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.                                                                           9
  531.  
  532.  
  533.  
  534.           Function 07h - Return timer tick information.
  535.  
  536.                Input:    AH = 07h
  537.  
  538.                Output:   AL = Timer tick interrupt number
  539.                          AH = Approximate interrupts per second (18 on IBM)
  540.                          DX = Approximate number of milliseconds per tick
  541.  
  542.           This  function  is used  to determine  the characteristic  of the
  543.           timer tick for the computer.
  544.  
  545.           Application  programs  can  use  information  returned  by   this
  546.           function to dynamically  set up  code that is  executed on  every
  547.           timer tick. 
  548.  
  549.           -----------------------------------------------------------------
  550.  
  551.           Function 08h - Flush output buffer.
  552.  
  553.                Input:    AH = 08h
  554.                          DX = Port number
  555.  
  556.                Output:   Nothing
  557.  
  558.           This  function  is  used to  wait  until  any  pending output  is
  559.           transmitted.   It does not  return until all  buffered output has
  560.           been sent.  This function should be used with care.  Flow control
  561.           (documented  below) can  cause your  system hang  in a  tight un-
  562.           interruptable loop given the right circumstances.
  563.  
  564.           Note:  X00 executes functions with  the interrupt mask  set as it
  565.           was when  entered.   That is,  if X00  is called will  interrupts
  566.           masked, interrupts  will remain  masked during the  processing of
  567.           the function.  If this function is called with interrupts masked,
  568.           it may never return.
  569.  
  570.           -----------------------------------------------------------------
  571.  
  572.           Function 09h - Purge output buffer.
  573.  
  574.                Input:    AH = 09h
  575.                          DX = Port number
  576.  
  577.                Output:   Nothing
  578.  
  579.           This function  is used to  remove any buffered  output (transmit)
  580.           data.   Any  output  data remaining  in  the output  buffer  (not
  581.           transmitted yet) is discarded.
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.                                                                          10
  590.  
  591.  
  592.  
  593.  
  594.           Function 0Ah - Purge input buffer.
  595.  
  596.                Input:    AH = 0Ah
  597.                          DX = Port number
  598.  
  599.                Output:   Nothing
  600.  
  601.           This function is  used to  remove any  buffered input  (received)
  602.           data.    Any  input data  which  is  in  the  receive  buffer  is
  603.           discarded.
  604.  
  605.           -----------------------------------------------------------------
  606.  
  607.           Function 0Bh - Transmit no wait.
  608.  
  609.                Input:    AH = 0Bh
  610.                          AL = Character
  611.                          DX = Port number
  612.  
  613.                Output:   AX = 0001h - Character was buffered for xmit
  614.                          AX = 0000h - Character was not buffered
  615.  
  616.           This is exactly  the same as  function 01h, except  that it  will
  617.           always  return immediately.    If X00  is  unable to  buffer  the
  618.           character  (the transmit  buffer is  full), a  value of  0000h is
  619.           returned in AX. If X00 accepts the character (room is available),
  620.           0001h is returned in AX.
  621.  
  622.           -----------------------------------------------------------------
  623.  
  624.           Function 0Ch - Non-destructive read-ahead (Peek).
  625.  
  626.  
  627.                Input:    AH = 0Ch    
  628.                          DX = Port number
  629.  
  630.                Output:   AH = 00h if character is available
  631.                          AL = Next character if available
  632.                          AX = 0FFFFh = If no character is available
  633.  
  634.           This function returns the next character from the receive buffer.
  635.           If the  receive buffer is empty,  0FFFFh is returned in  AX.  The
  636.           character   returned  remains   in  the   receive   buffer.  Some
  637.           programmers call this function "peek".
  638.  
  639.           Function 20h is a destructive read with no wait.
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.                                                                          11
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.           Function 0Dh - Keyboard read without wait.
  661.  
  662.  
  663.                Input:    AH = 0Dh
  664.  
  665.                Output:   AX = IBM-style scan code if available
  666.                             = 0FFFFh if no character not available
  667.  
  668.           This  function  returns  the  keyboard  scan  code  of  the  next
  669.           character from  the keyboard.   This is a  non-destructive (peek)
  670.           read of  the keyboard.  If no keyboard data is available,  0FFFFh
  671.           is returned in AX.
  672.  
  673.           -----------------------------------------------------------------
  674.  
  675.           Function 0Eh - Keyboard read with wait.
  676.  
  677.                Input:    AH = 0Eh
  678.  
  679.                Output:   AX = Keyboard scan code
  680.  
  681.           This  function  return  the  next character  available  from  the
  682.           keyboard.  If no keyboard input is available, this function waits
  683.           until  a keyboard  character  is available.   Returned  character
  684.           codes are the same as function 0Dh (IBM style scan codes). 
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.                                                                          12
  693.  
  694.  
  695.           Function 0Fh - Flow Control for serial I/O.
  696.  
  697.                Input:    AH = 0Fh
  698.                          AL = Bit defining the flow control to use
  699.                          DX = Port number
  700.  
  701.                Output:   Nothing
  702.  
  703.           Two kinds of basic flow control are supported.  One is  software,
  704.           called  Xon/Xoff  flow control.   The  other is  hardware, called
  705.           RTS/CTS flow  control.  Both  software and hardware  flow control
  706.           may be enabled at the same time.
  707.  
  708.           The bits in the parameter passed in AL are as follows:
  709.  
  710.                          Bit 0 = 1      Enable receiving of Xon/Xoff
  711.                          Bit 1 = 1      Enable RTS/CTS flow control
  712.  
  713.                          Bit 2          Reserved (should be zero)
  714.                          Bit 3 = 1      Enable transmitting of Xon/Xoff
  715.  
  716.           Setting  an appropriate bit to  zero will cause  the flow control
  717.           associated with that bit to be disabled.  
  718.  
  719.           Enabling  the  receiving  of  Xon/Xoff  will  cause  X00  to stop
  720.           transmitting   upon  receiving   an  Xoff.     X00   will  resume
  721.           transmitting when an Xon is received.
  722.  
  723.           Enabling the sending of  Xon/Xoff will cause X00 to send  an Xoff
  724.           when its buffers are 3/4  full.  When the buffers are  emptied to
  725.           1/4 full, X00 will send an Xon.
  726.  
  727.           X00  WILL ALWAYS CEASE  TRANSMITTING WHEN CTS  IS LOWERED (TURNED
  728.           OFF).  TRANSMISSION WILL RESUME WHEN CTS IS RAISED (TURNED ON).
  729.  
  730.           When  RTS/CTS flow control is  enabled, X00 will  drop (turn off)
  731.           RTS when  the receive buffer is  3/4 full.  X00  will raise (turn
  732.           on) RTS  when the  receive buffer empties  to 1/4 full.   RTS/CTS
  733.           flow control is almost  always used by modems that  operate above
  734.           2400  baud.    Some  2400  baud  modems  also  use/allow  RTS/CTS
  735.           handshaking
  736.  
  737.           If the  baud rate is locked  in the command line  that loads X00,
  738.           RTS/CTS  handshaking is  forced.   In this case,  the application
  739.           program can not disable RTS/CTS handshaking.
  740.  
  741.  
  742.  
  743.  
  744.  
  745.  
  746.  
  747.                                                                          13
  748.  
  749.  
  750.  
  751.           Function 10h - Control-C  /  Control-K  checking and  transmitter
  752.                          disable/enable.
  753.  
  754.                Input:    AH = 10h    
  755.                          AL = Control bits (defined below)
  756.                          DX = Port number
  757.  
  758.                Output:   AX = 0001h - A Control-C/K has been received
  759.                             = 0000h - A Control-C/K has not been received
  760.  
  761.           This is  used for BBS operation, primarily.  A bit mask is passed
  762.           in AL with the following flags:
  763.  
  764.                Bit 0     Enable/disable Control-C / Control-K checking
  765.                Bit 1     Disable/enable the transmitter
  766.  
  767.           To enable Control C/K checking set bit 0 = 1, to disable set  bit
  768.           0  = 0.    When checking  is  enabled,  a received  Control-C  or
  769.           Control-K will set  a flag  (internal to X00).   The  Control-C/K
  770.           character will not be stored  in the input buffer.  The  state of
  771.           the  internal Control-C/K flag will  be returned (then reset) the
  772.           next time  this function is  called.   The returned value  may be
  773.           used by the BBS software as it wishes.
  774.  
  775.           The  transmitter disable  (bit 1  =  1) and  Enable (bit  1 =  0)
  776.           function lets the application program to inhibit the transmitter.
  777.  
  778.           The disable of the transmitter is not absolute.  Several internal
  779.           functions can  cause the  transmitter to be  re-enabled, such  as
  780.           receiving an Xon when receiving of Xon/Xoff is enabled.
  781.  
  782.           -----------------------------------------------------------------
  783.  
  784.           Function 11h - Set current cursor location.
  785.  
  786.                Input:    AH = 11h
  787.                          DH = Row (line)
  788.                          DL = Column
  789.  
  790.                Output:   Nothing
  791.  
  792.           This function  is exactly like INT 10h, subfunction 2, on the IBM
  793.           PC.  The  desired cursor location is passed in DX,  row in DH and
  794.           column in DL.  The row and column are relative to zero.  That is,
  795.           the home position on the screen is row 0, column 0.
  796.  
  797.  
  798.  
  799.  
  800.  
  801.  
  802.  
  803.                                                                          14
  804.  
  805.  
  806.  
  807.  
  808.           Function 12h - Read current cursor location.
  809.  
  810.                Input:    AH = 12h
  811.  
  812.                Output:   DH = Row (line)
  813.                          DL = Column
  814.  
  815.           This function  is exactly like INT 10h, subfunction 3, on the IBM
  816.           PC.   The  current  cursor location  (using  the same  coordinate
  817.           system as function 16h) is returned in DX.
  818.  
  819.           -----------------------------------------------------------------
  820.  
  821.           Function 13h - Single character ANSI write to screen.
  822.  
  823.                Input:    AH = 13h
  824.                          AL = Character to display
  825.  
  826.                Output:   Nothing
  827.  
  828.           The character passed in AL is sent displayed on the screen at the
  829.           current cursor location.   ANSI.SYS type processing is performed.
  830.           This routine should  not be used  in such a  way that DOS  output
  831.           (which is not re-entrant)  can not be employed by  X00 to execute
  832.           the function.
  833.  
  834.           -----------------------------------------------------------------
  835.  
  836.           Function 14h - Enable or disable the DCD watchdog.
  837.  
  838.                Input:    AH = 14h
  839.                          AL = 01h - Enable watchdog
  840.                             = 00h - Disable watchdog
  841.                          DX = Port number
  842.  
  843.                Output:   Nothing
  844.  
  845.           This  function enables  and  disables the  monitoring of  carrier
  846.           detect.   When enabled, the state  of the carrier detect (DCD) is
  847.           constantly  monitored  during  timer  tick  processing.    Should
  848.           carrier  detect  be  lost  (turned  off),  the  system  will   be
  849.           re-booted.  Activate/Deactivate etc  have no effect on the  state
  850.           of the DCD watchdog.
  851.  
  852.  
  853.  
  854.  
  855.  
  856.  
  857.  
  858.                                                                          15
  859.  
  860.  
  861.           Function 15h - Write character to screen using BIOS.
  862.  
  863.                Input:    AH = 15h
  864.                          AL = Character to display
  865.  
  866.                Output:   Nothing
  867.  
  868.           The character passed in AL is sent to the screen using BIOS-level
  869.           Input/Output routines.   This differs  from function 13h  in that
  870.           DOS I/O will not be used.
  871.  
  872.           -----------------------------------------------------------------
  873.  
  874.           Function 16h - Add or delete a routine from the timer tick chain.
  875.  
  876.                Input:    AH = 16h
  877.                          AL = 01h - Add a function
  878.                             = 00h - Delete a function
  879.                          ES = Segment of function
  880.                          DX = Offset of function
  881.  
  882.                Output:   AX =  0000h or  ticks per  second if  operation is
  883.                               successful
  884.                             = 0FFFFh - Operation unsuccessful
  885.  
  886.           This function  is used to allow a central authority to manage the
  887.           timer interrupts, so that the integrity of the "timer tick chain"
  888.           is  not compromised.  Rather than using the traditional method of
  889.           saving  the old contents of the timer vector, storing the address
  890.           of your routine there, and calling the "old" routine, instead you
  891.           call this  function.  X00 manages a list of such entry points and
  892.           calls them on a timer tick (interrupt) using a FAR call.
  893.  
  894.           X00  will allow  up to  4 programs  to hook  into the  timer tick
  895.           processing.  Interrupts  are enabled when the hooked routines are
  896.           called.
  897.  
  898.           CAUTION, when  this FOSSIL function was  implemented, it provided
  899.           the  best  means to  hook into  the  timer tick  on multi-tasking
  900.           systems  at that time.   However, with  the 386  and virtual 8086
  901.           mode  of  operation  used by  DESQview,  Windows  V3.0 etc,  this
  902.           function  can crash the system.   The reason  is the virtual 8086
  903.           application (task/window) that  hooked in, may not be  the active
  904.           virtual 8086 (task/window) when the timer tick interrupt occurs.
  905.  
  906.           Due to popularity of the virtual 8086 type multi-tasking systems,
  907.           the  author  (who  originally  insisted  that  this  function  be
  908.           created) RECOMMENDS THAT THIS FUNCTION NOT BE USED.
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.                                                                          16
  917.  
  918.  
  919.           Function 17h - Reboot system.
  920.  
  921.                Input:    AH = 17h
  922.                          AL = 00h - "Cold boot"
  923.                             = 01h - "Warm boot"
  924.  
  925.                Output:   Nothing
  926.  
  927.           This  function is intended primarily  as a security  feature.  It
  928.           provides  the  application  with  a  last resort  escape  from  a
  929.           situation that could allow a security breach.
  930.  
  931.           -----------------------------------------------------------------
  932.  
  933.           Function 18h - Block Read.
  934.  
  935.  
  936.                Input:    AH = 18h
  937.                          CX = Requested number of characters to transfer
  938.                          DX = Port number
  939.                          ES = Segment of the caller's buffer
  940.                          DI = Offset of the caller's buffer
  941.  
  942.                Output:   AX = Number of characters actually transferred
  943.  
  944.           This function will transfer from 0 to 65534 characters from X00's
  945.           inbound circular  buffer to  the caller's  buffer. ES:DI  are not
  946.           changed by  this function.   The  number of  bytes placed  in the
  947.           caller's buffer is  returned in AX.   The  number returned in  AX
  948.           will be the lesser of the caller's requested amount or the entire
  949.           contents (if any) of X00's receive buffer.
  950.  
  951.           -----------------------------------------------------------------
  952.  
  953.           Function 19h - Block Write.
  954.  
  955.                Input:    AH = 19h
  956.                          CX = Requested number of characters to transfer
  957.                          DX = Port number
  958.                          ES = Segment of the caller's buffer
  959.                          DI = Offset of the caller's buffer
  960.  
  961.                Output:   AX = Number of characters actually transferred
  962.  
  963.           This function will transfer  from 0 to 65534 characters  to X00's
  964.           outbound  circular  buffer.    ES:DI  are  not  changed  by  this
  965.           function.  The number of bytes placed in X00's buffer is returned
  966.           in AX.   The  number returned  in AX  will be  the lesser  of the
  967.           caller's requested amount or the amount (if any) required to fill
  968.           X00's transmit buffer.
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.                                                                          17
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.  
  990.           Function 1Ah - Break begin or end.
  991.  
  992.                Input:    AH = 1Ah
  993.                          AL = 01h - Start sending 'break'
  994.                             = 00h - Stop sending 'break'
  995.                          DX = port number
  996.  
  997.                Output:   Nothing
  998.  
  999.           This function will  start or terminate a break signal.  If AL=01h
  1000.           X00 will start the transmission  of a break.  If AL=00h  X00 will
  1001.           terminate  any  break  signal.    This  function  is  useful  for
  1002.           activating command mode on some modems.  The  application program
  1003.           is responsible  for the timing  of the  BREAK.  If  X00 has  been
  1004.           restrained by an Xoff received  from the modem, the flag  will be
  1005.           cleared.   An  Activate or  Deavtivate will  stop an  in-progress
  1006.           BREAK.  
  1007.  
  1008.           It is the  experience of the author that the  duration of a break
  1009.           should be less than 0.1 seconds.
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.                                                                          18
  1018.  
  1019.  
  1020.           Function 1Bh - Return information about X00.
  1021.  
  1022.                Input:    AH = 1Bh
  1023.                          CX = Size of caller's info buffer in bytes
  1024.                          DX = Port number
  1025.                          ES = Segment of caller's info buffer
  1026.                          DI = Offset of caller's info buffer
  1027.  
  1028.                Output:   AX = Number of bytes actually transferred
  1029.                          CX = '0X'      First 2 bytes of 'X00 ' string
  1030.                          DX = ' 0'      Second 2 bytes of 'X00 ' string
  1031.  
  1032.           Note  that the  values returned  in CX  and DX  can be  stored in
  1033.           memory to form a  space terminated string 'X00 '.   Additionally,
  1034.           the values returned in CX and DX can be used to  determine if X00
  1035.           is installed.
  1036.  
  1037.           This function will transfer information about X00 and its current
  1038.           status  to the  caller.   This  function  is intended  to  assist
  1039.           "generic" applications to adjust to the current environment.
  1040.  
  1041.           The data structure  (assembly language style)  currently returned
  1042.           by X00 is as follows:
  1043.  
  1044.                INFO      EQU  $              ;DEFINE BEGIN OF STRUCTURE
  1045.                STRSIZ    DW   INFO_SIZE      ;SIZE OF THIS STRUC IN BYTES
  1046.                MAJVER    DB   CURR_FOSSIL    ;FOSSIL SPECIFICATION REV
  1047.                MINVER    DB   CURR_REV       ;REV OF THIS DRIVER.
  1048.                IDENT     DD   ID_STRING      ;"FAR" POINTER TO ASCIIZ
  1049.                                              ; DRIVER DESCRIPTION STRING.
  1050.                IBUFR     DW   IBSIZE         ;BYTE SIZE OF THE INPUT BUFFER
  1051.                IFREE     DW   ?              ;NUMBER OF BUFFERED RECV BYTES
  1052.                OBUFR     DW   OBSIZE         ;BYTE SIZE OF THE XMIT BUFFER
  1053.                OFREE     DW   ?              ;NUMBER OF BUFFERED XMIT BYTES
  1054.                SWIDTH    DB   SCREEN_WIDTH   ;WIDTH OF DISPLAY SCREEN
  1055.                SHEIGHT   DB   SCREEN_HEIGHT  ;HEIGHT OF DISPLAY SCREEN
  1056.                BAUD      DB   ?              ;BAUD RATE, COMPUTER TO MODEM
  1057.  
  1058.           The IDENT  string  is null-terminated,  and  does not  contain  a
  1059.           newline.  The baud rate byte contains  the bits that Function 00h
  1060.           would use to set the port to that speed.
  1061.  
  1062.           The  fields related to a particular port (buffer size, space left
  1063.           in the  buffer, baud rate) will  be undefined if port  0FFh or an
  1064.           invalid port is contained in DX.
  1065.  
  1066.           In some cases  X00 can  not accurately return  information.   For
  1067.           example, the user can  lock the baud rate at  115200 when loading
  1068.           X00.  There is no correct FOSSIL value that X00 can return in the
  1069.           BAUD  field.  X00 will set the  BAUD field equal to the last baud
  1070.           rate that the application attempted to set.
  1071.  
  1072.  
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.                                                                          19
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.           Superset Functions.
  1098.  
  1099.           Function  numbers above 1Bh and below 7Eh are X00 only functions.
  1100.           These functions will only  work with X00.  It is  the hope of the
  1101.           author that these functions will be added by other FOSSIL authors
  1102.           in  their  implementations  and  become  a  part  of  the  FOSSIL
  1103.           specification.
  1104.  
  1105.           Functions  1Ch and 1Dh are exact duplicated of FOSSIL functions 4
  1106.           and 5.
  1107.  
  1108.           Functions  1Eh and  1Fh are  intended to  be exact  duplicates of
  1109.           functions 4 and 5 of the PS/2's BIOS INT 14h.
  1110.  
  1111.           Function 20h is a destructive read with no wait.
  1112.  
  1113.           Function 21h is a Stuff/Poke character into the receive buffer.
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.                                                                          20
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.  
  1130.  
  1131.           Function  1Ch is  a  duplicate of  function 4.   The  function is
  1132.           duplicated so that at a future date, X00 functions 4 and 5 can be
  1133.           made compatible to the PS/2's function 4 and 5.
  1134.  
  1135.           Developers  are encouraged by the author to start using functions
  1136.           1Ch and  1Dh instead of functions  4 and 5.   See the application
  1137.           notes  section  for  instructions   on  a  compatible  method  of
  1138.           determining  if functions 1Ch and  1Dh should be  used instead of
  1139.           functions 4 and 5.
  1140.  
  1141.           Function 1Ch - Activate Port.
  1142.  
  1143.                Input:    AH = 1Ch
  1144.                          DX = port number
  1145.  
  1146.                Output:   AX = 1954h if successful
  1147.                          BL  =  maximum  function  number   supported  (not
  1148.                          counting functions 7Eh and above)
  1149.                          BH = rev of FOSSIL specification supported
  1150.  
  1151.           This function instructs X00  to use the FOSSIL  specification for
  1152.           the specified port.  Prior to issuing this function, any function
  1153.           that requires a port  number in DX will  be passed on to  BIOS or
  1154.           X00's  INT 14h BIOS emulator.  When this function  is called, all
  1155.           interrupts  involved   in  supporting  the   communications  port
  1156.           (specified in DX) are set up for  support by X00.  DTR is  turned
  1157.           on by this function.  The baud rate is NOT set or changed by this
  1158.           function.
  1159.  
  1160.           If an additional call  to this function occurs (2  Inits or Init,
  1161.           Read, Init, etc.) X00 will reset (clear) all buffers and all flow
  1162.           control is turned  off.  Values returned in the  registers upon a
  1163.           re-init are the same as an initial init (defined above).
  1164.  
  1165.  
  1166.  
  1167.  
  1168.  
  1169.  
  1170.  
  1171.                                                                          21
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.           Function  1Dh  is a  duplicate of  function 5.   The  function is
  1186.           duplicated so that at a future date, X00 functions 4 and 5 can be
  1187.           made compatible to the PS/2's functions 4 and 5.
  1188.  
  1189.           Developers  are encouraged by the author to start using functions
  1190.           1Ch and  1Dh instead of functions  4 and 5.   See the application
  1191.           notes  section  for  instructions  on  a  compatible  method   of
  1192.           determining  if functions 1Ch and  1Dh should be  used instead of
  1193.           functions 4 and 5.
  1194.  
  1195.           Function 1Dh - Deactivate Port.
  1196.  
  1197.                Input:    AH = 1Dh
  1198.                          DX = Port number
  1199.  
  1200.                Output:   Nothing
  1201.  
  1202.           This function instructs X00  that it should no longer  to process
  1203.           calls for  specified port (in DX) using the FOSSIL specification.
  1204.           If the port was never activated by function 4, then this function
  1205.           is ignored.  Any  subsequent function calls, that require  a port
  1206.           number  in  DX, will  be  passed  to BIOS  or  the  BIOS INT  14h
  1207.           emulator.
  1208.  
  1209.  
  1210.  
  1211.  
  1212.  
  1213.  
  1214.  
  1215.                                                                          22
  1216.  
  1217.  
  1218.  
  1219.           Function 1Eh - Extended line control initialization.
  1220.  
  1221.           This  function is intended to exactly emulate the PS/2's BIOS INT
  1222.           14 services, function 4.  Some  or all of the functions  provided
  1223.           here are duplicated by other X00 functions.
  1224.  
  1225.                Input:    AH = 1Eh
  1226.  
  1227.                          AL = Break, Where:
  1228.                             = 00h, No break and/or turn off break
  1229.                             = 01h, Start send of break.
  1230.  
  1231.                          BH = Parity, where:
  1232.                             = 00h, No parity
  1233.                             = 01h, Odd parity
  1234.                             = 02h, Even parity
  1235.                             = 03h, Mark parity (always 1)
  1236.                             = 04h, Space parity (always 0)
  1237.  
  1238.                          BL = Stop bits, where:
  1239.                             = 00h, One stop bit
  1240.                             = 01h, Two stop  bits for 6,  7 and 8  bit word
  1241.                                    length, 1  and 1/2  stop bits for  5 bit
  1242.                                    word length.
  1243.  
  1244.                          CH = Word length, where:
  1245.                             = 00h, 5 bits
  1246.                             = 01h, 6 bits
  1247.                             = 02h, 7 bits
  1248.                             = 03h, 8 bits
  1249.  
  1250.                          CL = Baud rate, where:
  1251.                             = 00h, 110 baud
  1252.                             = 01h, 150 baud
  1253.                             = 02h, 300 baud
  1254.                             = 03h, 600 baud
  1255.                             = 04h, 1200 baud
  1256.                             = 05h, 2400 baud
  1257.                             = 06h, 4800 baud
  1258.                             = 07h, 9600 baud
  1259.                             = 08h, 19200 baud
  1260.  
  1261.                          DX = Port number
  1262.  
  1263.                Output:   AX = Port status (see function 03h)
  1264.  
  1265.           If  locked at X00 load  time, the appropriate  parameters of this
  1266.           function are ignored.
  1267.  
  1268.  
  1269.  
  1270.  
  1271.  
  1272.  
  1273.  
  1274.                                                                          23
  1275.  
  1276.  
  1277.  
  1278.  
  1279.           Function 1Fh - Extended serial port status/control.
  1280.  
  1281.           This  function is intended to exactly emulate the PS/2's BIOS INT
  1282.           14 services, function  5.  Some or all of  the functions provided
  1283.           here are duplicated by other X00 functions.   This function has 2
  1284.           subfunctions specified by AL.
  1285.  
  1286.           Subfunction 00h - Read MCR
  1287.  
  1288.                Input:    AH = 1Fh
  1289.                          AL = 00h, Read modem control register (MCR)
  1290.                          DX = Port number
  1291.  
  1292.                Output:   AX = Port status (see function 03h)
  1293.                          BL = Modem control register, where:
  1294.                               Bits 7-5 = 0 (Reserved)
  1295.                               Bit 4    = 1 Loopback mode
  1296.                               Bit 3    = 1 OUT2 (interrupts) enabled
  1297.                               Bit 2    = 1 OUT1 active
  1298.                               Bit 1    = 1 Request to send active
  1299.                               Bit 0    = 1 Data terminal ready (DTR) active
  1300.  
  1301.           Subfunction 01h - Write MCR
  1302.  
  1303.                Input:    AH = 1Fh
  1304.                          AL = 01h, Write modem control register (MCR)
  1305.                          BL = Modem control register, where:
  1306.                               Bits 7-5 = 0 (Reserved)
  1307.                               Bit 4    = 1 Set loopback mode
  1308.                               Bit 3    = 1 Set OUT2 enable interrupts
  1309.                               Bit 2    = 1 Set OUT1 active (on)
  1310.                               Bit 1    = 1 Set Request to send active (on)
  1311.                               Bit 0    = 1 Set DTR active (on)
  1312.                          DX = Port number
  1313.  
  1314.                Output:   AX = Port status (see function 03h)
  1315.  
  1316.           In subfunction 01h (write  MCR) X00 will force bit 3  to 1.  That
  1317.           is,  X00  will not  allow  the  communications interrupts  to  be
  1318.           disabled.
  1319.  
  1320.           RTS may  be used  as a  flow  control signal  by X00.   When  the
  1321.           application program writes the MCR, the  RTS bit is treated as an
  1322.           RTS enable  bit.   This  means  that X00  will always  allow  the
  1323.           application program to turn RTS off.  However, X00 will  not turn
  1324.           on RTS unless it is safe to do so.
  1325.  
  1326.  
  1327.  
  1328.  
  1329.  
  1330.  
  1331.  
  1332.                                                                          24
  1333.  
  1334.  
  1335.  
  1336.           Function 20h - Read with no wait (destructive).
  1337.  
  1338.  
  1339.                Input:    AH = 20h
  1340.                          DX = Port number
  1341.  
  1342.                Output:   AH = 00h if character is available
  1343.                          AL = Next character if available
  1344.                          AX = 0FFFFh If no character is available
  1345.  
  1346.           This function returns the next character from the receive buffer.
  1347.           If the receive buffer is  empty, 0FFFFh is returned in AX.   This
  1348.           function  is the same as  function 0Ch except  that any character
  1349.           returned is removed from the receive buffer.
  1350.  
  1351.           ----------------------------------------------------------------
  1352.  
  1353.           Function 21h - Stuff/Poke the receive buffer.
  1354.  
  1355.  
  1356.                Input:    AH = 20h
  1357.                          AL = Character to place in the receive buffer
  1358.  
  1359.                Output:   Nothing
  1360.  
  1361.           This function will  insert the passed character  into the receive
  1362.           buffer (at the end).  Subsequent reading of the serial input will
  1363.           read the character.  The character is inserted at the  end of the
  1364.           buffer (as though it were just received).
  1365.  
  1366.           The  character is inserted into the receive buffer by calling the
  1367.           receive interrupt  routine.    All  normal  receive  checking  is
  1368.           preformed on the character.  Some things to note are:
  1369.  
  1370.                If  receiving  of  Xon/Xoff  is   enabled  and  an  Xoff  is
  1371.                stuffed/poked  into the  buffer,  the transmitter  will stop
  1372.                until a an Xon is received or stuffed/poked.
  1373.  
  1374.                If  Control C/K  checking is  enabled and  a Control  C/K is
  1375.                stuffed/poked, then the character  is not put in  the buffer
  1376.                and the internal flags is set.
  1377.  
  1378.           The above should give you a little to think about when using this
  1379.           function.
  1380.  
  1381.           This  function  is intended  to be  fully  re-entrant.   Thus, it
  1382.           should be callable from timer tick processing etc.
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.                                                                          25
  1391.  
  1392.  
  1393.  
  1394.  
  1395.           "Layered Application" services.
  1396.  
  1397.  
  1398.           The   functions   below  are   provided   to   meet  the   FOSSIL
  1399.           specification.   The following  functions  in effect  make X00  a
  1400.           dispatcher for other programs.
  1401.  
  1402.           To  operate  properly  on   a  multi-port  system,  any  "Layered
  1403.           Application" must be re-entrant.   The only "Layered Application"
  1404.           know  to the  author is  called a  Video FOSSIL.   The  one Video
  1405.           Fossil known to the author is not re-entrant and can  not be used
  1406.           on a multi-port system.
  1407.  
  1408.  
  1409.           Function 7Eh - Install an "external application" function.
  1410.  
  1411.                Input:    AH = 7Eh    
  1412.                          AL = Code assigned to external application
  1413.                          DX = Offset of application entry point
  1414.                          ES = Segment of application entry point
  1415.  
  1416.                Output:   AX = 1954h
  1417.                          BL = Code given to application (same as input AL)
  1418.                          BH = 01h - Installation was successful
  1419.                             = 00h - Installation failed
  1420.  
  1421.           This  function may be used by  external application code (special
  1422.           screen  drivers, modem code, database code, etc) to link into the
  1423.           INT 14h service  for use  by multiple applications.   The  "error
  1424.           return"  (BH=0   with  AX=1954h)   should  mean  that     another
  1425.           application layer  has already been installed  at that particular
  1426.           code. Codes 80h through 0BFh are be supported.  
  1427.  
  1428.           External   application  codes  80h-83h  are  reserved  by  FOSSIL
  1429.           developers  for  re-organizing  FOSSIL  services by  type  (comm,
  1430.           screen, keyboard, system).  
  1431.  
  1432.           Installed  application code will be entered, via a FAR call, from
  1433.           the  INT 14H  dispatcher  whenever  it  is  entered  (with  AH  =
  1434.           application code).
  1435.  
  1436.           If the value returned in AX  from this function is not 1954h, the
  1437.           service code that  is trying to be installed should  bring up its
  1438.           own  INT  14h code  that can  service  INT 14h  functions 7h-0BFh
  1439.           (80h-0BFh are "applications").
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.                                                                          26
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.  
  1461.  
  1462.  
  1463.  
  1464.           Function 7Fh - Remove an "external application" function.
  1465.  
  1466.                Input:    AH = 7Fh
  1467.                          AL = Code assigned to external application
  1468.                          DX = Offset of application entry point
  1469.                          ES = Segment of application entry point
  1470.  
  1471.                Output:   AX = 1954h
  1472.                          BL = Code given to application (same as input AL)
  1473.                          BH = 01h - Removal was successful
  1474.                             = 00h - Removal failed
  1475.  
  1476.           This  function removes an application's entry from the table.  If
  1477.           an error is returned, this means ES:DX did not match any entry at
  1478.           the  slot described by  AL.  An application  that wants to remove
  1479.           itself from memory  can issue  the 7F function  to remove  itself
  1480.           from  the  table,  then,  if it  is  successful,  un-install.  If
  1481.           installed with an INT  14h dispatcher it may  un-install provided
  1482.           no other application(s) have  been installed on top of  it (using
  1483.           its dispatcher).
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.                                                                          27
  1492.  
  1493.  
  1494.                                   Application Notes.
  1495.  
  1496.           Which Activate/Deactivate functions to use
  1497.  
  1498.           It is  the hope of  the author (after  a period of  time) to make
  1499.           X00's  functions 4  and  5 compatible  with  the PS/2's  INT  14h
  1500.           functions  4  and 5.    Currently, X00's  functions 4  and  5 are
  1501.           duplicated at functions 1Ch and 1Dh respectively.  I request that
  1502.           application  programmers start  using  functions 1Ch  and 1Dh  if
  1503.           those  functions are available.   That is, use  functions 1Ch and
  1504.           1Dh instead of functions 4 and 5 respectively.
  1505.  
  1506.           It is relatively simple to determine if the  functions at 1Ch and
  1507.           1Dh are available.   When your  program is ready to  activate X00
  1508.           for a given port, issue function 1Ch.  If 1954h is returned, then
  1509.           the port  is activated.   If 1954h  is not returned,  reissue the
  1510.           request to function 4.  Save the function number actually used to
  1511.           activate the port,  then increment  it by one  to deactivate  the
  1512.           port.
  1513.  
  1514.           Watch out for disk I/O
  1515.  
  1516.           Chris Irwin deserves  credit for discovering and  informing me of
  1517.           the following:  On  some (if not all) IBM/Clones,  interrupts are
  1518.           masked  for a long  period of  time during  DOS disk  I/O.   As a
  1519.           result, data  characters were  being lost  during  receive.   The
  1520.           problem is most noticeable on slower (4.77 meg) systems with 8250
  1521.           or 16450 type SIO chips installed using high speed modems.
  1522.  
  1523.           Remembering  that  all high  speed modems  (that  I know  of) use
  1524.           RTS/CTS  handshaking, I implemented a back door hook in some Beta
  1525.           X00s that  allowed Chris to turn  RTS off prior to  any disk I/O.
  1526.           Turning off  RTS while  a disk  write is  taking place fixed  the
  1527.           problem.   Also, turning off RTS  during disk I/O had  no adverse
  1528.           effect  on the transfer speed due to the modems internal buffers.
  1529.           While RTS is off,  the modem simply buffers the  data internally.
  1530.           When  RTS is  again  turned on,  the  modems internal  buffer  is
  1531.           emptied  because the transfer rate from the modem to the computer
  1532.           is faster than the line receive rate.
  1533.  
  1534.           X00  now has a front door (documented) function (1Fh) that allows
  1535.           application  programs to disable RTS.  Note that X00 function 1Fh
  1536.           is not a FOSSIL function.  I hope that it  will eventually become
  1537.           a FOSSIL function.  X00s function  1Fh is close to a duplicate of
  1538.           the PS/2's BIOS INT 14h, function 5.
  1539.  
  1540.           I strongly suggest that  application programmers consider turning
  1541.           off (disabling) RTS prior to any disk  I/O.  Even if the modem is
  1542.           not  using RTS/CTS handshaking, turning  off RTS will  not do any
  1543.           harm (that I know of).
  1544.  
  1545.  
  1546.  
  1547.  
  1548.  
  1549.  
  1550.  
  1551.                                                                          28
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.           Successive timer tick calls
  1558.  
  1559.           In some  environments,  the timer  tick chain  is called  several
  1560.           times in succession with  no delay between the calls.   I believe
  1561.           that one such environment is DESQview.  If a task has been asleep
  1562.           for 10  timer ticks, the timer tick chain will be called 10 times
  1563.           when the task is activated.
  1564.  
  1565.           X00 checks the DWORD at 46Ch.  If the  value at that location has
  1566.           not  changed,  X00  ignores  the  timer  tick.    Any  hooked  in
  1567.           application programs are not called.
  1568.  
  1569.           This  means  that the  timer tick  is  not reliable  for accurate
  1570.           timing.   All programs  (that I  know of)  that alter  the normal
  1571.           timer  tick  processing keeps  the DWORD  at  46Ch (time  of day)
  1572.           updated.  If not, your  time of day will be off.  If  you need to
  1573.           know elapsed  time, do not count  timer ticks.  Use  the DWORD at
  1574.           46Ch to calculate elapsed time.  The value stored in the DWORD at
  1575.           46Ch  is the number of timer ticks  since the computer was booted
  1576.           or the number of timer ticks past midnight.
  1577.  
  1578.  
  1579.  
  1580.  
  1581.  
  1582.  
  1583.  
  1584.                                                                          29
  1585.  
  1586.  
  1587.  
  1588.           Application Notes . . . . . . . . . . . . . . . . . . . . . .  27
  1589.           FOSSIL  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
  1590.           Function 00h  . . . . . . . . . . . . . . . . . . . . . . . . . 4
  1591.           Function 01h  . . . . . . . . . . . . . . . . . . . . . . . . . 5
  1592.           Function 02h  . . . . . . . . . . . . . . . . . . . . . . . . . 5
  1593.           Function 03h  . . . . . . . . . . . . . . . . . . . . . . . . . 6
  1594.           Function 04h  . . . . . . . . . . . . . . . . . . . . . . . . . 7
  1595.           Function 05h  . . . . . . . . . . . . . . . . . . . . . . . . . 8
  1596.           Function 06h  . . . . . . . . . . . . . . . . . . . . . . . . . 8
  1597.           Function 07h  . . . . . . . . . . . . . . . . . . . . . . . . . 9
  1598.           Function 08h  . . . . . . . . . . . . . . . . . . . . . . . . . 9
  1599.           Function 09h  . . . . . . . . . . . . . . . . . . . . . . . . . 9
  1600.           Function 0Ah  . . . . . . . . . . . . . . . . . . . . . . . .  10
  1601.           Function 0Bh  . . . . . . . . . . . . . . . . . . . . . . . .  10
  1602.           Function 0Ch  . . . . . . . . . . . . . . . . . . . . . . . .  10
  1603.           Function 0Dh  . . . . . . . . . . . . . . . . . . . . . . . .  11
  1604.           Function 0Eh  . . . . . . . . . . . . . . . . . . . . . . . .  11
  1605.           Function 0Fh  . . . . . . . . . . . . . . . . . . . . . . . .  12
  1606.           Function 10h  . . . . . . . . . . . . . . . . . . . . . . . .  13
  1607.           Function 11h  . . . . . . . . . . . . . . . . . . . . . . . .  13
  1608.           Function 12h  . . . . . . . . . . . . . . . . . . . . . . . .  14
  1609.           Function 13h  . . . . . . . . . . . . . . . . . . . . . . . .  14
  1610.           Function 14h  . . . . . . . . . . . . . . . . . . . . . . . .  14
  1611.           Function 15h  . . . . . . . . . . . . . . . . . . . . . . . .  15
  1612.           Function 16h  . . . . . . . . . . . . . . . . . . . . . . . .  15
  1613.           Function 17h  . . . . . . . . . . . . . . . . . . . . . . . .  16
  1614.           Function 18h  . . . . . . . . . . . . . . . . . . . . . . . .  16
  1615.           Function 19h  . . . . . . . . . . . . . . . . . . . . . . . .  16
  1616.           Function 1Ah  . . . . . . . . . . . . . . . . . . . . . . . .  17
  1617.           Function 1Bh  . . . . . . . . . . . . . . . . . . . . . . . .  18
  1618.           Function 1Ch  . . . . . . . . . . . . . . . . . . . . . . . .  20
  1619.           Function 1Dh  . . . . . . . . . . . . . . . . . . . . . . . .  21
  1620.           Function 1Eh  . . . . . . . . . . . . . . . . . . . . . . . .  22
  1621.           Function 1Fh  . . . . . . . . . . . . . . . . . . . . . . . .  23
  1622.           Function 20h  . . . . . . . . . . . . . . . . . . . . . . . .  24
  1623.           Function 21h  . . . . . . . . . . . . . . . . . . . . . . . .  24
  1624.           Function 7Eh  . . . . . . . . . . . . . . . . . . . . . . . .  25
  1625.           Function 7Fh  . . . . . . . . . . . . . . . . . . . . . . . .  26
  1626.           Licensing Information . . . . . . . . . . . . . . . . . . . . . 2
  1627.                Commercial License . . . . . . . . . . . . . . . . . . . . 2
  1628.                Non-Commercial License . . . . . . . . . . . . . . . . . . 2
  1629.           RTS/CTS flow control  . . . . . . . . . . . . . . . . . . . .  12
  1630.           SIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
  1631.           Warranty  . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
  1632.           WHAT IS X00 . . . . . . . . . . . . . . . . . . . . . . . . . . 1
  1633.           Xon/Xoff flow control . . . . . . . . . . . . . . . . . . . .  12
  1634.