Return to readme CVS log

Up to [WindowsNT SDKs] / ntddk / src / vdd / com_vdd

Annotation of ntddk/src/vdd/com_vdd/readme, revision 1.1

1.1     ! root        1: 
        !             2: This VDD sample implements serial port support for the Virtual DOS
        !             3: Machine (VDM) under Windows NT.
        !             4: 
        !             5: The Windows NT VDM has a built-in Virtual Device Driver for serial
        !             6: communications, so this sample driver is completely redundant.  It
        !             7: illustrates how serial support might have been implemented using Win32
        !             8: and the Windows NT DDK.  This sample is based in part on the built-in
        !             9: serial driver, but it has been significantly modified and works
        !            10: differently.  You should not rely on any feature of this driver when
        !            11: writing serial I/O code that might be used under Windows NT.
        !            12: 
        !            13: To install this VDD, use regedit to modify
        !            14: 
        !            15: HKEY_LOCAL_MACHINE
        !            16:  \ SYSTEM
        !            17:   \ CurrentControlSet
        !            18:    \ Control
        !            19:     \ VirtualDeviceDrivers
        !            20:      \ VDD
        !            21: 
        !            22: to include ddkroot\lib\*\com_vdd.dll from your DDK tree.  Shutdown and
        !            23: restart Windows NT to let this change take effect.  Note: once you
        !            24: install the DLL as a VDD you can only modify (rebuild) it when no
        !            25: VDM's are running.  Use regedit to uninstall the VDD from
        !            26: HKEY_LOCAL_MACHINE\...\VDD if you want to use the built-in serial
        !            27: support.
        !            28: 
        !            29: An optional feature of a VDD is the direct dispatch function.  Your
        !            30: application can call this function directly instead of through the I/O
        !            31: instruction trap.  A sample direct dispatch function is included
        !            32: (VDDDispatch), but it has not been completed or tested at this time.
        !            33: You may use it as a guide, but be aware of its status.  Also, there is
        !            34: no equivalent to this function in the built-in serial support.
        !            35: 
        !            36: The code is split into three modules.  The first module (COM_VDD.C) is
        !            37: the VDD interface.  This holds the code to install the VDM hooks and
        !            38: initialize the virtual UARTs, and to close and release them.  The
        !            39: second module (PC_COM.C) implements the DOS interface to the virtual
        !            40: UARTs.  It handles IN and OUT instructions to the UART ports and
        !            41: generates simulated interrupts as appropriate.  The final module
        !            42: (NT_COM.C) implements the interface to Win32.
        !            43: 
        !            44: Unlike the built-in serial support there is no provision for this VDD
        !            45: to ever release the serial port once it is used.  As long as the VDM
        !            46: remains active you will be able to access the serial port from it, but
        !            47: otherwise the serial port is locked out.  You should consider whether
        !            48: this is the way you want your VDD to act, and how you might deal with
        !            49: this problem.  One option would be to dynamically load and unload your
        !            50: VDD rather than installing it permanently.
        !            51: 
        !            52: This VDD is multithreaded.  Besides the thread that executes the DOS
        !            53: code there is a thread that monitors the serial port status and an
        !            54: optional thread for transmit buffering.  Multithreading is one way you
        !            55: can get better performance and reduce the drag on other apps.
        !            56: Transmit buffering is an example of how this works.  Through testing
        !            57: it was found that byte transmission offered the most room for
        !            58: improvement.  Each transmitted byte was being output using a WriteFile
        !            59: call.  By collecting several byt es into a buffer before doing the
        !            60: WriteFile the overhead can be reduced.  A separate transmit thread
        !            61: helps this work by delaying the actual write for a few milliseconds
        !            62: while trying to fill the buffer.
        !            63: 
        !            64: Transmit buffering also shows an example of how queues can be
        !            65: implemented using Win32.  Queues are not supported directly by Win32,
        !            66: but they are easy to implement using a mutual exclusion object and a
        !            67: semaphore object.  The TX_enqueue and TX_dequeue functions and
        !            68: TX_queue structure show one way to do this.
        !            69: 
        !            70: Overlapped I/O is another point that this VDD illustrates well.  Under
        !            71: Win32 you must specify overlapped I/O or any file operation will block
        !            72: all others until it completes.  For serial communications this
        !            73: includes WaitCommEvent as well as ReadFile and WriteFile.  In the VDD
        !            74: this would have prevented any reads or writes while the status
        !            75: monitoring thread was waiting for a comm event.  See the wait_comm,
        !            76: read_comm and write_comm routines for details.
        !            77: 
        !            78: A CRITICAL_SECTION object is used to control access to the UART state.
        !            79: This allows the status monitoring thread to update the virtual UART
        !            80: state asynchronously.  A Mutex object could have been used as with the
        !            81: transmit buffers, but a critical section is more appropriate in this
        !            82: context.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.