nattynarwhal / vmwmouse Goto Github PK

VMware mouse driver for Windows 3.1

Assembly 97.21% Batchfile 0.64% Makefile 2.15%

windows-3-x vmware mouse driver driver-programming qemu

vmwmouse's Introduction

VMware mouse driver for Windows 3.x

Running Windows 3.1 in VMware, DOSBox-X, or QEMU, but annoyed by having to grab and ungrab the cursor manually?

Wish you could just move the cursor in and out like a modern OS (one with USB tablet support or VMware Tools drivers), with no Ctrl+Alt(+G) dancing?

Or want to control your cursor at all under the ESXi web UI? (It doesn't do relative input.)

With this driver, now you can. It implements the interface that VMware uses (the backdoor), replacing the existing PS/2 mouse driver.

example.mp4

qemu.mp4

Well, how does it work?

Glad you asked!

Normally, mice work by sending a delta of their movements. You'd have to trap the mouse inside of the guest for this to work; any tracking difference would result in a very hard to control cursor. Being able to send the absolute coordinates would be great, because you can know the exact point when the cursor hits the edge.

However, there wasn't a standard way of doing absolute positioning with PC input devices until the USB tablet standard, and Windows 3.x/DOS massively predate USB, let alone have a USB stack. For those situations, VMware offers absolute positioning through a port I/O interface.

So let's use said interface. What we need to do is threefold for an MVP:

On initialization, make the cursor absolute (four calls)
On deinitialization, make the cursor relative (a single call)
Instead of parsing PS/2 mouse events, ask VMware for mouse events instead
Well, we should check if we're even using a supported host, but hey...

The challenge is doing this from real or 286 protected mode, because we need to set the 32-bit extended versions of the registers (i.e. EAX instead of AX). The toolchain we're using is MASM, since we're keeping this easy and using the example drivers from the DDK, just modified. This means we can just plop the .386 directive in a suitable place in the code, and EAX will become available to use.

One interesting bit with the mouse driver is the SF_ABSOLUTE bit in a Windows mouse driver. When passed as the flags for the mouse event (in AX), it'll be an absolute position instead of relative - exactly what we want, without any trickery! Even better, it takes a range of 0 through FFFFh, as basically a percentage of where it is on the screen, in BX and CX. This way, you don't need to know the resolution of the screen when calculating the absolute position. Turns out this is exactly how VMware sends the coordinates in EBX and ECX!

The unfortunate difference is in button handling; VMware sends what buttons are currently held, while Windows wants to know when the button goes down and when it comes up. I've implemented a crude solution, but I think it could be done a lot better. Right now, only two buttons are supported, but in theory, we could send a third with a refactor to the driver. (We're also throwing away the wheel event - that could be four and five, considering Windows 3.x predates the wheel entirely.)

One annoying thing about the sample driver is because the fact it supports multiple types of mouse, it uses a tactic of copying the interrupt handler into a specifically sized buffer. This means you can't go over 210 bytes for the interrupt handler right now; this could be alleviated with a major refactor or rewrite. For now, I've excised the normal PS/2 mouse handling in favour of only using the VMware backdoor. I've also had to occasionally be worried about the length of instructions; shaving things off by only using the 16-bit view of a register, for example.

Overall, I'm glad this was surprisingly easy, considering I didn't know x86 assembly before, and I only implemented this in a day - with lots of struggling against MASM and typos.

(Updates: I've cleaned up button handling, and I'm experimenting on the wheel.)

Supported hosts

VMware and QEMU are supported. I have tested Workstation and ESXi. I can't test Fusion because my Mac is M1, so oh well.

VMware will need no configuration. QEMU also needs no configuration - the vmmouse automatically gets attached when the backdoor is added. Don't try adding it any command line flags; you're likely to just crash it.

(For QEMU, you can verify things by running info mice and info qtree.)

Building from source

Make sure you have the Windows 3.1 Device Development Kit installed.

Inspect the values in SETUPENV.BAT and INSTALL.BAT, then run:

setupenv.bat
nmake

Installation

Source

If building from source; after building, run INSTALL.BAT. This will overwrite the stock mouse driver, so make a backup. The INF install is less crumbly, so I recommend you go for that.

Binaries

If using binaries, run Windows Setup. Point where the driver and INF file are; if you're using the floppy, it'll likely be A:. Restart Windows and enjoy. Serve with garnish.

Note that if you're using the GUI version of Windows Setup, after selecting the VMware mouse driver for the first time, the combo box might go blank. If that's the case, you need to select it again. This doesn't happen from the DOS version of Windows Setup (when setup is run outside of Windows or at install).

Similar drivers

Javier's VirtualBox mouse driver

vmwmouse's People

Contributors

Stargazers

Watchers

Forkers

catalinc404 wuyadie rastuszhang arne-cl cyberflamego cryptid joncampbell123 linomastro toivma pescej mrclan emupedia kernspeicher

vmwmouse's Issues

VMD for enhanced mode

The DDK includes source for this; do we need to tweak this? It seems we're telling VMD (the comments about Windows/386) that we're a PS/2 mouse, which is correct, but do we need any special behaviour for DOS stuff? I would assume perhaps hooking to become relative/absolute might be interesting.

Hide cursor when mouse leaves the VM

Is this something in the flags (high word of EAX) we're missing out on?

Video Driver for Windows 3.x

Thank you so much for developing a brand new mouse driver for Windows 3.x. Can you also make a video driver for Windows 3.x that can work on VMware and supports True Color (2²⁴ colors)?

Find exact terms for sample drivers

It's a known fact most Windows 3.x drivers are derived from the samples (i.e. video drivers are a lament configuration due to how much of GDI is implemented in them), but I don't know what exact terms there are (for i.e. making my changes easily licensed).

A friend is looking at their MSDN discs for answers.

OS/2 1.x PM

I have no idea if a DDK/OAK for this survives, or how related it is to the Windows one.

Remove other mice types

We don't really need these, since Windows already provides them and they're just now dead weight.

Check if the VMware backdoor works before enabling the device

Would be a good idea...

Add the fact this is also useful when using VNC in the readme.md

Since the readme.md lists a few problems that can be fixed by using this mouse driver, you can add "using the mouse under VNC" to the list of problems.

Building from Linux/CI

Right now, the driver needs to be built from DOS with the Windows DDK disc. While this isn't a problem outside of my own laziness for development, it'd be nice to be able to build from a modern OS. With that, we can also do automated builds and smoke tests.

As for CI, I suspect there's no convenient prefab thing.

I have a prototype using DOSBox, which is convenient, while it can run automatically, we'll be flying blind because DOSBox GUI only.

[cpu]
cycles = max
[autoexec]
imgmount d "/home/calvin/Downloads/Microsoft Windows 3.1 DDK/win16ddk.iso" -t cdrom
mount x .
x:
set PATH=D:\WIN31\DDK\286\TOOLS;D:\VISUALC\US\VC152C\MSVC15\BIN;C:\WINDOWS;C:\DOS
set LIB=D:\WIN31\DDK\286\LIB
set INCLUDE=D:\WIN31\DDK\286\INC
nmake
exit

Some notes to crib:

dosemu2's Windows driver, which is also another DDK derived driver. They use dosemu2 to build, which I haven't used before. For CI, would need a way to easily load up the DDK. At least we don't need to install anything; we can set %PATH% to the needed paths on the CD.
Javis' VirtualBox driver makefile, easily make floppies. They use Watcom, so not much else is relevant here.

Move VMware reading to the soft interrupt handler?

It seems we might be better off reading from VMware and putting the mouse state in there instead of reading it from the real interrupt handler. Right now, we just really ignore everything other than if there was a valid packet received, and the values it sets wouldn't be useful because they'd be bogus in absolute mode.

VirtualBox support

It seems VirtualBox pivoted to using mostly VMware devices, mouse included. How does this work?

Missing file?

Hi,

Great project.
Cannot locate the missing "vmwmouse.drv" when using the inf method.
Also the install.bat is calling that file (though in your document it is called "mouse.drv")

Windows 1/2/3.0 support

I don't know if these would work out of the box or any changes would need to be made. I skim-diffed the stock 3.1 DDK driver against the 2.x OAK and it seems most of the changes might be backwards compatible.

QEMU support

What's required here?

Windows Nt 3.1 / 3.51

Thank you for that driver!

Any Plans for Windows NT 3.1 or 3.51?
If you need a 3.51 VMware Image to test on, see fifth entry: https://winworldpc.com/product/windows-nt-3x/351
I used that as base image to make it work in Hyper-V, including networking - easier than doing it all fresh :D ...

DOS `mouse.com` implementations broken

When we enable absolute positioning, it hoses the PS/2 relative packets coming out, because you need to check the VMware backdoor instead. This means that a DOS program will just get an endless stream of moving the mouse to the bottom right as the mouse moves. (This is the same behaviour I saw in Windows when I got the absolute positioning mode working but didn't change the interrupt handler yet.)

I can reproduce this running CuteMouse before starting Windows, along with its mousetst.com. (Windows doesn't seem to bother using the mouse.com implementation itself.)

There are two solutions I'm guessing:

Implement a VMD that switches it to relative when entering a full-screen DOS application and back to absolute when exiting full-screen DOS. Would solve #3.
Implement a VMware absolute mouse.com. I believe the mouse API actually deals with absolute mice and relative mice are implemented on top of this, but it's based on pixel coordinates IIRC. Something else entirely, and also arguably a useful project.

Not sure what I'd implement.

Problems with Total Commander

The driver seems to cause problems with Total Commander 6.58 (legal, registered version - not a cracked one) - from time to time TC complains about damaged binary and quits. Happens randomly, sometimes very quickly, sometimes only after a couple of minutes of playing with the application. Tried with Windows 3.11 for Workgroups, running either using QEMU 6.2.0 or my private DOSBox Staging branch with VMware mouse support (https://github.com/FeralChild64/dosbox-staging/tree/fc/vmware-mouse-2) - happens on both emulators.

It does not seem to be a virus - the Total Commander executable looks intact, fresh installation does not help. Reverting to original PS/2 driver fixes the problem.

installation renders windows unbootable

following installation procedure for this driver on a fresh install of windows 3.11 (winver reports it as windows "3.10E"?) causes windows to throw an "error loading gdi.exe"

attempted in vmware workstation 16.2.1

INF setup

So we can actually provide a nice little driver floppy and make it easily switchable from Windows Setup.

Note that 3.0 has a different format?

Windows 9x

The current 3.x driver may work, but is less ideal.

Windows 95 DDK suggests the entire stack seems to have moved into VMD instead; also niceties like VMD_Post_Absolute_Pointer_Message.

Of course, VMware's own driver works fine on 9x, but it might be useful for VBox/QEMU?

Mouse driver crashes Program Manager

When I use both this driver and the patched SVGA driver for Windows 3.1, some weird errors show up. They stop appearing when I disable this driver.

Steps to replicate:

Create a VMware virtual machine and Install MS-DOS (I used version 5) and Windows 3.1
Download the Generic SVGA driver. as well as the VMware patch
Launch the Windows Setup from MS-DOS (cd C:\WINDOWS and SETUP.EXE) and install the Generic SVGA driver as a third-party display driver (I recommend the ET4000 1024x768 256 option, but you can select whichever one you like).
Lauch the Windows Setup (again from MS-DOS) and install the VMware Mouse driver
Insert the VMware Patch floppy drive into the VM
Type the following commands (overwrite existing files if asked):

A:
copy SVGA256.DRV C:\WINDOWS\SYSTEM
copy VGAPATCH.COM C:\WINDOWS\SYSTEM
C:
cd C:\WINDOWS\SYSTEM
vgapatch p
del VGAPATCH.COM
cd..
win

Try to move the mouse around. Also try exiting and restarting Windows a couple times, as well as minimizing/restoring the Program Manager. Eventually the first error should show up
The second error showed up when I tried messing around with Windows Setup from within Windows

weird disk issue in vmware

Mentioned before in #21 (where pics/gist are) but tl;dr is weird disk request when loading Windows. - With a fresh 3.11+DOS 6.2 (my main VM is WfW/DOS 5.0, seen it there sometimes but unsure why) seems to happen when not loading any CD drives/not setting last drive. Doesn't seem to occur under the debugger. It doesn't happen in standard (286) mode.

My guess is:

The fact it's during loading is probably pointing to enable call
The fact it's 386 mode specific means it's likely something kicking in 386 mode
The fact it's disk related

Thus, I think the hypercalls mangling extended registers is probably putting some future call by a disk subsystem at play. Problem is, where (which subsystem?) and why (I thought most Windows 3.x 386 stuff would be in the VMM isolated from this or know extended registers are mangled.). The fact it's 3.11 means there's no 32-bit disk/file access, but might be something like smartdrive?

Mitigation might be to save EAX-EDX anywhere we do hypercalls.

Refactor/rewrite

Related to #6, it'd be nice to clean up a lot of this to clarify licensing and simplify the code a lot more. A lot of the code for the interrupt handler is a slight mess because of the fact it has to accommodate the existing multi-mouse type scheme.

Rewrite button handler for less twitchy buttons

This is super finicky. I think it's because we're not really handling state transitions and just asserting up/down from what we get from VMware. We should look back at the original PS/2 mouse driver source for how it did button transitions, and only assert when the state changes.

Notable touchy examples are the splitter in winfile, holding to select in a combobox, and Calmira's start menu.

Third button and wheel

For third button: The DDK drivers don't include an example with one, nor does mouse.inc provide any insight into how you'd expose a third button to the event procedure. Maybe just the same pattern as i.e. SF_B2_UP?

For wheel: Not sure what we could do. Post WM_VSCROLL events to the active window? That seems ultra crumbly from a driver though, though there may be an example non-VMM driver that does it.

We'd probably need to get rid of the other drivers that are now dead weight in mouse.drv.