|
|
Installable Virtual Device Driver (VDD) Support For NTVDM==========================================================
Problem:--------There is a class of DOS applications which run on theirown custom hardware. Generally these applications willhave a pluggable card and a 16bit device driver for theircard. As these cards are beyond the scope of normal PCarchitecture, NTVDM cannot virtualize them in a securemanner. So all such applications are not supported underNTVDM.
Solution:---------
If an ISV is writing an NT native device driver for such acard, it is technically quite simple to provide the supportsuch that the DOS application runs unmodified and in a securefashion. The vendor has to write a Virtual Device Driver (VDD)which will virtualize the card for the DOS application by callingthe native device driver.
----------------------- | | | DOS Application | V86 mode | | ----------------------- I/O-map | ^ |Mem-Map | DMA IO | | |IO | -------------|----------------------------- | | | | V | V V ----------------------- | | DMA | | NTVDM -------| NT User mode code | | ----------------------- ^ | | | Dispatches the event to VDD | V ----------------------- | | | VDD | VDD is a DLL attached to NTVDM | | ----------------------- ^ | | | Call the real driver -------------|----------------------------- | | | V ----------------------- | | | NT Device Driver | Kernel mode | | ----------------------- ^ | | | Carries out the operation with its card | V ----------------------- | | | Plugged Card | | | -----------------------
Following are the main work items to achieve the above solution:
a. Loading the VDD b. Support for I/O mapped I/O c. Support for Memory mapped I/O d. Support for DMA operations e. Register manipulation services f. Memory accessing services g. Interrupt simulation services h. Miscelleneous services
a. Loading the VDD:
The system administrator will add the command lines in the \\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\CONTROL\"VirtualDeviceDrivers" section of the registry for all the VDDs to be loaded in the VDM process. The command line format is REG_MULT_SZ (i.e. ASCIIZZ). This key will laways be present and install program just need to add their VDD name.
[VirtualDeviceDrivers] VDD = <full-path of the VDD1.DLL>\0<full-path of the VDD2>\0\0
VDD ACTION :
NTVDM will load all these VDDs from the registry at the VDM process initialization time and call their initialization routine. VDDs should make sure at this time that their respective NT device driver is present and make all the resource allocations. The VDD handle passed in this initialization routine will be the Id of the VDD when calling the VDD services as described below.
b. Support for I/O mapped I/O:
Following services will be provided for VDDs to deal with IO ports:
BOOL VDDInstallIOHook (HANDLE, IO_PORT_RANGE, IO_PORT_HANDLERS); BOOL VDDDeInstallIOHook (HANDLE, IO_PORT_RANGE);
The HANDLE is the one passed to the VDD in its DLLInit routine. Only one IO hook may be installed for a given port, all subsequent requests will fail. On DeInstalling, the default IO hook will be placed, which means no one is hooked on those IO ports. IO_PORT_HANDLERS should atleast provide a byte read and a byte write handler. In addition, word and string handlers can also be provided. In the absense of word or string handlers, these will be emulated using byte handlers. A port has to be hooked for both read and write. VDDs should not hook DMA ports as these are virtualized by NTVDM and services are provided for VDDs to access DMA.
VDD Action: On an IO access (or on a series of IO accesses) the VDD can check if it needs to start the DMA. If so it can call the DMA services given in the following section. If it does'nt require the DMA or if the DMA has transfered the buffer, then the VDD can call its NT device driver to complete the desired request. (Its also possible that the VDD first requests the device driver and than using DMA services copies the contents to the VDM buffer).
c. Support for Memory mapped I/O:
Following services will be provided for VDDs to deal with their memory mapped addresses:
BOOL VDDInstallMemoryHooks (HANDLE, ADDR_RANGE, MEMORY_HANDLER); BOOL VDDDeInstallMemoryHooks (HANDLE, ADDR_RANGE);
The addr_range should be a valid range i.e. above RMSIZE and below system rom. Only one Memory hook may be installed for a given range, all subsequent requests will fail. On deinstalling the range, VDD will no longer get page fault on those ranges. Memory_handler will tell on which address the fault occured and whether it was a read or write fault. On its return from the memory handler it will be assumed that the fault was handled.
A port-range will actually result in a whole page to be reserved. That means the page will not remain available to EMM for EMM page frames and UMBs.
VDD Action: It can map the normal memory and let the app write to it. Later they can use the WIN32 API's or its device driver as per the case to deal the whole memory range.
d. Support for DMA operations
Following DMA service will be provided for the VDD:
DWORD VDDRequestDMA (HANDLE, DMA_CHANNEL, BUFFER, TRANSFER_BYTES); BOOL VDDQueryDMA (HANDLE, DMA_CHANNEL, DMA_INFO_BUFFER); BOOL VDDSetDma (HANDLE, DMA_CHANNEL, INDEX, DMA_INFO_BUFFER);
NTVDM will control all the DMA ports and will maintain all the information on per channel basis. There are two flavors in which a VDD can carry-out the DMA operations. It can call VDDRequestDMA and this service will interpret the DMA registers and do the DMA transfer. It should be clear at this point that this will involve two buffer copyings. For example, the VDD will ask the device driver to trasnfer some data in a buffer (allocated by VDD) then it will call this service to transfer this buffer to the address DOS application has asked for (through DMA programming).
On the other hand, a VDD can collect all the DMA registers using VDDQueryDMA and figure out where the DOS application has asked the DMA to take place, in what mode and how much to transfer. Then it can call the NT device driver with same address as asked by DOS app. In this case there will be only one copying. VDD should use VDDSetDMA after such an operation to update the DMA state.
e. Register manipulation services:
See the reference section for details. There is a get and a set service for each V86 registers.
f: Memory Accessing services:
Following services are provided for Manipulating VDM's memory.
PVOID GetVDMPointer(ULONG Address, ULONG Size, BOOL ProtectedMode); BOOL FreeVDMPointer(ULONG Address, ULONG Size, BOOL ProtectedMode); BOOL FlushVDMPointer(ULONG Addr, ULONG Size, PVOID Buffer, BOOL ProtectedMode);
g: Interrupt simulation services
Following services is provided for simulating an interrupt to the VDM.
VOID VDDSimulateInterrupt (BYTE ms, BYTE line, WORD count);
h. Miscellaneous Services
Following services will be provided for memory allocation/deallocation.
VDDAllocMem (HANDLE, ADDRESS, PAGES); VDDFreeMem (HANDLE, ADDRESS, PAGES);
VDD will use VDDAllocMem when it gets a page fault on a page which it has hooked using VDDInstallMemoryHook. Later it can free this memory using VDDFreeMem. We are asking VDDs to use WIN32 API for all their needs and here also a VDD could have used VirtualAlloc and VirtualFree. The problem is that on a non-x86 machine this would'nt have worked because on such a plateform the VDM memory is under the emulator's control and it has to be told of such memory changes.
Following service will be provided for VDM termination.
VDDTerminateVDM (VOID);
VDD will use this service to terminate the VDM. For instance if a VDD fails to allocate memory on a memory mapped IO, it may want to terminate the VDM as its state is inconsistenet.
VDDs should always use these services to achieve plateform independence.
---------------- REFERENCE SECTION -------------------------
/** Basic typedefs of VDD IO hooks **/
typedef VOID (*PFNVDD_INB) (WORD iport,BYTE * data);typedef VOID (*PFNVDD_INW) (WORD iport,WORD * data);typedef VOID (*PFNVDD_INSB) (WORD iport,BYTE * data,WORD count);typedef VOID (*PFNVDD_INSW) (WORD iport,WORD * data,WORD count);typedef VOID (*PFNVDD_OUTB) (WORD iport,BYTE data);typedef VOID (*PFNVDD_OUTW) (WORD iport,WORD data);typedef VOID (*PFNVDD_OUTSB) (WORD iport,BYTE * data,WORD count);typedef VOID (*PFNVDD_OUTSW) (WORD iport,WORD * data,WORD count);
/** Array of handlers for VDD IO hooks. **/
typedef struct _VDD_IO_HANDLERS { PFNVDD_INB inb_handler; PFNVDD_INW inw_handler; PFNVDD_INSB insb_handler; PFNVDD_INSW insw_handler; PFNVDD_OUTB outb_handler; PFNVDD_OUTW outw_handler; PFNVDD_OUTSB outsb_handler; PFNVDD_OUTSW outsw_handler;} VDD_IO_HANDLERS, *PVDD_IO_HANDLERS;
/** Port Range structure **/typedef struct _VDD_IO_PORTRANGE { WORD First; WORD Last;} VDD_IO_PORTRANGE, *PVDD_IO_PORTRANGE;
/** Memory mapped I/O handler. **/
typedef VOID (*PVDD_MEMORY_HANDLER) (PVOID FaultAddress, ULONG RWMode);
/** Buffer for returning DMA information **/typedef struct _VDD_DMA_INFO { WORD addr; WORD count; WORD page; BYTE status; BYTE mode; BYTE mask;} VDD_DMA_INFO, *PVDD_DMA_INFO;
/*** VDDInstallIOHook - This service is provided for VDDs to hook the * IO ports they are responsible for. * * INPUT: * hVDD ; VDD Handle * cPortRange; Number of VDD_IO_PORTRANGE structures * pPortRange; Pointer to array of VDD_IO_PORTRANGE * IOhandler : VDD handler for the ports. * * OUTPUT * SUCCESS : Returns TRUE * FAILURE : Returns FALSE * GetLastError has the extended error information. * * NOTES: * 1. The first one to hook a port will get control. Subsequent * requests will be failed. There is no concept of chaining * the hooks. * * 2. IOHandler must atleast provide a byte read and a byte write * handler. Others can be NULL. * * 3. If word or string handlers are not provided, their effect * will be emulated using byte handlers. * * 4. VDDs should not hook DMA ports. NTVDM manages it for all * the clients and services are provided to perform DMA * operations and to access and modify DMA data. * * 5. VDDs should not hook video ports as well. Such a hooking * will succeed but there is no gurantee that the IO handler will * get called. * * 6. Each Vdd is allowed to install only one set of IO hooks * at a time. * * 7. Extended Error codes: * * ERROR_ACCESS_DENIED - One of the requested ports is already hooked * ERROR_ALREADY_EXISTS - Vdd already has active IO port handlers * ERROR_OUTOFMEMORY - Insufficient resources for additional VDD * Port handler set. * ERROR_INVALID_ADDRESS - One of the IO port handlers has an invalid * address. */BOOL VDDInstallIOHook ( HANDLE hVdd, WORD cPortRange, PVDD_IO_PORTRANGE pPortRange, PVDD_IO_HANDLERS pIOFn);
/*** VDDDeInstallIOHook - This service is provided for VDDs to unhook the * IO ports they have hooked. * * INPUT: * hVDD : VDD Handle * * OUTPUT * None * * NOTES * * 1. On Deinstalling a hook, the defult hook is placed back on * those ports. Default hook returns 0xff on reading * and ignores the write operations. * */VOID VDDDeInstallIOHook ( HANDLE hVdd, WORD cPortRange, PVDD_IO_PORTRANGE pPortRange);
/*** VDDInstallMemoryHook - This service is provided for VDDs to hook the * Memory Mapped IO addresses they are resposible * for. * * INPUT: * hVDD : VDD Handle * addr : Starting linear address * count : Number of bytes * MemoryHandler : VDD handler for the memory addresses * * * OUTPUT * SUCCESS : Returns TRUE * FAILURE : Returns FALSE * GetLastError has the extended error information. * * NOTES * 1. The first one to hook an address will get the control. There * is no concept of chaining the hooks. VDD should grab the * memory range in its initialization routine. After all * the VDDs are loaded, EMM will eat up all the remaining * memory ranges for UMB support. * * 2. Memory handler will be called with the address on which the * page fault occured and with a falg telling whether it was a * read or write operation. * * 3. On returning from the hook handler it will be assumed that * the page fault was handled and the return will go back to the * VDM. * * 4. Installing a hook on a memory range will result in the * consumption of memory based upon page boundaries. The Starting * address is rounded down, and the count is rounded up to the * next page boundary. The VDD's memory hook handler will be * invoked for all addreses within the page(s) hooked. The page(s) * will be set aside as mapped reserved sections, and will no * longer be available for use by NTVDM or other VDDs. The VDD is * permitted to manipulate the memory (commit, free, etc) as needed. * * 5. After calling the MemoryHandler, NTVDM will return to the * faulting cs:ip in the 16bit app. If the VDD does'nt want * that to happen it should adjust cs:ip appropriatly by using * setCS and setIP. * * 6. Only one VDD will be allowed to have memory hooks in a page. * In other words a page si owned by a VDD exclusively. * * 7. Extended Error codes: * * ERROR_ACCESS_DENIED - One of the requested ports is already hooked * ERROR_OUTOFMEMORY - Insufficient resources. */BOOL VDDInstallMemoryHook ( HANDLE hVDD, PVOID pStart, DWORD count, PVDD_MEMORY_HANDLER MemoryHandler);
/*** VDDDeInstallMemoryHook - This service is provided for VDDs to unhook the * Memory Mapped IO addresses. * * INPUT: * hVDD : VDD Handle * addr : Starting linear address * count : Number of addresses * * OUTPUT * None * * NOTES * 1. On Deinstalling a hook, the memory range becomes invalid. * VDM's access of this memory range will cause a page fault. * * 2. Extended Error codes: * ERROR_INVALID_PARAMETER - One of the parameter is invalid. */BOOL VDDDeInstallMemoryHook ( HANDLE hVDD, PVOID pStart, DWORD count);
/*** VDDRequestDMA - This service is provided for VDDs to request a DMA * transfer. * * INPUT: * hVDD VDD Handle * iChannel DMA Channel on which the operation to take place * Buffer Buffer where to or from transfer to take place * length Transfer Count (in bytes) * If Zero, returns the Current VDMA transfer count * in bytes. * * OUTPUT * DWORD returns bytes transferred * if Zero and GetLastError is set means operation failed. * if Zero and GetLastError is clear means VDMA transfer count * was zero. * * NOTES * 1. This service is intended for those VDDs which do not want to * carry on the DMA operation on their own. Carrying on a DMA * operation involves understanding all the DMA registers and * figuring out what has to be copied, from where and how much. * * 2. This service will be slower than using VDDQueryDMA/VDDSetDMA and * doing the transfer on your own. * * 3. Extended Error codes: * * ERROR_ALREADY_EXISTS - Vdd already has active IO port handlers * ERROR_OUTOFMEMORY - Insufficient resources for additional VDD * Port handler set. * ERROR_INVALID_ADDRESS - One of the IO port handlers has an invalid * address. * */DWORD VDDRequestDMA ( HANDLE hVDD, WORD iChannel, PVOID Buffer, DWORD length);
/*** VDDQueryDMA - This service is provided for VDDs to collect all the DMA * data. * * INPUT: * hVDD VDD Handle * iChannel DMA Channel for which to query * Buffer Buffer where information will be returned * * OUTPUT * SUCCESS : Returns TRUE * FAILURE : Returns FALSE * GetLastError has the extended error information. * * * NOTES * 1. This service is intended for those VDD which are doing * performance critical work. These VDD can do their own DMA * transfers and avoid one extra buffer copying which is a * overhead in using VDDRequestDMA. * * 2. VDDs should use VDDSetDMA to properly update the state of * DMA after carrying on the operation. * * 3. Extended Error codes: * * ERROR_INVALID_ADDRESS - Invalid channel * */BOOL VDDQueryDMA ( HANDLE hVDD, WORD iChannel, PVDD_DMA_INFO pDmaInfo);
/*** VDDSetDMA - This service is provided for VDDs to set the DMA data. * * INPUT: * hVDD VDD Handle * iChannel DMA Channel for which to query * fDMA Bit Mask indicating which DMA data fields are to be set * VDD_DMA_ADDR * VDD_DMA_COUNT * VDD_DMA_PAGE * VDD_DMA_STATUS * VDD_DMA_ALL (all Above) * Buffer Buffer with DMA data * * OUTPUT * SUCCESS : Returns TRUE * FAILURE : Returns FALSE * GetLastError has the extended error information. * * NOTES * * 1. Extended Error codes: * * ERROR_INVALID_ADDRESS - Invalid channel * */BOOL VDDSetDMA ( HANDLE hVDD, WORD iChannel, WORD fDMA, PVDD_DMA_INFO pDmaInfo);
/** VDDAllocMem - Allocates memory at a given virtual address. * * INPUT * hVDD : VDD * Address: Address where memory is to be allocated (between 640k and 1Mb) * nBytes : Number of bytes to allocate * * OUTPUT * SUCCESS : Returns TRUE * FAILURE : Returns FALSE * GetLastError has the extended error information. * Notes: * 1. VDDs have to use this service instead of WIN32 VirtualAlloc * to be plateform independent. On non-x86 machines VDDAllocMem * tells the CPU emulator about this memory allocation. * * 2. The address will be made page aligned downwards and nBytes will * be streched upward to be page aligned. * * 3. Extended Error codes: * ERROR_OUTOFMEMORY - Insufficient memory * ERROR_INVALID_ADDRESS - Invalid address */VOID VDDAllocMem ( HANDLE hVDD, PVOID Address, ULONG nBytes);
/** VDDFreeMem - Free memory at a given virtual address. * * INPUT * hVDD : VDD * Address: Address where memory is to be freed * nBytes : Number of bytes to free * * OUTPUT * SUCCESS : Returns TRUE * FAILURE : Returns FALSE * GetLastError has the extended error information. * * Notes: * 1. Extended Error codes: * ERROR_INVALID_ADDRESS - Invalid address * * 2. The address will be made page aligned downwards and nBytes will * be streched upward to be page aligned. * */VOID VDDFreeMem ( HANDLE hVDD, PVOID Address, ULONG nBytes);
/** VDDTerminateVDM - Terminate the VDM. * * INPUT * None * * OUTPUT * None * * Notes: * 1. VDD should call this service on encoutering a fatal error, * such that VDDs state is inconsistent. * * 2. VDD can use MessageBox WIN32 API to putup a popup before * terminating the VDM. */VOID VDDTerminateVDM ( VOID);
/** Register Manipulation services * */
ULONG getEAX(VOID);USHORT getAX(VOID);UCHAR getAL(VOID);UCHAR getAH(VOID);ULONG getEBX(VOID);USHORT getBX(VOID);UCHAR getBL(VOID);UCHAR getBH(VOID);ULONG getECX(VOID);USHORT getCX(VOID);UCHAR getCL(VOID);UCHAR getCH(VOID);ULONG getEDX(VOID);USHORT getDX(VOID);UCHAR getDL(VOID);UCHAR getDH(VOID);ULONG getESP(VOID);USHORT getSP(VOID);ULONG getEBP(VOID);USHORT getBP(VOID);ULONG getESI(VOID);USHORT getSI(VOID);ULONG getEDI(VOID);USHORT getDI(VOID);ULONG getEIP(VOID);USHORT getIP(VOID);USHORT getCS(VOID);USHORT getSS(VOID);USHORT getDS(VOID);USHORT getES(VOID);USHORT getFS(VOID);USHORT getGS(VOID);ULONG getCF(VOID);ULONG getPF(VOID);ULONG getAF(VOID);ULONG getZF(VOID);ULONG getSF(VOID);ULONG getIF(VOID);ULONG getDF(VOID);ULONG getOF(VOID);USHORT getMSW(VOID);
VOID setEAX(ULONG);VOID setAX(USHORT);VOID setAH(UCHAR);VOID setAL(UCHAR);VOID setEBX(ULONG);VOID setBX(USHORT);VOID setBH(UCHAR);VOID setBL(UCHAR);VOID setECX(ULONG);VOID setCX(USHORT);VOID setCH(UCHAR);VOID setCL(UCHAR);VOID setEDX(ULONG);VOID setDX(USHORT);VOID setDH(UCHAR);VOID setDL(UCHAR);VOID setESP(ULONG);VOID setSP(USHORT);VOID setEBP(ULONG);VOID setBP(USHORT);VOID setESI(ULONG);VOID setSI(USHORT);VOID setEDI(ULONG);VOID setDI(USHORT);VOID setEIP(ULONG);VOID setIP(USHORT);VOID setCS(USHORT);VOID setSS(USHORT);VOID setDS(USHORT);VOID setES(USHORT);VOID setFS(USHORT);VOID setGS(USHORT);VOID setCF(ULONG);VOID setPF(ULONG);VOID setAF(ULONG);VOID setZF(ULONG);VOID setSF(ULONG);VOID setIF(ULONG);VOID setDF(ULONG);VOID setOF(ULONG);VOID setMSW(USHORT);
/** GetVDMPointer - Findout the linear address of a given VDM address * * INPUT * Address - seg/sel:off (hi word has segment or selector and loword * is offset) * Size - Range of the pointer * ProtectMode - If protectmode == TRUE its sel:off * If protectmode == FALSE its seg:off * * OUTPUT * Returns Linear address. * * NOTES: * 1. VDDs should use this service to convert the address rather * than shifting the seg by 4 and adding the offset. This makes * them plateform independent. On non-x86 machine VDM's 0 and * the process's 0 are different and the actual adddress conversion * is provided by the CPU emulator. */PVOID GetVDMPointer( ULONG Address, ULONG Size, BOOL ProtectedMode);
/** FlushVDMPointer - Flushes the contents (required because of emulator) * * INPUT * Address - seg/sel:off (hi word has segment or selector and loword * is offset) * Size - Range of the pointer * Buffer - Address returned by GetVDMPointer. * ProtectMode - If protecmeode == TRUE its sel:off * If protecmeode == FALSE its seg:off * * OUTPUT * Returns Linear address. * * NOTES: * 1. VDDs should use this service to make sure that on non-x86 * machines, the CPU emulator gets a chance to flush any data * associated with a memory range. */BOOL FlushVDMPointer( ULONG Addr, ULONG Size, PVOID Buffer, BOOL ProtectedMode);
/** FreeVDMPointer - Frees a pointer previously returned by GetVDMPointer * * INPUT * Address - seg/sel:off (hi word has segment or selector and loword * is offset) * Size - Range of the pointer * ProtectMode - If protecmeode == TRUE its sel:off * If protecmeode == FALSE its seg:off * * OUTPUT * None * * NOTES: * 1. FreeVDMPointer does FlushVDMPointer as well. */BOOL FreeVDMPointer( ULONG Address, ULONG Size, BOOL ProtectedMode);
/** VDDSimulateInterrupt - Simulates an interrupt to the VDM. * * INPUT * ms - Is either ICA_MASTER or ICA_SLAVE as appropriate * line - Interrupt line * count - allows a batch of interrupts to be delivered but will usually * be 1. * * OUTPUT * None */VOID VDDSimulateInterrupt ( BYTE ms, BYTE line, WORD count);
|
