home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 4 Drivers / 04-Drivers.zip / UOS2132.ZIP / XALL.DOC < prev    next >
Text File  |  1991-11-20  |  12KB  |  301 lines
  1.  
  2.                              12/1/91 
  3.  
  4.     Copyright (C) 1988-1990  DigiBoard Inc.   All rights reserved.
  5.                [ XALL.DOC ]
  6.  
  7.  
  8.     Version 1.3.2 of XALL.SYS is an OS/2 device driver for the following
  9.     DigiBoard intelligent multichannel cards:
  10.  
  11.         PC/Xi         PC/Xe         PC/Xm
  12.     MC/Xi         MC/Xi-Dos     MC/Xi-422     MC2/Xi
  13.     COM/Xi        COM/Xi-422
  14.     C/X (ISA)    C/X (EISA)    C/X (MCA)
  15.  
  16.     This document is intended for programmers developing software who need 
  17.     to be aware of the advantages and possible problems of using DigiBoard
  18.     hardware and this provided device driver.  
  19.  
  20.     Almost all of the standard Device IO commands are supported in full and
  21.     behave exactly as the standard OS/2 COM01.SYS driver.  There are however
  22.     a few expections as well as undefined or undocumented pieces of how
  23.     a 'well behaved' serial driver is to behave. Programmers should in
  24.     general be aware that these are INTELLIGENT cards with large on-board
  25.     memory buffers for data.  Calls to the driver that expect information
  26.     related to byte-by-byte activity of the driver are at best going to
  27.     return approximations and at worst will be simply missing some information.
  28.     Please read the sections below on the setting in the Device Control Block,
  29.     and GETCOMMSTATUS, GETLINESTATUS, GETCOMMERROR.
  30.  
  31.     FILES:
  32.           xall.sys    -- the executable device driver file.
  33.       xall.doc    -- this document.
  34.       install.doc    -- some installation notes for PC bus boards
  35.       relnotes.doc    -- upgrade notes.
  36.       dmode.exe    -- a MODE workalike with extended DEVICE capabilities.
  37.  
  38.      The device driver requires a number of command-line arguments 
  39.      described in the installation guide (INSTALL.DOC).
  40.  
  41.  
  42.            STANDARD OS/2 DEVICE DRIVER COMMANDS
  43.  
  44. READ     (4)    Fully Supported
  45.  
  46. NDREAD     (5)    Fully Supported
  47.  
  48. WRITE    (8)    Fully Supported
  49.         Writes will return to the caller AS SOON as the data has
  50.         cleared the card -- unless the request size indicates that
  51.         the transmission should take less than a few seconds -- in
  52.         which case it will return immediately.  If it is important to 
  53.         wait until the data has actually ALL been transmitted be sure 
  54.         to check with GETOUTQUEUECOUNT (see IOCtls below) to see how
  55.         many bytes remain in the transmit queue.
  56.  
  57. WRITEVFY(9)    Supported.  
  58.         We have discovered that even though undocumented in the 
  59.         Programmers Reference, this call gets generated by some
  60.         implementations of OS/2 if DISKVERIFY is set to ON in the
  61.         'config.sys' file EVERY TIME an application program calls
  62.         DosWrite.  Hence this will be treated like a DosWrite.
  63.  
  64. INSTAT    (6)    Fully Supported
  65.  
  66. OUTSTAT    (10)    Fully Supported
  67.  
  68. OPEN    (13)    Fully Supported
  69.         Shared opens are supported and permissions enforced by the
  70.         system.  Device Baud rates, data types, DCB information, etc. 
  71.         are set per system defaults if this is the first 'open' since 
  72.         system initialization.  
  73.         NOTE: This means that before the first open, the channel 
  74.               is NOT enabled and will NOT accept any data into the
  75.               receive buffer.  
  76.  
  77. CLOSE    (14)    Fully Supported
  78.         CLOSE will decrement the number of opens on this port.  If
  79.         this is the final close, CLOSE will flush any outstanding
  80.         READ requests.  If there are still some outstanding WRITEs 
  81.         AND some form of output handshaking is enabled then
  82.         CLOSE will block until they complete or time out.  
  83.         NOTE: If the process that currently owns the port dies or
  84.               is killed (eg. Cntl-C/Brk), CLOSE will NOT wait for 
  85.               data to clear before dropping the lines.  However, note
  86.               that OS/2 does NOT pass on signals to the threads
  87.               within a process; thus if a spawned thread is ALSO
  88.               blocked on IO when the process tries to die the
  89.               process will hang for whatever timeout is in effect
  90.               on the IO block in question.
  91.  
  92. *GEN_IOCTL --    See subsequent part of this document.
  93.  
  94. *PRT_ACS(21)    UNSUPPORTED.  The IO port associated with the card is 
  95.         not used by application programs for communications, but
  96.         by the driver for control of the card as a whole.  Will
  97.         return Error.
  98.  
  99.  
  100.            STANDARD OS/2 ioctl COMMANDS
  101.  
  102.  
  103.     Below are the functions defined in the Programmers Ref. manual.
  104.     Where behavior might not be exactly what you would expect, the function
  105.     name is preceded by an asterisk.  
  106.  
  107.  
  108.  
  109.     Category 01:
  110.  
  111. SETBAUDRATE    (41)    Supported in Full
  112.  
  113. SETLINECTRL    (42)    Supported in Full
  114.  
  115. TRANSMITIMM    (44)    Supported
  116.     Since commands must be issued to the card to temporarily suspend
  117.     software flow control if such is in effect it is possible that
  118.     if other data is in the Transmit queue that a byte or so of that may
  119.     also be transmitted.  In general this function is NOT recommended
  120.     if any software flow control is in effect as results on the 
  121.     receiving end may be unpredictable.
  122.  
  123. SETMODEMCTRL    (46)    Supported in Full
  124.     Attempts to set/clear modem lines that are currenly invloved in
  125.     flow control as per DCB.fbCtlHndShake (flag1) will fail.
  126.  
  127. SETBREAKON    (4b)    Supported
  128.     The length of time of the transmitted break is 1 min. max !
  129.  
  130. SETBREAKOFF    (45)    Supported in Full
  131.  
  132. STOPTRANSMIT    (47) (4c)    Supported in Full
  133.  
  134. STARTTRANSMIT    (48) (4d)    Supported
  135.  
  136. SETDCBINFO    (53)    Supported
  137.     Setting Flag2.bit6 AND Flag2.bit7 is supposed to enable the RTS-toggle
  138.     mode on Transmit.  This is not supported.  Setting BOTH of these bits
  139.     will be interpreted simply as RTS handshake on Input.
  140.  
  141.     DCB.fbTimeout bits 3-7 are documented in IBM's Device Driver guide
  142.     as relating to Extended Hardware Buffering.  Since the settings are
  143.     so tightly related to the particular hardware used by IBM on
  144.     their MCA machines and since setting these bits may have caused
  145.     application programs to assume the presence of a raw 8530 UART,
  146.     this driver will always clear these bits.
  147.  
  148. Character Replacement/Stripping:
  149.     NULL-stripping and BREAK- and ERR-char-replacement are supported 
  150.     in this version of the driver but it is important to note that
  151.     this is done by the driver code, not the on-board FEPOS.  Turning
  152.     these options ON will thus slow things down.  Also, if NULL-stripping
  153.     is enabled, there can be discrepancies between how many bytes 
  154.     GET_INQUEUE_COUNT says are in the buffer and how many bytes are
  155.     returned to the user by a read call.
  156.  
  157. GETBAUDRATE    (61)    Supported in Full
  158.     Beyond the normal limits of 19200 (IBM) or 38400 (MS), this driver
  159.     supports settings of 57600.  Settings beyond 19200 are NOT recommended
  160.     on the COM/Xi.
  161.  
  162. GETLINECTRL    (62)    Supported in Full
  163.  
  164. GETCOMMSTATUS    (64) (6b)    Supported
  165.     The information in this byte about hardware signal REASONS for Rx or 
  166.     Tx being paused is extracted from comparing the current line
  167.     signals with the handshake ones requested in DCB.fbCtlHndShake (flag1).
  168.     No explicit information is available from the DigiCHANNEL hardware
  169.     concerning those pauses/reasons but the above analysis will result
  170.     in accurate information barring strange cabling or severely ill
  171.     on-board operating system.  If Tx is paused for reasons of Software 
  172.     Flow control (i.e. an XOFF was received), that condition is accurately 
  173.     reflected in the COMMSTATUS byte.
  174.  
  175.     The TX_WAITING_TO_SEND_XON will never be set since the time between
  176.     the transmitter sending an XON and proceeding (i.e. no longer paused)
  177.     to subsequent data is not trappable by the Device Driver.
  178.  
  179.     Other bits are all set as per the MS OS/2 documentation.
  180.  
  181.     Note that on the C/X, information about the transmitter being paused 
  182.     can be inaccurate if all the data in the TX buffer is small enough to 
  183.     have LEFT the host adapter but is still paused on the remote 
  184.     Concentrator.  In such instances the above analysys ofcourse fails.
  185.     Likewise on the GETLINESTATUS call.
  186.  
  187. GETLINESTATUS    (65)    Supported
  188.     The HARDWARE_TRANSMITTING bit is set by cheating.  The call actually
  189.     pauses for the time increment to transmit 1 byte at the current
  190.     baud rate then checks to see if the transmit buffer head pointer has
  191.     moved.
  192.  
  193.     The WAITING_TO_SEND_XON and WAITING_TO_SEND_XOFF bits will never be
  194.     set as the batch nature of the intelligent card does not permit
  195.     that information to be reliable.
  196.  
  197. GETMODEMOUTPUT    (66)    Supported in Full
  198.  
  199. GETMODEMINPUT    (67)    Supported in Full
  200.  
  201. GETINQUECOUNT    (68)    Supported in Full
  202.     This count can be mistakenly large in certain circumstances.
  203.     Since the FEPOS encodes line-errors and certain data bytes as 
  204.     multi-byte sequences in the data stream, if such have occured then
  205.     the count returned will be a few bytes high.  The errors will only
  206.     be quantitative and not logical; the count will never be non-zero 
  207.     when it should be zero or vice-versa.
  208.  
  209. GETOUTQUECOUNT    (69)    Supported in Full
  210.     On the C/X there can be up to 2K of data out on the remote box
  211.     that the driver is [almost] oblivious of.  If the buffer on the
  212.     host adapter is empty, then the driver checks a boolean to see if
  213.     there is still activity on the remote box -- returning a character
  214.     count of 1 of there is.
  215.  
  216. GETCOMMERR    (6d)    Supported 
  217.     Errors in the input data are only detected as the data is read
  218.     from the card into user space.  Thus the COMMERROR byte will 
  219.     accurately indicate Parity, framing, and hardware-overrun errors on
  220.     data that has been read off the card into user-space.  We remain
  221.     oblivious of COM errors in the data out on the as yet un-read 
  222.     (i.e. un-requested) buffers of the card.
  223.  
  224. GETCOMMEVENT    (72)    Supported in Full
  225.  
  226. *GETDCBINFO    (73)    
  227.         Again, note quirks in SETDCBINFO
  228.  
  229.  
  230.     Category 0x0b
  231.  
  232.  
  233. FLUSHINPUT    (01)    Supported in Full
  234.  
  235. FLUSHOUTPUT    (02)    Supported in Full
  236.  
  237.  
  238. ********************************************
  239.     Category 0xD1    
  240. ********************************************
  241.  
  242. This is a non-standard category of IOCtl custom for the XALL driver.
  243. This section of code will ENABLE altpin processing on the given device.
  244. The _QUICKWRITE bit permits the writing of data to the card to happen
  245. much more efficently -- utilizing ALL the buffer space on the card before
  246. resorting to BLOCKING the process.  Without this bit set (default=0), the
  247. driver will mimick the Standard MS/IBM COM driver and wait for EACH write 
  248. request to clear the card before continuing with the next or returning to 
  249. the user program.
  250.  
  251. /* Enable-Disable reversed interpretations of DSR and CD for RJ45, and 
  252.  * method of waiting for WRITE requests. */
  253. #define IOCTL_CATEGORY_DIGI    0xd1
  254. #define DIGI_CUSTOM        0x07
  255. #define DIGI_QUERY        0x00    /* non-destructively READ settings */
  256. #define QUICKWRITE_ENABLE    0x10    /* if set, wait only on last close */
  257. #define ALTPIN_ENABLE        0x01
  258. #define ALTPIN_DISABLE        0x02    /* default Value */
  259.  
  260. unsigned char    Current, Want;
  261.  
  262.     ...
  263.     Want = DIGI_QUERY ;
  264.     ...
  265. /* Query current status without change */
  266.     if  ( DosDevIOCtl (    &Current,
  267.                 &Want,
  268.                 DIGI_CUSTOM,
  269.                 IOCTL_CATEGORY_DIGI,
  270.                 handle) )
  271.     {
  272.         printf ("This driver isn't XALL, won't do DIGI processing");
  273.     }
  274.     else
  275.     {    /* If need CD on 8-wire RJ45 and not already set up */
  276.         if ( 8_WIRE_RJ45 && ((Current & ALTPIN_ENABLE) == 0))
  277.         {
  278.             Want = (Current & (~ALTPIN_DISABLE)) | ALTPIN_ENABLE;
  279.             if  ( DosDevIOCtl (    &Current,
  280.                         &Want,
  281.                         DIGI_ALTPIN,
  282.                         IOCTL_CATEGORY_DIGI,
  283.                         handle) )
  284.                 printf ("Something ill in State of DIGI");
  285.     ...
  286.     ...
  287.         /* If I want to have QuickWrite processing on this port */
  288.         if ( (Current & QUICKWRITE_ENABLE) == 0))
  289.         {
  290.             Want = Current | QUICKWRITE_ENABLE;
  291.             if  ( DosDevIOCtl (    &Current,
  292.                         &Want,
  293.                         DIGI_ALTPIN,
  294.                         IOCTL_CATEGORY_DIGI,
  295.                         handle) )
  296.  
  297.  
  298. RETURN VALUE:
  299. The call will always return 0.  Current Status (0x1,0x2,0x11,0x12) returned in 
  300. 'Current' byte.  
  301.