1=head1 NAME 2 3xl.cfg - xl domain configuration file syntax 4 5=head1 SYNOPSIS 6 7 /etc/xen/xldomain 8 9=head1 DESCRIPTION 10 11Creating a VM (a domain in Xen terminology, sometimes called a guest) 12with xl requires the provision of a domain configuration file. Typically, 13these live in F</etc/xen/DOMAIN.cfg>, where DOMAIN is the name of the 14domain. 15 16=head1 SYNTAX 17 18A domain configuration file consists of a series of options, specified by 19using C<KEY=VALUE> pairs. 20 21Some C<KEY>s are mandatory, some are general options which apply to 22any guest type, while others relate only to specific guest types 23(e.g. PV or HVM guests). 24 25A C<VALUE> can be one of: 26 27=over 4 28 29=item B<"STRING"> 30 31A string, surrounded by either single or double quotes. But if the 32STRING is part of a SPEC_STRING, the quotes should be omitted. 33 34=item B<NUMBER> 35 36A number, in either decimal, octal (using a C<0> prefix) or 37hexadecimal (using a C<0x> prefix) format. 38 39=item B<BOOLEAN> 40 41A C<NUMBER> interpreted as C<False> (C<0>) or C<True> (any other 42value). 43 44=item B<[ VALUE, VALUE, ... ]> 45 46A list of C<VALUE>s of the above types. Lists can be heterogeneous and 47nested. 48 49=back 50 51The semantics of each C<KEY> defines which type of C<VALUE> is required. 52 53Pairs may be separated either by a newline or a semicolon. Both 54of the following are valid: 55 56 name="h0" 57 type="hvm" 58 59 name="h0"; type="hvm" 60 61=head1 OPTIONS 62 63=head2 Mandatory Configuration Items 64 65The following key is mandatory for any guest type. 66 67=over 4 68 69=item B<name="NAME"> 70 71Specifies the name of the domain. Names of domains existing on a 72single host must be unique. 73 74=back 75 76=head2 Selecting Guest Type 77 78=over 4 79 80=item B<type="pv"> 81 82Specifies that this is to be a PV domain, suitable for hosting Xen-aware 83guest operating systems. This is the default on x86. 84 85=item B<type="pvh"> 86 87Specifies that this is to be an PVH domain. That is a lightweight HVM-like 88guest without a device model and without many of the emulated devices 89available to HVM guests. Note that this mode requires a PVH aware kernel on 90x86. This is the default on Arm. 91 92=item B<type="hvm"> 93 94Specifies that this is to be an HVM domain. That is, a fully virtualised 95computer with emulated BIOS, disk and network peripherals, etc. 96 97=back 98 99=head3 Deprecated guest type selection 100 101Note that the builder option is being deprecated in favor of the type 102option. 103 104=over 4 105 106=item B<builder="generic"> 107 108Specifies that this is to be a PV domain, suitable for hosting Xen-aware guest 109operating systems. This is the default. 110 111=item B<builder="hvm"> 112 113Specifies that this is to be an HVM domain. That is, a fully 114virtualised computer with emulated BIOS, disk and network peripherals, 115etc. 116 117=back 118 119=head2 General Options 120 121The following options apply to guests of any type. 122 123=head3 CPU Allocation 124 125=over 4 126 127=item B<pool="CPUPOOLNAME"> 128 129Put the guest's vCPUs into the named CPU pool. 130 131=item B<vcpus=N> 132 133Start the guest with N vCPUs initially online. 134 135=item B<maxvcpus=M> 136 137Allow the guest to bring up a maximum of M vCPUs. When starting the guest, if 138B<vcpus=N> is less than B<maxvcpus=M> then the first B<N> vCPUs will be 139created online and the remainder will be created offline. 140 141=item B<cpus="CPULIST"> 142 143List of host CPUs the guest is allowed to use. Default is no pinning at 144all (more on this below). A C<CPULIST> may be specified as follows: 145 146=over 4 147 148=item "all" 149 150To allow all the vCPUs of the guest to run on all the CPUs on the host. 151 152=item "0-3,5,^1" 153 154To allow all the vCPUs of the guest to run on CPUs 0,2,3,5. It is possible to 155combine this with "all", meaning "all,^7" results in all the vCPUs 156of the guest being allowed to run on all the CPUs of the host except CPU 7. 157 158=item "nodes:0-3,^node:2" 159 160To allow all the vCPUs of the guest to run on the CPUs from NUMA nodes 1610,1,3 of the host. So, if CPUs 0-3 belong to node 0, CPUs 4-7 belong 162to node 1, CPUs 8-11 to node 2 and CPUs 12-15 to node 3, the above would mean 163all the vCPUs of the guest would be allowed to run on CPUs 0-7,12-15. 164 165Combining this notation with the one above is possible. For instance, 166"1,node:1,^6", means all the vCPUs of the guest will run on CPU 1 and 167on all the CPUs of NUMA node 1, but not on CPU 6. Following the same 168example as above, that would be CPUs 1,4,5,7. 169 170Combining this with "all" is also possible, meaning "all,^node:1" 171results in all the vCPUs of the guest running on all the CPUs on the 172host, except for the CPUs belonging to the host NUMA node 1. 173 174=item ["2", "3-8,^5"] 175 176To ask for specific vCPU mapping. That means (in this example), vCPU 0 177of the guest will run on CPU 2 of the host and vCPU 1 of the guest will 178run on CPUs 3,4,6,7,8 of the host (excluding CPU 5). 179 180More complex notation can be also used, exactly as described above. So 181"all,^5-8", or just "all", or "node:0,node:2,^9-11,18-20" are all legal, 182for each element of the list. 183 184=back 185 186If this option is not specified, no vCPU to CPU pinning is established, 187and the vCPUs of the guest can run on all the CPUs of the host. If this 188option is specified, the intersection of the vCPU pinning mask, provided 189here, and the soft affinity mask, if provided via B<cpus_soft=>, 190is utilized to compute the domain node-affinity for driving memory 191allocations. 192 193=item B<cpus_soft="CPULIST"> 194 195Exactly as B<cpus=>, but specifies soft affinity, rather than pinning 196(hard affinity). When using the credit scheduler, this means what CPUs 197the vCPUs of the domain prefer. 198 199A C<CPULIST> is specified exactly as for B<cpus=>, detailed earlier in the 200manual. 201 202If this option is not specified, the vCPUs of the guest will not have 203any preference regarding host CPUs. If this option is specified, 204the intersection of the soft affinity mask, provided here, and the vCPU 205pinning, if provided via B<cpus=>, is utilized to compute the 206domain node-affinity for driving memory allocations. 207 208If this option is not specified (and B<cpus=> is not specified either), 209libxl automatically tries to place the guest on the least possible 210number of nodes. A heuristic approach is used for choosing the best 211node (or set of nodes), with the goal of maximizing performance for 212the guest and, at the same time, achieving efficient utilization of 213host CPUs and memory. In that case, the soft affinity of all the vCPUs 214of the domain will be set to host CPUs belonging to NUMA nodes 215chosen during placement. 216 217For more details, see L<xl-numa-placement(7)>. 218 219=back 220 221=head3 CPU Scheduling 222 223=over 4 224 225=item B<cpu_weight=WEIGHT> 226 227A domain with a weight of 512 will get twice as much CPU as a domain 228with a weight of 256 on a contended host. 229Legal weights range from 1 to 65535 and the default is 256. 230Honoured by the credit and credit2 schedulers. 231 232=item B<cap=N> 233 234The cap optionally fixes the maximum amount of CPU a domain will be 235able to consume, even if the host system has idle CPU cycles. 236The cap is expressed as a percentage of one physical CPU: 237100 is 1 physical CPU, 50 is half a CPU, 400 is 4 CPUs, etc. 238The default, 0, means there is no cap. 239Honoured by the credit and credit2 schedulers. 240 241B<NOTE>: Many systems have features that will scale down the computing 242power of a CPU that is not 100% utilized. This can be done in the 243operating system, but can also sometimes be done below the operating system, 244in the BIOS. If you set a cap such that individual cores are running 245at less than 100%, this may have an impact on the performance of your 246workload over and above the impact of the cap. For example, if your 247processor runs at 2GHz, and you cap a VM at 50%, the power management 248system may also reduce the clock speed to 1GHz; the effect will be 249that your VM gets 25% of the available power (50% of 1GHz) rather than 25050% (50% of 2GHz). If you are not getting the performance you expect, 251look at performance and CPU frequency options in your operating system and 252your BIOS. 253 254=back 255 256=head3 Memory Allocation 257 258=over 4 259 260=item B<memory=MBYTES> 261 262Start the guest with MBYTES megabytes of RAM. 263 264=item B<maxmem=MBYTES> 265 266Specifies the maximum amount of memory a guest can ever see. 267The value of B<maxmem=> must be equal to or greater than that of B<memory=>. 268 269In combination with B<memory=> it will start the guest "pre-ballooned", 270if the values of B<memory=> and B<maxmem=> differ. 271A "pre-ballooned" HVM guest needs a balloon driver, without a balloon driver 272it will crash. 273 274B<NOTE>: Because of the way ballooning works, the guest has to allocate 275memory to keep track of maxmem pages, regardless of how much memory it 276actually has available to it. A guest with maxmem=262144 and 277memory=8096 will report significantly less memory available for use 278than a system with maxmem=8096 memory=8096 due to the memory overhead 279of having to track the unused pages. 280 281=back 282 283=head3 Guest Virtual NUMA Configuration 284 285=over 4 286 287=item B<vnuma=[ VNODE_SPEC, VNODE_SPEC, ... ]> 288 289Specify virtual NUMA configuration with positional arguments. The 290nth B<VNODE_SPEC> in the list specifies the configuration of the nth 291virtual node. 292 293Note that virtual NUMA is not supported for PV guests yet, because 294there is an issue with the CPUID instruction handling that affects PV virtual 295NUMA. Furthermore, guests with virtual NUMA cannot be saved or migrated 296because the migration stream does not preserve node information. 297 298Each B<VNODE_SPEC> is a list, which has a form of 299"[VNODE_CONFIG_OPTION, VNODE_CONFIG_OPTION, ... ]" (without the quotes). 300 301For example, vnuma = [ ["pnode=0","size=512","vcpus=0-4","vdistances=10,20"] ] 302means vnode 0 is mapped to pnode 0, has 512MB ram, has vcpus 0 to 4, the 303distance to itself is 10 and the distance to vnode 1 is 20. 304 305Each B<VNODE_CONFIG_OPTION> is a quoted C<KEY=VALUE> pair. Supported 306B<VNODE_CONFIG_OPTION>s are (they are all mandatory at the moment): 307 308=over 4 309 310=item B<pnode=NUMBER> 311 312Specifies which physical node this virtual node maps to. 313 314=item B<size=MBYTES> 315 316Specifies the size of this virtual node. The sum of memory sizes of all 317vnodes will become B<maxmem=>. If B<maxmem=> is specified separately, 318a check is performed to make sure the sum of all vnode memory matches 319B<maxmem=>. 320 321=item B<vcpus="CPUSTRING"> 322 323Specifies which vCPUs belong to this node. B<"CPUSTRING"> is a string of numerical 324values separated by a comma. You can specify a range and/or a single CPU. 325An example would be "vcpus=0-5,8", which means you specified vCPU 0 to vCPU 5, 326and vCPU 8. 327 328=item B<vdistances=NUMBER, NUMBER, ... > 329 330Specifies the virtual distance from this node to all nodes (including 331itself) with positional arguments. For example, "vdistance=10,20" 332for vnode 0 means the distance from vnode 0 to vnode 0 is 10, from 333vnode 0 to vnode 1 is 20. The number of arguments supplied must match 334the total number of vnodes. 335 336Normally you can use the values from B<xl info -n> or B<numactl 337--hardware> to fill the vdistances list. 338 339=back 340 341=back 342 343=head3 Event Actions 344 345=over 4 346 347=item B<on_poweroff="ACTION"> 348 349Specifies what should be done with the domain if it shuts itself down. 350The B<ACTION>s are: 351 352=over 4 353 354=item B<destroy> 355 356destroy the domain 357 358=item B<restart> 359 360destroy the domain and immediately create a new domain with the same 361configuration 362 363=item B<rename-restart> 364 365rename the domain which terminated, and then immediately create a new 366domain with the same configuration as the original 367 368=item B<preserve> 369 370keep the domain. It can be examined, and later destroyed with B<xl destroy>. 371 372=item B<coredump-destroy> 373 374write a "coredump" of the domain to F<@XEN_DUMP_DIR@/NAME> and then 375destroy the domain. 376 377=item B<coredump-restart> 378 379write a "coredump" of the domain to F<@XEN_DUMP_DIR@/NAME> and then 380restart the domain. 381 382=item B<soft-reset> 383 384Reset all Xen specific interfaces for the Xen-aware HVM domain allowing 385it to reestablish these interfaces and continue executing the domain. PV 386and non-Xen-aware HVM guests are not supported. 387 388=back 389 390The default for B<on_poweroff> is B<destroy>. 391 392=item B<on_reboot="ACTION"> 393 394Action to take if the domain shuts down with a reason code requesting 395a reboot. Default is B<restart>. 396 397=item B<on_watchdog="ACTION"> 398 399Action to take if the domain shuts down due to a Xen watchdog timeout. 400Default is B<destroy>. 401 402=item B<on_crash="ACTION"> 403 404Action to take if the domain crashes. Default is B<destroy>. 405 406=item B<on_soft_reset="ACTION"> 407 408Action to take if the domain performs a 'soft reset' (e.g. does B<kexec>). 409Default is B<soft-reset>. 410 411=back 412 413=head3 Direct Kernel Boot 414 415Direct kernel boot allows booting guests with a kernel and an initrd 416stored on a filesystem available to the host physical machine, allowing 417command line arguments to be passed directly. PV guest direct kernel boot is 418supported. HVM guest direct kernel boot is supported with some limitations 419(it's supported when using B<qemu-xen> and the default BIOS 'seabios', 420but not supported in case of using B<stubdom-dm> and the old 'rombios'.) 421 422=over 4 423 424=item B<kernel="PATHNAME"> 425 426Load the specified file as the kernel image. 427 428=item B<ramdisk="PATHNAME"> 429 430Load the specified file as the ramdisk. 431 432=item B<cmdline="STRING"> 433 434Append B<STRING> to the kernel command line. (Note: the meaning of 435this is guest specific). It can replace B<root="STRING"> 436along with B<extra="STRING"> and is preferred. When B<cmdline="STRING"> is set, 437B<root="STRING"> and B<extra="STRING"> will be ignored. 438 439=item B<root="STRING"> 440 441Append B<root=STRING> to the kernel command line (Note: the meaning of this 442is guest specific). 443 444=item B<extra="STRING"> 445 446Append B<STRING> to the kernel command line. (Note: the meaning of this 447is guest specific). 448 449=back 450 451=head3 Non direct Kernel Boot 452 453Non direct kernel boot allows booting guests with a firmware. This can be 454used by all types of guests, although the selection of options is different 455depending on the guest type. 456 457This option provides the flexibly of letting the guest decide which kernel 458they want to boot, while preventing having to poke at the guest file 459system form the toolstack domain. 460 461=head4 PV guest options 462 463=over 4 464 465=item B<firmware="pvgrub32|pvgrub64"> 466 467Boots a guest using a para-virtualized version of grub that runs inside 468of the guest. The bitness of the guest needs to be know, so that the right 469version of pvgrub can be selected. 470 471Note that xl expects to find the pvgrub32.bin and pvgrub64.bin binaries in 472F<@XENFIRMWAREDIR@>. 473 474=back 475 476=head4 HVM guest options 477 478=over 4 479 480=item B<firmware="bios"> 481 482Boot the guest using the default BIOS firmware, which depends on the 483chosen device model. 484 485=item B<firmware="uefi"> 486 487Boot the guest using the default UEFI firmware, currently OVMF. 488 489=item B<firmware="seabios"> 490 491Boot the guest using the SeaBIOS BIOS firmware. 492 493=item B<firmware="rombios"> 494 495Boot the guest using the ROMBIOS BIOS firmware. 496 497=item B<firmware="ovmf"> 498 499Boot the guest using the OVMF UEFI firmware. 500 501=item B<firmware="PATH"> 502 503Load the specified file as firmware for the guest. 504 505=back 506 507=head4 PVH guest options 508 509Currently there's no firmware available for PVH guests, they should be 510booted using the B<Direct Kernel Boot> method or the B<bootloader> option. 511 512=over 4 513 514=item B<pvshim=BOOLEAN> 515 516Whether to boot this guest as a PV guest within a PVH container. 517Ie, the guest will experience a PV environment, 518but 519processor hardware extensions are used to 520separate its address space 521to mitigate the Meltdown attack (CVE-2017-5754). 522 523Default is false. 524 525=item B<pvshim_path="PATH"> 526 527The PV shim is a specially-built firmware-like executable 528constructed from the hypervisor source tree. 529This option specifies to use a non-default shim. 530Ignored if pvhsim is false. 531 532=item B<pvshim_cmdline="STRING"> 533 534Command line for the shim. 535Default is "pv-shim console=xen,pv". 536Ignored if pvhsim is false. 537 538=item B<pvshim_extra="STRING"> 539 540Extra command line arguments for the shim. 541If supplied, appended to the value for pvshim_cmdline. 542Default is empty. 543Ignored if pvhsim is false. 544 545=back 546 547=head3 Other Options 548 549=over 4 550 551=item B<uuid="UUID"> 552 553Specifies the UUID of the domain. If not specified, a fresh unique 554UUID will be generated. 555 556=item B<seclabel="LABEL"> 557 558Assign an XSM security label to this domain. 559 560=item B<init_seclabel="LABEL"> 561 562Specify an XSM security label used for this domain temporarily during 563its build. The domain's XSM label will be changed to the execution 564seclabel (specified by B<seclabel>) once the build is complete, prior to 565unpausing the domain. With a properly constructed security policy (such 566as nomigrate_t in the example policy), this can be used to build a 567domain whose memory is not accessible to the toolstack domain. 568 569=item B<max_grant_frames=NUMBER> 570 571Specify the maximum number of grant frames the domain is allowed to have. 572This value controls how many pages the domain is able to grant access to for 573other domains, needed e.g. for the operation of paravirtualized devices. 574The default is settable via L<xl.conf(5)>. 575 576=item B<max_maptrack_frames=NUMBER> 577 578Specify the maximum number of grant maptrack frames the domain is allowed 579to have. This value controls how many pages of foreign domains can be accessed 580via the grant mechanism by this domain. The default value is settable via 581L<xl.conf(5)>. 582 583=item B<max_grant_version=NUMBER> 584 585Specify the maximum grant table version the domain is allowed to use. The 586default value is settable via L<xl.conf(5)>. 587 588=item B<nomigrate=BOOLEAN> 589 590Disable migration of this domain. This enables certain other features 591which are incompatible with migration. Currently this is limited to 592enabling the invariant TSC feature flag in CPUID results when TSC is 593not emulated. 594 595=item B<driver_domain=BOOLEAN> 596 597Specify that this domain is a driver domain. This enables certain 598features needed in order to run a driver domain. 599 600=item B<device_tree=PATH> 601 602Specify a partial device tree (compiled via the Device Tree Compiler). 603Everything under the node "/passthrough" will be copied into the guest 604device tree. For convenience, the node "/aliases" is also copied to allow 605the user to define aliases which can be used by the guest kernel. 606 607Given the complexity of verifying the validity of a device tree, this 608option should only be used with a trusted device tree. 609 610Note that the partial device tree should avoid using the phandle 65000 611which is reserved by the toolstack. 612 613=item B<passthrough="STRING"> 614 615Specify whether IOMMU mappings are enabled for the domain and hence whether 616it will be enabled for passthrough hardware. Valid values for this option 617are: 618 619=over 4 620 621=item B<disabled> 622 623IOMMU mappings are disabled for the domain and so hardware may not be 624passed through. 625 626This option is the default if no passthrough hardware is specified in the 627domain's configuration. 628 629=item B<enabled> 630 631This option enables IOMMU mappings and selects an appropriate default 632operating mode (see below for details of the operating modes). For HVM/PVH 633domains running on platforms where the option is available, this is 634equivalent to B<share_pt>. Otherwise, and also for PV domains, this 635option is equivalent to B<sync_pt>. 636 637This option is the default if passthrough hardware is specified in the 638domain's configuration. 639 640=item B<sync_pt> 641 642This option means that IOMMU mappings will be synchronized with the 643domain's P2M table as follows: 644 645For a PV domain, all writable pages assigned to the domain are identity 646mapped by MFN in the IOMMU page table. Thus a device driver running in the 647domain may program passthrough hardware for DMA using MFN values 648(i.e. host/machine frame numbers) looked up in its P2M. 649 650For an HVM/PVH domain, all non-foreign RAM pages present in its P2M will be 651mapped by GFN in the IOMMU page table. Thus a device driver running in the 652domain may program passthrough hardware using GFN values (i.e. guest 653physical frame numbers) without any further translation. 654 655This option is not currently available on Arm. 656 657=item B<share_pt> 658 659This option is unavailable for a PV domain. For an HVM/PVH domain, this 660option means that the IOMMU will be programmed to directly reference the 661domain's P2M table as its page table. From the point of view of a device 662driver running in the domain this is functionally equivalent to B<sync_pt> 663but places less load on the hypervisor and so should generally be selected 664in preference. However, the availability of this option is hardware 665specific. If B<xl info> reports B<virt_caps> containing 666B<iommu_hap_pt_share> then this option may be used. 667 668=item B<default> 669 670The default, which chooses between B<disabled> and B<enabled> 671according to whether passthrough devices are enabled in the config 672file. 673 674=back 675 676=item B<xend_suspend_evtchn_compat=BOOLEAN> 677 678If this option is B<true> the xenstore path for the domain's suspend 679event channel will not be created. Instead the old xend behaviour of 680making the whole xenstore B<device> sub-tree writable by the domain will 681be re-instated. 682 683The existence of the suspend event channel path can cause problems with 684certain PV drivers running in the guest (e.g. old Red Hat PV drivers for 685Windows). 686 687If this option is not specified then it will default to B<false>. 688 689=item B<vmtrace_buf_kb=KBYTES> 690 691Specifies the size of vmtrace buffer that would be allocated for each 692vCPU belonging to this domain. Disabled (i.e. B<vmtrace_buf_kb=0>) by 693default. 694 695B<NOTE>: Acceptable values are platform specific. For Intel Processor 696Trace, this value must be a power of 2 between 4k and 16M. 697 698=item B<vpmu=BOOLEAN> 699 700Currently ARM only. 701 702Specifies whether to enable the access to PMU registers by disabling 703the PMU traps. 704 705The PMU registers are not virtualized and the physical registers are directly 706accessible when this parameter is enabled. There is no interrupt support and 707Xen will not save/restore the register values on context switches. 708 709vPMU, by design and purpose, exposes system level performance 710information to the guest. Only to be used by sufficiently privileged 711domains. This feature is currently in experimental state. 712 713If this option is not specified then it will default to B<false>. 714 715=back 716 717=head2 Devices 718 719The following options define the paravirtual, emulated and physical 720devices which the guest will contain. 721 722=over 4 723 724=item B<disk=[ "DISK_SPEC_STRING", "DISK_SPEC_STRING", ...]> 725 726Specifies the disks (both emulated disks and Xen virtual block 727devices) which are to be provided to the guest, and what objects on 728the host they should map to. See L<xl-disk-configuration(5)> for more 729details. 730 731=item B<vif=[ "NET_SPEC_STRING", "NET_SPEC_STRING", ...]> 732 733Specifies the network interfaces (both emulated network adapters, 734and Xen virtual interfaces) which are to be provided to the guest. See 735L<xl-network-configuration(5)> for more details. 736 737=item B<vtpm=[ "VTPM_SPEC_STRING", "VTPM_SPEC_STRING", ...]> 738 739Specifies the Virtual Trusted Platform module to be 740provided to the guest. See L<xen-vtpm(7)> for more details. 741 742Each B<VTPM_SPEC_STRING> is a comma-separated list of C<KEY=VALUE> 743settings from the following list: 744 745=over 4 746 747=item B<backend=domain-id> 748 749Specifies the backend domain name or id. B<This value is required!> 750If this domain is a guest, the backend should be set to the 751vTPM domain name. If this domain is a vTPM, the 752backend should be set to the vTPM manager domain name. 753 754=item B<uuid=UUID> 755 756Specifies the UUID of this vTPM device. The UUID is used to uniquely 757identify the vTPM device. You can create one using the B<uuidgen(1)> 758program on unix systems. If left unspecified, a new UUID 759will be randomly generated every time the domain boots. 760If this is a vTPM domain, you should specify a value. The 761value is optional if this is a guest domain. 762 763=back 764 765=item B<p9=[ "9PFS_SPEC_STRING", "9PFS_SPEC_STRING", ...]> 766 767Creates a Xen 9pfs connection to share a filesystem from the backend to the 768frontend. 769 770Each B<9PFS_SPEC_STRING> is a comma-separated list of C<KEY=VALUE> 771settings, from the following list: 772 773=over 4 774 775=item B<type=TYPE> 776 777The backendtype for the PV device. Supported values are B<qemu> and 778B<xen_9pfsd>. The default is B<qemu>. 779 780=item B<tag=STRING> 781 7829pfs tag to identify the filesystem share. The tag is needed on the 783guest side to mount it. For the backendtype of B<xen_9pfsd> the tag defaults to 784"Xen". 785 786=item B<security_model="none"> 787 788Only "none" is supported today, which means that the files are stored using 789the same credentials as those they have in the guest (no user ownership 790squash or remap). 791 792=item B<path=STRING> 793 794Filesystem path on the backend to export. For the backendtype of B<xen_9pfsd> 795the path defaults to "@XEN_LOG_DIR@/guests/<guest-name>". 796 797=item B<backend=domain-id> 798 799Specify the backend domain name or id, defaults to dom0. 800 801=item B<max-files=NUMBER> 802 803Specify the maximum number of files below B<path>. A value of 0 (which 804is the default) doesn't limit the number of files. Only valid for 805B<type=xen_9pfsd>. 806 807=item B<max-open-files=NUMBER> 808 809Specify the maximum number of concurrently opened files below B<path>. 810Multiple opens of the same file are counted individually. Only valid for 811B<type=xen_9pfsd>, which has a default of B<max-open-files=5>. 812 813=item B<max-space=NUMBER> 814 815Specify the maximum used disk space in MiB below B<path>. A value of 0 (which 816is the default) doesn't limit the usable disk space. Only valid for 817B<type=xen_9pfsd>. 818 819=item B<auto-delete=BOOLEAN> 820 821When set the backend will delete the oldest file which is currently not 822opened by the guest in case the disk space limit set via B<max-space> or the 823file limit set via B<max-files> is being reached. Only valid for 824B<type=xen_9pfsd>. 825 826=back 827 828=item B<pvcalls=[ "backend=domain-id", ... ]> 829 830Creates a Xen pvcalls connection to handle pvcalls requests from 831frontend to backend. It can be used as an alternative networking model. 832For more information about the protocol, see 833https://xenbits.xenproject.org/docs/unstable/misc/pvcalls.html. 834 835=item B<vfb=[ "VFB_SPEC_STRING", "VFB_SPEC_STRING", ...]> 836 837Specifies the paravirtual framebuffer devices which should be supplied 838to the domain. 839 840This option does not control the emulated graphics card presented to 841an HVM guest. See B<Emulated VGA Graphics Device> below for how to 842configure the emulated device. If B<Emulated VGA Graphics Device> options 843are used in a PV guest configuration, B<xl> will pick up B<vnc>, B<vnclisten>, 844B<vncpasswd>, B<vncdisplay>, B<vncunused>, B<sdl>, B<opengl> and 845B<keymap> to construct the paravirtual framebuffer device for the guest. 846 847Each B<VFB_SPEC_STRING> is a comma-separated list of C<KEY=VALUE> 848settings, from the following list: 849 850=over 4 851 852=item B<vnc=BOOLEAN> 853 854Allow access to the display via the VNC protocol. This enables the 855other VNC-related settings. Default is 1 (enabled). 856 857=item B<vnclisten=ADDRESS[:DISPLAYNUM]> 858 859Specifies the IP address, and optionally the VNC display number, to use. 860 861Note: if you specify the display number here, you should not use 862the B<vncdisplay> option. 863 864=item B<vncdisplay=DISPLAYNUM> 865 866Specifies the VNC display number to use. The actual TCP port number 867will be DISPLAYNUM+5900. 868 869Note: you should not use this option if you set the DISPLAYNUM in the 870B<vnclisten> option. 871 872=item B<vncunused=BOOLEAN> 873 874Requests that the VNC display setup searches for a free TCP port to use. 875The actual display used can be accessed with B<xl vncviewer>. 876 877=item B<vncpasswd=PASSWORD> 878 879Specifies the password for the VNC server. If the password is set to an 880empty string, authentication on the VNC server will be disabled, 881allowing any user to connect. 882 883=item B<sdl=BOOLEAN> 884 885Specifies that the display should be presented via an X window (using 886Simple DirectMedia Layer). The default is 0 (not enabled). 887 888=item B<display=DISPLAY> 889 890Specifies the X Window display that should be used when the B<sdl> option 891is used. 892 893=item B<xauthority=XAUTHORITY> 894 895Specifies the path to the X authority file that should be used to 896connect to the X server when the B<sdl> option is used. 897 898=item B<opengl=BOOLEAN> 899 900Enable OpenGL acceleration of the SDL display. Only effects machines 901using B<device_model_version="qemu-xen-traditional"> and only if the 902device-model was compiled with OpenGL support. The default is 0 (disabled). 903 904=item B<keymap=LANG> 905 906Configure the keymap to use for the keyboard associated with this 907display. If the input method does not easily support raw keycodes 908(e.g. this is often the case when using VNC) then this allows us to 909correctly map the input keys into keycodes seen by the guest. The 910specific values which are accepted are defined by the version of the 911device-model which you are using. See B<Keymaps> below or consult the 912B<qemu(1)> manpage. The default is B<en-us>. 913 914=back 915 916=item B<channel=[ "CHANNEL_SPEC_STRING", "CHANNEL_SPEC_STRING", ...]> 917 918Specifies the virtual channels to be provided to the guest. A 919channel is a low-bandwidth, bidirectional byte stream, which resembles 920a serial link. Typical uses for channels include transmitting VM 921configuration after boot and signalling to in-guest agents. Please see 922L<xen-pv-channel(7)> for more details. 923 924Each B<CHANNEL_SPEC_STRING> is a comma-separated list of C<KEY=VALUE> 925settings. Leading and trailing whitespace is ignored in both KEY and 926VALUE. Neither KEY nor VALUE may contain ',', '=' or '"'. Defined values 927are: 928 929=over 4 930 931=item B<backend=domain-id> 932 933Specifies the backend domain name or id. This parameter is optional. If 934this parameter is omitted then the toolstack domain will be assumed. 935 936=item B<name=NAME> 937 938Specifies the name for this device. B<This parameter is mandatory!> 939This should be a well-known name for a specific application (e.g. 940guest agent) and should be used by the frontend to connect the 941application to the right channel device. There is no formal registry 942of channel names, so application authors are encouraged to make their 943names unique by including the domain name and a version number in the string 944(e.g. org.mydomain.guestagent.1). 945 946=item B<connection=CONNECTION> 947 948Specifies how the backend will be implemented. The following options are 949available: 950 951=over 4 952 953=item B<SOCKET> 954 955The backend will bind a Unix domain socket (at the path given by 956B<path=PATH>), listen for and accept connections. The backend will proxy 957data between the channel and the connected socket. 958 959=item B<PTY> 960 961The backend will create a pty and proxy data between the channel and the 962master device. The command B<xl channel-list> can be used to discover the 963assigned slave device. 964 965=back 966 967=back 968 969=item B<rdm="RDM_RESERVATION_STRING"> 970 971B<HVM/x86 only!> Specifies information about Reserved Device Memory (RDM), 972which is necessary to enable robust device passthrough. One example of RDM 973is reporting through the ACPI Reserved Memory Region Reporting (RMRR) structure 974on the x86 platform. 975 976B<RDM_RESERVATION_STRING> is a comma separated list of C<KEY=VALUE> settings, 977from the following list: 978 979=over 4 980 981=item B<strategy=STRING> 982 983Currently there is only one valid type, and that is "host". 984 985=over 4 986 987=item B<host> 988 989If set to "host" it means all reserved device memory on this platform should 990be checked to reserve regions in this VM's address space. This global RDM 991parameter allows the user to specify reserved regions explicitly, and using 992"host" includes all reserved regions reported on this platform, which is 993useful when doing hotplug. 994 995By default this isn't set so we don't check all RDMs. Instead, we just check 996the RDM specific to a given device if we're assigning this kind of a device. 997 998Note: this option is not recommended unless you can make sure that no 999conflicts exist. 1000 1001For example, you're trying to set "memory = 2800" to allocate memory to one 1002given VM but the platform owns two RDM regions like: 1003 1004Device A [sbdf_A]: RMRR region_A: base_addr ac6d3000 end_address ac6e6fff 1005 1006Device B [sbdf_B]: RMRR region_B: base_addr ad800000 end_address afffffff 1007 1008In this conflict case, 1009 1010#1. If B<strategy> is set to "host", for example: 1011 1012rdm = "strategy=host,policy=strict" or rdm = "strategy=host,policy=relaxed" 1013 1014it means all conflicts will be handled according to the policy 1015introduced by B<policy> as described below. 1016 1017#2. If B<strategy> is not set at all, but 1018 1019pci = [ 'sbdf_A, rdm_policy=xxxxx' ] 1020 1021it means only one conflict of region_A will be handled according to the policy 1022introduced by B<rdm_policy=STRING> as described inside B<pci> options. 1023 1024=back 1025 1026=item B<policy=STRING> 1027 1028Specifies how to deal with conflicts when reserving already reserved device 1029memory in the guest address space. 1030 1031=over 4 1032 1033=item B<strict> 1034 1035Specifies that in case of an unresolved conflict the VM can't be created, 1036or the associated device can't be attached in the case of hotplug. 1037 1038=item B<relaxed> 1039 1040Specifies that in case of an unresolved conflict the VM is allowed to be 1041created but may cause the VM to crash if a pass-through device accesses RDM. 1042For example, the Windows IGD GFX driver always accesses RDM regions so it 1043leads to a VM crash. 1044 1045Note: this may be overridden by the B<rdm_policy> option in the B<pci> 1046device configuration. 1047 1048=back 1049 1050=back 1051 1052=item B<usbctrl=[ "USBCTRL_SPEC_STRING", "USBCTRL_SPEC_STRING", ...]> 1053 1054Specifies the USB controllers created for this guest. 1055 1056Each B<USBCTRL_SPEC_STRING> is a comma-separated list of C<KEY=VALUE> 1057settings, from the following list: 1058 1059=over 4 1060 1061=item B<type=TYPE> 1062 1063Specifies the usb controller type. 1064 1065=over 4 1066 1067=item B<pv> 1068 1069Specifies a kernel based PVUSB backend. 1070 1071=item B<qusb> 1072 1073Specifies a QEMU based PVUSB backend. 1074 1075=item B<devicemodel> 1076 1077Specifies a USB controller emulated by QEMU. 1078It will show up as a PCI-device in the guest. 1079 1080=item B<auto> 1081 1082Determines whether a kernel based backend is installed. 1083If this is the case, B<pv> is used, otherwise B<qusb> will be used. 1084For HVM domains B<devicemodel> will be selected. 1085 1086This option is the default. 1087 1088=back 1089 1090=item B<version=VERSION> 1091 1092Specifies the usb controller version. Possible values include 10931 (USB1.1), 2 (USB2.0) and 3 (USB3.0). 1094Default is 2 (USB2.0). 1095Value 3 (USB3.0) is available for the B<devicemodel> type only. 1096 1097=item B<ports=PORTS> 1098 1099Specifies the total number of ports of the usb controller. The maximum 1100number is 31. The default is 8. 1101With the type B<devicemodel> the number of ports is more limited: 1102a USB1.1 controller always has 2 ports, 1103a USB2.0 controller always has 6 ports 1104and a USB3.0 controller can have up to 15 ports. 1105 1106USB controller ids start from 0. In line with the USB specification, however, 1107ports on a controller start from 1. 1108 1109B<EXAMPLE> 1110 1111=over 2 1112 1113usbctrl=["version=1,ports=4", "version=2,ports=8"] 1114 1115The first controller is USB1.1 and has: 1116 1117controller id = 0, and ports 1,2,3,4. 1118 1119The second controller is USB2.0 and has: 1120 1121controller id = 1, and ports 1,2,3,4,5,6,7,8. 1122 1123=back 1124 1125=back 1126 1127=item B<usbdev=[ "USBDEV_SPEC_STRING", "USBDEV_SPEC_STRING", ...]> 1128 1129Specifies the USB devices to be attached to the guest at boot. 1130 1131Each B<USBDEV_SPEC_STRING> is a comma-separated list of C<KEY=VALUE> 1132settings, from the following list: 1133 1134=over 4 1135 1136=item B<type=hostdev> 1137 1138Specifies USB device type. Currently only "hostdev" is supported. 1139 1140=item B<hostbus=busnum> 1141 1142Specifies busnum of the USB device from the host perspective. 1143 1144=item B<hostaddr=devnum> 1145 1146Specifies devnum of the USB device from the host perspective. 1147 1148=item B<controller=CONTROLLER> 1149 1150Specifies the USB controller id, to which controller the USB device is 1151attached. 1152 1153If no controller is specified, an available controller:port combination 1154will be used. If there are no available controller:port combinations, 1155a new controller will be created. 1156 1157=item B<port=PORT> 1158 1159Specifies the USB port to which the USB device is attached. The B<port> 1160option is valid only when the B<controller> option is specified. 1161 1162=back 1163 1164=item B<pci=[ "PCI_SPEC_STRING", "PCI_SPEC_STRING", ...]> 1165 1166Specifies the host PCI devices to passthrough to this guest. 1167See L<xl-pci-configuration(5)> for more details. 1168 1169=item B<pci_permissive=BOOLEAN> 1170 1171Changes the default value of B<permissive> for all PCI devices passed 1172through to this VM. See B<permissive> above. 1173 1174=item B<pci_msitranslate=BOOLEAN> 1175 1176Changes the default value of B<msitranslate> for all PCI devices passed 1177through to this VM. See B<msitranslate> above. 1178 1179=item B<pci_seize=BOOLEAN> 1180 1181Changes the default value of B<seize> for all PCI devices passed 1182through to this VM. See B<seize> above. 1183 1184=item B<pci_power_mgmt=BOOLEAN> 1185 1186B<(HVM only)> Changes the default value of B<power_mgmt> for all PCI 1187devices passed through to this VM. See B<power_mgmt> 1188above. 1189 1190=item B<gfx_passthru=BOOLEAN|"STRING"> 1191 1192Enable graphics device PCI passthrough. This option makes an assigned 1193PCI graphics card become the primary graphics card in the VM. The QEMU 1194emulated graphics adapter is disabled and the VNC console for the VM 1195will not have any graphics output. All graphics output, including boot 1196time QEMU BIOS messages from the VM, will go to the physical outputs 1197of the passed through physical graphics card. 1198 1199The graphics card PCI device to pass through is chosen with the B<pci> 1200option, in exactly the same way a normal Xen PCI device 1201passthrough/assignment is done. Note that B<gfx_passthru> does not do 1202any kind of sharing of the GPU, so you can assign the GPU to only one 1203single VM at a time. 1204 1205B<gfx_passthru> also enables various legacy VGA memory ranges, BARs, MMIOs, 1206and ioports to be passed through to the VM, since those are required 1207for correct operation of things like VGA BIOS, text mode, VBE, etc. 1208 1209Enabling the B<gfx_passthru> option also copies the physical graphics card 1210video BIOS to the guest memory, and executes the VBIOS in the guest 1211to initialize the graphics card. 1212 1213Most graphics adapters require vendor specific tweaks for properly 1214working graphics passthrough. See the XenVGAPassthroughTestedAdapters 1215L<https://wiki.xenproject.org/wiki/XenVGAPassthroughTestedAdapters> wiki page 1216for graphics cards currently supported by B<gfx_passthru>. 1217 1218B<gfx_passthru> is currently supported both with the qemu-xen-traditional 1219device-model and upstream qemu-xen device-model. 1220 1221When given as a boolean the B<gfx_passthru> option either disables graphics 1222card passthrough or enables autodetection. 1223 1224When given as a string the B<gfx_passthru> option describes the type 1225of device to enable. Note that this behavior is only supported with the 1226upstream qemu-xen device-model. With qemu-xen-traditional IGD (Intel Graphics 1227Device) is always assumed and options other than autodetect or explicit IGD 1228will result in an error. 1229 1230Currently, valid values for the option are: 1231 1232=over 4 1233 1234=item B<0> 1235 1236Disables graphics device PCI passthrough. 1237 1238=item B<1>, B<"default"> 1239 1240Enables graphics device PCI passthrough and autodetects the type of device 1241which is being used. 1242 1243=item B<"igd"> 1244 1245Enables graphics device PCI passthrough but forcing the type of device to 1246Intel Graphics Device. 1247 1248=back 1249 1250Note that some graphics cards (AMD/ATI cards, for example) do not 1251necessarily require the B<gfx_passthru> option, so you can use the normal Xen 1252PCI passthrough to assign the graphics card as a secondary graphics 1253card to the VM. The QEMU-emulated graphics card remains the primary 1254graphics card, and VNC output is available from the QEMU-emulated 1255primary adapter. 1256 1257More information about the Xen B<gfx_passthru> feature is available 1258on the XenVGAPassthrough L<https://wiki.xenproject.org/wiki/XenVGAPassthrough> 1259wiki page. 1260 1261=item B<rdm_mem_boundary=MBYTES> 1262 1263Number of megabytes to set for a boundary when checking for RDM conflicts. 1264 1265When RDM conflicts with RAM, RDM is probably scattered over the whole RAM 1266space. Having multiple RDM entries would worsen this and lead to a complicated 1267memory layout. Here we're trying to figure out a simple solution to 1268avoid breaking the existing layout. When a conflict occurs, 1269 1270 #1. Above a predefined boundary 1271 - move lowmem_end below the reserved region to solve the conflict; 1272 1273 #2. Below a predefined boundary 1274 - Check if the policy is strict or relaxed. 1275 A "strict" policy leads to a fail in libxl. 1276 Note that when both policies are specified on a given region, 1277 "strict" is always preferred. 1278 The "relaxed" policy issues a warning message and also masks this 1279 entry INVALID to indicate we shouldn't expose this entry to 1280 hvmloader. 1281 1282The default value is 2048. 1283 1284=item B<dtdev=[ "DTDEV_PATH", "DTDEV_PATH", ...]> 1285 1286Specifies the host device tree nodes to passt hrough to this guest. Each 1287DTDEV_PATH is an absolute path in the device tree. 1288 1289=item B<ioports=[ "IOPORT_RANGE", "IOPORT_RANGE", ...]> 1290 1291Allow the guest to access specific legacy I/O ports. Each B<IOPORT_RANGE> 1292is given in hexadecimal format and may either be a range, e.g. C<2f8-2ff> 1293(inclusive), or a single I/O port, e.g. C<2f8>. 1294 1295It is recommended to only use this option for trusted VMs under 1296administrator's control. 1297 1298=item B<iomem=[ "IOMEM_START,NUM_PAGES[@GFN]", "IOMEM_START,NUM_PAGES[@GFN]", ...]> 1299 1300Allow auto-translated domains to access specific hardware I/O memory pages. 1301 1302B<IOMEM_START> is a physical page number. B<NUM_PAGES> is the number of pages, 1303beginning with B<START_PAGE>, to allow access to. B<GFN> specifies the guest 1304frame number where the mapping will start in the guest's address space. If 1305B<GFN> is not specified, the mapping will be performed using B<IOMEM_START> 1306as a start in the guest's address space, therefore performing a 1:1 mapping 1307by default. 1308All of these values must be given in hexadecimal format. 1309 1310Note that the IOMMU won't be updated with the mappings specified with this 1311option. This option therefore should not be used to pass through any 1312IOMMU-protected devices. 1313 1314It is recommended to only use this option for trusted VMs under 1315administrator's control. 1316 1317=item B<irqs=[ NUMBER, NUMBER, ...]> 1318 1319Allow a guest to access specific physical IRQs. 1320 1321It is recommended to only use this option for trusted VMs under 1322administrator's control. 1323 1324If vuart console is enabled then irq 32 is reserved for it. See 1325L</vuart="uart"> to know how to enable vuart console. 1326 1327=item B<max_event_channels=N> 1328 1329Limit the guest to using at most N event channels (PV interrupts). 1330Guests use hypervisor resources for each event channel they use. 1331 1332The default of 1023 should be sufficient for typical guests. The 1333maximum value depends on what the guest supports. Guests supporting the 1334FIFO-based event channel ABI support up to 131,071 event channels. 1335Other guests are limited to 4095 (64-bit x86 and ARM) or 1023 (32-bit 1336x86). 1337 1338=item B<vdispl=[ "VDISPL_SPEC_STRING", "VDISPL_SPEC_STRING", ...]> 1339 1340Specifies the virtual display devices to be provided to the guest. 1341 1342Each B<VDISPL_SPEC_STRING> is a comma-separated list of C<KEY=VALUE> 1343settings, from the following list: 1344 1345=over 4 1346 1347=item C<backend=DOMAIN> 1348 1349Specifies the backend domain name or id. If not specified Domain-0 is used. 1350 1351=item C<be-alloc=BOOLEAN> 1352 1353Indicates if backend can be a buffer provider/allocator for this domain. See 1354display protocol for details. 1355 1356=item C<connectors=CONNECTORS> 1357 1358Specifies virtual connectors for the device in following format 1359<id>:<W>x<H>;<id>:<W>x<H>... where: 1360 1361=over 4 1362 1363=item C<id> 1364 1365String connector unique id. Space, comma symbols are not allowed. 1366 1367=item C<W> 1368 1369Connector width in pixels. 1370 1371=item C<H> 1372 1373Connector height in pixels. 1374 1375=back 1376 1377B<EXAMPLE> 1378 1379=over 4 1380 1381connectors=id0:1920x1080;id1:800x600;id2:640x480 1382 1383=back 1384 1385=back 1386 1387=item B<dm_restrict=BOOLEAN> 1388 1389Restrict the device model after startup, 1390to limit the consequencese of security vulnerabilities in qemu. 1391 1392See docs/features/qemu-depriv.pandoc for more information 1393on Linux and QEMU version requirements, device model user setup, 1394and current limitations. 1395 1396This feature is a B<technology preview>. 1397See SUPPORT.md for a security support statement. 1398 1399=item B<device_model_user=USERNAME> 1400 1401When running dm_restrict, run the device model as this user. 1402 1403NOTE: Each domain MUST have a SEPARATE username. 1404 1405See docs/features/qemu-depriv.pandoc for more information. 1406 1407=item B<vsnd=[ VCARD_SPEC, VCARD_SPEC, ... ]> 1408 1409Specifies the virtual sound cards to be provided to the guest. 1410Each B<VCARD_SPEC> is a list, which has a form of 1411"[VSND_ITEM_SPEC, VSND_ITEM_SPEC, ... ]" (without the quotes). 1412The virtual sound card has hierarchical structure. 1413Every card has a set of PCM devices and streams, each could be individually 1414configured. 1415 1416B<VSND_ITEM_SPEC> describes individual item parameters. 1417B<VSND_ITEM_SPEC> is a string of comma separated item parameters 1418headed by item identifier. Each item parameter is C<KEY=VALUE> pair: 1419 1420=over 4 1421 1422"identifier, param = value, ...". 1423 1424=back 1425 1426Identifier shall be one of following values: "CARD", "PCM", "STREAM". 1427The child item treated as belonging to the previously defined parent item. 1428 1429All parameters are optional. 1430 1431There are group of parameters which are common for all items. 1432This group can be defined at higher level of the hierarchy and be fully or 1433partially re-used by the underlying layers. These parameters are: 1434 1435=over 4 1436 1437* number of channels (min/max) 1438 1439* supported sample rates 1440 1441* supported sample formats 1442 1443=back 1444 1445E.g. one can define these values for the whole card, device or stream. 1446Every underlying layer in turn can re-define some or all of them to better 1447fit its needs. For example, card may define number of channels to be 1448in [1; 8] range, and some particular stream may be limited to [1; 2] only. 1449The rule is that the underlying layer must be a subset of the upper layer 1450range. 1451 1452I<COMMON parameters:> 1453 1454=over 4 1455 1456=over 4 1457 1458=item B<sample-rates=RATES> 1459 1460List of integer values separated by semicolon: sample-rates=8000;22050;44100 1461 1462=item B<sample-formats=FORMATS> 1463 1464List of string values separated by semicolon: sample-formats=s16_le;s8;u32_be 1465 1466Supported formats: s8, u8, s16_le, s16_be, u16_le, u16_be, s24_le, s24_be, 1467u24_le, u24_be, s32_le, s32_be, u32_le, u32_be, float_le, float_be, 1468float64_le, float64_be, iec958_subframe_le, iec958_subframe_be, 1469mu_law, a_law, ima_adpcm, mpeg, gsm 1470 1471=item B<channels-min=NUMBER> 1472 1473The minimum amount of channels. 1474 1475=item B<channels-max=NUMBER> 1476 1477The maximum amount of channels. 1478 1479=item B<buffer-size=NUMBER> 1480 1481The maximum size in octets of the buffer to allocate per stream. 1482 1483=back 1484 1485=back 1486 1487I<CARD specification:> 1488 1489=over 4 1490 1491=over 4 1492 1493=item B<backend=domain-id> 1494 1495Specify the backend domain name or id, defaults to dom0. 1496 1497=item B<short-name=STRING> 1498 1499Short name of the virtual sound card. 1500 1501=item B<long-name=STRING> 1502 1503Long name of the virtual sound card. 1504 1505=back 1506 1507=back 1508 1509I<PCM specification:> 1510 1511=over 4 1512 1513=over 4 1514 1515=item B<name=STRING> 1516 1517Name of the PCM sound device within the virtual sound card. 1518 1519=back 1520 1521=back 1522 1523I<STREAM specification:> 1524 1525=over 4 1526 1527=over 4 1528 1529=item B<unique-id=STRING> 1530 1531Unique stream identifier. 1532 1533=item B<type=TYPE> 1534 1535Stream type: "p" - playback stream, "c" - capture stream. 1536 1537=back 1538 1539=back 1540 1541I<EXAMPLE:> 1542 1543 vsnd = [ 1544 ['CARD, short-name=Main, sample-formats=s16_le;s8;u32_be', 1545 'PCM, name=Main', 1546 'STREAM, id=0, type=p', 1547 'STREAM, id=1, type=c, channels-max=2' 1548 ], 1549 ['CARD, short-name=Second', 1550 'PCM, name=Second, buffer-size=1024', 1551 'STREAM, id=2, type=p', 1552 'STREAM, id=3, type=c' 1553 ] 1554 ] 1555 1556=item B<vkb=[ "VKB_SPEC_STRING", "VKB_SPEC_STRING", ...]> 1557 1558Specifies the virtual keyboard device to be provided to the guest. 1559 1560Each B<VKB_SPEC_STRING> is a comma-separated list of C<KEY=VALUE> 1561settings from the following list: 1562 1563=over 4 1564 1565=item B<unique-id=STRING> 1566 1567Specifies the unique input device id. 1568 1569=item B<backend=domain-id> 1570 1571Specifies the backend domain name or id. 1572 1573=item B<backend-type=type> 1574 1575Specifies the backend type: qemu - for QEMU backend or linux - for Linux PV 1576domain. 1577 1578=item B<feature-disable-keyboard=BOOLEAN> 1579 1580Indicates if keyboard device is disabled. 1581 1582=item B<feature-disable-pointer=BOOLEAN> 1583 1584Indicates if pointer device is disabled. 1585 1586=item B<feature-abs-pointer=BOOLEAN> 1587 1588Indicates if pointer device can return absolute coordinates. 1589 1590=item B<feature-raw-pointer=BOOLEAN> 1591 1592Indicates if pointer device can return raw (unscaled) absolute coordinates. 1593 1594=item B<feature-multi-touch=BOOLEAN> 1595 1596Indicates if input device supports multi touch. 1597 1598=item B<multi-touch-width=MULTI_TOUCH_WIDTH> 1599 1600Set maximum width for multi touch device. 1601 1602=item B<multi-touch-height=MULTI_TOUCH_HEIGHT> 1603 1604Set maximum height for multi touch device. 1605 1606=item B<multi-touch-num-contacts=MULTI_TOUCH_NUM_CONTACTS> 1607 1608Set maximum contacts number for multi touch device. 1609 1610=item B<width=WIDTH> 1611 1612Set maximum width for pointer device. 1613 1614=item B<height=HEIGHT> 1615 1616Set maximum height for pointer device. 1617 1618=back 1619 1620=item B<virtio=[ "VIRTIO_DEVICE_STRING", "VIRTIO_DEVICE_STRING", ...]> 1621 1622Specifies the Virtio devices to be provided to the guest. 1623 1624Each B<VIRTIO_DEVICE_STRING> is a comma-separated list of C<KEY=VALUE> settings 1625from the following list. As a special case, a single comma is allowed in the 1626VALUE of the "type" KEY, where the VALUE is set with "virtio,device<N>". 1627 1628=over 4 1629 1630=item B<backend=domain-id> 1631 1632Specifies the backend domain name or id, defaults to dom0. 1633 1634=item B<type=STRING> 1635 1636Specifies the compatible string for the specific Virtio device. The same will be 1637written in the Device Tree compatible property of the Virtio device. For 1638example, "type=virtio,device22" for the I2C device, whose device-tree binding is 1639present here: 1640 1641L<https://www.kernel.org/doc/Documentation/devicetree/bindings/i2c/i2c-virtio.yaml> 1642 1643For other generic virtio devices, where we don't need to set special or 1644compatible properties in the Device Tree, the type field must be set to 1645"virtio,device" or "virtio,device<N>", where "N" is the virtio device id in 1646hexadecimal format, without the "0x" prefix and all in lower case, like 1647"virtio,device1a" for the file system device. 1648 1649=item B<transport=STRING> 1650 1651Specifies the transport mechanism for the Virtio device, only "mmio" is 1652supported for now. 1653 1654=item B<grant_usage=BOOLEAN> 1655 1656If this option is B<true>, the Xen grants are always enabled. 1657If this option is B<false>, the Xen grants are always disabled. 1658 1659If this option is missing, then the default grant setting will be used, 1660i.e. enable grants if backend-domid != 0. 1661 1662=back 1663 1664=item B<tee="STRING"> 1665 1666B<Arm only.> Set TEE type for the guest. TEE is a Trusted Execution 1667Environment -- separate secure OS found on some platforms. B<STRING> can be one of the: 1668 1669=over 4 1670 1671=item B<none> 1672 1673"Don't allow the guest to use TEE if present on the platform. This is 1674the default value. 1675 1676=item B<optee> 1677 1678Allow a guest to access the host OP-TEE OS. Xen will mediate the 1679access to OP-TEE and the resource isolation will be provided directly 1680by OP-TEE. OP-TEE itself may limit the number of guests that can 1681concurrently use it. This requires a virtualization-aware OP-TEE for 1682this to work. 1683 1684You can refer to 1685L<OP-TEE documentation|https://optee.readthedocs.io/en/latest/architecture/virtualization.html> 1686for more information about how to enable and configure virtualization support 1687in OP-TEE. 1688 1689This feature is a B<technology preview>. 1690 1691=item B<ffa> 1692 1693B<Arm only.> Allow a guest to communicate via FF-A with Secure Partitions 1694(SP), default false. 1695 1696Currently only a small subset of the FF-A specification is supported. Just 1697enough to communicate with OP-TEE. In general only direct messaging and 1698sharing memory with one SP. More advanced use cases where memory might be 1699shared or donated to multiple SPs are not supported. 1700 1701See L<https://developer.arm.com/documentation/den0077/latest> for more 1702information about FF-A. 1703 1704This feature is a B<technology preview>. 1705 1706=back 1707 1708=back 1709 1710=head2 Paravirtualised (PV) Guest Specific Options 1711 1712The following options apply only to Paravirtual (PV) guests. 1713 1714=over 4 1715 1716=item B<bootloader="PROGRAM"> 1717 1718Run C<PROGRAM> to find the kernel image and ramdisk to use. Normally 1719C<PROGRAM> would be C<pygrub>, which is an emulation of 1720grub/grub2/syslinux. Either B<kernel> or B<bootloader> must be specified 1721for PV guests. 1722 1723=item B<bootloader_args=[ "ARG", "ARG", ...]> 1724 1725Append B<ARG>s to the arguments to the B<bootloader> 1726program. Alternatively if the argument is a simple string then it will 1727be split into words at whitespace B<(this second option is deprecated)>. 1728 1729=item B<bootloader_restrict=BOOLEAN> 1730 1731Attempt to restrict the bootloader after startup, to limit the 1732consequences of security vulnerabilities due to parsing guest 1733owned image files. 1734 1735See docs/features/qemu-deprivilege.pandoc for more information 1736on how to setup the unprivileged users. 1737 1738Note that running the bootloader in restricted mode also implies using 1739non-interactive mode, and the disk image must be readable by the 1740restricted user. 1741 1742=item B<bootloader_user=USERNAME> 1743 1744When using bootloader_restrict, run the bootloader as this user. If not 1745set the default QEMU restrict users will be used. 1746 1747NOTE: Each domain MUST have a SEPARATE username. 1748 1749See docs/features/qemu-deprivilege.pandoc for more information. 1750 1751=item B<e820_host=BOOLEAN> 1752 1753Selects whether to expose the host e820 (memory map) to the guest via 1754the virtual e820. When this option is false (0) the guest pseudo-physical 1755address space consists of a single contiguous RAM region. When this 1756option is specified the virtual e820 instead reflects the host e820 1757and contains the same PCI holes. The total amount of RAM represented 1758by the memory map is always the same, this option configures only how 1759it is laid out. 1760 1761Exposing the host e820 to the guest gives the guest kernel the 1762opportunity to set aside the required part of its pseudo-physical 1763address space in order to provide address space to map passedthrough 1764PCI devices. It is guest Operating System dependent whether this 1765option is required, specifically it is required when using a mainline 1766Linux ("pvops") kernel. This option defaults to true (1) if any PCI 1767passthrough devices are configured and false (0) otherwise. If you do not 1768configure any passthrough devices at domain creation time but expect 1769to hotplug devices later then you should set this option. Conversely 1770if your particular guest kernel does not require this behaviour then 1771it is safe to allow this to be enabled but you may wish to disable it 1772anyway. 1773 1774=back 1775 1776=head2 Fully-virtualised (HVM) Guest Specific Options 1777 1778The following options apply only to Fully-virtualised (HVM) guests. 1779 1780=head3 Boot Device 1781 1782=over 4 1783 1784=item B<boot="STRING"> 1785 1786Specifies the emulated virtual device to boot from. 1787 1788Possible values are: 1789 1790=over 4 1791 1792=item B<c> 1793 1794Hard disk. 1795 1796=item B<d> 1797 1798CD-ROM. 1799 1800=item B<n> 1801 1802Network / PXE. 1803 1804=back 1805 1806B<Note:> multiple options can be given and will be attempted in the order they 1807are given, e.g. to boot from CD-ROM but fall back to the hard disk you can 1808specify it as B<dc>. 1809 1810The default is B<cd>, meaning try booting from the hard disk first, but fall 1811back to the CD-ROM. 1812 1813 1814=back 1815 1816=head3 Emulated disk controller type 1817 1818=over 4 1819 1820=item B<hdtype=STRING> 1821 1822Specifies the hard disk type. 1823 1824Possible values are: 1825 1826=over 4 1827 1828=item B<ide> 1829 1830If thise mode is specified B<xl> adds an emulated IDE controller, which is 1831suitable even for older operation systems. 1832 1833=item B<ahci> 1834 1835If this mode is specified, B<xl> adds an ich9 disk controller in AHCI mode and 1836uses it with upstream QEMU to emulate disks instead of IDE. It decreases boot 1837time but may not be supported by default in older operating systems, e.g. 1838Windows XP. 1839 1840=back 1841 1842The default is B<ide>. 1843 1844=back 1845 1846=head3 Paging 1847 1848The following options control the mechanisms used to virtualise guest 1849memory. The defaults are selected to give the best results for the 1850common cases so you should normally leave these options 1851unspecified. 1852 1853=over 4 1854 1855=item B<hap=BOOLEAN> 1856 1857Turns "hardware assisted paging" (the use of the hardware nested page 1858table feature) on or off. This feature is called EPT (Extended Page 1859Tables) by Intel and NPT (Nested Page Tables) or RVI (Rapid 1860Virtualisation Indexing) by AMD. If turned 1861off, Xen will run the guest in "shadow page table" mode where the 1862guest's page table updates and/or TLB flushes etc. will be emulated. 1863Use of HAP is the default when available. 1864 1865=item B<oos=BOOLEAN> 1866 1867Turns "out of sync pagetables" on or off. When running in shadow page 1868table mode, the guest's page table updates may be deferred as 1869specified in the Intel/AMD architecture manuals. However, this may 1870expose unexpected bugs in the guest, or find bugs in Xen, so it is 1871possible to disable this feature. Use of out of sync page tables, 1872when Xen thinks it appropriate, is the default. 1873 1874=item B<shadow_memory=MBYTES> 1875 1876Number of megabytes to set aside for shadowing guest pagetable pages 1877(effectively acting as a cache of translated pages) or to use for HAP 1878state. By default this is 1MB per guest vCPU plus 8KB per MB of guest 1879RAM. You should not normally need to adjust this value. However, if you 1880are not using hardware assisted paging (i.e. you are using shadow 1881mode) and your guest workload consists of a very large number of 1882similar processes then increasing this value may improve performance. 1883 1884=back 1885 1886=head3 Processor and Platform Features 1887 1888The following options allow various processor and platform level 1889features to be hidden or exposed from the guest's point of view. This 1890can be useful when running older guest Operating Systems which may 1891misbehave when faced with more modern features. In general, you should 1892accept the defaults for these options wherever possible. 1893 1894=over 4 1895 1896=item B<bios="STRING"> 1897 1898Select the virtual firmware that is exposed to the guest. 1899By default, a guess is made based on the device model, but sometimes 1900it may be useful to request a different one, like UEFI. 1901 1902=over 4 1903 1904=item B<rombios> 1905 1906Loads ROMBIOS, a 16-bit x86 compatible BIOS. This is used by default 1907when B<device_model_version=qemu-xen-traditional>. This is the only BIOS 1908option supported when B<device_model_version=qemu-xen-traditional>. This is 1909the BIOS used by all previous Xen versions. 1910 1911=item B<seabios> 1912 1913Loads SeaBIOS, a 16-bit x86 compatible BIOS. This is used by default 1914with device_model_version=qemu-xen. 1915 1916=item B<ovmf> 1917 1918Loads OVMF, a standard UEFI firmware by Tianocore project. 1919Requires device_model_version=qemu-xen. 1920 1921=back 1922 1923=item B<bios_path_override="PATH"> 1924 1925Override the path to the blob to be used as BIOS. The blob provided here MUST 1926be consistent with the B<bios=> which you have specified. You should not 1927normally need to specify this option. 1928 1929This option does not have any effect if using B<bios="rombios"> or 1930B<device_model_version="qemu-xen-traditional">. 1931 1932=item B<pae=BOOLEAN> 1933 1934Hide or expose the IA32 Physical Address Extensions. These extensions 1935make it possible for a 32 bit guest Operating System to access more 1936than 4GB of RAM. Enabling PAE also enabled other features such as 1937NX. PAE is required if you wish to run a 64-bit guest Operating 1938System. In general, you should leave this enabled and allow the guest 1939Operating System to choose whether or not to use PAE. (X86 only) 1940 1941=item B<acpi=BOOLEAN> 1942 1943Expose ACPI (Advanced Configuration and Power Interface) tables from 1944the virtual firmware to the guest Operating System. ACPI is required 1945by most modern guest Operating Systems. This option is enabled by 1946default and usually you should omit it. However, it may be necessary to 1947disable ACPI for compatibility with some guest Operating Systems. 1948This option is true for x86 while it's false for ARM by default. 1949 1950=item B<acpi_s3=BOOLEAN> 1951 1952Include the S3 (suspend-to-ram) power state in the virtual firmware 1953ACPI table. True (1) by default. 1954 1955=item B<acpi_s4=BOOLEAN> 1956 1957Include S4 (suspend-to-disk) power state in the virtual firmware ACPI 1958table. True (1) by default. 1959 1960=item B<acpi_laptop_slate=BOOLEAN> 1961 1962Include the Windows laptop/slate mode switch device in the virtual 1963firmware ACPI table. False (0) by default. 1964 1965=item B<apic=BOOLEAN> 1966 1967B<(x86 only)> Include information regarding APIC (Advanced Programmable Interrupt 1968Controller) in the firmware/BIOS tables on a single processor 1969guest. This causes the MP (multiprocessor) and PIR (PCI Interrupt 1970Routing) tables to be exported by the virtual firmware. This option 1971has no effect on a guest with multiple virtual CPUs as they must 1972always include these tables. This option is enabled by default and you 1973should usually omit it but it may be necessary to disable these 1974firmware tables when using certain older guest Operating 1975Systems. These tables have been superseded by newer constructs within 1976the ACPI tables. 1977 1978=item B<nx=BOOLEAN> 1979 1980B<(x86 only)> Hides or exposes the No-eXecute capability. This allows a guest 1981Operating System to map pages in such a way that they cannot be executed which 1982can enhance security. This options requires that PAE also be 1983enabled. 1984 1985=item B<hpet=BOOLEAN> 1986 1987B<(x86 only)> Enables or disables HPET (High Precision Event Timer). This 1988option is enabled by default and you should usually omit it. 1989It may be necessary to disable the HPET in order to improve compatibility with 1990guest Operating Systems. 1991 1992=item B<altp2m="MODE"> 1993 1994B<(x86 only)> Specifies the access mode to the alternate-p2m capability. 1995Alternate-p2m allows a guest to manage multiple p2m guest physical "memory 1996views" (as opposed to a single p2m). 1997You may want this option if you want to access-control/isolate 1998access to specific guest physical memory pages accessed by the guest, e.g. for 1999domain memory introspection or for isolation/access-control of memory between 2000components within a single guest domain. This option is disabled by default. 2001 2002The valid values are as follows: 2003 2004=over 4 2005 2006=item B<disabled> 2007 2008Altp2m is disabled for the domain (default). 2009 2010=item B<mixed> 2011 2012The mixed mode allows access to the altp2m interface for both in-guest 2013and external tools as well. 2014 2015=item B<external> 2016 2017Enables access to the alternate-p2m capability by external privileged tools. 2018 2019=item B<limited> 2020 2021Enables limited access to the alternate-p2m capability, 2022ie. giving the guest access only to enable/disable the VMFUNC and #VE features. 2023 2024=back 2025 2026=item B<altp2mhvm=BOOLEAN> 2027 2028Enables or disables HVM guest access to alternate-p2m capability. 2029Alternate-p2m allows a guest to manage multiple p2m guest physical 2030"memory views" (as opposed to a single p2m). This option is 2031disabled by default and is available only to HVM domains. 2032You may want this option if you want to access-control/isolate 2033access to specific guest physical memory pages accessed by 2034the guest, e.g. for HVM domain memory introspection or 2035for isolation/access-control of memory between components within 2036a single guest HVM domain. B<This option is deprecated, use the option 2037"altp2m" instead.> 2038 2039B<Note>: While the option "altp2mhvm" is deprecated, legacy applications for 2040x86 systems will continue to work using it. 2041 2042=item B<nestedhvm=BOOLEAN> 2043 2044Enable or disables guest access to hardware virtualisation features, 2045e.g. it allows a guest Operating System to also function as a 2046hypervisor. You may want this 2047option if you want to run another hypervisor (including another copy 2048of Xen) within a Xen guest or to support a guest Operating System 2049which uses hardware virtualisation extensions (e.g. Windows XP 2050compatibility mode on more modern Windows OS). 2051This option is disabled by default. 2052 2053=item B<cpuid="LIBXL_STRING"> or B<cpuid=[ "XEND_STRING", "XEND_STRING" ]> 2054 2055Configure the value returned when a guest executes the CPUID instruction. 2056Two versions of config syntax are recognized: libxl and xend. 2057 2058Both formats use a common notation for specifying a single feature bit. 2059Possible values are: 2060 '1' -> force the corresponding bit to 1 2061 '0' -> force to 0 2062 'x' -> Get a safe value (pass through and mask with the default policy) 2063 'k' -> pass through the host bit value (at boot only - value preserved on migrate) 2064 's' -> legacy alias for 'k' 2065 2066B<Libxl format>: 2067 2068=over 4 2069 2070The libxl format is a single string, starting with the word "host", and 2071followed by a comma separated list of key=value pairs. A few keys take a 2072numerical value, all others take a single character which describes what to do 2073with the feature bit. e.g.: 2074 2075=over 4 2076 2077cpuid="host,tm=0,sse3=0" 2078 2079=back 2080 2081List of keys taking a value: 2082 2083=over 4 2084 2085apicidsize brandid clflush family localapicid maxleaf maxhvleaf model nc 2086proccount procpkg stepping 2087 2088=back 2089 2090List of keys taking a character can be found in the public header file 2091L<arch-x86/cpufeatureset.h|https://xenbits.xen.org/docs/unstable/hypercall/x86_64/include,public,arch-x86,cpufeatureset.h.html> 2092 2093The feature names described in C<cpufeatureset.h> should be specified in all 2094lowercase letters, and with underscores converted to hyphens. For example in 2095order to reference feature C<LAHF_LM> the string C<lahf-lm> should be used. 2096 2097Note that C<clflush> is described as an option that takes a value, and that 2098takes precedence over the C<clflush> flag in C<cpufeatureset.h>. The feature 2099flag must be referenced as C<clfsh>. 2100 2101=back 2102 2103B<Xend format>: 2104 2105=over 4 2106 2107Xend format consists of an array of one or more strings of the form 2108"leaf:reg=bitstring,...". e.g. (matching the libxl example above): 2109 2110=over 4 2111 2112cpuid=["1:ecx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0,edx=xx0xxxxxxxxxxxxxxxxxxxxxxxxxxxxx", ...] 2113 2114=back 2115 2116"leaf" is an integer, either decimal or hex with a "0x" prefix. e.g. to 2117specify something in the AMD feature leaves, use "0x80000001:ecx=...". 2118 2119Some leaves have subleaves which can be specified as "leaf,subleaf". e.g. for 2120the Intel structured feature leaf, use "7,0:ebx=..." 2121 2122The bitstring represents all bits in the register, its length must be 32 2123chars. Each successive character represent a lesser-significant bit. 2124 2125=back 2126 2127Note: when specifying B<cpuid> for hypervisor leaves (0x4000xxxx major group) 2128only the lowest 8 bits of leaf's 0x4000xx00 EAX register are processed, the 2129rest are ignored (these 8 bits signify maximum number of hypervisor leaves). 2130 2131More info about the CPUID instruction can be found in the processor manuals, 2132and on Wikipedia: L<https://en.wikipedia.org/wiki/CPUID> 2133 2134=item B<acpi_firmware="STRING"> 2135 2136Specifies a path to a file that contains extra ACPI firmware tables to pass into 2137a guest. The file can contain several tables in their binary AML form 2138concatenated together. Each table self describes its length so no additional 2139information is needed. These tables will be added to the ACPI table set in the 2140guest. Note that existing tables cannot be overridden by this feature. For 2141example, this cannot be used to override tables like DSDT, FADT, etc. 2142 2143=item B<smbios_firmware="STRING"> 2144 2145Specifies a path to a file that contains extra SMBIOS firmware structures to 2146pass into a guest. The file can contain a set of DMTF predefined structures 2147which will override the internal defaults. Not all predefined structures can be 2148overridden, 2149only the following types: 0, 1, 2, 3, 11, 22, 39. The file can also contain any 2150number of vendor defined SMBIOS structures (type 128 - 255). Since SMBIOS 2151structures do not present their overall size, each entry in the file must be 2152preceded by a 32b integer indicating the size of the following structure. 2153 2154=item B<smbios=[ "SMBIOS_SPEC_STRING", "SMBIOS_SPEC_STRING", ...]> 2155 2156Specifies the SMBIOS values to be provided to the guest. These set or 2157override specific entries in the tables provided to the guest. 2158 2159Each B<SMBIOS_SPEC_STRING> is a C<KEY=VALUE> string from the following list: 2160 2161=over 4 2162 2163=item B<bios_vendor=STRING> 2164 2165=item B<bios_version=STRING> 2166 2167=item B<system_manufacturer=STRING> 2168 2169=item B<system_product_name=STRING> 2170 2171=item B<system_version=STRING> 2172 2173=item B<system_serial_number=STRING> 2174 2175=item B<baseboard_manufacturer=STRING> 2176 2177=item B<baseboard_product_name=STRING> 2178 2179=item B<baseboard_version=STRING> 2180 2181=item B<baseboard_serial_number=STRING> 2182 2183=item B<baseboard_asset_tag=STRING> 2184 2185=item B<baseboard_location_in_chassis=STRING> 2186 2187=item B<enclosure_manufacturer=STRING> 2188 2189=item B<enclosure_serial_number=STRING> 2190 2191=item B<enclosure_asset_tag=STRING> 2192 2193=item B<battery_manufacturer=STRING> 2194 2195=item B<battery_device_name=STRING> 2196 2197=item B<oem=STRING> 2198 2199oem= can be specified up to 99 times. 2200 2201=back 2202 2203=item B<ms_vm_genid="OPTION"> 2204 2205Provide a VM generation ID to the guest. 2206 2207The VM generation ID is a 128-bit random number that a guest may use 2208to determine if the guest has been restored from an earlier snapshot 2209or cloned. 2210 2211This is required for Microsoft Windows Server 2012 (and later) domain 2212controllers. 2213 2214Valid options are: 2215 2216=over 4 2217 2218=item B<generate> 2219 2220Generate a random VM generation ID every time the domain is created or 2221restored. 2222 2223=item B<none> 2224 2225Do not provide a VM generation ID. 2226 2227=back 2228 2229See also "Virtual Machine Generation ID" by Microsoft: 2230L<https://docs.microsoft.com/en-us/windows/win32/hyperv_v2/virtual-machine-generation-identifier> 2231 2232=back 2233 2234=head3 Guest Virtual Time Controls 2235 2236=over 4 2237 2238=item B<tsc_mode="MODE"> 2239 2240B<(x86 only)> Specifies how the TSC (Time Stamp Counter) should be provided to 2241the guest. B<Specifying this option as a number is deprecated.> 2242 2243Options are: 2244 2245=over 4 2246 2247=item B<default> 2248 2249Guest rdtsc/p is executed natively when monotonicity can be guaranteed 2250and emulated otherwise (with frequency scaled if necessary). 2251 2252If a HVM container in B<default> TSC mode is created on a host that 2253provides constant host TSC, its guest TSC frequency will be the same 2254as the host. If it is later migrated to another host that provide 2255constant host TSC and supports Intel VMX TSC scaling/AMD SVM TSC 2256ratio, its guest TSC frequency will be the same before and after 2257migration, and guest rdtsc/p will be executed natively after migration as well 2258 2259=item B<always_emulate> 2260 2261Guest rdtsc/p is always emulated and the virtual TSC will appear to increment 2262(kernel and user) at a fixed 1GHz rate, regardless of the pCPU HZ rate or 2263power state. Although there is an overhead associated with emulation, 2264this will NOT affect underlying CPU performance. 2265 2266=item B<native> 2267 2268Guest rdtsc/p is always executed natively (no monotonicity/frequency 2269guarantees). Guest rdtsc/p is emulated at native frequency if unsupported 2270by h/w, else executed natively. 2271 2272=item B<native_paravirt> 2273 2274This mode has been removed. 2275 2276=back 2277 2278Please see B<xen-tscmode(7)> for more information on this option. 2279 2280=item B<localtime=BOOLEAN> 2281 2282Set the real time clock to local time or to UTC. False (0) by default, 2283i.e. set to UTC. 2284 2285=item B<rtc_timeoffset=SECONDS> 2286 2287Set the real time clock offset in seconds. No offset (0) by default. 2288 2289=item B<vpt_align=BOOLEAN> 2290 2291Specifies that periodic Virtual Platform Timers should be aligned to 2292reduce guest interrupts. Enabling this option can reduce power 2293consumption, especially when a guest uses a high timer interrupt 2294frequency (HZ) values. The default is true (1). 2295 2296=item B<timer_mode="MODE"> 2297 2298Specifies the mode for Virtual Timers. The valid values are as follows: 2299 2300=over 4 2301 2302=item B<delay_for_missed_ticks> 2303 2304Delay for missed ticks. Do not advance a vCPU's time beyond the 2305correct delivery time for interrupts that have been missed due to 2306preemption. Deliver missed interrupts when the vCPU is rescheduled and 2307advance the vCPU's virtual time stepwise for each one. 2308 2309=item B<no_delay_for_missed_ticks> 2310 2311No delay for missed ticks. As above, missed interrupts are delivered, 2312but guest time always tracks wallclock (i.e., real) time while doing 2313so. This is the default. 2314 2315=item B<no_missed_ticks_pending> 2316 2317No missed interrupts are held pending. Instead, to ensure ticks are 2318delivered at some non-zero rate, if we detect missed ticks then the 2319internal tick alarm is not disabled if the vCPU is preempted during 2320the next tick period. 2321 2322=item B<one_missed_tick_pending> 2323 2324One missed tick pending. Missed interrupts are collapsed 2325together and delivered as one 'late tick'. Guest time always tracks 2326wallclock (i.e., real) time. 2327 2328=back 2329 2330=back 2331 2332=head3 Memory layout 2333 2334=over 4 2335 2336=item B<mmio_hole=MBYTES> 2337 2338Specifies the size the MMIO hole below 4GiB will be. Only valid for 2339B<device_model_version="qemu-xen">. 2340 2341Cannot be smaller than 256. Cannot be larger than 3840. 2342 2343Known good large value is 3072. 2344 2345=back 2346 2347=head3 Support for Paravirtualisation of HVM Guests 2348 2349The following options allow Paravirtualised features (such as devices) 2350to be exposed to the guest Operating System in an HVM guest. 2351Utilising these features requires specific guest support but when 2352available they will result in improved performance. 2353 2354=over 4 2355 2356=item B<xen_platform_pci=BOOLEAN> 2357 2358Enable or disable the Xen platform PCI device. The presence of this 2359virtual device enables a guest Operating System (subject to the 2360availability of suitable drivers) to make use of paravirtualisation 2361features such as disk and network devices etc. Enabling these drivers 2362improves performance and is strongly recommended when available. PV 2363drivers are available for various Operating Systems including HVM 2364Linux (out-of-the-box) and Microsoft 2365Windows L<https://xenproject.org/windows-pv-drivers/>. 2366 2367Setting B<xen_platform_pci=0> with the default device_model "qemu-xen" 2368requires at least QEMU 1.6. 2369 2370=item B<viridian=[ "GROUP", "GROUP", ...]> or B<viridian=BOOLEAN> 2371 2372The groups of Microsoft Hyper-V (AKA viridian) compatible enlightenments 2373exposed to the guest. The following groups of enlightenments may be 2374specified: 2375 2376=over 4 2377 2378=item B<base> 2379 2380This group incorporates the Hypercall MSRs, Virtual processor index MSR, 2381and APIC access MSRs. These enlightenments can improve performance of 2382Windows Vista and Windows Server 2008 onwards and setting this option 2383for such guests is strongly recommended. 2384This group is also a pre-requisite for all others. If it is disabled 2385then it is an error to attempt to enable any other group. 2386 2387=item B<freq> 2388 2389This group incorporates the TSC and APIC frequency MSRs. These 2390enlightenments can improve performance of Windows 7 and Windows 2391Server 2008 R2 onwards. 2392 2393=item B<time_ref_count> 2394 2395This group incorporates Partition Time Reference Counter MSR. This 2396enlightenment can improve performance of Windows 8 and Windows 2397Server 2012 onwards. 2398 2399=item B<reference_tsc> 2400 2401This set incorporates the Partition Reference TSC MSR. This 2402enlightenment can improve performance of Windows 7 and Windows 2403Server 2008 R2 onwards. 2404 2405=item B<hcall_remote_tlb_flush> 2406 2407This set incorporates use of hypercalls for remote TLB flushing. 2408This enlightenment may improve performance of Windows guests running 2409on hosts with higher levels of (physical) CPU contention. 2410 2411=item B<apic_assist> 2412 2413This set incorporates use of the APIC assist page to avoid EOI of 2414the local APIC. 2415This enlightenment may improve performance of guests that make use of 2416per-vCPU event channel upcall vectors. 2417Note that this enlightenment will have no effect if the guest is 2418using APICv posted interrupts. 2419 2420=item B<crash_ctl> 2421 2422This group incorporates the crash control MSRs. These enlightenments 2423allow Windows to write crash information such that it can be logged 2424by Xen. 2425 2426=item B<stimer> 2427 2428This set incorporates the SynIC and synthetic timer MSRs. Windows will 2429use synthetic timers in preference to emulated HPET for a source of 2430ticks and hence enabling this group will ensure that ticks will be 2431consistent with use of an enlightened time source (B<time_ref_count> or 2432B<reference_tsc>). 2433 2434=item B<hcall_ipi> 2435 2436This set incorporates use of a hypercall for interprocessor interrupts. 2437This enlightenment may improve performance of Windows guests with multiple 2438virtual CPUs. 2439 2440=item B<ex_processor_masks> 2441 2442This set enables new hypercall variants taking a variably-sized sparse 2443B<Virtual Processor Set> as an argument, rather than a simple 64-bit 2444mask. Hence this enlightenment must be specified for guests with more 2445than 64 vCPUs if B<hcall_remote_tlb_flush> and/or B<hcall_ipi> are also 2446specified. 2447 2448=item B<no_vp_limit> 2449 2450This group when set indicates to a guest that the hypervisor does not 2451explicitly have any limits on the number of Virtual processors a guest 2452is allowed to bring up. It is strongly recommended to keep this enabled 2453for guests with more than 64 vCPUs. 2454 2455=item B<cpu_hotplug> 2456 2457This set enables dynamic changes to Virtual processor states in Windows 2458guests effectively allowing vCPU hotplug. 2459 2460=item B<defaults> 2461 2462This is a special value that enables the default set of groups, which 2463is currently the B<base>, B<freq>, B<time_ref_count>, B<apic_assist>, 2464B<crash_ctl>, B<stimer>, B<no_vp_limit> and B<cpu_hotplug> groups. 2465 2466=item B<all> 2467 2468This is a special value that enables all available groups. 2469 2470=back 2471 2472Groups can be disabled by prefixing the name with '!'. So, for example, 2473to enable all groups except B<freq>, specify: 2474 2475=over 4 2476 2477B<viridian=[ "all", "!freq" ]> 2478 2479=back 2480 2481For details of the enlightenments see the latest version of Microsoft's 2482Hypervisor Top-Level Functional Specification. 2483 2484The enlightenments should be harmless for other versions of Windows 2485(although they will not give any benefit) and the majority of other 2486non-Windows OSes. 2487However it is known that they are incompatible with some other Operating 2488Systems and in some circumstance can prevent Xen's own paravirtualisation 2489interfaces for HVM guests from being used. 2490 2491The viridian option can be specified as a boolean. A value of true (1) 2492is equivalent to the list [ "defaults" ], and a value of false (0) is 2493equivalent to an empty list. 2494 2495=item B<hvm_pirq=BOOLEAN> 2496 2497Select whether the guest is allowed to route interrupts from devices (either 2498emulated or passed through) over event channels. 2499 2500This option is disabled by default. 2501 2502=back 2503 2504=head3 Emulated VGA Graphics Device 2505 2506The following options control the features of the emulated graphics 2507device. Many of these options behave similarly to the equivalent key 2508in the B<VFB_SPEC_STRING> for configuring virtual frame buffer devices 2509(see above). 2510 2511=over 4 2512 2513=item B<videoram=MBYTES> 2514 2515Sets the amount of RAM which the emulated video card will contain, 2516which in turn limits the resolutions and bit depths which will be 2517available. 2518 2519When using the qemu-xen-traditional device-model, the default as well as 2520minimum amount of video RAM for stdvga is 8 MB, which is sufficient for e.g. 25211600x1200 at 32bpp. For the upstream qemu-xen device-model, the default and 2522minimum is 16 MB. 2523 2524When using the emulated Cirrus graphics card (B<vga="cirrus">) and the 2525qemu-xen-traditional device-model, the amount of video RAM is fixed at 4 MB, 2526which is sufficient for 1024x768 at 32 bpp. For the upstream qemu-xen 2527device-model, the default and minimum is 8 MB. 2528 2529For QXL vga, both the default and minimal are 128MB. 2530If B<videoram> is set less than 128MB, an error will be triggered. 2531 2532=item B<stdvga=BOOLEAN> 2533 2534Specifies a standard VGA card with VBE (VESA BIOS Extensions) as the 2535emulated graphics device. If your guest supports VBE 2.0 or 2536later (e.g. Windows XP onwards) then you should enable this. 2537stdvga supports more video ram and bigger resolutions than Cirrus. 2538The default is false (0) which means to emulate 2539a Cirrus Logic GD5446 VGA card. 2540B<This option is deprecated, use vga="stdvga" instead>. 2541 2542=item B<vga="STRING"> 2543 2544Selects the emulated video card. 2545Options are: B<none>, B<stdvga>, B<cirrus> and B<qxl>. 2546The default is B<cirrus>. 2547 2548In general, QXL should work with the Spice remote display protocol 2549for acceleration, and a QXL driver is necessary in the guest in that case. 2550QXL can also work with the VNC protocol, but it will be like a standard 2551VGA card without acceleration. 2552 2553=item B<vnc=BOOLEAN> 2554 2555Allow access to the display via the VNC protocol. This enables the 2556other VNC-related settings. The default is (1) enabled. 2557 2558=item B<vnclisten="ADDRESS[:DISPLAYNUM]"> 2559 2560Specifies the IP address and, optionally, the VNC display number to use. 2561 2562=item B<vncdisplay=DISPLAYNUM> 2563 2564Specifies the VNC display number to use. The actual TCP port number 2565will be DISPLAYNUM+5900. 2566 2567=item B<vncunused=BOOLEAN> 2568 2569Requests that the VNC display setup searches for a free TCP port to use. 2570The actual display used can be accessed with B<xl vncviewer>. 2571 2572=item B<vncpasswd="PASSWORD"> 2573 2574Specifies the password for the VNC server. If the password is set to an 2575empty string, authentication on the VNC server will be disabled 2576allowing any user to connect. 2577 2578=item B<keymap="LANG"> 2579 2580Configure the keymap to use for the keyboard associated with this 2581display. If the input method does not easily support raw keycodes 2582(e.g. this is often the case when using VNC) then this allows us to 2583correctly map the input keys into keycodes seen by the guest. The 2584specific values which are accepted are defined by the version of the 2585device-model which you are using. See B<Keymaps> below or consult the 2586B<qemu(1)> manpage. The default is B<en-us>. 2587 2588=item B<sdl=BOOLEAN> 2589 2590Specifies that the display should be presented via an X window (using 2591Simple DirectMedia Layer). The default is (0) not enabled. 2592 2593=item B<opengl=BOOLEAN> 2594 2595Enable OpenGL acceleration of the SDL display. Only effects machines 2596using B<device_model_version="qemu-xen-traditional"> and only if the 2597device-model was compiled with OpenGL support. Default is (0) false. 2598 2599=item B<nographic=BOOLEAN> 2600 2601Enable or disable the virtual graphics device. The default is to 2602provide a VGA graphics device but this option can be used to disable 2603it. 2604 2605=back 2606 2607=head3 Spice Graphics Support 2608 2609The following options control the features of SPICE. 2610 2611=over 4 2612 2613=item B<spice=BOOLEAN> 2614 2615Allow access to the display via the SPICE protocol. This enables the 2616other SPICE-related settings. 2617 2618=item B<spicehost="ADDRESS"> 2619 2620Specifies the interface address to listen on if given, otherwise any 2621interface. 2622 2623=item B<spiceport=NUMBER> 2624 2625Specifies the port to listen on by the SPICE server if SPICE is 2626enabled. 2627 2628=item B<spicetls_port=NUMBER> 2629 2630Specifies the secure port to listen on by the SPICE server if SPICE 2631is enabled. At least one of B<spiceport> or B<spicetls_port> must be 2632given if SPICE is enabled. 2633 2634B<Note:> the options depending on B<spicetls_port> 2635have not been supported. 2636 2637=item B<spicedisable_ticketing=BOOLEAN> 2638 2639Enable clients to connect without specifying a password. When disabled, 2640B<spicepasswd> must be set. The default is (0) false. 2641 2642=item B<spicepasswd="PASSWORD"> 2643 2644Specify the password which is used by clients for establishing a connection. 2645 2646=item B<spiceagent_mouse=BOOLEAN> 2647 2648Whether SPICE agent is used for client mouse mode. The default is (1) true. 2649 2650=item B<spicevdagent=BOOLEAN> 2651 2652Enables the SPICE vdagent. The SPICE vdagent is an optional component for 2653enhancing user experience and performing guest-oriented management 2654tasks. Its features include: client mouse mode (no need to grab the mouse 2655by the client, no mouse lag), automatic adjustment of screen resolution, 2656copy and paste (text and image) between the client and the guest. It also 2657requires the vdagent service installed on the guest OS to work. 2658The default is (0) disabled. 2659 2660=item B<spice_clipboard_sharing=BOOLEAN> 2661 2662Enables SPICE clipboard sharing (copy/paste). It requires that 2663B<spicevdagent> is enabled. The default is (0) false. 2664 2665=item B<spiceusbredirection=NUMBER> 2666 2667Enables SPICE USB redirection. Creates a NUMBER of USB redirection channels 2668for redirecting up to 4 USB devices from the SPICE client to the guest's QEMU. 2669It requires an USB controller and, if not defined, it will automatically add 2670an USB2.0 controller. The default is (0) disabled. 2671 2672=item B<spice_image_compression="COMPRESSION"> 2673 2674Specifies what image compression is to be used by SPICE (if given), otherwise 2675the QEMU default will be used. Please see the documentation of your QEMU 2676version for more details. 2677 2678Available options are: B<auto_glz, auto_lz, quic, glz, lz, off>. 2679 2680=item B<spice_streaming_video="VIDEO"> 2681 2682Specifies what streaming video setting is to be used by SPICE (if given), 2683otherwise the QEMU default will be used. 2684 2685Available options are: B<filter, all, off>. 2686 2687=back 2688 2689=head3 Miscellaneous Emulated Hardware 2690 2691=over 4 2692 2693=item B<serial=[ "DEVICE", "DEVICE", ...]> 2694 2695Redirect virtual serial ports to B<DEVICE>s. Please see the 2696B<-serial> option in the B<qemu(1)> manpage for details of the valid 2697B<DEVICE> options. Default is B<vc> when in graphical mode and 2698B<stdio> if B<nographic=1> is used. 2699 2700The form serial=DEVICE is also accepted for backwards compatibility. 2701 2702=item B<soundhw="DEVICE"> 2703 2704Select the virtual sound card to expose to the guest. The valid devices are 2705B<hda>, B<ac97>, B<es1370>, B<adlib>, B<cs4231a>, B<gus>, B<sb16> if there are 2706available with the device model QEMU. The default is not to export any sound 2707device. 2708 2709=item B<vkb_device=BOOLEAN> 2710 2711Specifies that the HVM guest gets a vkdb. The default is true (1). 2712 2713This option is only used when B<vkb=[]> is unset. 2714 2715=item B<usb=BOOLEAN> 2716 2717Enables or disables an emulated USB bus in the guest. 2718 2719=item B<usbversion=NUMBER> 2720 2721Specifies the type of an emulated USB bus in the guest, values 1 for USB1.1, 27222 for USB2.0 and 3 for USB3.0. It is available only with an upstream QEMU. 2723Due to implementation limitations this is not compatible with the B<usb> 2724and B<usbdevice> parameters. 2725Default is (0) no USB controller defined. 2726 2727=item B<usbdevice=[ "DEVICE", "DEVICE", ...]> 2728 2729Adds B<DEVICE>s to the emulated USB bus. The USB bus must also be 2730enabled using B<usb=1>. The most common use for this option is 2731B<usbdevice=['tablet']> which adds a pointer device using absolute 2732coordinates. Such devices function better than relative coordinate 2733devices (such as a standard mouse) since many methods of exporting 2734guest graphics (such as VNC) work better in this mode. Note that this 2735is independent of the actual pointer device you are using on the 2736host/client side. 2737 2738Host devices can also be passed through in this way, by specifying 2739host:USBID, where USBID is of the form xxxx:yyyy. The USBID can 2740typically be found by using B<lsusb(1)> or B<usb-devices(1)>. 2741 2742If you wish to use the "host:bus.addr" format, remove any leading '0' from the 2743bus and addr. For example, for the USB device on bus 008 dev 002, you should 2744write "host:8.2". 2745 2746The form usbdevice=DEVICE is also accepted for backwards compatibility. 2747 2748More valid options can be found in the "usbdevice" section of the QEMU 2749documentation. 2750 2751=item B<vendor_device="VENDOR_DEVICE"> 2752 2753Selects which variant of the QEMU xen-pvdevice should be used for this 2754guest. Valid values are: 2755 2756=over 4 2757 2758=item B<none> 2759 2760The xen-pvdevice should be omitted. This is the default. 2761 2762=item B<xenserver> 2763 2764The xenserver variant of the xen-pvdevice (device-id=C000) will be 2765specified, enabling the use of XenServer PV drivers in the guest. 2766 2767=back 2768 2769This parameter only takes effect when device_model_version=qemu-xen. 2770See B<xen-pci-device-reservations(7)> for more information. 2771 2772=back 2773 2774=head2 PVH Guest Specific Options 2775 2776=over 4 2777 2778=item B<nestedhvm=BOOLEAN> 2779 2780Enable or disables guest access to hardware virtualisation features, 2781e.g. it allows a guest Operating System to also function as a hypervisor. 2782You may want this option if you want to run another hypervisor (including 2783another copy of Xen) within a Xen guest or to support a guest Operating 2784System which uses hardware virtualisation extensions (e.g. Windows XP 2785compatibility mode on more modern Windows OS). 2786 2787This option is disabled by default. 2788 2789=item B<bootloader="PROGRAM"> 2790 2791Run C<PROGRAM> to find the kernel image and ramdisk to use. Normally 2792C<PROGRAM> would be C<pygrub>, which is an emulation of 2793grub/grub2/syslinux. Either B<kernel> or B<bootloader> must be specified 2794for PV guests. 2795 2796=item B<bootloader_args=[ "ARG", "ARG", ...]> 2797 2798Append B<ARG>s to the arguments to the B<bootloader> 2799program. Alternatively if the argument is a simple string then it will 2800be split into words at whitespace B<(this second option is deprecated)>. 2801 2802=item B<bootloader_restrict=BOOLEAN> 2803 2804Attempt to restrict the bootloader after startup, to limit the 2805consequences of security vulnerabilities due to parsing guest 2806owned image files. 2807 2808See docs/features/qemu-deprivilege.pandoc for more information 2809on how to setup the unprivileged users. 2810 2811Note that running the bootloader in restricted mode also implies using 2812non-interactive mode, and the disk image must be readable by the 2813restricted user. 2814 2815=item B<bootloader_user=USERNAME> 2816 2817When using bootloader_restrict, run the bootloader as this user. 2818 2819NOTE: Each domain MUST have a SEPARATE username. 2820 2821See docs/features/qemu-deprivilege.pandoc for more information. 2822 2823=item B<timer_mode="MODE"> 2824 2825Specifies the mode for Virtual Timers. The valid values are as follows: 2826 2827=over 4 2828 2829=item B<delay_for_missed_ticks> 2830 2831Delay for missed ticks. Do not advance a vCPU's time beyond the 2832correct delivery time for interrupts that have been missed due to 2833preemption. Deliver missed interrupts when the vCPU is rescheduled and 2834advance the vCPU's virtual time stepwise for each one. 2835 2836=item B<no_delay_for_missed_ticks> 2837 2838No delay for missed ticks. As above, missed interrupts are delivered, 2839but guest time always tracks wallclock (i.e., real) time while doing 2840so. This is the default. 2841 2842=item B<no_missed_ticks_pending> 2843 2844No missed interrupts are held pending. Instead, to ensure ticks are 2845delivered at some non-zero rate, if we detect missed ticks then the 2846internal tick alarm is not disabled if the vCPU is preempted during 2847the next tick period. 2848 2849=item B<one_missed_tick_pending> 2850 2851One missed tick pending. Missed interrupts are collapsed 2852together and delivered as one 'late tick'. Guest time always tracks 2853wallclock (i.e., real) time. 2854 2855=back 2856 2857=back 2858 2859=head3 Paging 2860 2861The following options control the mechanisms used to virtualise guest 2862memory. The defaults are selected to give the best results for the 2863common cases so you should normally leave these options 2864unspecified. 2865 2866=over 4 2867 2868=item B<hap=BOOLEAN> 2869 2870Turns "hardware assisted paging" (the use of the hardware nested page 2871table feature) on or off. This feature is called EPT (Extended Page 2872Tables) by Intel and NPT (Nested Page Tables) or RVI (Rapid 2873Virtualisation Indexing) by AMD. If turned 2874off, Xen will run the guest in "shadow page table" mode where the 2875guest's page table updates and/or TLB flushes etc. will be emulated. 2876Use of HAP is the default when available. 2877 2878=item B<oos=BOOLEAN> 2879 2880Turns "out of sync pagetables" on or off. When running in shadow page 2881table mode, the guest's page table updates may be deferred as 2882specified in the Intel/AMD architecture manuals. However, this may 2883expose unexpected bugs in the guest, or find bugs in Xen, so it is 2884possible to disable this feature. Use of out of sync page tables, 2885when Xen thinks it appropriate, is the default. 2886 2887=item B<shadow_memory=MBYTES> 2888 2889Number of megabytes to set aside for shadowing guest pagetable pages 2890(effectively acting as a cache of translated pages) or to use for HAP 2891state. By default this is 1MB per guest vCPU plus 8KB per MB of guest 2892RAM. You should not normally need to adjust this value. However, if you 2893are not using hardware assisted paging (i.e. you are using shadow 2894mode) and your guest workload consists of a very large number of 2895similar processes then increasing this value may improve performance. 2896 2897On Arm, this field is used to determine the size of the guest P2M pages 2898pool, and the default value is the same as x86 HAP mode, plus 512KB to 2899cover the extended regions. Users should adjust this value if bigger 2900P2M pool size is needed. 2901 2902=back 2903 2904=head2 Device-Model Options 2905 2906The following options control the selection of the device-model. This 2907is the component which provides emulation of the virtual devices to an 2908HVM guest. For a PV guest a device-model is sometimes used to provide 2909backends for certain PV devices (most usually a virtual framebuffer 2910device). 2911 2912=over 4 2913 2914=item B<device_model_version="DEVICE-MODEL"> 2915 2916Selects which variant of the device-model should be used for this 2917guest. 2918 2919Valid values are: 2920 2921=over 4 2922 2923=item B<qemu-xen> 2924 2925Use the device-model merged into the upstream QEMU project. 2926This device-model is the default for Linux dom0. 2927 2928=item B<qemu-xen-traditional> 2929 2930Use the device-model based upon the historical Xen fork of QEMU. 2931This device-model is still the default for NetBSD dom0. 2932 2933=back 2934 2935It is recommended to accept the default value for new guests. If 2936you have existing guests then, depending on the nature of the guest 2937Operating System, you may wish to force them to use the device 2938model which they were installed with. 2939 2940=item B<device_model_override="PATH"> 2941 2942Override the path to the binary to be used as the device-model running in 2943toolstack domain. The binary provided here MUST be consistent with the 2944B<device_model_version> which you have specified. You should not normally need 2945to specify this option. 2946 2947=item B<stubdomain_kernel="PATH"> 2948 2949Override the path to the kernel image used as device-model stubdomain. 2950The binary provided here MUST be consistent with the 2951B<device_model_version> which you have specified. 2952In case of B<qemu-xen-traditional> it is expected to be MiniOS-based stubdomain 2953image, in case of B<qemu-xen> it is expected to be Linux-based stubdomain 2954kernel. 2955 2956=item B<stubdomain_cmdline="STRING"> 2957 2958Set the device-model stubdomain kernel command line to B<STRING>. 2959 2960=item B<stubdomain_ramdisk="PATH"> 2961 2962Override the path to the ramdisk image used as device-model stubdomain. 2963The binary provided here is to be used by a kernel pointed by B<stubdomain_kernel>. 2964It is known to be used only by Linux-based stubdomain kernel. 2965 2966=item B<stubdomain_memory=MBYTES> 2967 2968Start the stubdomain with MBYTES megabytes of RAM. Default is 128. 2969 2970=item B<device_model_stubdomain_override=BOOLEAN> 2971 2972Override the use of stubdomain based device-model. Normally this will 2973be automatically selected based upon the other features and options 2974you have selected. 2975 2976=item B<device_model_stubdomain_seclabel="LABEL"> 2977 2978Assign an XSM security label to the device-model stubdomain. 2979 2980=item B<device_model_args=[ "ARG", "ARG", ...]> 2981 2982Pass additional arbitrary options on the device-model command 2983line. Each element in the list is passed as an option to the 2984device-model. 2985 2986=item B<device_model_args_pv=[ "ARG", "ARG", ...]> 2987 2988Pass additional arbitrary options on the device-model command line for 2989a PV device model only. Each element in the list is passed as an 2990option to the device-model. 2991 2992=item B<device_model_args_hvm=[ "ARG", "ARG", ...]> 2993 2994Pass additional arbitrary options on the device-model command line for 2995an HVM device model only. Each element in the list is passed as an 2996option to the device-model. 2997 2998=back 2999 3000=head2 Keymaps 3001 3002The keymaps available are defined by the device-model which you are 3003using. Commonly this includes: 3004 3005 ar de-ch es fo fr-ca hu ja mk no pt-br sv 3006 da en-gb et fr fr-ch is lt nl pl ru th 3007 de en-us fi fr-be hr it lv nl-be pt sl tr 3008 3009The default is B<en-us>. 3010 3011See B<qemu(1)> for more information. 3012 3013=head2 Architecture Specific options 3014 3015=head3 ARM 3016 3017=over 4 3018 3019=item B<gic_version="vN"> 3020 3021Version of the GIC emulated for the guest. 3022 3023Currently, the following versions are supported: 3024 3025=over 4 3026 3027=item B<v2> 3028 3029Emulate a GICv2 3030 3031=item B<v3> 3032 3033Emulate a GICv3. Note that the emulated GIC does not support the 3034GICv2 compatibility mode. 3035 3036=item B<default> 3037 3038Emulate the same version as the native GIC hardware used by the host where 3039the domain was created. 3040 3041=back 3042 3043This requires hardware compatibility with the requested version, either 3044natively or via hardware backwards compatibility support. 3045 3046=item B<vuart="uart"> 3047 3048To enable vuart console, user must specify the following option in the 3049VM config file: 3050 3051vuart = "sbsa_uart" 3052 3053Currently, only the "sbsa_uart" model is supported for ARM. 3054 3055=back 3056 3057=over 4 3058 3059=item B<sve="vl"> 3060 3061The `sve` parameter enables Arm Scalable Vector Extension (SVE) usage for the 3062guest and sets the maximum SVE vector length, the option is applicable only to 3063AArch64 guests. 3064A value equal to "disabled" disables the feature, this is the default value. 3065Allowed values are "disabled", "128", "256", "384", "512", "640", "768", "896", 3066"1024", "1152", "1280", "1408", "1536", "1664", "1792", "1920", "2048", "hw". 3067Specifying "hw" means that the maximum vector length supported by the platform 3068will be used. 3069Please be aware that if a specific vector length is passed and its value is 3070above the maximum vector length supported by the platform, an error will be 3071raised. 3072 3073=back 3074 3075=over 4 3076 3077=item B<nr_spis="NR_SPIS"> 3078 3079An optional integer parameter specifying the number of SPIs (Shared 3080Peripheral Interrupts) to allocate for the domain. Max is 991 SPIs. If 3081the value specified by the `nr_spis` parameter is smaller than the 3082number of SPIs calculated by the toolstack based on the devices 3083allocated for the domain, or the `nr_spis` parameter is not specified, 3084the value calculated by the toolstack will be used for the domain. 3085Otherwise, the value specified by the `nr_spis` parameter will be used. 3086The number of SPIs should match the highest interrupt ID that will be 3087assigned to the domain. 3088 3089=back 3090 3091=head3 x86 3092 3093=over 4 3094 3095=item B<mca_caps=[ "CAP", "CAP", ... ]> 3096 3097(HVM only) Enable MCA capabilities besides default ones enabled 3098by Xen hypervisor for the HVM domain. "CAP" can be one in the 3099following list: 3100 3101=over 4 3102 3103=item B<"lmce"> 3104 3105Intel local MCE 3106 3107=item B<default> 3108 3109No MCA capabilities in above list are enabled. 3110 3111=back 3112 3113=item B<msr_relaxed=BOOLEAN> 3114 3115The "msr_relaxed" boolean is an interim option, and defaults to false. 3116 3117In Xen 4.15, the default behaviour for unhandled MSRs has been changed, 3118to avoid leaking host data into guests, and to avoid breaking guest 3119logic which uses #GP probing to identify the availability of MSRs. 3120 3121However, this new stricter behaviour has the possibility to break 3122guests, and a more 4.14-like behaviour can be selected by setting this 3123option. 3124 3125If using this option is necessary to fix an issue, please report a bug. 3126 3127=back 3128 3129=head1 SEE ALSO 3130 3131=over 4 3132 3133=item L<xl(1)> 3134 3135=item L<xl.conf(5)> 3136 3137=item L<xlcpupool.cfg(5)> 3138 3139=item L<xl-disk-configuration(5)> 3140 3141=item L<xl-network-configuration(5)> 3142 3143=item L<xen-tscmode(7)> 3144 3145=back 3146 3147=head1 FILES 3148 3149F</etc/xen/NAME.cfg> 3150F<@XEN_DUMP_DIR@/NAME> 3151 3152=head1 BUGS 3153 3154This document may contain items which require further 3155documentation. Patches to improve incomplete items (or any other item) 3156are gratefully received on the xen-devel@lists.xenproject.org mailing 3157list. Please see L<https://wiki.xenproject.org/wiki/Submitting_Xen_Project_Patches> for 3158information on how to submit a patch to Xen. 3159 3160