HOWTO: USB Mass Storage on x86 inside of KVM.

[pocketprobe]

DISCLAIMER: This is unsupported by VSI, even if it worked well enough for me to have a Prolific USB:serial adapter talk to a terminal, and to initialize a USB flash drive and write some files, move it to another computer and mount it there. As well as editing system files is normally a bad idea.

It turns out that the USB stack does in fact seem to work, or at least USB->serial devices as well as USB mass storage devices. If you add an entry for the EHCI USB controller on KVM, the USB configuration server will actually start, and allow you to use these devices.

Step 1:
Edit SYS$COMMON:[SYSEXE]SYS$USER_CONFIG.DAT

This is a file that [historically] is intended for third parties to add entries for device drivers to allow OpenVMS to interact with them. Here we are going to add an entry for the EHCI USB controller inside of KVM at the end of the file. This is the correct device ID for the 'ich9-ehci1' USB controller in KVM, however you may need to determine the correct ID if this example isn't.

Code: Select all

!------------------------------------------------------------------------------
device		= "82801I (ICH9 Family) USB2 EHCI Controller #1"
  name		= EH
  driver	= SYS$EHCIDRIVER
  adapter	= PCIE
  id		= 0x293A8086
  boot_class    = DN
  boot_flags    = HW_CTRL_LTR, UNIT_0
  flags         = PORT, BOOT
  ASSOC         = UCM, USB
end_device

Step 2:
Reboot your virtual machine.

Step 3:
Once the machine is back up run SHOW DEVICES EH and you should see

Code: Select all

$ SHOW DEVICE EH

Device                  Device           Error
 Name                   Status           Count
EHA0:                   Offline              0

If you see

Code: Select all

$ SHOW DEVICE EH
%SYSTEM-W-NOSUCHDEV, no such device available

then you will need to determine the device ID of your USB controller in your virtual machine.

Step 4:
Edit SYS$MANAGER:USB$STARTUP.COM

Search for a line containing

Code: Select all

$ if (f$getdvi("oh","exists") .or. f$getdvi("uh","exists"))

and change it to

Code: Select all

$ if (f$getdvi("oh","exists") .or. f$getdvi("uh","exists") .or. f$getdvi("eh","exists"))

This will enable the startup script for UCM (USB Configuration Manager) to find the EHCI USB Controller and actually start up.

Step 5:
Reboot again

Step 6:
Check out a couple of things

Code: Select all

$ SHOW SYSTEM
OpenVMS V9.2-2  on node V922    8-MAY-2024 03:06:55.49   Uptime  0 00:02:06
  Pid    Process Name    State  Pri      I/O       CPU       Page flts  Pages
00000401 SWAPPER         HIB     16        0   0 00:00:00.00         0     17   
00000404 USB$UCM_SERVER  HIB      6      252   0 00:00:00.14       283    387   
00000405 LANACP          HIB     14       65   0 00:00:00.00       204    255   
00000407 FASTPATH_SERVER HIB     10        8   0 00:00:00.01       161    202   
00000408 IPCACP          HIB     10        8   0 00:00:00.00       138    180   
00000409 ERRFMT          HIB      9       47   0 00:00:00.02       187    232   
0000040B OPCOM           HIB      7       38   0 00:00:00.01       157    205   
0000040C AUDIT_SERVER    HIB      9       55   0 00:00:00.02       227    287   
0000040D JOB_CONTROL     HIB     10       26   0 00:00:00.00       177    243   
0000040F SECURITY_SERVER HIB     10       20   0 00:00:00.01       285    338 M 
00000412 SMHANDLER       HIB      8       51   0 00:00:00.01       270    294   
00000413 SYSTEM          CUR   0  4      140   0 00:00:00.09       568    320   
$ 

And note the second process in the list.

Code: Select all

$ SHOW DEVICE 

Device                  Device           Error   Volume          Free  Trans Mnt
 Name                   Status           Count    Label         Blocks Count Cnt
V922$DMM0:              Offline              0
V922$DKA0:              Mounted              0 V922            6023360   182   1
V922$LDM0:              Online               0
V922$LDM5454:           Mounted              0 MD24078DC54A      25584    26   1

Device                  Device           Error
 Name                   Status           Count
OPA0:                   Online               0
FTA0:                   Offline              0
MOU0:                   Online               0

Device                  Device           Error
 Name                   Status           Count
PKA0:                   Online               0
SRA0:                   Online               0
MPA0:                   Online               0
EIA0:                   Online               0
EHA0:                   Online               0
UCM0:                   Online               0
USB0:                   Online               0
SMA0:                   Online               0
WSA0:                   Offline              0
HID0:                   Online               0

EHA0 is now online, and USB0 is now present.

Step 7:
Passthrough a USB Mass Storage Device.

Step 8:
Look for the new disk device.

Code: Select all

$ SHOW DEVICE 

Device                  Device           Error   Volume          Free  Trans Mnt
 Name                   Status           Count    Label         Blocks Count Cnt
V922$DMM0:              Offline              0
V922$DKA0:              Mounted              0 V922            6023344   182   1
V922$LDM0:              Online               0
V922$LDM5454:           Mounted              0 MD24078DC54A      25584    26   1
V922$DNA0:              Online               0

Device                  Device           Error
 Name                   Status           Count
OPA0:                   Online               0
FTA0:                   Offline              0
MOU0:                   Online               0

Device                  Device           Error
 Name                   Status           Count
PKA0:                   Online               0
SRA0:                   Online               0
MPA0:                   Online               0
EIA0:                   Online               0
EHA0:                   Online               0
UCM0:                   Online               0
USB0:                   Online               0
SMA0:                   Online               0
WSA0:                   Offline              0
HID0:                   Online               0
$

Step 9:
We now have a new DNA0: device which is this USB Mass Storage device. You are now free to initialize it, or even mount it as foreign if you're lucky enough to have it formatted as a filesystem OpenVMS supports.

Code: Select all

$ INITIALIZE/STRUCTURE=5/GPT DNA0 USBSTICK
$ MOUNT DNA0 USBSTICK USBSTICK
%MOUNT-I-MOUNTED, USBSTICK mounted on _V922$DNA0:
$ 

Copy some files, play with it. It's a passed through USB storage device.

Known Issue: Even if you ask for a GPT header on the USB Disk, it isn't created so your host will insist that it is blank. Be careful.
PS: It even works on a bare metal x86 machine.

[pjacobi]

USB is officially *not* supported on any X86 VMS versions. USB was on the x86 roadmap at one time, but it has since been replaced by projects of higher priority.

As you have noticed, the existing USB drivers are available on the system disk but are missing an entry in SYS$CONFIG.DAT. There has only been very minimal testing done on the drivers. Complete testing and qualification are still TBD.

There are absolutely no plans for USB 3.0 and beyond.


Paul A. Jacobi
VMS Software