PVE/QemuServer/USB.pm

   1 package PVE::QemuServer::USB;
   2
   3 use strict;
   4 use warnings;
   5 use PVE::QemuServer::PCI qw(print_pci_addr);
   6 use PVE::QemuServer::Machine;
   7 use PVE::QemuServer::Helpers qw(min_version windows_version);
   8 use PVE::JSONSchema;
   9 use PVE::Mapping::USB;
  10 use base 'Exporter';
  11
  12 our @EXPORT_OK = qw(
  13 parse_usb_device
  14 get_usb_controllers
  15 get_usb_devices
  16 );
  17
  18 my $OLD_MAX_USB = 5;
  19 our $MAX_USB_DEVICES = 14;
  20
  21
  22 my $USB_ID_RE = qr/(0x)?([0-9A-Fa-f]{4}):(0x)?([0-9A-Fa-f]{4})/;
  23 my $USB_PATH_RE = qr/(\d+)\-(\d+(\.\d+)*)/;
  24
  25 my $usb_fmt = {
  26     host => {
  27         default_key => 1,
  28         optional => 1,
  29         type => 'string',
  30         pattern => qr/(?:(?:$USB_ID_RE)|(?:$USB_PATH_RE)|[Ss][Pp][Ii][Cc][Ee])/,
  31         format_description => 'HOSTUSBDEVICE|spice',
  32         description => <<EODESCR,
  33 The Host USB device or port or the value 'spice'. HOSTUSBDEVICE syntax is:
  34
  35  'bus-port(.port)*' (decimal numbers) or
  36  'vendor_id:product_id' (hexadeciaml numbers) or
  37  'spice'
  38
  39 You can use the 'lsusb -t' command to list existing usb devices.
  40
  41 NOTE: This option allows direct access to host hardware. So it is no longer possible to migrate such
  42 machines - use with special care.
  43
  44 The value 'spice' can be used to add a usb redirection devices for spice.
  45
  46 Either this or the 'mapping' key must be set.
  47 EODESCR
  48     },
  49     mapping => {
  50         optional => 1,
  51         type => 'string',
  52         format_description => 'mapping-id',
  53         format => 'pve-configid',
  54         description => "The ID of a cluster wide mapping. Either this or the default-key 'host'"
  55             ." must be set.",
  56     },
  57     usb3 => {
  58         optional => 1,
  59         type => 'boolean',
  60         description => "Specifies whether if given host option is a USB3 device or port."
  61             ." For modern guests (machine version >= 7.1 and ostype l26 and windows > 7), this flag"
  62             ." is irrelevant (all devices are plugged into a xhci controller).",
  63         default => 0,
  64     },
  65 };
  66
  67 PVE::JSONSchema::register_format('pve-qm-usb', $usb_fmt);
  68
  69 our $usbdesc = {
  70     optional => 1,
  71     type => 'string', format => $usb_fmt,
  72     description => "Configure an USB device (n is 0 to 4, for machine version >= 7.1 and ostype"
  73         ." l26 or windows > 7, n can be up to 14).",
  74 };
  75 PVE::JSONSchema::register_standard_option("pve-qm-usb", $usbdesc);
  76
  77 sub parse_usb_device {
  78     my ($value, $mapping) = @_;
  79
  80     return if $value && $mapping; # not a valid configuration
  81
  82     my $res = {};
  83     if (defined($value)) {
  84         if ($value =~ m/^$USB_ID_RE$/) {
  85             $res->{vendorid} = $2;
  86             $res->{productid} = $4;
  87         } elsif ($value =~ m/^$USB_PATH_RE$/) {
  88             $res->{hostbus} = $1;
  89             $res->{hostport} = $2;
  90         } elsif ($value =~ m/^spice$/i) {
  91             $res->{spice} = 1;
  92         }
  93     } elsif (defined($mapping)) {
  94         my $devices = PVE::Mapping::USB::find_on_current_node($mapping);
  95         die "USB device mapping not found for '$mapping'\n" if !$devices || !scalar($devices->@*);
  96         die "More than one USB mapping per host not supported\n" if scalar($devices->@*) > 1;
  97         eval {
  98             PVE::Mapping::USB::assert_valid($mapping, $devices->[0]);
  99         };
 100         if (my $err = $@) {
 101             die "USB Mapping invalid (hardware probably changed): $err\n";
 102         }
 103         my $device = $devices->[0];
 104
 105         if ($device->{path}) {
 106             $res = parse_usb_device($device->{path});
 107         } else {
 108             $res = parse_usb_device($device->{id});
 109         }
 110     }
 111
 112     return $res;
 113 }
 114
 115 my sub assert_usb_index_is_useable {
 116     my ($index, $use_qemu_xhci) = @_;
 117
 118     die "using usb$index is only possible with machine type >= 7.1 and ostype l26 or windows > 7\n"
 119         if $index >= $OLD_MAX_USB && !$use_qemu_xhci;
 120
 121     return undef;
 122 }
 123
 124 sub get_usb_controllers {
 125     my ($conf, $bridges, $arch, $machine, $machine_version) = @_;
 126
 127     my $devices = [];
 128     my $pciaddr = "";
 129
 130     my $ostype = $conf->{ostype};
 131
 132     my $use_qemu_xhci = min_version($machine_version, 7, 1)
 133         && defined($ostype) && ($ostype eq 'l26' || windows_version($ostype) > 7);
 134     my $is_q35 = PVE::QemuServer::Machine::machine_type_is_q35($conf);
 135
 136     if ($arch eq 'aarch64') {
 137         $pciaddr = print_pci_addr('ehci', $bridges, $arch, $machine);
 138         push @$devices, '-device', "usb-ehci,id=ehci$pciaddr";
 139     } elsif (!$is_q35) {
 140         $pciaddr = print_pci_addr("piix3", $bridges, $arch, $machine);
 141         push @$devices, '-device', "piix3-usb-uhci,id=uhci$pciaddr.0x2";
 142     }
 143
 144     my ($use_usb2, $use_usb3) = 0;
 145     my $any_usb = 0;
 146     for (my $i = 0; $i < $MAX_USB_DEVICES; $i++)  {
 147         next if !$conf->{"usb$i"};
 148         assert_usb_index_is_useable($i, $use_qemu_xhci);
 149         my $d = eval { PVE::JSONSchema::parse_property_string($usb_fmt, $conf->{"usb$i"}) } or next;
 150         $any_usb = 1;
 151         $use_usb3 = 1 if $d->{usb3};
 152         $use_usb2 = 1 if !$d->{usb3};
 153     }
 154
 155     if (!$use_qemu_xhci && !$is_q35 && $use_usb2 && $arch ne 'aarch64') {
 156         # include usb device config if still on x86 before-xhci machines and if USB 3 is not used
 157         push @$devices, '-readconfig', '/usr/share/qemu-server/pve-usb.cfg';
 158     }
 159
 160     $pciaddr = print_pci_addr("xhci", $bridges, $arch, $machine);
 161     if ($use_qemu_xhci && $any_usb) {
 162         push @$devices, '-device', print_qemu_xhci_controller($pciaddr);
 163     } elsif ($use_usb3) {
 164         push @$devices, '-device', "nec-usb-xhci,id=xhci$pciaddr";
 165     }
 166
 167     return @$devices;
 168 }
 169
 170 sub get_usb_devices {
 171     my ($conf, $features, $bootorder, $machine_version) = @_;
 172
 173     my $devices = [];
 174
 175     my $ostype = $conf->{ostype};
 176     my $use_qemu_xhci = min_version($machine_version, 7, 1)
 177         && defined($ostype) && ($ostype eq 'l26' || windows_version($ostype) > 7);
 178
 179     for (my $i = 0; $i < $MAX_USB_DEVICES; $i++)  {
 180         my $devname = "usb$i";
 181         next if !$conf->{$devname};
 182         assert_usb_index_is_useable($i, $use_qemu_xhci);
 183         my $d = eval { PVE::JSONSchema::parse_property_string($usb_fmt, $conf->{$devname}) };
 184         next if !$d;
 185
 186         my $port = $use_qemu_xhci ? $i + 1 : undef;
 187
 188         if ($d->{host} && $d->{host} =~ m/^spice$/) {
 189             # usb redir support for spice
 190             my $bus = 'ehci';
 191             $bus = 'xhci' if ($d->{usb3} && $features->{spice_usb3}) || $use_qemu_xhci;
 192
 193             push @$devices, '-chardev', "spicevmc,id=usbredirchardev$i,name=usbredir";
 194             push @$devices, '-device', print_spice_usbdevice($i, $bus, $port);
 195
 196             warn "warning: spice usb port set as bootdevice, ignoring\n" if $bootorder->{$devname};
 197         } else {
 198             push @$devices, '-device', print_usbdevice_full($conf, $devname, $d, $bootorder, $port);
 199         }
 200     }
 201
 202     return @$devices;
 203 }
 204
 205 sub print_qemu_xhci_controller {
 206     my ($pciaddr) = @_;
 207     return "qemu-xhci,p2=15,p3=15,id=xhci$pciaddr";
 208 }
 209
 210 sub print_spice_usbdevice {
 211     my ($index, $bus, $port) = @_;
 212     my $device = "usb-redir,chardev=usbredirchardev$index,id=usbredirdev$index,bus=$bus.0";
 213     if (defined($port)) {
 214         $device .= ",port=$port";
 215     }
 216     return $device;
 217 }
 218
 219 sub print_usbdevice_full {
 220     my ($conf, $deviceid, $device, $bootorder, $port) = @_;
 221
 222     return if !$device;
 223     my $usbdevice = "usb-host";
 224
 225     # if it is a usb3 device or with newer qemu, attach it to the xhci controller, else omit the bus option
 226     if ($device->{usb3} || defined($port)) {
 227         $usbdevice .= ",bus=xhci.0";
 228         $usbdevice .= ",port=$port" if defined($port);
 229     }
 230
 231     my $parsed = parse_usb_device($device->{host}, $device->{mapping});
 232
 233     if (defined($parsed->{vendorid}) && defined($parsed->{productid})) {
 234         $usbdevice .= ",vendorid=0x$parsed->{vendorid},productid=0x$parsed->{productid}";
 235     } elsif (defined($parsed->{hostbus}) && defined($parsed->{hostport})) {
 236         $usbdevice .= ",hostbus=$parsed->{hostbus},hostport=$parsed->{hostport}";
 237     } else {
 238         die "no usb id or path given\n";
 239     }
 240
 241     $usbdevice .= ",id=$deviceid";
 242     $usbdevice .= ",bootindex=$bootorder->{$deviceid}" if $bootorder->{$deviceid};
 243     return $usbdevice;
 244 }
 245
 246 1;