Merge remote-tracking branch 'remotes/bonzini/tags/for-upstream' into staging

[mirror_qemu.git] / docs / multiseat.txt

multiseat howto (with some multihead coverage)
==============================================

host devices
------------

First you must compile qemu with a user interface supporting
multihead/multiseat and input event routing.  Right now this
list includes sdl2, gtk (both 2+3) and vnc:

  ./configure --enable-sdl

or

  ./configure --enable-gtk


Next put together the qemu command line (sdk/gtk):

qemu	-accel kvm -usb $memory $disk $whatever \
	-display [ sdl | gtk ] \
	-vga std \
	-device usb-tablet

That is it for the first seat, which will use the standard vga, the
standard ps/2 keyboard (implicitly there) and the usb-tablet.  Now the
additional switches for the second seat:

	-device pci-bridge,addr=12.0,chassis_nr=2,id=head.2 \
	-device secondary-vga,bus=head.2,addr=02.0,id=video.2 \
	-device nec-usb-xhci,bus=head.2,addr=0f.0,id=usb.2 \
	-device usb-kbd,bus=usb.2.0,port=1,display=video.2 \
	-device usb-tablet,bus=usb.2.0,port=2,display=video.2

This places a pci bridge in slot 12, connects a display adapter and
xhci (usb) controller to the bridge.  Then it adds a usb keyboard and
usb mouse, both connected to the xhci and linked to the display.

The "display=video2" sets up the input routing.  Any input coming from
the window which belongs to the video.2 display adapter will be routed
to these input devices.

Starting with qemu 2.4 and linux kernel 4.1 you can also use virtio
for the input devices, using this ...

	-device pci-bridge,addr=12.0,chassis_nr=2,id=head.2 \
	-device secondary-vga,bus=head.2,addr=02.0,id=video.2 \
	-device virtio-keyboard-pci,bus=head.2,addr=03.0,display=video.2 \
	-device virtio-tablet-pci,bus=head.2,addr=03.0,display=video.2

... instead of xhci and usb hid devices.

host ui
-------

The sdl2 ui will start up with two windows, one for each display
device.  The gtk ui will start with a single window and each display
in a separate tab.  You can either simply switch tabs to switch heads,
or use the "View / Detach tab" menu item to move one of the displays
to its own window so you can see both display devices side-by-side.

For vnc some additional configuration on the command line is needed.
We'll create two vnc server instances, and bind the second one to the
second seat, similar to input devices:

	-display vnc=:1,id=primary \
	-display vnc=:2,id=secondary,display=video.2

Connecting to vnc display :1 gives you access to the first seat, and
likewise connecting to vnc display :2 shows the second seat.

Note on spice: Spice handles multihead just fine.  But it can't do
multiseat.  For tablet events the event source is sent to the spice
agent.  But qemu can't figure it, so it can't do input routing.
Fixing this needs a new or extended input interface between
libspice-server and qemu.  For keyboard events it is even worse:  The
event source isn't included in the spice protocol, so the wire
protocol must be extended to support this.


guest side
----------

You need a pretty recent linux guest.  systemd with loginctl.  kernel
3.14+ with CONFIG_DRM_BOCHS enabled.  Fedora 20 will do.  Must be
fully updated for the new kernel though, i.e. the live iso doesn't cut
it.

Now we'll have to configure the guest.  Boot and login.  "lspci -vt"
should list the pci bridge with the display adapter and usb controller:

    [root@fedora ~]# lspci -vt
    -[0000:00]-+-00.0  Intel Corporation 440FX - 82441FX PMC [Natoma]
               [ ... ]
               \-12.0-[01]--+-02.0  Device 1234:1111
                            \-0f.0  NEC Corporation USB 3.0 Host Controller

Good.  Now lets tell the system that the pci bridge and all devices
below it belong to a separate seat by dropping a file into
/etc/udev/rules.d:

    [root@fedora ~]# cat /etc/udev/rules.d/70-qemu-autoseat.rules
    SUBSYSTEMS=="pci", DEVPATH=="*/0000:00:12.0", TAG+="seat", ENV{ID_AUTOSEAT}="1"

Reboot.  System should come up with two seats.  With loginctl you can
check the configuration:

    [root@fedora ~]# loginctl list-seats
    SEAT
    seat0
    seat-pci-pci-0000_00_12_0

    2 seats listed.

You can use "loginctl seat-status seat-pci-pci-0000_00_12_0" to list
the devices attached to the seat.

Background info is here:
  http://www.freedesktop.org/wiki/Software/systemd/multiseat/


guest side with pci-bridge-seat
-------------------------------

Qemu version 2.4 and newer has a new pci-bridge-seat device which
can be used instead of pci-bridge.  Just swap the device name in the
qemu command line above.  The only difference between the two devices
is the pci id.  We can match the pci id instead of the device path
with a nice generic rule now, which simplifies the guest
configuration:

    [root@fedora ~]# cat /etc/udev/rules.d/70-qemu-pci-bridge-seat.rules
    SUBSYSTEM=="pci", ATTR{vendor}=="0x1b36", ATTR{device}=="0x000a", \
            TAG+="seat", ENV{ID_AUTOSEAT}="1"

Patch with this rule has been submitted to upstream udev/systemd, was
accepted and should be included in the next systemd release (222).
So, if your guest has this or a newer version, multiseat will work just
fine without any manual guest configuration.

Enjoy!

--
Gerd Hoffmann <kraxel@redhat.com>