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