home *** CD-ROM | disk | FTP | other *** search
/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / GENUTIL / FCI0106.ZIP / FCI.TXT < prev    next >
Text File  |  1994-10-24  |  23KB  |  793 lines
  1.  
  2.  
  3.  
  4.        FCI 1.06- Reference Manual
  5.  
  6.  
  7.  
  8.  
  9.                                        FCI
  10.                            Fossil Compatible Interface
  11.                               Version 1.06 Oct 1994
  12.                            Copyright 1994, Mario Viara
  13.                                All Rights Reserved
  14.  
  15.                                    Mario Viara
  16.                                    P.O BOX 130
  17.                                 12100 CUNEO ITALY
  18.  
  19.  
  20.                                BBS: +39 171-691995
  21.                                FAX: +39 171-691995
  22.                                VOICE:+39 171-695128
  23.                     NETMAIL: Mario Viara 2:334/705@fidonet.org
  24.                            EMAIL: M.Viara@agora.stm.it
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.        Pag. 1
  68.  
  69.  
  70.        FCI 1.06- Reference Manual
  71.  
  72.  
  73.                                       INDEX
  74.  
  75.  
  76.  
  77.        1. INTRODUCTION                                                   3
  78.  
  79.          1.1. NOTICE                                                     3
  80.  
  81.          1.2. REGISTRATION INFORMATION                                   3
  82.  
  83.          1.3. DISTRIBUTION NOTICE                                        3
  84.  
  85.          1.4. Simple Description                                         4
  86.           1.4.1. System requirement                                      4
  87.           1.4.2. Most important properties                               4
  88.           1.4.3. Contact the author                                      4
  89.           1.4.4. Distribution Form                                       4
  90.  
  91.  
  92.        2. INSTALLATION                                                   5
  93.  
  94.          2.1. Specific version                                           5
  95.  
  96.          2.2. Multi task installation                                    5
  97.           2.2.1. Multi task performance                                  5
  98.  
  99.          2.3. Command line parameter                                     5
  100.  
  101.  
  102.        3. CONFIGURATION                                                  7
  103.  
  104.          3.1. Configuration parameters                                   7
  105.           3.1.1. Generic parameters                                      7
  106.           3.1.2. Port specific parameters                                7
  107.  
  108.  
  109.        4. ADVANCED CONFIGURATION                                        10
  110.  
  111.          4.1. Detect idle time                                          10
  112.  
  113.          4.2. Automatic Transmission/Reception                          10
  114.           4.2.1. Automatic Transmission                                 10
  115.           4.2.2. Automatic Reception                                    10
  116.  
  117.          4.3. FCIDUMP Utility                                           10
  118.  
  119.  
  120.        5. TECHNICAL INFORMATION                                         12
  121.  
  122.          5.1. Tick functions and user function                          12
  123.  
  124.          5.2. Function CALL                                             12
  125.  
  126.          5.3. FCI API                                                   12
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.        Pag. 2
  134.  
  135.  
  136.        FCI 1.06- Reference Manual
  137.  
  138.  
  139.  
  140.        1.   INTRODUCTION
  141.  
  142.  
  143.  
  144.  
  145.  
  146.        1.1.  NOTICE
  147.  
  148.                  THIS IS NOT FREE  SOFTWARE!  If you paid a "public
  149.        domain" vendor for this program,  you  paid  for  the service  of
  150.        copying  the  program, and not for the program itself.  Rest
  151.        assured that nothing  ever  gets  to  the  originators of this
  152.        product from such a  sale.  You may evaluate this product for 30
  153.        days,   after this evaluation period if you make use of it,  you
  154.        must register your copy.
  155.  
  156.  
  157.        1.2. REGISTRATION INFORMATION
  158.  
  159.        The non-commercial single-user registration fee for  FCI is   $20
  160.        US.
  161.        The  commercial  and  multisystem  site  fee  for FCI is $50 US.
  162.        The check can be in US $ or equivalent value in other currency.
  163.        Send a check or company P.O. for the appropriate amount to:
  164.  
  165.                                    Viara Mario
  166.                                Casella Postale 130
  167.                                12100 CUNEO - ITALY
  168.  
  169.        After the registration you will receive one registration KEY and
  170.        the instruction for register FCI and all new released version.
  171.        For more detailed information  see the file REGISTER.TXT.
  172.  
  173.  
  174.          3.        1.   DISTRIBUTION NOTICE
  175.  
  176.        This  is  "user-supported"  software.    You are hereby granted a
  177.        license by Mario Viara to distribute this evaluation copy of  FCI
  178.        and its documentation, subject to the following conditions:
  179.  
  180.          FCI may be distributed freely without charge  in   evaluation       . 
  181.          form only.
  182.        . FCI may not be sold,  licensed, or a fee charged   for its use.
  183.          If a fee is charged in  connection  with FCI it  must cover the
  184.          cost of copying or dissemination only.   Such charges must be
  185.          clearly  identified as such by the originating party.  Under no
  186.          circumstances  may  the  purchaser be given the impression
  187.          that he is buying FCI itself.
  188.          FCI must be presented as a complete unit, including this       . 
  189.          documentation.   Neither  FCI nor  its documentation may be
  190.          amended or altered in any way.
  191.        . By  granting you the right to distribute the evaluation  form of
  192.          Con>Format,  you do not  become  the  owner  of  FCI  in any
  193.          form.
  194.        . Any   other  use,   distribution  or  representation  of FCI is
  195.          expressly forbidden  without  the  written  consent of Mario
  196.          Viara.
  197.  
  198.  
  199.        Pag. 3
  200.  
  201.  
  202.        FCI 1.06- Reference Manual
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.        1.4. Simple Description
  214.  
  215.  
  216.        FCI is one implementation of FOSSIL 03 specification with some
  217.        important and very interesting innovation.
  218.  
  219.          4.       1.    System requirement           1. 
  220.  
  221.        Fci required one system with all this  properties :
  222.  
  223.          IBM-AT ISA or EISA Compatible architecture       . 
  224.        . Intel 80286 or higher processor
  225.          UART NS16450 or 16550 compatible       . 
  226.          
  227.          4.       1.    Most important properties           2. 
  228.  
  229.        FCI have this  important properties :
  230.  
  231.          386 or higher specific version       . 
  232.          Can be loaded in UMB       . 
  233.          32 different port       . 
  234.        . Multi serial board support
  235.          Multi tasking support       . 
  236.          Interrupt lost automatic recovery support       . 
  237.        . Automatic support when lost one character of handshake
  238.  
  239.        1.4.  Contact the author           3. 
  240.  
  241.        I'm very happy if  you want send me your impression or hint for
  242.        future version. For this purpose use one of mail or e-mail address
  243.        present in the introduction page.
  244.  
  245.        1.4.4.              Distribution Form
  246.  
  247.        FCI is distributed in one unique file called FCIxxxxb.ZIP that
  248.        contains all documentation and executable file, xxxx is the
  249.        version number and b if present is the identification for one beta
  250.        version. For example the version 1.02 have the name FCI0102.ZIP.
  251.        The latest version of FCI can be download from my BBS with file
  252.        request magic name FCI.
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.        Pag. 4
  266.  
  267.  
  268.        FCI 1.06- Reference Manual
  269.  
  270.  
  271.  
  272.        2.   Installation
  273.  
  274.  
  275.  
  276.  
  277.  
  278.        2.1. Specific version
  279.  
  280.  
  281.        FCI is distributed in two different form FCI.EXE and FCI386.EXE.
  282.        FCI.EXE is a general version for all CPU from 80286 and FCI386.EXE
  283.        is one special version that use some 386 specific instruction to
  284.        improve performance and can be used in all system with one 80386 ,
  285.        80486 or higher system. The two version are identical for all
  286.        options only the 386 version is more fast. All  instructions are
  287.        for FCI.EXE but can be applied to FCI386.EXE.
  288.  
  289.  
  290.  
  291.        2.2. Multi task installation
  292.  
  293.  
  294.        When work in one multi task environment FCI can be installed in
  295.        two way ,in the common memory, if is installed before starting the
  296.        multi tasking ,or in the task memory , if installed after the
  297.        multi tasker. For multitasker supported like DesqView or Windows
  298.        3.x FCI must be, for better performance, before the multitasker
  299.        for other multitaskter must be installed in any single task that
  300.        use it.
  301.        One very important difference from FCI and other FOSSIL driver is
  302.        that FCI detect and support automatically multi tasking and d'ont
  303.        need TAME-aware program.
  304.  
  305.          2.       2.  1.              Multi task performance
  306.  
  307.        In one multi task environment all time spent for wait character
  308.        form serial board or for wait that one transmission is complete
  309.        with one normal fossil driver is lost, FCI can automatically
  310.        detect this time and give it to the system that can run other
  311.        task, with greater improvement of general system performance.
  312.  
  313.  
  314.          3.        2.   Command line parameter
  315.  
  316.        FCI for is installation take parameter from one file that default
  317.        name is FCI.CFG and must be located in the current directory from
  318.        where the driver is started. This filename can be changed using
  319.        the F option described later.
  320.  
  321.        For installing FCI use this command :
  322.  
  323.        FCI [Options]
  324.  
  325.        where options are :
  326.  
  327.        .  Filename - Can be used only for installing the driver and if is
  328.           present filename override the default configuration file name
  329.           FCI.CFG.
  330.  
  331.        Pag. 5
  332.  
  333.  
  334.        FCI 1.06- Reference Manual
  335.  
  336.  
  337.        .  I - Can be used only after installation and display some driver
  338.           information.
  339.        .  U - Can be used only after installation and if is possible
  340.        uninstall the driver.
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.        Pag. 6
  398.  
  399.  
  400.        FCI 1.06- Reference Manual
  401.  
  402.  
  403.  
  404.        3.    Configuration
  405.  
  406.  
  407.  
  408.        Configuration of FCI is made by one ASCII text files that contain
  409.        all parameter. This is file can be modified with any normal DOS
  410.        text editor starting from the default FCI.CFG supplied with the
  411.        packet. All line that start with one ; are comment and are
  412.        ignored, comment can be put after any parameter.
  413.  
  414.  
  415.  
  416.          1.        3.   Configuration parameters
  417.  
  418.  
  419.        The configuration file have this generic form :
  420.  
  421.             NAME[x]   [VALUE]
  422.  
  423.        Where NAME is the name of  the parameter that  want change/set and
  424.        VALUE if  present is the relative value. NAME can be followed from
  425.        one number for parameter that are port specific like base address
  426.        , irq number etc. VALUE is not present for 'FLAG PARAMETER' that
  427.        do not require one value but are only options that are activated.
  428.        In this document parameter that are not port specific are called
  429.        generic parameter and the others port specific parameter.
  430.  
  431.        3.1.  Generic parameters           1. 
  432.  
  433.  
  434.            NAME            DEFAULT VALUE                    BASE                            DESCRIPTION
  435.  
  436.        PORTN         10          4        Maximum number of ports that
  437.                                           can be installed, the maximum
  438.                                           current supported number is 32.
  439.  
  440.        MAXWAIT       10         100       Number of nop call to the
  441.                                           fossil driver before of
  442.                                           automatic idle context switch.
  443.  
  444.        MAXTWAIT      10         10        Maximum time in tick for
  445.                                           MAXWAIT nop call.
  446.  
  447.        MAXAUTORX     10         800       Time-out in tick after that if
  448.                                           no chars are received the
  449.                                           driver send one XON.
  450.  
  451.        MAXAUTOTX     10         100       Maximum time in tick after one
  452.                                           XOFF is received that driver
  453.                                           enable automatically the
  454.                                           transmission.
  455.  
  456.  
  457.          1.       3.    Port specific parameters           2. 
  458.  
  459.  
  460.             NAME      BASE  DEFAULT VALUE             DESCRIPTION
  461.  
  462.  
  463.        Pag. 7
  464.  
  465.  
  466.        FCI 1.06- Reference Manual
  467.  
  468.  
  469.        BASEx                3F8,2F8,3E8,2E                       16                  Base address of the port.
  470.                                   8
  471.  
  472.        PSTSx           16         -        Status port for multiserial
  473.                                            board.
  474.  
  475.        PMASKx          16         -        Status port mask for
  476.                                            multiserial board.
  477.  
  478.        PVALUEx         16         -        Status port value for
  479.                                            multiserial board. When one
  480.                                            interrupt from one multiserial
  481.                                            board occurs the driver for
  482.                                            decide the interested port read
  483.                                            the PSTSx make the and with
  484.                                            PMASKx and compare the value
  485.                                            with PVALUEx if  are the same
  486.                                            the interrupt for the specified
  487.                                            port is served otherwise skip
  488.                                            to the next port configured in
  489.                                            the same multiserial board.
  490.  
  491.        IRQx            10      4,3,5,7     This is the interrupt request
  492.                                            number for the port if is 0 the
  493.                                            port is not interrupt driven
  494.                                            but polled. Polled port can
  495.                                            work fine with low speed baud
  496.                                            rate in non multitasking
  497.                                            environment.
  498.  
  499.        RXSIZEx         10        1024      Size of recv buffer.
  500.  
  501.        TXSIZEx         10        512       Size of tx buffer.
  502.  
  503.        RXVHIx                RXSIZEx*7/8                       10                  Limit of number of char in recv
  504.                                            buffer that when is  reach  if
  505.                                            XON/XOFF is enabled the driver
  506.                                            send one XOFF for every char
  507.                                            received.
  508.  
  509.        RXHIx           10    RXSIZEx*3/4   Limit of number of char in recv
  510.                                            buffer that when is reach the
  511.                                            driver, if enabled, send one
  512.                                            XOFF and lower the CTS signal.
  513.  
  514.        RXLOWx          10     RXSIZEx/2    Lower limit of handshake when
  515.                                            if  reach the driver ,if
  516.                                            enabled, send one XON and
  517.                                            rising the CTS signal.
  518.  
  519.        BAUDx           10         -        If this parameter is specified
  520.                                            the baud rate is locked to the
  521.                                            specified value and every try
  522.                                            to change it take no effect.
  523.                                            All baud rate from 300 to
  524.                                            115200 can be written the only
  525.                                            exception is for 115200 baud
  526.                                            that must be written 11520.
  527.  
  528.  
  529.        Pag. 8
  530.  
  531.  
  532.        FCI 1.06- Reference Manual
  533.  
  534.  
  535.  
  536.        FIFOx           10         8        Is the value of receive FIFO
  537.                                            buffer for uart that support
  538.                                            it. This value can be raised if
  539.                                            the system have one very low
  540.                                            interrupt latency.
  541.  
  542.        FLAGIDLEx      FLAG        NO       If specified the driver detect
  543.                                            idle time, for multitasking
  544.                                            environment,  according to
  545.                                            MAXWAIT and MAXTWAIT and  give
  546.                                            it to the system.
  547.  
  548.        FLAGAUTOTXx    FLAG        NO       If present the system enable
  549.                                            the logic of auto transmission
  550.                                            according with MAXAUTOTX.
  551.  
  552.        FLAGAUTORXx    FLAG        NO       If present the system enable
  553.                                            the logic of auto receive
  554.                                            according with MAXAUTORX.
  555.  
  556.        FLAGINT13x     FLAG        NO       If present when one INT 13 call
  557.                                            is invoked automatically the
  558.                                            system disable the RTS during
  559.                                            the call. This flag is very
  560.                                            useful for system that take for
  561.                                            too much time the interrupt
  562.                                            disabled during I/O.
  563.  
  564.        FLAGDSRx       FLAG        NO       The driver return DSR signal
  565.                                            every time active without
  566.                                            regarding to the real state.
  567.  
  568.        FLAGCTSx       FLAG        NO       The driver return CTS signal
  569.                                            every time active without
  570.                                            regarding to the real state.
  571.  
  572.        FLAGDCDx       FLAG        NO       The driver return DCD signal
  573.                                            every time active without
  574.                                            regarding to the real state.
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.        Pag. 9
  596.  
  597.  
  598.        FCI 1.06- Reference Manual
  599.  
  600.  
  601.  
  602.        4.   Advanced configuration
  603.  
  604.  
  605.  
  606.        Some characteristic of FCI are very useful but need one more
  607.        detailed explanation for use it in the most good way, this chapter
  608.        explain of configure FCI in the most typical situation.
  609.  
  610.  
  611.  
  612.          1.        4.   Detect idle time
  613.  
  614.        MAXWAIT and MAXTWAIT are very important for improve performance in
  615.        multitasking environment, this parameter permit to FCI of decide
  616.        when must give control to the system.
  617.        When one fossil call is made without input/output transfer, for
  618.        example check if some  haracter are available or check if the
  619.        transmission buffer is full, FCI understand that
  620.        this is one `nop' call. MAXWAIT is the number of consecutive `nop'
  621.        call must occur before that the control is give to the operating
  622.        system. MAXTWAIT is the maximum time ,in system tick  (each 55
  623.        ms),  in that the MAXWAIT is checked.
  624.        FCI detect automatically all other condition that the idle time
  625.        must release to the operating system, for example if one program
  626.        wait for one character to be received and have no character in the
  627.        receive buffer all the time that must wait for one character
  628.        available is released to the operating system.
  629.        Detect idle time can be enable or disable for any port via the
  630.        flag FLAGIDLEx.
  631.  
  632.        See also : Port specific parameters
  633.  
  634.  
  635.  
  636.  
  637.        4.2. Automatic Transmission/Reception
  638.  
  639.        FCI implement one logic of automatic transmission/reception that
  640.        is very useful when one character of handshake is lost. This logic
  641.        is controlled by two parameter MAXAUTOTX and MAXAUTORX.
  642.  
  643.          2.       4.  1.              Automatic Transmission
  644.        When FCI receive one XOFF for one specific port, if the relative
  645.        FLAGAUTOTXx is enabled, start one counter that when reach
  646.        MAXAUTOTX without receive one XON, FCI cancel the effect of the
  647.        XOFF and start to send data. This function is very useful for bad
  648.        quality line that lost many characters.
  649.  
  650.          2.       4.  2.              Automatic Reception
  651.        Automatic reception work like automatic transmission but in
  652.        opposite front, if FCI detect that one port , with FLAGAUTORXx
  653.        enabled, d'ont receive character for one time that is greater of
  654.        MAXAUTORX send automatically one XON.
  655.  
  656.  
  657.        4.3. FCIDUMP Utility
  658.  
  659.  
  660.  
  661.        Pag. 10
  662.  
  663.  
  664.        FCI 1.06- Reference Manual
  665.  
  666.  
  667.        With FCI is present one program named FCIDUMP.EXE. The scope of
  668.        this program is monitoring FCI activity and is very important
  669.        during debug fase but also I have include it in the distribution
  670.        package because can also be used for configure FCI for best
  671.        performance. FCIDUMP run in two form. If is invoked without
  672.        command line options send to the standard output all parameter of
  673.        FCI.  If invoked with any options display the same parameter in
  674.        real time, this last form is very interesting if used in one multi
  675.        task environment for example is possible monitoring FOSSIL
  676.        activity of all task that running in the system. One complete
  677.        explanation of all the parameter displayed is out of scope of this
  678.        document but all the name of the parameter that are displayed are
  679.        self explained and I think that any one that now how one fossil
  680.        driver work can understand all.
  681.  
  682.  
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.        Pag. 11
  728.  
  729.  
  730.        FCI 1.06- Reference Manual
  731.  
  732.  
  733.  
  734.        5.   Technical information
  735.  
  736.  
  737.  
  738.        In this chapter I analyze how FCI handle some situation that are
  739.        not completely clear in the FOSSIL specification.
  740.  
  741.  
  742.  
  743.        5.1. Tick functions and user function
  744.  
  745.        FCI like other fossil driver handle tick and user function, but
  746.        multitask environment need some little clarification. If the
  747.        function is connected before that multitasking is started this
  748.        function is called at every tick but the function running in non
  749.        specific V86 machine and cannot access to any process specific
  750.        function. Otherwise if the function is connected after starting of
  751.        multitasking the function is specific for the task the connect it
  752.        and can access to the data of the specified V86 machine. Normally
  753.        is better load program that user tick or user defined fossil
  754.        functions in the environment of  the process that use it.
  755.  
  756.  
  757.          2.        5.   Function CALL
  758.  
  759.  
  760.        All function not in the fossil specification, for example all
  761.        function call with number greater of 1ch are passed without any
  762.        check to the previous INT 14 handler.
  763.        All fossil function that reference one port not open are again
  764.        passed to the previous INT 14 handler, with exclusion of  fossil
  765.        open port function.
  766.  
  767.  
  768.  
  769.        5.3. FCI API
  770.  
  771.        Over of fossil specification FCI implement one internal API any
  772.        one that is interested can ask the author for one copy of FCI API
  773.        specification.
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.        Pag. 12