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

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.