1xl.cfg(5)                             Xen                            xl.cfg(5)
2
3
4

NAME

6       xl.cfg - xl domain configuration file syntax
7

SYNOPSIS

9        /etc/xen/xldomain
10

DESCRIPTION

12       Creating a VM (a domain in Xen terminology, sometimes called a guest)
13       with xl requires the provision of a domain configuration file.
14       Typically, these live in /etc/xen/DOMAIN.cfg, where DOMAIN is the name
15       of the domain.
16

SYNTAX

18       A domain configuration file consists of a series of options, specified
19       by using "KEY=VALUE" pairs.
20
21       Some "KEY"s are mandatory, some are general options which apply to any
22       guest type, while others relate only to specific guest types (e.g. PV
23       or HVM guests).
24
25       A "VALUE" can be one of:
26
27       "STRING"
28           A string, surrounded by either single or double quotes. But if the
29           STRING is part of a SPEC_STRING, the quotes should be omitted.
30
31       NUMBER
32           A number, in either decimal, octal (using a 0 prefix) or
33           hexadecimal (using a "0x" prefix) format.
34
35       BOOLEAN
36           A "NUMBER" interpreted as "False" (0) or "True" (any other value).
37
38       [ VALUE, VALUE, ... ]
39           A list of "VALUE"s of the above types. Lists can be heterogeneous
40           and nested.
41
42       The semantics of each "KEY" defines which type of "VALUE" is required.
43
44       Pairs may be separated either by a newline or a semicolon.  Both of the
45       following are valid:
46
47         name="h0"
48         type="hvm"
49
50         name="h0"; type="hvm"
51

OPTIONS

53   Mandatory Configuration Items
54       The following key is mandatory for any guest type.
55
56       name="NAME"
57           Specifies the name of the domain.  Names of domains existing on a
58           single host must be unique.
59
60   Selecting Guest Type
61       type="pv"
62           Specifies that this is to be a PV domain, suitable for hosting Xen-
63           aware guest operating systems. This is the default on x86.
64
65       type="pvh"
66           Specifies that this is to be an PVH domain. That is a lightweight
67           HVM-like guest without a device model and without many of the
68           emulated devices available to HVM guests. Note that this mode
69           requires a PVH aware kernel on x86. This is the default on Arm.
70
71       type="hvm"
72           Specifies that this is to be an HVM domain. That is, a fully
73           virtualised computer with emulated BIOS, disk and network
74           peripherals, etc.
75
76       Deprecated guest type selection
77
78       Note that the builder option is being deprecated in favor of the type
79       option.
80
81       builder="generic"
82           Specifies that this is to be a PV domain, suitable for hosting Xen-
83           aware guest operating systems. This is the default.
84
85       builder="hvm"
86           Specifies that this is to be an HVM domain.  That is, a fully
87           virtualised computer with emulated BIOS, disk and network
88           peripherals, etc.
89
90   General Options
91       The following options apply to guests of any type.
92
93       CPU Allocation
94
95       pool="CPUPOOLNAME"
96           Put the guest's vCPUs into the named CPU pool.
97
98       vcpus=N
99           Start the guest with N vCPUs initially online.
100
101       maxvcpus=M
102           Allow the guest to bring up a maximum of M vCPUs. When starting the
103           guest, if vcpus=N is less than maxvcpus=M then the first N vCPUs
104           will be created online and the remainder will be created offline.
105
106       cpus="CPULIST"
107           List of host CPUs the guest is allowed to use. Default is no
108           pinning at all (more on this below). A "CPULIST" may be specified
109           as follows:
110
111           "all"
112               To allow all the vCPUs of the guest to run on all the CPUs on
113               the host.
114
115           "0-3,5,^1"
116               To allow all the vCPUs of the guest to run on CPUs 0,2,3,5. It
117               is possible to combine this with "all", meaning "all,^7"
118               results in all the vCPUs of the guest being allowed to run on
119               all the CPUs of the host except CPU 7.
120
121           "nodes:0-3,^node:2"
122               To allow all the vCPUs of the guest to run on the CPUs from
123               NUMA nodes 0,1,3 of the host. So, if CPUs 0-3 belong to node 0,
124               CPUs 4-7 belong to node 1, CPUs 8-11 to node 2 and CPUs 12-15
125               to node 3, the above would mean all the vCPUs of the guest
126               would be allowed to run on CPUs 0-7,12-15.
127
128               Combining this notation with the one above is possible. For
129               instance, "1,node:1,^6", means all the vCPUs of the guest will
130               run on CPU 1 and on all the CPUs of NUMA node 1, but not on CPU
131               6. Following the same example as above, that would be CPUs
132               1,4,5,7.
133
134               Combining this with "all" is also possible, meaning
135               "all,^node:1" results in all the vCPUs of the guest running on
136               all the CPUs on the host, except for the CPUs belonging to the
137               host NUMA node 1.
138
139           ["2", "3-8,^5"]
140               To ask for specific vCPU mapping. That means (in this example),
141               vCPU 0 of the guest will run on CPU 2 of the host and vCPU 1 of
142               the guest will run on CPUs 3,4,6,7,8 of the host (excluding CPU
143               5).
144
145               More complex notation can be also used, exactly as described
146               above. So "all,^5-8", or just "all", or
147               "node:0,node:2,^9-11,18-20" are all legal, for each element of
148               the list.
149
150           If this option is not specified, no vCPU to CPU pinning is
151           established, and the vCPUs of the guest can run on all the CPUs of
152           the host. If this option is specified, the intersection of the vCPU
153           pinning mask, provided here, and the soft affinity mask, if
154           provided via cpus_soft=, is utilized to compute the domain node-
155           affinity for driving memory allocations.
156
157       cpus_soft="CPULIST"
158           Exactly as cpus=, but specifies soft affinity, rather than pinning
159           (hard affinity). When using the credit scheduler, this means what
160           CPUs the vCPUs of the domain prefer.
161
162           A "CPULIST" is specified exactly as for cpus=, detailed earlier in
163           the manual.
164
165           If this option is not specified, the vCPUs of the guest will not
166           have any preference regarding host CPUs. If this option is
167           specified, the intersection of the soft affinity mask, provided
168           here, and the vCPU pinning, if provided via cpus=, is utilized to
169           compute the domain node-affinity for driving memory allocations.
170
171           If this option is not specified (and cpus= is not specified
172           either), libxl automatically tries to place the guest on the least
173           possible number of nodes. A heuristic approach is used for choosing
174           the best node (or set of nodes), with the goal of maximizing
175           performance for the guest and, at the same time, achieving
176           efficient utilization of host CPUs and memory. In that case, the
177           soft affinity of all the vCPUs of the domain will be set to host
178           CPUs belonging to NUMA nodes chosen during placement.
179
180           For more details, see xl-numa-placement(7).
181
182       CPU Scheduling
183
184       cpu_weight=WEIGHT
185           A domain with a weight of 512 will get twice as much CPU as a
186           domain with a weight of 256 on a contended host.  Legal weights
187           range from 1 to 65535 and the default is 256.  Honoured by the
188           credit and credit2 schedulers.
189
190       cap=N
191           The cap optionally fixes the maximum amount of CPU a domain will be
192           able to consume, even if the host system has idle CPU cycles.  The
193           cap is expressed as a percentage of one physical CPU: 100 is 1
194           physical CPU, 50 is half a CPU, 400 is 4 CPUs, etc.  The default,
195           0, means there is no cap.  Honoured by the credit and credit2
196           schedulers.
197
198           NOTE: Many systems have features that will scale down the computing
199           power of a CPU that is not 100% utilized.  This can be done in the
200           operating system, but can also sometimes be done below the
201           operating system, in the BIOS.  If you set a cap such that
202           individual cores are running at less than 100%, this may have an
203           impact on the performance of your workload over and above the
204           impact of the cap. For example, if your processor runs at 2GHz, and
205           you cap a VM at 50%, the power management system may also reduce
206           the clock speed to 1GHz; the effect will be that your VM gets 25%
207           of the available power (50% of 1GHz) rather than 50% (50% of 2GHz).
208           If you are not getting the performance you expect, look at
209           performance and CPU frequency options in your operating system and
210           your BIOS.
211
212       Memory Allocation
213
214       memory=MBYTES
215           Start the guest with MBYTES megabytes of RAM.
216
217       maxmem=MBYTES
218           Specifies the maximum amount of memory a guest can ever see.  The
219           value of maxmem= must be equal to or greater than that of memory=.
220
221           In combination with memory= it will start the guest "pre-
222           ballooned", if the values of memory= and maxmem= differ.  A "pre-
223           ballooned" HVM guest needs a balloon driver, without a balloon
224           driver it will crash.
225
226           NOTE: Because of the way ballooning works, the guest has to
227           allocate memory to keep track of maxmem pages, regardless of how
228           much memory it actually has available to it.  A guest with
229           maxmem=262144 and memory=8096 will report significantly less memory
230           available for use than a system with maxmem=8096 memory=8096 due to
231           the memory overhead of having to track the unused pages.
232
233       Guest Virtual NUMA Configuration
234
235       vnuma=[ VNODE_SPEC, VNODE_SPEC, ... ]
236           Specify virtual NUMA configuration with positional arguments. The
237           nth VNODE_SPEC in the list specifies the configuration of the nth
238           virtual node.
239
240           Note that virtual NUMA is not supported for PV guests yet, because
241           there is an issue with the CPUID instruction handling that affects
242           PV virtual NUMA. Furthermore, guests with virtual NUMA cannot be
243           saved or migrated because the migration stream does not preserve
244           node information.
245
246           Each VNODE_SPEC is a list, which has a form of
247           "[VNODE_CONFIG_OPTION, VNODE_CONFIG_OPTION, ... ]"  (without the
248           quotes).
249
250           For example, vnuma = [
251           ["pnode=0","size=512","vcpus=0-4","vdistances=10,20"] ] means vnode
252           0 is mapped to pnode 0, has 512MB ram, has vcpus 0 to 4, the
253           distance to itself is 10 and the distance to vnode 1 is 20.
254
255           Each VNODE_CONFIG_OPTION is a quoted "KEY=VALUE" pair. Supported
256           VNODE_CONFIG_OPTIONs are (they are all mandatory at the moment):
257
258           pnode=NUMBER
259               Specifies which physical node this virtual node maps to.
260
261           size=MBYTES
262               Specifies the size of this virtual node. The sum of memory
263               sizes of all vnodes will become maxmem=. If maxmem= is
264               specified separately, a check is performed to make sure the sum
265               of all vnode memory matches maxmem=.
266
267           vcpus="CPUSTRING"
268               Specifies which vCPUs belong to this node. "CPUSTRING" is a
269               string of numerical values separated by a comma. You can
270               specify a range and/or a single CPU.  An example would be
271               "vcpus=0-5,8", which means you specified vCPU 0 to vCPU 5, and
272               vCPU 8.
273
274           vdistances=NUMBER, NUMBER, ...
275               Specifies the virtual distance from this node to all nodes
276               (including itself) with positional arguments. For example,
277               "vdistance=10,20" for vnode 0 means the distance from vnode 0
278               to vnode 0 is 10, from vnode 0 to vnode 1 is 20. The number of
279               arguments supplied must match the total number of vnodes.
280
281               Normally you can use the values from xl info -n or numactl
282               --hardware to fill the vdistances list.
283
284       Event Actions
285
286       on_poweroff="ACTION"
287           Specifies what should be done with the domain if it shuts itself
288           down.  The ACTIONs are:
289
290           destroy
291               destroy the domain
292
293           restart
294               destroy the domain and immediately create a new domain with the
295               same configuration
296
297           rename-restart
298               rename the domain which terminated, and then immediately create
299               a new domain with the same configuration as the original
300
301           preserve
302               keep the domain.  It can be examined, and later destroyed with
303               xl destroy.
304
305           coredump-destroy
306               write a "coredump" of the domain to /var/lib/xen/dump/NAME and
307               then destroy the domain.
308
309           coredump-restart
310               write a "coredump" of the domain to /var/lib/xen/dump/NAME and
311               then restart the domain.
312
313           soft-reset
314               Reset all Xen specific interfaces for the Xen-aware HVM domain
315               allowing it to reestablish these interfaces and continue
316               executing the domain. PV and non-Xen-aware HVM guests are not
317               supported.
318
319           The default for on_poweroff is destroy.
320
321       on_reboot="ACTION"
322           Action to take if the domain shuts down with a reason code
323           requesting a reboot.  Default is restart.
324
325       on_watchdog="ACTION"
326           Action to take if the domain shuts down due to a Xen watchdog
327           timeout.  Default is destroy.
328
329       on_crash="ACTION"
330           Action to take if the domain crashes.  Default is destroy.
331
332       on_soft_reset="ACTION"
333           Action to take if the domain performs a 'soft reset' (e.g. does
334           kexec).  Default is soft-reset.
335
336       Direct Kernel Boot
337
338       Direct kernel boot allows booting guests with a kernel and an initrd
339       stored on a filesystem available to the host physical machine, allowing
340       command line arguments to be passed directly. PV guest direct kernel
341       boot is supported. HVM guest direct kernel boot is supported with some
342       limitations (it's supported when using qemu-xen and the default BIOS
343       'seabios', but not supported in case of using stubdom-dm and the old
344       'rombios'.)
345
346       kernel="PATHNAME"
347           Load the specified file as the kernel image.
348
349       ramdisk="PATHNAME"
350           Load the specified file as the ramdisk.
351
352       cmdline="STRING"
353           Append STRING to the kernel command line. (Note: the meaning of
354           this is guest specific). It can replace root="STRING" along with
355           extra="STRING" and is preferred. When cmdline="STRING" is set,
356           root="STRING" and extra="STRING" will be ignored.
357
358       root="STRING"
359           Append root=STRING to the kernel command line (Note: the meaning of
360           this is guest specific).
361
362       extra="STRING"
363           Append STRING to the kernel command line. (Note: the meaning of
364           this is guest specific).
365
366       Non direct Kernel Boot
367
368       Non direct kernel boot allows booting guests with a firmware. This can
369       be used by all types of guests, although the selection of options is
370       different depending on the guest type.
371
372       This option provides the flexibly of letting the guest decide which
373       kernel they want to boot, while preventing having to poke at the guest
374       file system form the toolstack domain.
375
376       PV guest options
377
378       firmware="pvgrub32|pvgrub64"
379           Boots a guest using a para-virtualized version of grub that runs
380           inside of the guest. The bitness of the guest needs to be know, so
381           that the right version of pvgrub can be selected.
382
383           Note that xl expects to find the pvgrub32.bin and pvgrub64.bin
384           binaries in /usr/libexec/xen/boot.
385
386       HVM guest options
387
388       firmware="bios"
389           Boot the guest using the default BIOS firmware, which depends on
390           the chosen device model.
391
392       firmware="uefi"
393           Boot the guest using the default UEFI firmware, currently OVMF.
394
395       firmware="seabios"
396           Boot the guest using the SeaBIOS BIOS firmware.
397
398       firmware="rombios"
399           Boot the guest using the ROMBIOS BIOS firmware.
400
401       firmware="ovmf"
402           Boot the guest using the OVMF UEFI firmware.
403
404       firmware="PATH"
405           Load the specified file as firmware for the guest.
406
407       PVH guest options
408
409       Currently there's no firmware available for PVH guests, they should be
410       booted using the Direct Kernel Boot method or the bootloader option.
411
412       pvshim=BOOLEAN
413           Whether to boot this guest as a PV guest within a PVH container.
414           Ie, the guest will experience a PV environment, but processor
415           hardware extensions are used to separate its address space to
416           mitigate the Meltdown attack (CVE-2017-5754).
417
418           Default is false.
419
420       pvshim_path="PATH"
421           The PV shim is a specially-built firmware-like executable
422           constructed from the hypervisor source tree.  This option specifies
423           to use a non-default shim.  Ignored if pvhsim is false.
424
425       pvshim_cmdline="STRING"
426           Command line for the shim.  Default is "pv-shim console=xen,pv".
427           Ignored if pvhsim is false.
428
429       pvshim_extra="STRING"
430           Extra command line arguments for the shim.  If supplied, appended
431           to the value for pvshim_cmdline.  Default is empty.  Ignored if
432           pvhsim is false.
433
434       Other Options
435
436       uuid="UUID"
437           Specifies the UUID of the domain.  If not specified, a fresh unique
438           UUID will be generated.
439
440       seclabel="LABEL"
441           Assign an XSM security label to this domain.
442
443       init_seclabel="LABEL"
444           Specify an XSM security label used for this domain temporarily
445           during its build. The domain's XSM label will be changed to the
446           execution seclabel (specified by seclabel) once the build is
447           complete, prior to unpausing the domain. With a properly
448           constructed security policy (such as nomigrate_t in the example
449           policy), this can be used to build a domain whose memory is not
450           accessible to the toolstack domain.
451
452       max_grant_frames=NUMBER
453           Specify the maximum number of grant frames the domain is allowed to
454           have.  This value controls how many pages the domain is able to
455           grant access to for other domains, needed e.g. for the operation of
456           paravirtualized devices.  The default is settable via xl.conf(5).
457
458       max_maptrack_frames=NUMBER
459           Specify the maximum number of grant maptrack frames the domain is
460           allowed to have. This value controls how many pages of foreign
461           domains can be accessed via the grant mechanism by this domain. The
462           default value is settable via xl.conf(5).
463
464       nomigrate=BOOLEAN
465           Disable migration of this domain.  This enables certain other
466           features which are incompatible with migration. Currently this is
467           limited to enabling the invariant TSC feature flag in CPUID results
468           when TSC is not emulated.
469
470       driver_domain=BOOLEAN
471           Specify that this domain is a driver domain. This enables certain
472           features needed in order to run a driver domain.
473
474       device_tree=PATH
475           Specify a partial device tree (compiled via the Device Tree
476           Compiler).  Everything under the node "/passthrough" will be copied
477           into the guest device tree. For convenience, the node "/aliases" is
478           also copied to allow the user to define aliases which can be used
479           by the guest kernel.
480
481           Given the complexity of verifying the validity of a device tree,
482           this option should only be used with a trusted device tree.
483
484           Note that the partial device tree should avoid using the phandle
485           65000 which is reserved by the toolstack.
486
487       passthrough="STRING"
488           Specify whether IOMMU mappings are enabled for the domain and hence
489           whether it will be enabled for passthrough hardware. Valid values
490           for this option are:
491
492           disabled
493               IOMMU mappings are disabled for the domain and so hardware may
494               not be passed through.
495
496               This option is the default if no passthrough hardware is
497               specified in the domain's configuration.
498
499           enabled
500               This option enables IOMMU mappings and selects an appropriate
501               default operating mode (see below for details of the operating
502               modes). For HVM/PVH domains running on platforms where the
503               option is available, this is equivalent to share_pt. Otherwise,
504               and also for PV domains, this option is equivalent to sync_pt.
505
506               This option is the default if passthrough hardware is specified
507               in the domain's configuration.
508
509           sync_pt
510               This option means that IOMMU mappings will be synchronized with
511               the domain's P2M table as follows:
512
513               For a PV domain, all writable pages assigned to the domain are
514               identity mapped by MFN in the IOMMU page table. Thus a device
515               driver running in the domain may program passthrough hardware
516               for DMA using MFN values (i.e. host/machine frame numbers)
517               looked up in its P2M.
518
519               For an HVM/PVH domain, all non-foreign RAM pages present in its
520               P2M will be mapped by GFN in the IOMMU page table. Thus a
521               device driver running in the domain may program passthrough
522               hardware using GFN values (i.e. guest physical frame numbers)
523               without any further translation.
524
525               This option is not currently available on Arm.
526
527           share_pt
528               This option is unavailable for a PV domain. For an HVM/PVH
529               domain, this option means that the IOMMU will be programmed to
530               directly reference the domain's P2M table as its page table.
531               From the point of view of a device driver running in the domain
532               this is functionally equivalent to sync_pt but places less load
533               on the hypervisor and so should generally be selected in
534               preference. However, the availability of this option is
535               hardware specific. If xl info reports virt_caps containing
536               iommu_hap_pt_share then this option may be used.
537
538           default
539               The default, which chooses between disabled and enabled
540               according to whether passthrough devices are enabled in the
541               config file.
542
543       xend_suspend_evtchn_compat=BOOLEAN
544           If this option is true the xenstore path for the domain's suspend
545           event channel will not be created. Instead the old xend behaviour
546           of making the whole xenstore device sub-tree writable by the domain
547           will be re-instated.
548
549           The existence of the suspend event channel path can cause problems
550           with certain PV drivers running in the guest (e.g. old Red Hat PV
551           drivers for Windows).
552
553           If this option is not specified then it will default to false.
554
555   Devices
556       The following options define the paravirtual, emulated and physical
557       devices which the guest will contain.
558
559       disk=[ "DISK_SPEC_STRING", "DISK_SPEC_STRING", ...]
560           Specifies the disks (both emulated disks and Xen virtual block
561           devices) which are to be provided to the guest, and what objects on
562           the host they should map to.  See xl-disk-configuration(5) for more
563           details.
564
565       vif=[ "NET_SPEC_STRING", "NET_SPEC_STRING", ...]
566           Specifies the network interfaces (both emulated network adapters,
567           and Xen virtual interfaces) which are to be provided to the guest.
568           See xl-network-configuration(5) for more details.
569
570       vtpm=[ "VTPM_SPEC_STRING", "VTPM_SPEC_STRING", ...]
571           Specifies the Virtual Trusted Platform module to be provided to the
572           guest. See xen-vtpm(7) for more details.
573
574           Each VTPM_SPEC_STRING is a comma-separated list of "KEY=VALUE"
575           settings from the following list:
576
577           backend=domain-id
578               Specifies the backend domain name or id. This value is
579               required!  If this domain is a guest, the backend should be set
580               to the vTPM domain name. If this domain is a vTPM, the backend
581               should be set to the vTPM manager domain name.
582
583           uuid=UUID
584               Specifies the UUID of this vTPM device. The UUID is used to
585               uniquely identify the vTPM device. You can create one using the
586               uuidgen(1) program on unix systems. If left unspecified, a new
587               UUID will be randomly generated every time the domain boots.
588               If this is a vTPM domain, you should specify a value. The value
589               is optional if this is a guest domain.
590
591       p9=[ "9PFS_SPEC_STRING", "9PFS_SPEC_STRING", ...]
592           Creates a Xen 9pfs connection to share a filesystem from the
593           backend to the frontend.
594
595           Each 9PFS_SPEC_STRING is a comma-separated list of "KEY=VALUE"
596           settings, from the following list:
597
598           tag=STRING
599               9pfs tag to identify the filesystem share. The tag is needed on
600               the guest side to mount it.
601
602           security_model="none"
603               Only "none" is supported today, which means that the files are
604               stored using the same credentials as those they have in the
605               guest (no user ownership squash or remap).
606
607           path=STRING
608               Filesystem path on the backend to export.
609
610           backend=domain-id
611               Specify the backend domain name or id, defaults to dom0.
612
613       pvcalls=[ "backend=domain-id", ... ]
614           Creates a Xen pvcalls connection to handle pvcalls requests from
615           frontend to backend. It can be used as an alternative networking
616           model.  For more information about the protocol, see
617           https://xenbits.xenproject.org/docs/unstable/misc/pvcalls.html.
618
619       vfb=[ "VFB_SPEC_STRING", "VFB_SPEC_STRING", ...]
620           Specifies the paravirtual framebuffer devices which should be
621           supplied to the domain.
622
623           This option does not control the emulated graphics card presented
624           to an HVM guest. See Emulated VGA Graphics Device below for how to
625           configure the emulated device. If Emulated VGA Graphics Device
626           options are used in a PV guest configuration, xl will pick up vnc,
627           vnclisten, vncpasswd, vncdisplay, vncunused, sdl, opengl and keymap
628           to construct the paravirtual framebuffer device for the guest.
629
630           Each VFB_SPEC_STRING is a comma-separated list of "KEY=VALUE"
631           settings, from the following list:
632
633           vnc=BOOLEAN
634               Allow access to the display via the VNC protocol.  This enables
635               the other VNC-related settings.  Default is 1 (enabled).
636
637           vnclisten=ADDRESS[:DISPLAYNUM]
638               Specifies the IP address, and optionally the VNC display
639               number, to use.
640
641               Note: if you specify the display number here, you should not
642               use the vncdisplay option.
643
644           vncdisplay=DISPLAYNUM
645               Specifies the VNC display number to use.  The actual TCP port
646               number will be DISPLAYNUM+5900.
647
648               Note: you should not use this option if you set the DISPLAYNUM
649               in the vnclisten option.
650
651           vncunused=BOOLEAN
652               Requests that the VNC display setup searches for a free TCP
653               port to use.  The actual display used can be accessed with xl
654               vncviewer.
655
656           vncpasswd=PASSWORD
657               Specifies the password for the VNC server. If the password is
658               set to an empty string, authentication on the VNC server will
659               be disabled, allowing any user to connect.
660
661           sdl=BOOLEAN
662               Specifies that the display should be presented via an X window
663               (using Simple DirectMedia Layer). The default is 0 (not
664               enabled).
665
666           display=DISPLAY
667               Specifies the X Window display that should be used when the sdl
668               option is used.
669
670           xauthority=XAUTHORITY
671               Specifies the path to the X authority file that should be used
672               to connect to the X server when the sdl option is used.
673
674           opengl=BOOLEAN
675               Enable OpenGL acceleration of the SDL display. Only effects
676               machines using device_model_version="qemu-xen-traditional" and
677               only if the device-model was compiled with OpenGL support. The
678               default is 0 (disabled).
679
680           keymap=LANG
681               Configure the keymap to use for the keyboard associated with
682               this display. If the input method does not easily support raw
683               keycodes (e.g. this is often the case when using VNC) then this
684               allows us to correctly map the input keys into keycodes seen by
685               the guest. The specific values which are accepted are defined
686               by the version of the device-model which you are using. See
687               Keymaps below or consult the qemu(1) manpage. The default is
688               en-us.
689
690       channel=[ "CHANNEL_SPEC_STRING", "CHANNEL_SPEC_STRING", ...]
691           Specifies the virtual channels to be provided to the guest. A
692           channel is a low-bandwidth, bidirectional byte stream, which
693           resembles a serial link. Typical uses for channels include
694           transmitting VM configuration after boot and signalling to in-guest
695           agents. Please see xen-pv-channel(7) for more details.
696
697           Each CHANNEL_SPEC_STRING is a comma-separated list of "KEY=VALUE"
698           settings. Leading and trailing whitespace is ignored in both KEY
699           and VALUE. Neither KEY nor VALUE may contain ',', '=' or '"'.
700           Defined values are:
701
702           backend=domain-id
703               Specifies the backend domain name or id. This parameter is
704               optional. If this parameter is omitted then the toolstack
705               domain will be assumed.
706
707           name=NAME
708               Specifies the name for this device. This parameter is
709               mandatory!  This should be a well-known name for a specific
710               application (e.g.  guest agent) and should be used by the
711               frontend to connect the application to the right channel
712               device. There is no formal registry of channel names, so
713               application authors are encouraged to make their names unique
714               by including the domain name and a version number in the string
715               (e.g. org.mydomain.guestagent.1).
716
717           connection=CONNECTION
718               Specifies how the backend will be implemented. The following
719               options are available:
720
721               SOCKET
722                   The backend will bind a Unix domain socket (at the path
723                   given by path=PATH), listen for and accept connections. The
724                   backend will proxy data between the channel and the
725                   connected socket.
726
727               PTY The backend will create a pty and proxy data between the
728                   channel and the master device. The command xl channel-list
729                   can be used to discover the assigned slave device.
730
731       rdm="RDM_RESERVATION_STRING"
732           HVM/x86 only! Specifies information about Reserved Device Memory
733           (RDM), which is necessary to enable robust device passthrough. One
734           example of RDM is reporting through the ACPI Reserved Memory Region
735           Reporting (RMRR) structure on the x86 platform.
736
737           RDM_RESERVATION_STRING is a comma separated list of "KEY=VALUE"
738           settings, from the following list:
739
740           strategy=STRING
741               Currently there is only one valid type, and that is "host".
742
743               host
744                   If set to "host" it means all reserved device memory on
745                   this platform should be checked to reserve regions in this
746                   VM's address space. This global RDM parameter allows the
747                   user to specify reserved regions explicitly, and using
748                   "host" includes all reserved regions reported on this
749                   platform, which is useful when doing hotplug.
750
751                   By default this isn't set so we don't check all RDMs.
752                   Instead, we just check the RDM specific to a given device
753                   if we're assigning this kind of a device.
754
755                   Note: this option is not recommended unless you can make
756                   sure that no conflicts exist.
757
758                   For example, you're trying to set "memory = 2800" to
759                   allocate memory to one given VM but the platform owns two
760                   RDM regions like:
761
762                   Device A [sbdf_A]: RMRR region_A: base_addr ac6d3000
763                   end_address ac6e6fff
764
765                   Device B [sbdf_B]: RMRR region_B: base_addr ad800000
766                   end_address afffffff
767
768                   In this conflict case,
769
770                   #1. If strategy is set to "host", for example:
771
772                   rdm = "strategy=host,policy=strict" or rdm =
773                   "strategy=host,policy=relaxed"
774
775                   it means all conflicts will be handled according to the
776                   policy introduced by policy as described below.
777
778                   #2. If strategy is not set at all, but
779
780                   pci = [ 'sbdf_A, rdm_policy=xxxxx' ]
781
782                   it means only one conflict of region_A will be handled
783                   according to the policy introduced by rdm_policy=STRING as
784                   described inside pci options.
785
786           policy=STRING
787               Specifies how to deal with conflicts when reserving already
788               reserved device memory in the guest address space.
789
790               strict
791                   Specifies that in case of an unresolved conflict the VM
792                   can't be created, or the associated device can't be
793                   attached in the case of hotplug.
794
795               relaxed
796                   Specifies that in case of an unresolved conflict the VM is
797                   allowed to be created but may cause the VM to crash if a
798                   pass-through device accesses RDM.  For example, the Windows
799                   IGD GFX driver always accesses RDM regions so it leads to a
800                   VM crash.
801
802                   Note: this may be overridden by the rdm_policy option in
803                   the pci device configuration.
804
805       usbctrl=[ "USBCTRL_SPEC_STRING", "USBCTRL_SPEC_STRING", ...]
806           Specifies the USB controllers created for this guest.
807
808           Each USBCTRL_SPEC_STRING is a comma-separated list of "KEY=VALUE"
809           settings, from the following list:
810
811           type=TYPE
812               Specifies the usb controller type.
813
814               pv  Specifies a kernel based PVUSB backend.
815
816               qusb
817                   Specifies a QEMU based PVUSB backend.
818
819               devicemodel
820                   Specifies a USB controller emulated by QEMU.  It will show
821                   up as a PCI-device in the guest.
822
823               auto
824                   Determines whether a kernel based backend is installed.  If
825                   this is the case, pv is used, otherwise qusb will be used.
826                   For HVM domains devicemodel will be selected.
827
828                   This option is the default.
829
830           version=VERSION
831               Specifies the usb controller version.  Possible values include
832               1 (USB1.1), 2 (USB2.0) and 3 (USB3.0).  Default is 2 (USB2.0).
833               Value 3 (USB3.0) is available for the devicemodel type only.
834
835           ports=PORTS
836               Specifies the total number of ports of the usb controller. The
837               maximum number is 31. The default is 8.  With the type
838               devicemodel the number of ports is more limited: a USB1.1
839               controller always has 2 ports, a USB2.0 controller always has 6
840               ports and a USB3.0 controller can have up to 15 ports.
841
842               USB controller ids start from 0.  In line with the USB
843               specification, however, ports on a controller start from 1.
844
845               EXAMPLE
846
847                 usbctrl=["version=1,ports=4", "version=2,ports=8"]
848
849                 The first controller is USB1.1 and has:
850
851                 controller id = 0, and ports 1,2,3,4.
852
853                 The second controller is USB2.0 and has:
854
855                 controller id = 1, and ports 1,2,3,4,5,6,7,8.
856
857       usbdev=[ "USBDEV_SPEC_STRING", "USBDEV_SPEC_STRING", ...]
858           Specifies the USB devices to be attached to the guest at boot.
859
860           Each USBDEV_SPEC_STRING is a comma-separated list of "KEY=VALUE"
861           settings, from the following list:
862
863           type=hostdev
864               Specifies USB device type. Currently only "hostdev" is
865               supported.
866
867           hostbus=busnum
868               Specifies busnum of the USB device from the host perspective.
869
870           hostaddr=devnum
871               Specifies devnum of the USB device from the host perspective.
872
873           controller=CONTROLLER
874               Specifies the USB controller id, to which controller the USB
875               device is attached.
876
877               If no controller is specified, an available controller:port
878               combination will be used.  If there are no available
879               controller:port combinations, a new controller will be created.
880
881           port=PORT
882               Specifies the USB port to which the USB device is attached. The
883               port option is valid only when the controller option is
884               specified.
885
886       pci=[ "PCI_SPEC_STRING", "PCI_SPEC_STRING", ...]
887           Specifies the host PCI devices to passthrough to this guest.  Each
888           PCI_SPEC_STRING has the form of
889           [DDDD:]BB:DD.F[@VSLOT],KEY=VALUE,KEY=VALUE,... where:
890
891           [DDDD:]BB:DD.F
892               Identifies the PCI device from the host perspective in the
893               domain (DDDD), Bus (BB), Device (DD) and Function (F) syntax.
894               This is the same scheme as used in the output of lspci(1) for
895               the device in question.
896
897               Note: by default lspci(1) will omit the domain (DDDD) if it is
898               zero and it is optional here also. You may specify the function
899               (F) as * to indicate all functions.
900
901           @VSLOT
902               Specifies the virtual slot where the guest will see this
903               device. This is equivalent to the DD which the guest sees. In a
904               guest DDDD and BB are "0000:00".
905
906           permissive=BOOLEAN
907               By default pciback only allows PV guests to write "known safe"
908               values into PCI configuration space, likewise QEMU (both qemu-
909               xen and qemu-xen-traditional) imposes the same constraint on
910               HVM guests.  However, many devices require writes to other
911               areas of the configuration space in order to operate properly.
912               This option tells the backend (pciback or QEMU) to allow all
913               writes to the PCI configuration space of this device by this
914               domain.
915
916               This option should be enabled with caution: it gives the guest
917               much more control over the device, which may have security or
918               stability implications.  It is recommended to only enable this
919               option for trusted VMs under administrator's control.
920
921           msitranslate=BOOLEAN
922               Specifies that MSI-INTx translation should be turned on for the
923               PCI device. When enabled, MSI-INTx translation will always
924               enable MSI on the PCI device regardless of whether the guest
925               uses INTx or MSI. Some device drivers, such as NVIDIA's, detect
926               an inconsistency and do not function when this option is
927               enabled. Therefore the default is false (0).
928
929           seize=BOOLEAN
930               Tells xl to automatically attempt to re-assign a device to
931               pciback if it is not already assigned.
932
933               WARNING: If you set this option, xl will gladly re-assign a
934               critical system device, such as a network or a disk controller
935               being used by dom0 without confirmation.  Please use with care.
936
937           power_mgmt=BOOLEAN
938               (HVM only) Specifies that the VM should be able to program the
939               D0-D3hot power management states for the PCI device. The
940               default is false (0).
941
942           rdm_policy=STRING
943               (HVM/x86 only) This is the same as the policy setting inside
944               the rdm option but just specific to a given device. The default
945               is "relaxed".
946
947               Note: this would override global rdm option.
948
949       pci_permissive=BOOLEAN
950           Changes the default value of permissive for all PCI devices passed
951           through to this VM. See permissive above.
952
953       pci_msitranslate=BOOLEAN
954           Changes the default value of msitranslate for all PCI devices
955           passed through to this VM. See msitranslate above.
956
957       pci_seize=BOOLEAN
958           Changes the default value of seize for all PCI devices passed
959           through to this VM. See seize above.
960
961       pci_power_mgmt=BOOLEAN
962           (HVM only) Changes the default value of power_mgmt for all PCI
963           devices passed through to this VM. See power_mgmt above.
964
965       gfx_passthru=BOOLEAN|"STRING"
966           Enable graphics device PCI passthrough. This option makes an
967           assigned PCI graphics card become the primary graphics card in the
968           VM. The QEMU emulated graphics adapter is disabled and the VNC
969           console for the VM will not have any graphics output. All graphics
970           output, including boot time QEMU BIOS messages from the VM, will go
971           to the physical outputs of the passed through physical graphics
972           card.
973
974           The graphics card PCI device to pass through is chosen with the pci
975           option, in exactly the same way a normal Xen PCI device
976           passthrough/assignment is done.  Note that gfx_passthru does not do
977           any kind of sharing of the GPU, so you can assign the GPU to only
978           one single VM at a time.
979
980           gfx_passthru also enables various legacy VGA memory ranges, BARs,
981           MMIOs, and ioports to be passed through to the VM, since those are
982           required for correct operation of things like VGA BIOS, text mode,
983           VBE, etc.
984
985           Enabling the gfx_passthru option also copies the physical graphics
986           card video BIOS to the guest memory, and executes the VBIOS in the
987           guest to initialize the graphics card.
988
989           Most graphics adapters require vendor specific tweaks for properly
990           working graphics passthrough. See the
991           XenVGAPassthroughTestedAdapters
992           <https://wiki.xenproject.org/wiki/XenVGAPassthroughTestedAdapters>
993           wiki page for graphics cards currently supported by gfx_passthru.
994
995           gfx_passthru is currently supported both with the qemu-xen-
996           traditional device-model and upstream qemu-xen device-model.
997
998           When given as a boolean the gfx_passthru option either disables
999           graphics card passthrough or enables autodetection.
1000
1001           When given as a string the gfx_passthru option describes the type
1002           of device to enable. Note that this behavior is only supported with
1003           the upstream qemu-xen device-model. With qemu-xen-traditional IGD
1004           (Intel Graphics Device) is always assumed and options other than
1005           autodetect or explicit IGD will result in an error.
1006
1007           Currently, valid values for the option are:
1008
1009           0   Disables graphics device PCI passthrough.
1010
1011           1, "default"
1012               Enables graphics device PCI passthrough and autodetects the
1013               type of device which is being used.
1014
1015           "igd"
1016               Enables graphics device PCI passthrough but forcing the type of
1017               device to Intel Graphics Device.
1018
1019           Note that some graphics cards (AMD/ATI cards, for example) do not
1020           necessarily require the gfx_passthru option, so you can use the
1021           normal Xen PCI passthrough to assign the graphics card as a
1022           secondary graphics card to the VM. The QEMU-emulated graphics card
1023           remains the primary graphics card, and VNC output is available from
1024           the QEMU-emulated primary adapter.
1025
1026           More information about the Xen gfx_passthru feature is available on
1027           the XenVGAPassthrough
1028           <https://wiki.xenproject.org/wiki/XenVGAPassthrough> wiki page.
1029
1030       rdm_mem_boundary=MBYTES
1031           Number of megabytes to set for a boundary when checking for RDM
1032           conflicts.
1033
1034           When RDM conflicts with RAM, RDM is probably scattered over the
1035           whole RAM space. Having multiple RDM entries would worsen this and
1036           lead to a complicated memory layout. Here we're trying to figure
1037           out a simple solution to avoid breaking the existing layout. When a
1038           conflict occurs,
1039
1040               #1. Above a predefined boundary
1041                   - move lowmem_end below the reserved region to solve the conflict;
1042
1043               #2. Below a predefined boundary
1044                   - Check if the policy is strict or relaxed.
1045                   A "strict" policy leads to a fail in libxl.
1046                   Note that when both policies are specified on a given region,
1047                   "strict" is always preferred.
1048                   The "relaxed" policy issues a warning message and also masks this
1049                   entry INVALID to indicate we shouldn't expose this entry to
1050                   hvmloader.
1051
1052           The default value is 2048.
1053
1054       dtdev=[ "DTDEV_PATH", "DTDEV_PATH", ...]
1055           Specifies the host device tree nodes to passt hrough to this guest.
1056           Each DTDEV_PATH is an absolute path in the device tree.
1057
1058       ioports=[ "IOPORT_RANGE", "IOPORT_RANGE", ...]
1059           Allow the guest to access specific legacy I/O ports. Each
1060           IOPORT_RANGE is given in hexadecimal format and may either be a
1061           range, e.g. "2f8-2ff" (inclusive), or a single I/O port, e.g.
1062           "2f8".
1063
1064           It is recommended to only use this option for trusted VMs under
1065           administrator's control.
1066
1067       iomem=[ "IOMEM_START,NUM_PAGES[@GFN]", "IOMEM_START,NUM_PAGES[@GFN]",
1068       ...]
1069           Allow auto-translated domains to access specific hardware I/O
1070           memory pages.
1071
1072           IOMEM_START is a physical page number. NUM_PAGES is the number of
1073           pages, beginning with START_PAGE, to allow access to. GFN specifies
1074           the guest frame number where the mapping will start in the guest's
1075           address space. If GFN is not specified, the mapping will be
1076           performed using IOMEM_START as a start in the guest's address
1077           space, therefore performing a 1:1 mapping by default.  All of these
1078           values must be given in hexadecimal format.
1079
1080           Note that the IOMMU won't be updated with the mappings specified
1081           with this option. This option therefore should not be used to pass
1082           through any IOMMU-protected devices.
1083
1084           It is recommended to only use this option for trusted VMs under
1085           administrator's control.
1086
1087       irqs=[ NUMBER, NUMBER, ...]
1088           Allow a guest to access specific physical IRQs.
1089
1090           It is recommended to only use this option for trusted VMs under
1091           administrator's control.
1092
1093           If vuart console is enabled then irq 32 is reserved for it. See
1094           "vuart="uart"" to know how to enable vuart console.
1095
1096       max_event_channels=N
1097           Limit the guest to using at most N event channels (PV interrupts).
1098           Guests use hypervisor resources for each event channel they use.
1099
1100           The default of 1023 should be sufficient for typical guests.  The
1101           maximum value depends on what the guest supports.  Guests
1102           supporting the FIFO-based event channel ABI support up to 131,071
1103           event channels.  Other guests are limited to 4095 (64-bit x86 and
1104           ARM) or 1023 (32-bit x86).
1105
1106       vdispl=[ "VDISPL_SPEC_STRING", "VDISPL_SPEC_STRING", ...]
1107           Specifies the virtual display devices to be provided to the guest.
1108
1109           Each VDISPL_SPEC_STRING is a comma-separated list of "KEY=VALUE"
1110           settings, from the following list:
1111
1112           "backend=DOMAIN"
1113               Specifies the backend domain name or id. If not specified
1114               Domain-0 is used.
1115
1116           "be-alloc=BOOLEAN"
1117               Indicates if backend can be a buffer provider/allocator for
1118               this domain. See display protocol for details.
1119
1120           "connectors=CONNECTORS"
1121               Specifies virtual connectors for the device in following format
1122               <id>:<W>x<H>;<id>:<W>x<H>... where:
1123
1124               "id"
1125                   String connector unique id. Space, comma symbols are not
1126                   allowed.
1127
1128               "W" Connector width in pixels.
1129
1130               "H" Connector height in pixels.
1131
1132               EXAMPLE
1133
1134                   connectors=id0:1920x1080;id1:800x600;id2:640x480
1135
1136       dm_restrict=BOOLEAN
1137           Restrict the device model after startup, to limit the consequencese
1138           of security vulnerabilities in qemu.
1139
1140           See docs/features/qemu-depriv.pandoc for more information on Linux
1141           and QEMU version requirements, device model user setup, and current
1142           limitations.
1143
1144           This feature is a technology preview.  See SUPPORT.md for a
1145           security support statement.
1146
1147       device_model_user=USERNAME
1148           When running dm_restrict, run the device model as this user.
1149
1150           NOTE: Each domain MUST have a SEPARATE username.
1151
1152           See docs/features/qemu-depriv.pandoc for more information.
1153
1154       vsnd=[ VCARD_SPEC, VCARD_SPEC, ... ]
1155           Specifies the virtual sound cards to be provided to the guest.
1156           Each VCARD_SPEC is a list, which has a form of "[VSND_ITEM_SPEC,
1157           VSND_ITEM_SPEC, ... ]" (without the quotes).  The virtual sound
1158           card has hierarchical structure.  Every card has a set of PCM
1159           devices and streams, each could be individually configured.
1160
1161           VSND_ITEM_SPEC describes individual item parameters.
1162           VSND_ITEM_SPEC is a string of comma separated item parameters
1163           headed by item identifier. Each item parameter is "KEY=VALUE" pair:
1164
1165               "identifier, param = value, ...".
1166
1167           Identifier shall be one of following values: "CARD", "PCM",
1168           "STREAM".  The child item treated as belonging to the previously
1169           defined parent item.
1170
1171           All parameters are optional.
1172
1173           There are group of parameters which are common for all items.  This
1174           group can be defined at higher level of the hierarchy and be fully
1175           or partially re-used by the underlying layers. These parameters
1176           are:
1177
1178               * number of channels (min/max)
1179
1180               * supported sample rates
1181
1182               * supported sample formats
1183
1184           E.g. one can define these values for the whole card, device or
1185           stream.  Every underlying layer in turn can re-define some or all
1186           of them to better fit its needs. For example, card may define
1187           number of channels to be in [1; 8] range, and some particular
1188           stream may be limited to [1; 2] only.  The rule is that the
1189           underlying layer must be a subset of the upper layer range.
1190
1191           COMMON parameters:
1192
1193               sample-rates=RATES
1194                   List of integer values separated by semicolon:
1195                   sample-rates=8000;22050;44100
1196
1197               sample-formats=FORMATS
1198                   List of string values separated by semicolon:
1199                   sample-formats=s16_le;s8;u32_be
1200
1201                   Supported formats: s8, u8, s16_le, s16_be, u16_le, u16_be,
1202                   s24_le, s24_be, u24_le, u24_be, s32_le, s32_be, u32_le,
1203                   u32_be, float_le, float_be, float64_le, float64_be,
1204                   iec958_subframe_le, iec958_subframe_be, mu_law, a_law,
1205                   ima_adpcm, mpeg, gsm
1206
1207               channels-min=NUMBER
1208                   The minimum amount of channels.
1209
1210               channels-max=NUMBER
1211                   The maximum amount of channels.
1212
1213               buffer-size=NUMBER
1214                   The maximum size in octets of the buffer to allocate per
1215                   stream.
1216
1217           CARD specification:
1218
1219               backend=domain-id
1220                   Specify the backend domain name or id, defaults to dom0.
1221
1222               short-name=STRING
1223                   Short name of the virtual sound card.
1224
1225               long-name=STRING
1226                   Long name of the virtual sound card.
1227
1228           PCM specification:
1229
1230               name=STRING
1231                   Name of the PCM sound device within the virtual sound card.
1232
1233           STREAM specification:
1234
1235               unique-id=STRING
1236                   Unique stream identifier.
1237
1238               type=TYPE
1239                   Stream type: "p" - playback stream, "c" - capture stream.
1240
1241           EXAMPLE:
1242
1243               vsnd = [
1244                   ['CARD, short-name=Main, sample-formats=s16_le;s8;u32_be',
1245                       'PCM, name=Main',
1246                           'STREAM, id=0, type=p',
1247                           'STREAM, id=1, type=c, channels-max=2'
1248                   ],
1249                   ['CARD, short-name=Second',
1250                       'PCM, name=Second, buffer-size=1024',
1251                           'STREAM, id=2, type=p',
1252                           'STREAM, id=3, type=c'
1253                   ]
1254               ]
1255
1256       vkb=[ "VKB_SPEC_STRING", "VKB_SPEC_STRING", ...]
1257           Specifies the virtual keyboard device to be provided to the guest.
1258
1259           Each VKB_SPEC_STRING is a comma-separated list of "KEY=VALUE"
1260           settings from the following list:
1261
1262           unique-id=STRING
1263               Specifies the unique input device id.
1264
1265           backend=domain-id
1266               Specifies the backend domain name or id.
1267
1268           backend-type=type
1269               Specifies the backend type: qemu - for QEMU backend or linux -
1270               for Linux PV domain.
1271
1272           feature-disable-keyboard=BOOLEAN
1273               Indicates if keyboard device is disabled.
1274
1275           feature-disable-pointer=BOOLEAN
1276               Indicates if pointer device is disabled.
1277
1278           feature-abs-pointer=BOOLEAN
1279               Indicates if pointer device can return absolute coordinates.
1280
1281           feature-raw-pointer=BOOLEAN
1282               Indicates if pointer device can return raw (unscaled) absolute
1283               coordinates.
1284
1285           feature-multi-touch=BOOLEAN
1286               Indicates if input device supports multi touch.
1287
1288           multi-touch-width=MULTI_TOUCH_WIDTH
1289               Set maximum width for multi touch device.
1290
1291           multi-touch-height=MULTI_TOUCH_HEIGHT
1292               Set maximum height for multi touch device.
1293
1294           multi-touch-num-contacts=MULTI_TOUCH_NUM_CONTACTS
1295               Set maximum contacts number for multi touch device.
1296
1297           width=WIDTH
1298               Set maximum width for pointer device.
1299
1300           height=HEIGHT
1301               Set maximum height for pointer device.
1302
1303       tee="STRING"
1304           Arm only. Set TEE type for the guest. TEE is a Trusted Execution
1305           Environment -- separate secure OS found on some platforms. STRING
1306           can be one of the:
1307
1308           none
1309               "Don't allow the guest to use TEE if present on the platform.
1310               This is the default value.
1311
1312           optee
1313               Allow a guest to access the host OP-TEE OS. Xen will mediate
1314               the access to OP-TEE and the resource isolation will be
1315               provided directly by OP-TEE. OP-TEE itself may limit the number
1316               of guests that can concurrently use it. This requires a
1317               virtualization-aware OP-TEE for this to work.
1318
1319               You can refer to OP-TEE documentation
1320               <https://optee.readthedocs.io/en/latest/architecture/virtualization.html>
1321               for more information about how to enable and configure
1322               virtualization support in OP-TEE.
1323
1324               This feature is a technology preview.
1325
1326   Paravirtualised (PV) Guest Specific Options
1327       The following options apply only to Paravirtual (PV) guests.
1328
1329       bootloader="PROGRAM"
1330           Run "PROGRAM" to find the kernel image and ramdisk to use.
1331           Normally "PROGRAM" would be "pygrub", which is an emulation of
1332           grub/grub2/syslinux. Either kernel or bootloader must be specified
1333           for PV guests.
1334
1335       bootloader_args=[ "ARG", "ARG", ...]
1336           Append ARGs to the arguments to the bootloader program.
1337           Alternatively if the argument is a simple string then it will be
1338           split into words at whitespace (this second option is deprecated).
1339
1340       e820_host=BOOLEAN
1341           Selects whether to expose the host e820 (memory map) to the guest
1342           via the virtual e820. When this option is false (0) the guest
1343           pseudo-physical address space consists of a single contiguous RAM
1344           region. When this option is specified the virtual e820 instead
1345           reflects the host e820 and contains the same PCI holes. The total
1346           amount of RAM represented by the memory map is always the same,
1347           this option configures only how it is laid out.
1348
1349           Exposing the host e820 to the guest gives the guest kernel the
1350           opportunity to set aside the required part of its pseudo-physical
1351           address space in order to provide address space to map
1352           passedthrough PCI devices. It is guest Operating System dependent
1353           whether this option is required, specifically it is required when
1354           using a mainline Linux ("pvops") kernel. This option defaults to
1355           true (1) if any PCI passthrough devices are configured and false
1356           (0) otherwise. If you do not configure any passthrough devices at
1357           domain creation time but expect to hotplug devices later then you
1358           should set this option. Conversely if your particular guest kernel
1359           does not require this behaviour then it is safe to allow this to be
1360           enabled but you may wish to disable it anyway.
1361
1362   Fully-virtualised (HVM) Guest Specific Options
1363       The following options apply only to Fully-virtualised (HVM) guests.
1364
1365       Boot Device
1366
1367       boot="STRING"
1368           Specifies the emulated virtual device to boot from.
1369
1370           Possible values are:
1371
1372           c   Hard disk.
1373
1374           d   CD-ROM.
1375
1376           n   Network / PXE.
1377
1378           Note: multiple options can be given and will be attempted in the
1379           order they are given, e.g. to boot from CD-ROM but fall back to the
1380           hard disk you can specify it as dc.
1381
1382           The default is cd, meaning try booting from the hard disk first,
1383           but fall back to the CD-ROM.
1384
1385       Emulated disk controller type
1386
1387       hdtype=STRING
1388           Specifies the hard disk type.
1389
1390           Possible values are:
1391
1392           ide If thise mode is specified xl adds an emulated IDE controller,
1393               which is suitable even for older operation systems.
1394
1395           ahci
1396               If this mode is specified, xl adds an ich9 disk controller in
1397               AHCI mode and uses it with upstream QEMU to emulate disks
1398               instead of IDE. It decreases boot time but may not be supported
1399               by default in older operating systems, e.g.  Windows XP.
1400
1401           The default is ide.
1402
1403       Paging
1404
1405       The following options control the mechanisms used to virtualise guest
1406       memory.  The defaults are selected to give the best results for the
1407       common cases so you should normally leave these options unspecified.
1408
1409       hap=BOOLEAN
1410           Turns "hardware assisted paging" (the use of the hardware nested
1411           page table feature) on or off.  This feature is called EPT
1412           (Extended Page Tables) by Intel and NPT (Nested Page Tables) or RVI
1413           (Rapid Virtualisation Indexing) by AMD. If turned off, Xen will run
1414           the guest in "shadow page table" mode where the guest's page table
1415           updates and/or TLB flushes etc. will be emulated.  Use of HAP is
1416           the default when available.
1417
1418       oos=BOOLEAN
1419           Turns "out of sync pagetables" on or off.  When running in shadow
1420           page table mode, the guest's page table updates may be deferred as
1421           specified in the Intel/AMD architecture manuals.  However, this may
1422           expose unexpected bugs in the guest, or find bugs in Xen, so it is
1423           possible to disable this feature.  Use of out of sync page tables,
1424           when Xen thinks it appropriate, is the default.
1425
1426       shadow_memory=MBYTES
1427           Number of megabytes to set aside for shadowing guest pagetable
1428           pages (effectively acting as a cache of translated pages) or to use
1429           for HAP state. By default this is 1MB per guest vCPU plus 8KB per
1430           MB of guest RAM. You should not normally need to adjust this value.
1431           However, if you are not using hardware assisted paging (i.e. you
1432           are using shadow mode) and your guest workload consists of a very
1433           large number of similar processes then increasing this value may
1434           improve performance.
1435
1436       Processor and Platform Features
1437
1438       The following options allow various processor and platform level
1439       features to be hidden or exposed from the guest's point of view. This
1440       can be useful when running older guest Operating Systems which may
1441       misbehave when faced with more modern features. In general, you should
1442       accept the defaults for these options wherever possible.
1443
1444       bios="STRING"
1445           Select the virtual firmware that is exposed to the guest.  By
1446           default, a guess is made based on the device model, but sometimes
1447           it may be useful to request a different one, like UEFI.
1448
1449           rombios
1450               Loads ROMBIOS, a 16-bit x86 compatible BIOS. This is used by
1451               default when device_model_version=qemu-xen-traditional. This is
1452               the only BIOS option supported when
1453               device_model_version=qemu-xen-traditional. This is the BIOS
1454               used by all previous Xen versions.
1455
1456           seabios
1457               Loads SeaBIOS, a 16-bit x86 compatible BIOS. This is used by
1458               default with device_model_version=qemu-xen.
1459
1460           ovmf
1461               Loads OVMF, a standard UEFI firmware by Tianocore project.
1462               Requires device_model_version=qemu-xen.
1463
1464       bios_path_override="PATH"
1465           Override the path to the blob to be used as BIOS. The blob provided
1466           here MUST be consistent with the bios= which you have specified.
1467           You should not normally need to specify this option.
1468
1469           This option does not have any effect if using bios="rombios" or
1470           device_model_version="qemu-xen-traditional".
1471
1472       pae=BOOLEAN
1473           Hide or expose the IA32 Physical Address Extensions. These
1474           extensions make it possible for a 32 bit guest Operating System to
1475           access more than 4GB of RAM. Enabling PAE also enabled other
1476           features such as NX. PAE is required if you wish to run a 64-bit
1477           guest Operating System. In general, you should leave this enabled
1478           and allow the guest Operating System to choose whether or not to
1479           use PAE. (X86 only)
1480
1481       acpi=BOOLEAN
1482           Expose ACPI (Advanced Configuration and Power Interface) tables
1483           from the virtual firmware to the guest Operating System. ACPI is
1484           required by most modern guest Operating Systems. This option is
1485           enabled by default and usually you should omit it. However, it may
1486           be necessary to disable ACPI for compatibility with some guest
1487           Operating Systems.  This option is true for x86 while it's false
1488           for ARM by default.
1489
1490       acpi_s3=BOOLEAN
1491           Include the S3 (suspend-to-ram) power state in the virtual firmware
1492           ACPI table. True (1) by default.
1493
1494       acpi_s4=BOOLEAN
1495           Include S4 (suspend-to-disk) power state in the virtual firmware
1496           ACPI table. True (1) by default.
1497
1498       acpi_laptop_slate=BOOLEAN
1499           Include the Windows laptop/slate mode switch device in the virtual
1500           firmware ACPI table. False (0) by default.
1501
1502       apic=BOOLEAN
1503           (x86 only) Include information regarding APIC (Advanced
1504           Programmable Interrupt Controller) in the firmware/BIOS tables on a
1505           single processor guest. This causes the MP (multiprocessor) and PIR
1506           (PCI Interrupt Routing) tables to be exported by the virtual
1507           firmware. This option has no effect on a guest with multiple
1508           virtual CPUs as they must always include these tables. This option
1509           is enabled by default and you should usually omit it but it may be
1510           necessary to disable these firmware tables when using certain older
1511           guest Operating Systems. These tables have been superseded by newer
1512           constructs within the ACPI tables.
1513
1514       nx=BOOLEAN
1515           (x86 only) Hides or exposes the No-eXecute capability. This allows
1516           a guest Operating System to map pages in such a way that they
1517           cannot be executed which can enhance security. This options
1518           requires that PAE also be enabled.
1519
1520       hpet=BOOLEAN
1521           (x86 only) Enables or disables HPET (High Precision Event Timer).
1522           This option is enabled by default and you should usually omit it.
1523           It may be necessary to disable the HPET in order to improve
1524           compatibility with guest Operating Systems.
1525
1526       altp2m="MODE"
1527           (x86 only) Specifies the access mode to the alternate-p2m
1528           capability.  Alternate-p2m allows a guest to manage multiple p2m
1529           guest physical "memory views" (as opposed to a single p2m).  You
1530           may want this option if you want to access-control/isolate access
1531           to specific guest physical memory pages accessed by the guest, e.g.
1532           for domain memory introspection or for isolation/access-control of
1533           memory between components within a single guest domain. This option
1534           is disabled by default.
1535
1536           The valid values are as follows:
1537
1538           disabled
1539               Altp2m is disabled for the domain (default).
1540
1541           mixed
1542               The mixed mode allows access to the altp2m interface for both
1543               in-guest and external tools as well.
1544
1545           external
1546               Enables access to the alternate-p2m capability by external
1547               privileged tools.
1548
1549           limited
1550               Enables limited access to the alternate-p2m capability, ie.
1551               giving the guest access only to enable/disable the VMFUNC and
1552               #VE features.
1553
1554       altp2mhvm=BOOLEAN
1555           Enables or disables HVM guest access to alternate-p2m capability.
1556           Alternate-p2m allows a guest to manage multiple p2m guest physical
1557           "memory views" (as opposed to a single p2m). This option is
1558           disabled by default and is available only to HVM domains.  You may
1559           want this option if you want to access-control/isolate access to
1560           specific guest physical memory pages accessed by the guest, e.g.
1561           for HVM domain memory introspection or for isolation/access-control
1562           of memory between components within a single guest HVM domain. This
1563           option is deprecated, use the option "altp2m" instead.
1564
1565           Note: While the option "altp2mhvm" is deprecated, legacy
1566           applications for x86 systems will continue to work using it.
1567
1568       nestedhvm=BOOLEAN
1569           Enable or disables guest access to hardware virtualisation
1570           features, e.g. it allows a guest Operating System to also function
1571           as a hypervisor. You may want this option if you want to run
1572           another hypervisor (including another copy of Xen) within a Xen
1573           guest or to support a guest Operating System which uses hardware
1574           virtualisation extensions (e.g. Windows XP compatibility mode on
1575           more modern Windows OS).  This option is disabled by default.
1576
1577       cpuid="LIBXL_STRING" or cpuid=[ "XEND_STRING", "XEND_STRING" ]
1578           Configure the value returned when a guest executes the CPUID
1579           instruction.  Two versions of config syntax are recognized: libxl
1580           and xend.
1581
1582           Both formats use a common notation for specifying a single feature
1583           bit.  Possible values are:
1584             '1' -> force the corresponding bit to 1
1585             '0' -> force to 0
1586             'x' -> Get a safe value (pass through and mask with the default
1587           policy)
1588             'k' -> pass through the host bit value (at boot only - value
1589           preserved on migrate)
1590             's' -> legacy alias for 'k'
1591
1592           Libxl format:
1593
1594               The libxl format is a single string, starting with the word
1595               "host", and followed by a comma separated list of key=value
1596               pairs.  A few keys take a numerical value, all others take a
1597               single character which describes what to do with the feature
1598               bit.  e.g.:
1599
1600                   cpuid="host,tm=0,sse3=0"
1601
1602               List of keys taking a value:
1603
1604                   apicidsize brandid clflush family localapicid maxleaf
1605                   maxhvleaf model nc proccount procpkg stepping
1606
1607               List of keys taking a character:
1608
1609                   3dnow 3dnowext 3dnowprefetch abm acpi adx aes altmovcr8
1610                   apic arat avx avx2 avx512-4fmaps avx512-4vnniw avx512bw
1611                   avx512cd avx512dq avx512er avx512f avx512ifma avx512pf
1612                   avx512vbmi avx512vl bmi1 bmi2 clflushopt clfsh clwb cmov
1613                   cmplegacy cmpxchg16 cmpxchg8 cmt cntxid dca de ds dscpl
1614                   dtes64 erms est extapic f16c ffxsr fma fma4 fpu fsgsbase
1615                   fxsr hle htt hypervisor ia64 ibs invpcid invtsc lahfsahf lm
1616                   lwp mca mce misalignsse mmx mmxext monitor movbe mpx msr
1617                   mtrr nodeid nx ospke osvw osxsave pae page1gb pat pbe pcid
1618                   pclmulqdq pdcm perfctr_core perfctr_nb pge pku popcnt pse
1619                   pse36 psn rdrand rdseed rdtscp rtm sha skinit smap smep smx
1620                   ss sse sse2 sse3 sse4.1 sse4.2 sse4_1 sse4_2 sse4a ssse3
1621                   svm svm_decode svm_lbrv svm_npt svm_nrips svm_pausefilt
1622                   svm_tscrate svm_vmcbclean syscall sysenter tbm tm tm2
1623                   topoext tsc tsc-deadline tsc_adjust umip vme vmx wdt x2apic
1624                   xop xsave xtpr
1625
1626           Xend format:
1627
1628               Xend format consists of an array of one or more strings of the
1629               form "leaf:reg=bitstring,...".  e.g. (matching the libxl
1630               example above):
1631
1632                   cpuid=["1:ecx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0,edx=xx0xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
1633                   ...]
1634
1635               "leaf" is an integer, either decimal or hex with a "0x" prefix.
1636               e.g. to specify something in the AMD feature leaves, use
1637               "0x80000001:ecx=...".
1638
1639               Some leaves have subleaves which can be specified as
1640               "leaf,subleaf".  e.g. for the Intel structured feature leaf,
1641               use "7,0:ebx=..."
1642
1643               The bitstring represents all bits in the register, its length
1644               must be 32 chars.  Each successive character represent a
1645               lesser-significant bit.
1646
1647           Note: when specifying cpuid for hypervisor leaves (0x4000xxxx major
1648           group) only the lowest 8 bits of leaf's 0x4000xx00 EAX register are
1649           processed, the rest are ignored (these 8 bits signify maximum
1650           number of hypervisor leaves).
1651
1652           More info about the CPUID instruction can be found in the processor
1653           manuals, and on Wikipedia: <https://en.wikipedia.org/wiki/CPUID>
1654
1655       acpi_firmware="STRING"
1656           Specifies a path to a file that contains extra ACPI firmware tables
1657           to pass into a guest. The file can contain several tables in their
1658           binary AML form concatenated together. Each table self describes
1659           its length so no additional information is needed. These tables
1660           will be added to the ACPI table set in the guest. Note that
1661           existing tables cannot be overridden by this feature. For example,
1662           this cannot be used to override tables like DSDT, FADT, etc.
1663
1664       smbios_firmware="STRING"
1665           Specifies a path to a file that contains extra SMBIOS firmware
1666           structures to pass into a guest. The file can contain a set of DMTF
1667           predefined structures which will override the internal defaults.
1668           Not all predefined structures can be overridden, only the following
1669           types: 0, 1, 2, 3, 11, 22, 39. The file can also contain any number
1670           of vendor defined SMBIOS structures (type 128 - 255). Since SMBIOS
1671           structures do not present their overall size, each entry in the
1672           file must be preceded by a 32b integer indicating the size of the
1673           following structure.
1674
1675       ms_vm_genid="OPTION"
1676           Provide a VM generation ID to the guest.
1677
1678           The VM generation ID is a 128-bit random number that a guest may
1679           use to determine if the guest has been restored from an earlier
1680           snapshot or cloned.
1681
1682           This is required for Microsoft Windows Server 2012 (and later)
1683           domain controllers.
1684
1685           Valid options are:
1686
1687           generate
1688               Generate a random VM generation ID every time the domain is
1689               created or restored.
1690
1691           none
1692               Do not provide a VM generation ID.
1693
1694           See also "Virtual Machine Generation ID" by Microsoft:
1695           <https://docs.microsoft.com/en-us/windows/win32/hyperv_v2/virtual-machine-generation-identifier>
1696
1697       Guest Virtual Time Controls
1698
1699       tsc_mode="MODE"
1700           (x86 only) Specifies how the TSC (Time Stamp Counter) should be
1701           provided to the guest. Specifying this option as a number is
1702           deprecated.
1703
1704           Options are:
1705
1706           default
1707               Guest rdtsc/p is executed natively when monotonicity can be
1708               guaranteed and emulated otherwise (with frequency scaled if
1709               necessary).
1710
1711               If a HVM container in default TSC mode is created on a host
1712               that provides constant host TSC, its guest TSC frequency will
1713               be the same as the host. If it is later migrated to another
1714               host that provide constant host TSC and supports Intel VMX TSC
1715               scaling/AMD SVM TSC ratio, its guest TSC frequency will be the
1716               same before and after migration, and guest rdtsc/p will be
1717               executed natively after migration as well
1718
1719           always_emulate
1720               Guest rdtsc/p is always emulated and the virtual TSC will
1721               appear to increment (kernel and user) at a fixed 1GHz rate,
1722               regardless of the pCPU HZ rate or power state. Although there
1723               is an overhead associated with emulation, this will NOT affect
1724               underlying CPU performance.
1725
1726           native
1727               Guest rdtsc/p is always executed natively (no
1728               monotonicity/frequency guarantees). Guest rdtsc/p is emulated
1729               at native frequency if unsupported by h/w, else executed
1730               natively.
1731
1732           native_paravirt
1733               This mode has been removed.
1734
1735           Please see xen-tscmode(7) for more information on this option.
1736
1737       localtime=BOOLEAN
1738           Set the real time clock to local time or to UTC. False (0) by
1739           default, i.e. set to UTC.
1740
1741       rtc_timeoffset=SECONDS
1742           Set the real time clock offset in seconds. No offset (0) by
1743           default.
1744
1745       vpt_align=BOOLEAN
1746           Specifies that periodic Virtual Platform Timers should be aligned
1747           to reduce guest interrupts. Enabling this option can reduce power
1748           consumption, especially when a guest uses a high timer interrupt
1749           frequency (HZ) values. The default is true (1).
1750
1751       timer_mode="MODE"
1752           Specifies the mode for Virtual Timers. The valid values are as
1753           follows:
1754
1755           delay_for_missed_ticks
1756               Delay for missed ticks. Do not advance a vCPU's time beyond the
1757               correct delivery time for interrupts that have been missed due
1758               to preemption. Deliver missed interrupts when the vCPU is
1759               rescheduled and advance the vCPU's virtual time stepwise for
1760               each one.
1761
1762           no_delay_for_missed_ticks
1763               No delay for missed ticks. As above, missed interrupts are
1764               delivered, but guest time always tracks wallclock (i.e., real)
1765               time while doing so. This is the default.
1766
1767           no_missed_ticks_pending
1768               No missed interrupts are held pending. Instead, to ensure ticks
1769               are delivered at some non-zero rate, if we detect missed ticks
1770               then the internal tick alarm is not disabled if the vCPU is
1771               preempted during the next tick period.
1772
1773           one_missed_tick_pending
1774               One missed tick pending. Missed interrupts are collapsed
1775               together and delivered as one 'late tick'.  Guest time always
1776               tracks wallclock (i.e., real) time.
1777
1778       Memory layout
1779
1780       mmio_hole=MBYTES
1781           Specifies the size the MMIO hole below 4GiB will be.  Only valid
1782           for device_model_version="qemu-xen".
1783
1784           Cannot be smaller than 256. Cannot be larger than 3840.
1785
1786           Known good large value is 3072.
1787
1788       Support for Paravirtualisation of HVM Guests
1789
1790       The following options allow Paravirtualised features (such as devices)
1791       to be exposed to the guest Operating System in an HVM guest.  Utilising
1792       these features requires specific guest support but when available they
1793       will result in improved performance.
1794
1795       xen_platform_pci=BOOLEAN
1796           Enable or disable the Xen platform PCI device.  The presence of
1797           this virtual device enables a guest Operating System (subject to
1798           the availability of suitable drivers) to make use of
1799           paravirtualisation features such as disk and network devices etc.
1800           Enabling these drivers improves performance and is strongly
1801           recommended when available. PV drivers are available for various
1802           Operating Systems including HVM Linux (out-of-the-box) and
1803           Microsoft Windows <https://xenproject.org/windows-pv-drivers/>.
1804
1805           Setting xen_platform_pci=0 with the default device_model "qemu-xen"
1806           requires at least QEMU 1.6.
1807
1808       viridian=[ "GROUP", "GROUP", ...] or viridian=BOOLEAN
1809           The groups of Microsoft Hyper-V (AKA viridian) compatible
1810           enlightenments exposed to the guest. The following groups of
1811           enlightenments may be specified:
1812
1813           base
1814               This group incorporates the Hypercall MSRs, Virtual processor
1815               index MSR, and APIC access MSRs. These enlightenments can
1816               improve performance of Windows Vista and Windows Server 2008
1817               onwards and setting this option for such guests is strongly
1818               recommended.  This group is also a pre-requisite for all
1819               others. If it is disabled then it is an error to attempt to
1820               enable any other group.
1821
1822           freq
1823               This group incorporates the TSC and APIC frequency MSRs. These
1824               enlightenments can improve performance of Windows 7 and Windows
1825               Server 2008 R2 onwards.
1826
1827           time_ref_count
1828               This group incorporates Partition Time Reference Counter MSR.
1829               This enlightenment can improve performance of Windows 8 and
1830               Windows Server 2012 onwards.
1831
1832           reference_tsc
1833               This set incorporates the Partition Reference TSC MSR. This
1834               enlightenment can improve performance of Windows 7 and Windows
1835               Server 2008 R2 onwards.
1836
1837           hcall_remote_tlb_flush
1838               This set incorporates use of hypercalls for remote TLB
1839               flushing.  This enlightenment may improve performance of
1840               Windows guests running on hosts with higher levels of
1841               (physical) CPU contention.
1842
1843           apic_assist
1844               This set incorporates use of the APIC assist page to avoid EOI
1845               of the local APIC.  This enlightenment may improve performance
1846               of guests that make use of per-vCPU event channel upcall
1847               vectors.  Note that this enlightenment will have no effect if
1848               the guest is using APICv posted interrupts.
1849
1850           crash_ctl
1851               This group incorporates the crash control MSRs. These
1852               enlightenments allow Windows to write crash information such
1853               that it can be logged by Xen.
1854
1855           stimer
1856               This set incorporates the SynIC and synthetic timer MSRs.
1857               Windows will use synthetic timers in preference to emulated
1858               HPET for a source of ticks and hence enabling this group will
1859               ensure that ticks will be consistent with use of an enlightened
1860               time source (time_ref_count or reference_tsc).
1861
1862           hcall_ipi
1863               This set incorporates use of a hypercall for interprocessor
1864               interrupts.  This enlightenment may improve performance of
1865               Windows guests with multiple virtual CPUs.
1866
1867           defaults
1868               This is a special value that enables the default set of groups,
1869               which is currently the base, freq, time_ref_count, apic_assist,
1870               crash_ctl and stimer groups.
1871
1872           all This is a special value that enables all available groups.
1873
1874           Groups can be disabled by prefixing the name with '!'. So, for
1875           example, to enable all groups except freq, specify:
1876
1877               viridian=[ "all", "!freq" ]
1878
1879           For details of the enlightenments see the latest version of
1880           Microsoft's Hypervisor Top-Level Functional Specification.
1881
1882           The enlightenments should be harmless for other versions of Windows
1883           (although they will not give any benefit) and the majority of other
1884           non-Windows OSes.  However it is known that they are incompatible
1885           with some other Operating Systems and in some circumstance can
1886           prevent Xen's own paravirtualisation interfaces for HVM guests from
1887           being used.
1888
1889           The viridian option can be specified as a boolean. A value of true
1890           (1) is equivalent to the list [ "defaults" ], and a value of false
1891           (0) is equivalent to an empty list.
1892
1893       Emulated VGA Graphics Device
1894
1895       The following options control the features of the emulated graphics
1896       device.  Many of these options behave similarly to the equivalent key
1897       in the VFB_SPEC_STRING for configuring virtual frame buffer devices
1898       (see above).
1899
1900       videoram=MBYTES
1901           Sets the amount of RAM which the emulated video card will contain,
1902           which in turn limits the resolutions and bit depths which will be
1903           available.
1904
1905           When using the qemu-xen-traditional device-model, the default as
1906           well as minimum amount of video RAM for stdvga is 8 MB, which is
1907           sufficient for e.g.  1600x1200 at 32bpp. For the upstream qemu-xen
1908           device-model, the default and minimum is 16 MB.
1909
1910           When using the emulated Cirrus graphics card (vga="cirrus") and the
1911           qemu-xen-traditional device-model, the amount of video RAM is fixed
1912           at 4 MB, which is sufficient for 1024x768 at 32 bpp. For the
1913           upstream qemu-xen device-model, the default and minimum is 8 MB.
1914
1915           For QXL vga, both the default and minimal are 128MB.  If videoram
1916           is set less than 128MB, an error will be triggered.
1917
1918       stdvga=BOOLEAN
1919           Speficies a standard VGA card with VBE (VESA BIOS Extensions) as
1920           the emulated graphics device. If your guest supports VBE 2.0 or
1921           later (e.g. Windows XP onwards) then you should enable this.
1922           stdvga supports more video ram and bigger resolutions than Cirrus.
1923           The default is false (0) which means to emulate a Cirrus Logic
1924           GD5446 VGA card.  This option is deprecated, use vga="stdvga"
1925           instead.
1926
1927       vga="STRING"
1928           Selects the emulated video card.  Options are: none, stdvga, cirrus
1929           and qxl.  The default is cirrus.
1930
1931           In general, QXL should work with the Spice remote display protocol
1932           for acceleration, and a QXL driver is necessary in the guest in
1933           that case.  QXL can also work with the VNC protocol, but it will be
1934           like a standard VGA card without acceleration.
1935
1936       vnc=BOOLEAN
1937           Allow access to the display via the VNC protocol.  This enables the
1938           other VNC-related settings.  The default is (1) enabled.
1939
1940       vnclisten="ADDRESS[:DISPLAYNUM]"
1941           Specifies the IP address and, optionally, the VNC display number to
1942           use.
1943
1944       vncdisplay=DISPLAYNUM
1945           Specifies the VNC display number to use. The actual TCP port number
1946           will be DISPLAYNUM+5900.
1947
1948       vncunused=BOOLEAN
1949           Requests that the VNC display setup searches for a free TCP port to
1950           use.  The actual display used can be accessed with xl vncviewer.
1951
1952       vncpasswd="PASSWORD"
1953           Specifies the password for the VNC server. If the password is set
1954           to an empty string, authentication on the VNC server will be
1955           disabled allowing any user to connect.
1956
1957       keymap="LANG"
1958           Configure the keymap to use for the keyboard associated with this
1959           display. If the input method does not easily support raw keycodes
1960           (e.g. this is often the case when using VNC) then this allows us to
1961           correctly map the input keys into keycodes seen by the guest. The
1962           specific values which are accepted are defined by the version of
1963           the device-model which you are using. See Keymaps below or consult
1964           the qemu(1) manpage. The default is en-us.
1965
1966       sdl=BOOLEAN
1967           Specifies that the display should be presented via an X window
1968           (using Simple DirectMedia Layer). The default is (0) not enabled.
1969
1970       opengl=BOOLEAN
1971           Enable OpenGL acceleration of the SDL display. Only effects
1972           machines using device_model_version="qemu-xen-traditional" and only
1973           if the device-model was compiled with OpenGL support. Default is
1974           (0) false.
1975
1976       nographic=BOOLEAN
1977           Enable or disable the virtual graphics device.  The default is to
1978           provide a VGA graphics device but this option can be used to
1979           disable it.
1980
1981       Spice Graphics Support
1982
1983       The following options control the features of SPICE.
1984
1985       spice=BOOLEAN
1986           Allow access to the display via the SPICE protocol.  This enables
1987           the other SPICE-related settings.
1988
1989       spicehost="ADDRESS"
1990           Specifies the interface address to listen on if given, otherwise
1991           any interface.
1992
1993       spiceport=NUMBER
1994           Specifies the port to listen on by the SPICE server if SPICE is
1995           enabled.
1996
1997       spicetls_port=NUMBER
1998           Specifies the secure port to listen on by the SPICE server if SPICE
1999           is enabled. At least one of spiceport or spicetls_port must be
2000           given if SPICE is enabled.
2001
2002           Note: the options depending on spicetls_port have not been
2003           supported.
2004
2005       spicedisable_ticketing=BOOLEAN
2006           Enable clients to connect without specifying a password. When
2007           disabled, spicepasswd must be set. The default is (0) false.
2008
2009       spicepasswd="PASSWORD"
2010           Specify the password which is used by clients for establishing a
2011           connection.
2012
2013       spiceagent_mouse=BOOLEAN
2014           Whether SPICE agent is used for client mouse mode. The default is
2015           (1) true.
2016
2017       spicevdagent=BOOLEAN
2018           Enables the SPICE vdagent. The SPICE vdagent is an optional
2019           component for enhancing user experience and performing guest-
2020           oriented management tasks. Its features include: client mouse mode
2021           (no need to grab the mouse by the client, no mouse lag), automatic
2022           adjustment of screen resolution, copy and paste (text and image)
2023           between the client and the guest. It also requires the vdagent
2024           service installed on the guest OS to work.  The default is (0)
2025           disabled.
2026
2027       spice_clipboard_sharing=BOOLEAN
2028           Enables SPICE clipboard sharing (copy/paste). It requires that
2029           spicevdagent is enabled. The default is (0) false.
2030
2031       spiceusbredirection=NUMBER
2032           Enables SPICE USB redirection. Creates a NUMBER of USB redirection
2033           channels for redirecting up to 4 USB devices from the SPICE client
2034           to the guest's QEMU.  It requires an USB controller and, if not
2035           defined, it will automatically add an USB2.0 controller. The
2036           default is (0) disabled.
2037
2038       spice_image_compression="COMPRESSION"
2039           Specifies what image compression is to be used by SPICE (if given),
2040           otherwise the QEMU default will be used. Please see the
2041           documentation of your QEMU version for more details.
2042
2043           Available options are: auto_glz, auto_lz, quic, glz, lz, off.
2044
2045       spice_streaming_video="VIDEO"
2046           Specifies what streaming video setting is to be used by SPICE (if
2047           given), otherwise the QEMU default will be used.
2048
2049           Available options are: filter, all, off.
2050
2051       Miscellaneous Emulated Hardware
2052
2053       serial=[ "DEVICE", "DEVICE", ...]
2054           Redirect virtual serial ports to DEVICEs. Please see the -serial
2055           option in the qemu(1) manpage for details of the valid DEVICE
2056           options. Default is vc when in graphical mode and stdio if
2057           nographic=1 is used.
2058
2059           The form serial=DEVICE is also accepted for backwards
2060           compatibility.
2061
2062       soundhw="DEVICE"
2063           Select the virtual sound card to expose to the guest. The valid
2064           devices are defined by the device model configuration, please see
2065           the qemu(1) manpage for details. The default is not to export any
2066           sound device.
2067
2068       vkb_device=BOOLEAN
2069           Specifies that the HVM guest gets a vkdb. The default is true (1).
2070
2071       usb=BOOLEAN
2072           Enables or disables an emulated USB bus in the guest.
2073
2074       usbversion=NUMBER
2075           Specifies the type of an emulated USB bus in the guest, values 1
2076           for USB1.1, 2 for USB2.0 and 3 for USB3.0. It is available only
2077           with an upstream QEMU.  Due to implementation limitations this is
2078           not compatible with the usb and usbdevice parameters.  Default is
2079           (0) no USB controller defined.
2080
2081       usbdevice=[ "DEVICE", "DEVICE", ...]
2082           Adds DEVICEs to the emulated USB bus. The USB bus must also be
2083           enabled using usb=1. The most common use for this option is
2084           usbdevice=['tablet'] which adds a pointer device using absolute
2085           coordinates. Such devices function better than relative coordinate
2086           devices (such as a standard mouse) since many methods of exporting
2087           guest graphics (such as VNC) work better in this mode. Note that
2088           this is independent of the actual pointer device you are using on
2089           the host/client side.
2090
2091           Host devices can also be passed through in this way, by specifying
2092           host:USBID, where USBID is of the form xxxx:yyyy.  The USBID can
2093           typically be found by using lsusb(1) or usb-devices(1).
2094
2095           If you wish to use the "host:bus.addr" format, remove any leading
2096           '0' from the bus and addr. For example, for the USB device on bus
2097           008 dev 002, you should write "host:8.2".
2098
2099           The form usbdevice=DEVICE is also accepted for backwards
2100           compatibility.
2101
2102           More valid options can be found in the "usbdevice" section of the
2103           QEMU documentation.
2104
2105       vendor_device="VENDOR_DEVICE"
2106           Selects which variant of the QEMU xen-pvdevice should be used for
2107           this guest. Valid values are:
2108
2109           none
2110               The xen-pvdevice should be omitted. This is the default.
2111
2112           xenserver
2113               The xenserver variant of the xen-pvdevice (device-id=C000) will
2114               be specified, enabling the use of XenServer PV drivers in the
2115               guest.
2116
2117           This parameter only takes effect when
2118           device_model_version=qemu-xen.  See xen-pci-device-reservations(7)
2119           for more information.
2120
2121   PVH Guest Specific Options
2122       nestedhvm=BOOLEAN
2123           Enable or disables guest access to hardware virtualisation
2124           features, e.g. it allows a guest Operating System to also function
2125           as a hypervisor.  You may want this option if you want to run
2126           another hypervisor (including another copy of Xen) within a Xen
2127           guest or to support a guest Operating System which uses hardware
2128           virtualisation extensions (e.g. Windows XP compatibility mode on
2129           more modern Windows OS).
2130
2131           This option is disabled by default.
2132
2133       bootloader="PROGRAM"
2134           Run "PROGRAM" to find the kernel image and ramdisk to use.
2135           Normally "PROGRAM" would be "pygrub", which is an emulation of
2136           grub/grub2/syslinux. Either kernel or bootloader must be specified
2137           for PV guests.
2138
2139       bootloader_args=[ "ARG", "ARG", ...]
2140           Append ARGs to the arguments to the bootloader program.
2141           Alternatively if the argument is a simple string then it will be
2142           split into words at whitespace (this second option is deprecated).
2143
2144       timer_mode="MODE"
2145           Specifies the mode for Virtual Timers. The valid values are as
2146           follows:
2147
2148           delay_for_missed_ticks
2149               Delay for missed ticks. Do not advance a vCPU's time beyond the
2150               correct delivery time for interrupts that have been missed due
2151               to preemption. Deliver missed interrupts when the vCPU is
2152               rescheduled and advance the vCPU's virtual time stepwise for
2153               each one.
2154
2155           no_delay_for_missed_ticks
2156               No delay for missed ticks. As above, missed interrupts are
2157               delivered, but guest time always tracks wallclock (i.e., real)
2158               time while doing so. This is the default.
2159
2160           no_missed_ticks_pending
2161               No missed interrupts are held pending. Instead, to ensure ticks
2162               are delivered at some non-zero rate, if we detect missed ticks
2163               then the internal tick alarm is not disabled if the vCPU is
2164               preempted during the next tick period.
2165
2166           one_missed_tick_pending
2167               One missed tick pending. Missed interrupts are collapsed
2168               together and delivered as one 'late tick'.  Guest time always
2169               tracks wallclock (i.e., real) time.
2170
2171       Paging
2172
2173       The following options control the mechanisms used to virtualise guest
2174       memory.  The defaults are selected to give the best results for the
2175       common cases so you should normally leave these options unspecified.
2176
2177       hap=BOOLEAN
2178           Turns "hardware assisted paging" (the use of the hardware nested
2179           page table feature) on or off.  This feature is called EPT
2180           (Extended Page Tables) by Intel and NPT (Nested Page Tables) or RVI
2181           (Rapid Virtualisation Indexing) by AMD. If turned off, Xen will run
2182           the guest in "shadow page table" mode where the guest's page table
2183           updates and/or TLB flushes etc. will be emulated.  Use of HAP is
2184           the default when available.
2185
2186       oos=BOOLEAN
2187           Turns "out of sync pagetables" on or off.  When running in shadow
2188           page table mode, the guest's page table updates may be deferred as
2189           specified in the Intel/AMD architecture manuals.  However, this may
2190           expose unexpected bugs in the guest, or find bugs in Xen, so it is
2191           possible to disable this feature.  Use of out of sync page tables,
2192           when Xen thinks it appropriate, is the default.
2193
2194       shadow_memory=MBYTES
2195           Number of megabytes to set aside for shadowing guest pagetable
2196           pages (effectively acting as a cache of translated pages) or to use
2197           for HAP state. By default this is 1MB per guest vCPU plus 8KB per
2198           MB of guest RAM. You should not normally need to adjust this value.
2199           However, if you are not using hardware assisted paging (i.e. you
2200           are using shadow mode) and your guest workload consists of a very
2201           large number of similar processes then increasing this value may
2202           improve performance.
2203
2204   Device-Model Options
2205       The following options control the selection of the device-model.  This
2206       is the component which provides emulation of the virtual devices to an
2207       HVM guest.  For a PV guest a device-model is sometimes used to provide
2208       backends for certain PV devices (most usually a virtual framebuffer
2209       device).
2210
2211       device_model_version="DEVICE-MODEL"
2212           Selects which variant of the device-model should be used for this
2213           guest.
2214
2215           Valid values are:
2216
2217           qemu-xen
2218               Use the device-model merged into the upstream QEMU project.
2219               This device-model is the default for Linux dom0.
2220
2221           qemu-xen-traditional
2222               Use the device-model based upon the historical Xen fork of
2223               QEMU.  This device-model is still the default for NetBSD dom0.
2224
2225           It is recommended to accept the default value for new guests.  If
2226           you have existing guests then, depending on the nature of the guest
2227           Operating System, you may wish to force them to use the device
2228           model which they were installed with.
2229
2230       device_model_override="PATH"
2231           Override the path to the binary to be used as the device-model
2232           running in toolstack domain. The binary provided here MUST be
2233           consistent with the device_model_version which you have specified.
2234           You should not normally need to specify this option.
2235
2236       stubdomain_kernel="PATH"
2237           Override the path to the kernel image used as device-model
2238           stubdomain.  The binary provided here MUST be consistent with the
2239           device_model_version which you have specified.  In case of qemu-
2240           xen-traditional it is expected to be MiniOS-based stubdomain image,
2241           in case of qemu-xen it is expected to be Linux-based stubdomain
2242           kernel.
2243
2244       stubdomain_ramdisk="PATH"
2245           Override the path to the ramdisk image used as device-model
2246           stubdomain.  The binary provided here is to be used by a kernel
2247           pointed by stubdomain_kernel.  It is known to be used only by
2248           Linux-based stubdomain kernel.
2249
2250       stubdomain_memory=MBYTES
2251           Start the stubdomain with MBYTES megabytes of RAM. Default is 128.
2252
2253       device_model_stubdomain_override=BOOLEAN
2254           Override the use of stubdomain based device-model.  Normally this
2255           will be automatically selected based upon the other features and
2256           options you have selected.
2257
2258       device_model_stubdomain_seclabel="LABEL"
2259           Assign an XSM security label to the device-model stubdomain.
2260
2261       device_model_args=[ "ARG", "ARG", ...]
2262           Pass additional arbitrary options on the device-model command line.
2263           Each element in the list is passed as an option to the device-
2264           model.
2265
2266       device_model_args_pv=[ "ARG", "ARG", ...]
2267           Pass additional arbitrary options on the device-model command line
2268           for a PV device model only. Each element in the list is passed as
2269           an option to the device-model.
2270
2271       device_model_args_hvm=[ "ARG", "ARG", ...]
2272           Pass additional arbitrary options on the device-model command line
2273           for an HVM device model only. Each element in the list is passed as
2274           an option to the device-model.
2275
2276   Keymaps
2277       The keymaps available are defined by the device-model which you are
2278       using. Commonly this includes:
2279
2280               ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
2281               da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
2282               de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
2283
2284       The default is en-us.
2285
2286       See qemu(1) for more information.
2287
2288   Architecture Specific options
2289       ARM
2290
2291       gic_version="vN"
2292           Version of the GIC emulated for the guest.
2293
2294           Currently, the following versions are supported:
2295
2296           v2  Emulate a GICv2
2297
2298           v3  Emulate a GICv3. Note that the emulated GIC does not support
2299               the GICv2 compatibility mode.
2300
2301           default
2302               Emulate the same version as the native GIC hardware used by the
2303               host where the domain was created.
2304
2305           This requires hardware compatibility with the requested version,
2306           either natively or via hardware backwards compatibility support.
2307
2308       vuart="uart"
2309           To enable vuart console, user must specify the following option in
2310           the VM config file:
2311
2312           vuart = "sbsa_uart"
2313
2314           Currently, only the "sbsa_uart" model is supported for ARM.
2315
2316       x86
2317
2318       mca_caps=[ "CAP", "CAP", ... ]
2319           (HVM only) Enable MCA capabilities besides default ones enabled by
2320           Xen hypervisor for the HVM domain. "CAP" can be one in the
2321           following list:
2322
2323           "lmce"
2324               Intel local MCE
2325
2326           default
2327               No MCA capabilities in above list are enabled.
2328

SEE ALSO

2330       xl(1)
2331       xl.conf(5)
2332       xlcpupool.cfg(5)
2333       xl-disk-configuration(5)
2334       xl-network-configuration(5)
2335       xen-tscmode(7)
2336

FILES

2338       /etc/xen/NAME.cfg /var/lib/xen/dump/NAME
2339

BUGS

2341       This document may contain items which require further documentation.
2342       Patches to improve incomplete items (or any other item) are gratefully
2343       received on the xen-devel@lists.xenproject.org mailing list. Please see
2344       <https://wiki.xenproject.org/wiki/Submitting_Xen_Project_Patches> for
2345       information on how to submit a patch to Xen.
2346
2347
2348
23494.14.2                            2021-05-04                         xl.cfg(5)
Impressum