The USB configuration allows you to add, delete, or modify an existing USB device.
The 'device' field may contain one of the following items:
By default, this emulates a 3-button mouse. After a reset, it is set up to send the Report Protocol report and consists of a 4-byte report:
byte 0: 00000BBB Bits 7:3 are zero
Bit 2 is button 3
Bit 1 is button 2
Bit 0 is button 1
byte 1: XXXXXXXX 8-bit X displacement (-127 -> 127)
byte 2: YYYYYYYY 8-bit Y displacement (-127 -> 127)
byte 3: WWWWWWWW 8-bit Wheel displacement (-127 -> 127)Using the 'model:xxxx" parameter, you can set the mouse to report a different type packet. See below.
This device may be used on all Host Controller types using a speed of 'low', 'full', or 'high' (see model 'm388phy').
Note: Only one mouse/tablet device may be used at one time per emulation session.
usb_uhci: enabled=1, port1=mouse, options1="speed:low" # default report packet shown above usb_ohci: enabled=1, port1=mouse, options1="speed:full, model:m228" # 3-byte report packet, 2 button, 8-bits usb_ehci: enabled=1, port1=mouse, options1="speed:high, model:m338" # 3-byte report packet, 3 button, 8-bits usb_xhci: enabled=3, port3=mouse, options1="speed:full, model:m3312" # 3-byte report packet, 3 button, 12-bits
The model: parameter may have one of the following names: 'm228', 'm338', 'm3312', 'm3316', 'm338phy', or 'm33xDebug'.
Returns the 4-byte packet shown below.
byte 0: 00000001 Report ID (1)
byte 1: 000000BB Bits 7:2 are zero
Bit 1 is button 2
Bit 0 is button 1
byte 2: XXXXXXXX 8-bit X displacement (-128 -> 127)
byte 3: YYYYYYYY 8-bit Y displacement (-128 -> 127)Note: This model uses a Report ID, and prepends this byte ID to the Report Packet. (See byte 0 above)
Returns the 4-byte packet shown at Section 5.7.1 above. This is the default model and will be used if the model: parameter is not used.
Returns the default 4-byte packet, same as m338, but includes a HID Physical Descriptor and associated Designator entries.
Note: To make the Bochs source code simpler, this model must be used with low- and full-speed devices only.
Note: Note that some Guests, including (older) widely used commercial Guests, see an HID Report with Physical indicators (Designator Min/Max) as invalid and won't continue to use the mouse.
Returns the 5-byte packet shown below.
byte 0: 00000BBB Bits 7:3 are zero
Bit 2 is button 3
Bit 1 is button 2
Bit 0 is button 1
byte 1: XXXXXXXX 12-bit X displacement (-2048 -> 2047)
byte 2: YYYYXXXX
byte 3: YYYYYYYY 12-bit Y displacement (-2048 -> 2047)
byte 4: WWWWWWWW 8-bit Wheel displacement (-128 -> 127)Returns the 6-byte packet shown below.
byte 0: 00000BBB Bits 7:3 are zero
Bit 2 is button 3
Bit 1 is button 2
Bit 0 is button 1
byte 1: XXXXXXXX 16-bit X displacement (-32768 -> 32767)
byte 2: XXXXXXXX
byte 4: YYYYYYYY 16-bit Y displacement (-32768 -> 32767)
byte 5: YYYYYYYY
byte 6: WWWWWWWW 8-bit Wheel displacement (-128 -> 127)This report is deliberately irregular by design, so that a Guest can test its HID Report Descriptor Parser.
the button fields are not consecutive and are at arbitrary positions in the report.
the coords fields are not byte aligned or consecutively spaced.
the coords fields are of an irregular size, each a different size.
there are padding fields between entries that do not align the next field on a byte boundary.
this also uses the push/pop mechanism to test the function of your parser.
Again, this is deliberate. A correctly written parser will extract the neccessary fields no matter the irregularity.
Returns the 5-byte packet shown below.
byte 0: YYYYYYY0 10-bit Y displacement (-512 -> 511) byte 1: WWWW0YYY 8-bit Wheel displacement (-128 -> 127) byte 2: 0B00WWWW bit 6 is Button #2 (right button) byte 3: XXXXX0B0 9-bit X displacement, bit 1 is Button #1 (left button) byte 4: 0B00XXXX bit 6 is Button #3 (middle button)
Please note that this model is not for normal use. It is intentionally irregular, and its purpose is to test an HID Parser.
Note: Note that most physical USB mice will be 'low-speed' only.
Note: Note that the mouse is known to not function correctly in a Windows 2000 Guest. Clearing HANDLE_TOGGLE_CONTROL to zero in usb_common.h and rebuilding Bochs allows this guest to function more regularly, though there are still some issues. Since the USB mouse and keyboard work in all other regulary tested Guests, it must be a quirk with Win2k that needs to be investigated.
This emulates a standard keyboard. Key press and release codes are translated from the Host's keyboard to the Guest as USB Interrupt packets.
After a reset, it is set up to send the Report Protocol report and consists of a 8-byte report:
byte 0: MMMMMMMM Modifier Keys
Bit 7 = Right GUI
Bit 6 = Right Alt
Bit 5 = Right Shift
Bit 4 = Right Ctrl
Bit 3 = Left GUI
Bit 2 = Left Alt
Bit 1 = Left Shift
Bit 0 = Left Ctrl
byte 1: 00000000 Reserved
byte 2: xxxxxxxx Key Code 1
byte 3: xxxxxxxx Key Code 2
byte 4: xxxxxxxx Key Code 3
byte 5: xxxxxxxx Key Code 4
byte 6: xxxxxxxx Key Code 5
byte 7: xxxxxxxx Key Code 6The keyboard expects the following 'Output' packet when modifying the Num Lock, Caps Lock, and Scroll Lock states:
byte 0: 00000LLL Lock States
Bit 2 = Scroll Lock
Bit 1 = Caps Lock
Bit 0 = Num LockThis device may be used on all Host Controller types using a speed of 'low', 'full', or 'high'.
Note: Only one keyboard/keypad device may be used at one time per emulation session.
usb_uhci: enabled=1, port1=keyboard, options1="speed:low" usb_ohci: enabled=1, port1=keyboard, options1="speed:full" usb_ehci: enabled=1, port1=keyboard, options1="speed:high" usb_xhci: enabled=3, port3=keyboard, options1="speed:full"
Note: Please note that most physical USB keyboards will be 'low-speed' only.
This emulates a numeric keypad. Key press and release codes are translated from the Host's keyboard to the Guest as USB Interrupt packets.
Only the keys that are on a standard 104-key keyboard's keypad are returned. These keys are the USB HID Usage ID's 0x53 to 0x63 and are handled by the USB keypad and are sent to the Guest via USB Interrupt packets. (see the 'Keyboard' item above for the format of this packet).
All remaining key press and release events are handled by the underlining keyboard emulation, usually the AT/PS2 keyboard emulation. Therefore, the guest will still receive other keypress events. Only the key range noted before will be sent via the USB emulation.
This device may be used on all Host Controller types using a speed of 'low', 'full', or 'high'.
Note: Only one keyboard/keypad device may be used at one time per emulation session.
usb_uhci: enabled=1, port1=keypad, options1="speed:low" usb_ohci: enabled=1, port1=keypad, options1="speed:full" usb_ehci: enabled=1, port1=keypad, options1="speed:high" usb_xhci: enabled=3, port3=keypad, options1="speed:full"
Note: Please note that most physical USB keypads will be 'low-speed' only.
This emulates a 3-button mouse. After a reset, it is set up to send the Report Protocol report and consists of a 6-byte report:
byte 0: 00000BBB Bits 7:3 are zero
Bit 2 is button 3
Bit 1 is button 2
Bit 0 is button 1
byte 1: XXXXXXXX 8-bit X Displacement (low byte)
byte 2: XXXXXXXX 8-bit X Displacement (high byte)
byte 3: YYYYYYYY 8-bit Y Displacement (low byte)
byte 4: YYYYYYYY 8-bit Y Displacement (high byte)
byte 5: ZZZZZZZZ 8-bit Z Displacement
Note: Please note that the X and Y Displacement values are absolute, not relative values.
Note: Only one mouse/tablet device may be used at one time per emulation session.
usb_uhci: enabled=1, port1=tablet, options1="speed:low" usb_ohci: enabled=1, port1=tablet, options1="speed:full" usb_ehci: enabled=1, port1=tablet, options1="speed:high" usb_xhci: enabled=3, port3=tablet, options1="speed:full"
Note: Please note that most physical USB tablets will be 'low-speed' only.
This emulates a media device in the form of a hard-drive or CD-ROM. By default, the emulation uses the "Bulk-only" transport, also known as "Bulk/Bulk/Bulk". For high- and super-speed devices, you can specify the "UASP" protocol, also known as "USB Attached SCSI Protocol".
This device may be used on all Host Controller types using a speed of 'full', 'high', or 'super'.
Note: Any number of disk/CD-ROM devices may be used as long as there is an available HC/Hub port, and that each instance uses its own image file, i.e.: image files cannot be shared.
usb_uhci: enabled=1, port1=disk, options1="speed:full, path:hdd.img" # defaults to the BBB protocol usb_ohci: enabled=1, port1=disk, options1="speed:full, path:hdd.img" usb_ehci: enabled=1, port1=disk, options1="speed:high, path:hdd.img" usb_ehci: enabled=1, port1=disk, options1="speed:high, path:hdd.img, proto:bbb" usb_ehci: enabled=1, port1=disk, options1="speed:high, path:hdd.img, proto:uasp" usb_xhci: enabled=3, port1=disk, options3="speed:full, path:hdd.img" usb_xhci: enabled=3, port1=disk, options3="speed:high, path:hdd.img, proto:bbb" usb_xhci: enabled=3, port1=disk, options3="speed:high, path:hdd.img, proto:uasp" usb_xhci: enabled=1, port1=disk, options1="speed:super, path:hdd.img, proto:bbb" usb_xhci: enabled=1, port1=disk, options1="speed:super, path:hdd.img, proto:uasp"An image format, similar to the ATA option, can be used. Replace 'mode' below with the desired format.
usb_xhci: enabled=3, port1=disk, options3="speed:high, path:mode:hdd.img, proto:bbb" usb_xhci: enabled=3, port1=disk, options3="speed:high, path:mode:hdd.img, proto:uasp"To emuate a CD-ROM, replace 'disk' in the examples above with 'cdrom', and adjust the 'path' accordingly.
Note: Specifying 'proto:uasp' does not guarantee that the Guest will use that protocol. See a previous section for more information.
Note: Please note that this device is not allowed as a low-speed only device. Low-speed should not be specified.
This emulates a media device in the form of an external Floppy drive. By default, the emulation uses the "Control/Bulk/Interrupt" transport, aka "CBI". A compile-time option can be given to use the "Control/Bulk" transport, aka "CB".
This device may be used on all Host Controller types using a speed of 'full'.
Note: Any number of floppy devices may be used as long as there is an available HC/Hub port, and that each instance uses its own image file, i.e.: image files cannot be shared.
usb_uhci: enabled=1, port1=floppy, options1="speed:full, path:floppy.img" usb_ohci: enabled=1, port1=floppy, options1="speed:full, path:floppy.img, model:teac" usb_ehci: enabled=1, port1=floppy, options1="speed:full, path:floppy.img, model:teac" usb_xhci: enabled=1, port3=floppy, options3="speed:full, path:floppy.img"An image format, similar to the ATA option, can be used. Replace 'mode' below with the desired format.
usb_uhci: enabled=1, port1=floppy, options1="speed:full, path:mode:floppy.img"
The 'model:teac' option can be used to emulate that specific model, else a default
model will be used. If a guest does not see the attached floppy, try specifying the 'teac'
model.The 'nofail' option can be used to disable the INQUIRY quirk. This quirk is enabled by default.
usb_uhci: enabled=1, port1=floppy, options1="speed:full, path:floppy.img, nofail"To be consistant with real hardware, we need to fail with a STALL twice for any command after the first INQUIRY command except for the INQUIRY command itself and the REQUEST SENSE command. (I don't know why, and will document further when I know more.)
Bochs allows more than one USB floppy devices to be used at one time, one on each available port. Each will be displayed in the status bar, the first as USB-FD1, the second as USB-FD2, etc.
Note: Please note that this device is a full-speed only device. No other speed should be specified.
This emulates a simple USB printer. All data sent to the printer will be written to a specified file on the Host.
This device may be used on all Host Controller types using a speed of 'full'.
Note: Any number of printer devices may be used as long as there is an available HC/Hub port, and that each instance uses its own target file, i.e.: target files cannot be shared.
usb_uhci: enabled=1, port1=printer, options1="speed:full, file:printdata.bin" usb_ohci: enabled=1, port1=printer, options1="speed:full, file:printdata.bin" usb_ehci: enabled=1, port1=printer, options1="speed:full, file:printdata.bin" usb_xhci: enabled=1, port3=printer, options3="speed:full, file:printdata.bin"
Note: Please note that this device is a full-speed only device. No other speed should be specified.
This emulates a full-speed 4-port external hub. The number of ports can be changed, with a range of 2 to 8.
This device may be used on all Host Controller types using a speed of 'full'.
Note: Any number of hub devices may be used as long as there is an available HC/Hub port.
usb_uhci: enabled=1, port1=hub, options1="speed:full" usb_ohci: enabled=1, port1=hub, options1="speed:full, ports:4" usb_ehci: enabled=1, port1=hub, options1="speed:full, ports:6" usb_xhci: enabled=1, port1=hub, options1="speed:full, ports:8"At startup, no device is attached to this hub. However, after start up, using the runtime interface, a device can be attached to any or all of the ports.
Any device attached to this hub (via the runtime interface), must be the same as or less than the hub's current speed (which is currently only full-speed). Any device plugged into a hub, no matter its max speed, can only function at or below the speed of the hub it is attached to.
Note: Please note that this device is a full-speed only device. No other speed should be specified.
All devices may use the 'pcap' option to send all data to a Packet Capture formatted file.
usb_uhci: enabled=1, port1=hub, options1="speed:full, pcap:outfile.pcap"This file is formatted to be used with Linux' usbmon and utilities such as Wire Shark.
Note: Please note that this option will not capture any data that would normally flow through an external hub, so if you use the 'pcap' option for a hub, as with the example above, only the hub's data is captured, not the device(s) attached to it.
During emulation, using the runtime configuration, you can signal an over-current event on any device using the 'over-current' checkbox (GUI) or text configuration option. This will signal an over-current event on the Host Controller for that port.
Over-current is considered undefined on the UHCI, though Intel 430TX and later controllers may have implemented over-current via two previously unused bits.
All devices allow the 'debug' option to be used. This turns on the BX_DEBUG() logging for that device.
usb_uhci: enabled=1, port1=hub, options1="speed:full, debug"
You can wrap options in double-quotes in your bochsrc file. However, the runtime config interface has problems when double-quotes are used. Therefore, don't use them in the runtime configuration interface.
When adjusting an xHCI port within the runtime configuration, you must remove a device from a companion port before adding to the other associated port. For example, if port 1 and port 3 are paired and you currently have something on port 3, you must remove it from port 3, continue the emulation, then come back and add something to port 1. You cannot remove something from port 3 and add something to port 1 at the same time.
The USB emulation has been tested on numerous Guests. You can find these results at here.