TVicHW32.DLL version 3.0
                      ========================

               Copyright (C) 1997,1998 Victor Ishikeev
             e-mail: ivi@ufanet.ru, tools@entechtaiwan.com
                 http://www.entechatiwan.com/tools.htm


                             AS_DLL.TXT
                            ============

CONTENTS
========

1. GENERAL TVicHW32 FUNCTIONS
2. DIRECT MEMORY ACCESS WITH TVicHW32 (NEW features!)
3. DIRECT PORT I/O WITH TVicHW32
4. HARDWARE INTERRUPT HANDLING WITH TVicHW32 (NEW features!)
5. SPECIFIC WORK WITH THE LPT PORT (NEW!)
6. CONTACT INFORMATION


1. GENERAL TVicHW32 FUNCTIONS
====================================================

TVicHW32 has the following general functions:

    PVicHW32Descriptor OpenTVicHW32(PVicHW32Descriptor HW32);
    ----------------------------------------------------------
    Loads the vichwXX.vxd (under Windows 95) or vichwXX.sys (under 
    Windows NT) kernel-mode driver, providing direct access to the 
    hardware. If the kernel-mode driver was successfully opened, the
    GetActiveHW() returns True; if the function fails, the GetActiveHW() 
    returns False.

    Note! Before first call to OpenTVicHW32() HW32 should be NULL!

    PVicHW32Descriptor CloseTVicHW32(PVicHW32Descriptor HW32);
    -----------------------------------------------------------
    Closes the kernel-mode driver and releases memory allocated to it.
    If a hardware interrupt was "unmasked", the "mask" is restored. If the
    driver was successfully closed, the GetActiveHW() always returns False.

    BOOL GetActiveHW(PVicHW32Descriptor HW32);
    --------------------------------------------
    This boolean function specifies whether the kernel-mode driver is open.
    Returns True if the driver is already open, or False if it is not.


2. DIRECT MEMORY ACCESS WITH TVicHW32
=====================================

The following function permits direct memory acccess:

    long MapPhysToLinear(PVicHW32Descriptor HW32, long PhAddr, long Size);
    ---------------------------------------- --------------------------------
    Maps a specific physical address to a pointer in linear memory, 
    where PhAddr is the base address and Size is the actual number of
    bytes to which access is required (returns type long, should be
    converted to pointer before using).
   
    NEW! Now you can get up 16 of valid pointers to various physical 
    ===  addresses.

    The following example returns a pointer to the system ROM BIOS area:

    char *pBios;
    PVicHW32Descriptop HW32 = NULL;


    HW32 = OpenTVicHW32( HW32);

    if (GetActiveHW(HW32)) {

       pBios = (char*)MapPhysToLinear (HW32,0xF8000,256); //255 bytes beginning at $F8000

       //...working with pBIOS...

       HW32 = CloseTVicHW32(HW32);

     }

     else ...  //  failed

3. DIRECT PORT I/O WITH TVicHW32
================================

The following functions permit direct I/O port access:
------------------------------------------------------

    short GetPortByte (PVicHW32Descriptor HW32, short wPortAddress);              // read one byte 
    short GetPortWord (PVicHW32Descriptor HW32, short wPortAddress);              // read one word
    long  GetPortLong (PVicHW32Descriptor HW32, short wPortAddress);              // read four bytes
    void  SetPortByte (PVicHW32Descriptor HW32, short wPortAddress, short bData);  // write one byte
    void  SetPortWord (PVicHW32Descriptor HW32, short wPortAddress, short wData);  // write one word
    void  SetPortLong (PVicHW32Descriptor HW32, short wPortAddress, long lData); // write four bytes

    void  SetHardAccess(PVicHW32Descriptor HW32, BOOL HardAccess);
    --------------------------------------------------------------
    The SetHardAccess() function determines whether the kernel-mode driver
    should use "hard" or "soft" access to the I/O ports. If set to True
    "hard" access is employed; if set to False "soft" access is employed.

    "Soft" access provides higher performance access to ports, but may fail
    if the port(s) addressed are already in use by another kernel-mode
    driver. While slower, "Hard" access provides more reliable access to
    ports which have already been opened by another kernel-mode driver. 

    BOOL  GetHardAccess(PVicHW32Descriptor HW32);
    --------------------------
    Returns True is "hard" access is used.

4. HARDWARE INTERRUPT HANDLING WITH TVicHW32
============================================

In a Win32 environment, hardware interrupts are normally prohibited
by Windows; the TVicHW32 kernel-mode driver allows you to use the
interrupt for direct handling by your application. Note that only one
interrupt can be handled at a time.

The following functions permit access to hardware interrupts.

    void  SetIRQ(PVicHW32Descriptor HW32,
                 short              IRQNumber,
                 TOnHWInterrupt     HWHandler);
    -------------------------------------------

    Assign the interrupt specified by the IRQNumber value (1..15) to
    the HWHandler() handler. Note that IRQ0 (the system timer) is *not* 
    supported.

    typedef void (__stdcall *TOnHWInterrupt)(
                             long  HWCounter,
                             short LPT_DataReg,
                             short LPT_StatusReg,
                             short Keyb_ScanCode
                             );


    HwCounter       : shows how many interruption was processed in the driver.
    LPT_DataReg     : if used IRQ7 then driver reads base LPT port (data)
    LPT_StatusReg   : if used IRQ7 then driver reads status LPT register(base+2)
    Keyb_ScanKode   : if used IRQ1 then driver allows you see all keystrokes
                      (scan codes) from the keyboard.


    void  UnmaskIRQ(PVicHW32Descriptor HW32); 
    -----------------------------------------
    Physically unmasks the hardware interrupt specified by the IRQNumber
    property, so that an lpfnOnHWInterrupt function will be called 
    when a hardware interrupt occurs. 

    void  MaskIRQ(PVicHW32Descriptor HW32); 
    --------------------------
    Physically masks the hardware interrupt unmasked by UnmaskIRQ().

    BOOL  IsIRQMasked(PVicHW32Descriptor HW32);
    ------------------------------------------
    Function which specifies whether the hardware interrupt 
    has been physically masked (True).

    short GetIRQNumber(PVicHW32Descriptor HW32); 
    -------------------------------------------
    Returns IRQ value assigned by SetIRQ()

5. SPECIFIC WORK WITH THE LPT PORT (NEW!)

Now TVicHW32 provides extended functions for work with the printer (LPT) port.   
See test examples for more info.

==== BASE ====

    short GetLPTNumPorts(PVicHW32Descriptor HW32); 
    -------------------------------------------
    Shows how many LPT ports are installed on your PC.

    short GetLPTNumber(PVicHW32Descriptor HW32); 
    --------------------------------------------
    Shows current LPT number.

    short SetLPTNumber(PVicHW32Descriptor HW32, short nNewValue); 
    ------------------------------------------------------------
    Allows select a current LPT port.

    short GetLPTBasePort(PVicHW32Descriptor HW32);
    --------------------------------------------
    Returns a base address of the current LPT port.

==== PINS ====

    BOOL GetPin(PVicHW32Descriptor HW32, short nPin);
    -------------------------------------------------
    Allows read an electrical level from the select pin of current 
    LPT port. Returns TRUE if current level is HIGH.

    void SetPin(PVicHW32Descriptor HW32, short nPin, BOOL nNewValue);
    ----------------------------------------------------------------
    Allows write an electrical level to the selected pin.
    If nNewValue = TRUE - HIGH level.

    Note: Not all pins are accessible for this operation. Run test example
          for more info.

==== STATUS ====

    BOOL GetLPTAckwl(PVicHW32Descriptor HW32);
    ------------------------------------------
    Returns ACKWL state from the printer

    BOOL GetLPTBusy(PVicHW32Descriptor HW32);
    -------------------------------------
    Returns BUSY state from the printer

    BOOL GetLPTPaperEnd(PVicHW32Descriptor HW32);
    --------------------------------------------
    Returns PAPER END state from the printer
    
    BOOL GetLPTSlct(PVicHW32Descriptor HW32);
    ------------------------------------------
    Returns SLCT state from the printer

    BOOL GetLPTError(PVicHW32Descriptor HW32);
    ------------------------------------------
    Returns ERROR state from the printer

=== COMMANDS ===

    void SetLPTStrobe(PVicHW32Descriptor HW32);
    ----------------------------
    Sends STROBE signal to the printer

    void SetLPTAutofd(PVicHW32Descriptor HW32, BOOL Flag);
    ------------------------------------------------------
    Sets current AUTOFD  state on printer

    void SetLPTInit(PVicHW32Descriptor HW32);
    ----------------------------------------
    Resets printer by sending INIT signal

    void SetLPTSlctIn(PVicHW32Descriptor HW32);
    -------------------------------------------
    Sends SLCTIN signal to the printer

    BOOL LPTPrintChar((PVicHW32Descriptor HW32, short ch);
    -----------------------------------------------------
    Sends one symbol to the printer. Returns TRUE if
    successed. Otherwise you need repeat this operation

6. CONTACT INFORMATION
======================

    Comments, questions and suggestions regarding TVicHW32 can be directed 
by e-mail to ivi@ufanet.ru or tools@entechtaiwan.com. 

With best wishes,

Victor Ishikeev
Oct 1998