From mboxrd@z Thu Jan 1 00:00:00 1970 From: Andrew Cooper Subject: Re: [PATCH DOCDAY] improve documentation of Xen command line paramters Date: Mon, 30 Jul 2012 20:49:03 +0100 Message-ID: <5016E52F.9020903@citrix.com> References: <5016DC9E.4020801@citrix.com> <20120730194131.GC8228@US-SEA-R8XVZTX> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: <20120730194131.GC8228@US-SEA-R8XVZTX> List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Sender: xen-devel-bounces@lists.xen.org Errors-To: xen-devel-bounces@lists.xen.org To: Matt Wilson Cc: Ian Campbell , "xen-devel@lists.xen.org" List-Id: xen-devel@lists.xenproject.org On 30/07/12 20:41, Matt Wilson wrote: > On Mon, Jul 30, 2012 at 12:12:30PM -0700, Andrew Cooper wrote: >> On 30/07/12 20:06, Matt Wilson wrote: >>> This change improves documentation for several Xen command line >>> parameters. Some of the Itanium-specific options are now removed. A >>> more thorough check should be performed to remove any other remnants. >>> >>> I've reformatted some of the entries to fit in 80 column terminals. >>> >>> Options that are yet undocumented but accept standard boolean / >>> integer values are now annotated as such. >>> >>> The size suffixes have been corrected to use the binary prefixes >>> instead of decimal prefixes. >>> >>> Signed-off-by: Matt Wilson >> Acked-by: Andrew Cooper > Unfortunately subject line has a horrible typo and doesn't have docs: > in front. Should I submit a fixed patch, or could someone fix it up > if it's committed? > > Sorry about that! > > Matt I suggest a resend, as it will not have been committed in this short time. ~Andrew > >>> diff -r bf922651da96 -r c3a6e679bdfa docs/misc/xen-command-line.markdown >>> --- a/docs/misc/xen-command-line.markdown Sat Jul 28 17:27:30 2012 +0000 >>> +++ b/docs/misc/xen-command-line.markdown Mon Jul 30 19:04:59 2012 +0000 >>> @@ -46,9 +46,9 @@ if a leading `0` is present. >>> >>> A size parameter may be any integer, with a size suffix >>> >>> -* `G` or `g`: Giga (2^30) >>> -* `M` or `m`: Mega (2^20) >>> -* `K` or `k`: Kilo (2^10) >>> +* `G` or `g`: Gibi (2^30) >>> +* `M` or `m`: Mibi (2^20) >>> +* `K` or `k`: Kibi (2^10) >>> * `B` or `b`: Bytes >>> >>> Without a size suffix, the default will be kilo. >>> @@ -107,8 +107,10 @@ Specify which ACPI MADT table to parse f >>> than one is present. >>> >>> ### acpi\_pstate\_strict >>> +> `= ` >>> >>> ### acpi\_skip\_timer\_override >>> +> `= ` >>> >>> Instruct Xen to ignore timer-interrupt override. >>> >>> @@ -117,6 +119,8 @@ the domain 0 kernel this option is autom >>> domain 0 command line >>> >>> ### acpi\_sleep >>> +> `= s3_bios | s3_mode` >>> + >>> ### allowsuperpage >>> > `= ` >>> >>> @@ -136,12 +140,12 @@ there are more than 8 CPUs, Xen will swi >>> >>> > Default: `false` >>> >>> -Force boot on potentially unsafe systems. By default Xen will refuse to boot on >>> -systems with the following errata: >>> +Force boot on potentially unsafe systems. By default Xen will refuse >>> +to boot on systems with the following errata: >>> >>> * AMD Erratum 121. Processors with this erratum are subject to a guest >>> - triggerable Denial of Service. Override only if you trust all of your PV >>> - guests. >>> + triggerable Denial of Service. Override only if you trust all of >>> + your PV guests. >>> >>> ### apic\_verbosity >>> > `= verbose | debug` >>> @@ -153,15 +157,16 @@ Increase the verbosity of the APIC code >>> >>> > Default: `true` >>> >>> -Permits Xen to set up and use PCI Address Translation Services, which is required >>> -for PCI Passthrough. >>> +Permits Xen to set up and use PCI Address Translation Services, which >>> +is required for PCI Passthrough. >>> >>> ### availmem >>> > `= ` >>> >>> > Default: `0` (no limit) >>> >>> -Specify a maximum amount of available memory, to which Xen will clamp the e820 table. >>> +Specify a maximum amount of available memory, to which Xen will clamp >>> +the e820 table. >>> >>> ### badpage >>> > `= List of [ | - ]` >>> @@ -176,8 +181,9 @@ Xen's command line. >>> >>> > Default: `true` >>> >>> -Scrub free RAM during boot. This is a safety feature to prevent accidentally leaking >>> -sensitive VM data into other VMs if Xen crashes and reboots. >>> +Scrub free RAM during boot. This is a safety feature to prevent >>> +accidentally leaking sensitive VM data into other VMs if Xen crashes >>> +and reboots. >>> >>> ### cachesize >>> > `= ` >>> @@ -227,7 +233,6 @@ Both option `com1` and `com2` follow the >>> >>> A typical setup for most situations might be `com1=115200,8n1` >>> >>> - >>> ### conring\_size >>> > `= ` >>> >>> @@ -300,25 +305,30 @@ Indicate where the responsibility for dr >>> ### cpuid\_mask\_cpu (AMD only) >>> > `= fam_0f_rev_c | fam_0f_rev_d | fam_0f_rev_e | fam_0f_rev_f | fam_0f_rev_g | fam_10_rev_b | fam_10_rev_c | fam_11_rev_b` >>> >>> -If the other **cpuid\_mask\_{,ext\_}e{c,d}x** options are fully set (unspecified >>> -on the command line), specify a pre-canned cpuid mask to mask the current >>> -processor down to appear as the specified processor. It is important to ensure >>> -that all hosts in a pool appear the same to guests to allow successful live >>> -migration. >>> +If the other **cpuid\_mask\_{,ext\_}e{c,d}x** options are fully set >>> +(unspecified on the command line), specify a pre-canned cpuid mask to >>> +mask the current processor down to appear as the specified processor. >>> +It is important to ensure that all hosts in a pool appear the same to >>> +guests to allow successful live migration. >>> >>> ### cpuid\_mask\_ ecx,edx,ext\_ecx,ext\_edx,xsave_eax >>> > `= ` >>> >>> > Default: `~0` (all bits set) >>> >>> -These five command line parameters are used to specify cpuid masks to help with >>> -cpuid levelling across a pool of hosts. Setting a bit in the mask indicates that >>> -the feature should be enabled, while clearing a bit in the mask indicates that >>> -the feature should be disabled. It is important to ensure that all hosts in a >>> -pool appear the same to guests to allow successful live migration. >>> +These five command line parameters are used to specify cpuid masks to >>> +help with cpuid levelling across a pool of hosts. Setting a bit in >>> +the mask indicates that the feature should be enabled, while clearing >>> +a bit in the mask indicates that the feature should be disabled. It >>> +is important to ensure that all hosts in a pool appear the same to >>> +guests to allow successful live migration. >>> >>> ### cpuidle >>> +> `= ` >>> + >>> ### cpuinfo >>> +> `= ` >>> + >>> ### crashinfo_maxaddr >>> > `= ` >>> >>> @@ -328,17 +338,42 @@ Specify the maximum address to allocate >>> combination with the `low_crashinfo` command line option. >>> >>> ### crashkernel >>> +> `= :[,...][@]` >>> + >>> ### credit2\_balance\_over >>> +> `= ` >>> + >>> ### credit2\_balance\_under >>> +> `= ` >>> + >>> ### credit2\_load\_window\_shift >>> +> `= ` >>> + >>> ### debug\_stack\_lines >>> +> `= ` >>> + >>> +> Default: `20` >>> + >>> +Limits the number lines printed in Xen stack traces. >>> + >>> ### debugtrace >>> +> `= ` >>> + >>> +> Default: `128` >>> + >>> +Specify the size of the console debug trace buffer in KiB. The debug >>> +trace feature is only enabled in debugging builds of Xen. >>> + >>> ### dma\_bits >>> > `= ` >>> >>> Specify the bit width of the DMA heap. >>> >>> ### dom0\_ioports\_disable >>> +> `= List of -` >>> + >>> +Specify a list of IO ports to be excluded from dom0 access. >>> + >>> ### dom0\_max\_vcpus >>> > `= ` >>> >>> @@ -372,6 +407,8 @@ For example, to set dom0's initial memor >>> allow it to balloon up as far as 1GB use `dom0_mem=512M,max:1G` >>> >>> ### dom0\_shadow >>> +> `= ` >>> + >>> ### dom0\_vcpus\_pin >>> > `= ` >>> >>> @@ -379,10 +416,21 @@ allow it to balloon up as far as 1GB use >>> >>> Pin dom0 vcpus to their respective pcpus >>> >>> -### dom0\_vhpt\_size\_log2 >>> -### dom\_rid\_bits >>> ### e820-mtrr-clip >>> +> `= ` >>> + >>> +Flag that specifies if RAM should be clipped to the highest cacheable >>> +MTRR. >>> + >>> +> Default: `true` on Intel CPUs, otherwise `false` >>> + >>> ### e820-verbose >>> +> `= ` >>> + >>> +> Default: `false` >>> + >>> +Flag that enables verbose output when processing e820 information and >>> +applying clipping. >>> >>> ### edd (x86) >>> > `= off | on | skipmbr` >>> @@ -397,17 +445,32 @@ Either force retrieval of monitor EDID i >>> disable it (edid=no). This option should not normally be required >>> except for debugging purposes. >>> >>> -### efi\_print >>> ### extra\_guest\_irqs >>> > `= ` >>> >>> Increase the number of PIRQs available for the guest. The default is 32. >>> >>> ### flask\_enabled >>> +> `= ` >>> + >>> ### flask\_enforcing >>> +> `= ` >>> + >>> ### font >>> +> `= ` where height is `8x8 | 8x14 | 8x16 '` >>> + >>> +Specify the font size when using the VESA console driver. >>> + >>> ### gdb >>> +> `= [/][,DPS[,[,[,[,]]]] | pci | amt ] ` >>> + >>> +Specify the serial parameters for the GDB stub. >>> + >>> ### gnttab\_max\_nr\_frames >>> +> `= ` >>> + >>> +Specify the maximum number of frames per grant table operation. >>> + >>> ### guest\_loglvl >>> > `= [/]` where level is `none | error | warning | info | debug | all` >>> >>> @@ -420,15 +483,41 @@ The optional `` opti >>> should be rate limited. >>> >>> ### hap\_1gb >>> +> `= ` >>> + >>> +> Default: `true` >>> + >>> +Flag to enable 1 GB host page table support for Hardware Assisted >>> +Paging (HAP). >>> + >>> ### hap\_2mb >>> +> `= ` >>> + >>> +> Default: `true` >>> + >>> +Flag to enable 1 GB host page table support for Hardware Assisted >>> +Paging (HAP). >>> + >>> ### hpetbroadcast >>> +> `= ` >>> + >>> ### hvm\_debug >>> +> `= ` >>> + >>> ### hvm\_port80 >>> +> `= ` >>> + >>> ### idle\_latency\_factor >>> +> `= ` >>> + >>> ### ioapic\_ack >>> ### iommu >>> ### iommu\_inclusive\_mapping >>> +> `= ` >>> + >>> ### irq\_ratelimit >>> +> `= ` >>> + >>> ### irq\_vector\_map >>> ### lapic >>> >>> @@ -437,7 +526,11 @@ if left disabled by the BIOS. This opti >>> all. >>> >>> ### lapic\_timer\_c2\_ok >>> +> `= ` >>> + >>> ### ler >>> +> `= ` >>> + >>> ### loglvl >>> > `= [/]` where level is `none | error | warning | info | debug | all` >>> >>> @@ -461,18 +554,38 @@ so the crash kernel may find find them. >>> with **crashinfo_maxaddr**. >>> >>> ### max\_cstate >>> +> `= ` >>> + >>> ### max\_gsi\_irqs >>> +> `= ` >>> + >>> ### maxcpus >>> +> `= ` >>> + >>> ### mce >>> +> `= ` >>> + >>> ### mce\_fb >>> +> `= ` >>> + >>> ### mce\_verbosity >>> +> `= verbose` >>> + >>> +Specify verbose machine check output. >>> + >>> ### mem >>> > `= ` >>> >>> -Specifies the maximum address of physical RAM. Any RAM beyond this >>> +Specify the maximum address of physical RAM. Any RAM beyond this >>> limit is ignored by Xen. >>> >>> ### mmcfg >>> +> `= [,amd-fam10]` >>> + >>> +> Default: `1` >>> + >>> +Specify if the MMConfig space should be enabled. >>> + >>> ### nmi >>> > `= ignore | dom0 | fatal` >>> >>> @@ -493,6 +606,8 @@ domain 0 kernel this option is automatic >>> 0 command line. >>> >>> ### nofxsr >>> +> `= ` >>> + >>> ### noirqbalance >>> > `= ` >>> >>> @@ -501,11 +616,15 @@ systems such as Dell 1850/2850 that have >>> IRQ routing issues. >>> >>> ### nolapic >>> +> `= ` >>> + >>> +> Default: `false` >>> >>> Ignore the local APIC on a uniprocessor system, even if enabled by the >>> BIOS. This option will accept value. >>> >>> ### no-real-mode (x86) >>> +> `= ` >>> >>> Do not execute real-mode bootstrap code when booting Xen. This option >>> should not be used except for debugging. It will effectively disable >>> @@ -519,6 +638,10 @@ catching debug output. Defaults to auto >>> seconds. >>> >>> ### noserialnumber >>> +> `= ` >>> + >>> +Disable CPU serial number reporting. >>> + >>> ### nosmp >>> > `= ` >>> >>> @@ -526,11 +649,39 @@ Disable SMP support. No secondary proce >>> Defaults to booting secondary processors. >>> >>> ### nr\_irqs >>> +> `= ` >>> + >>> ### numa >>> -### pervcpu\_vhpt >>> +> `= on | off | fake= | noacpi` >>> + >>> +Default: `on` >>> + >>> ### ple\_gap >>> +> `= ` >>> + >>> ### ple\_window >>> +> `= ` >>> + >>> ### reboot >>> +> `= b[ios] | t[riple] | k[bd] | n[o] [, [w]arm | [c]old]` >>> + >>> +Default: `0` >>> + >>> +Specify the host reboot method. >>> + >>> +`warm` instructs Xen to not set the cold reboot flag. >>> + >>> +`cold` instructs Xen to set the cold reboot flag. >>> + >>> +`bios` instructs Xen to reboot the host by jumping to BIOS. This is >>> +only available on 32-bit x86 platforms. >>> + >>> +`triple` instructs Xen to reboot the host by causing a triple fault. >>> + >>> +`kbd` instructs Xen to reboot the host via the keyboard controller. >>> + >>> +`acpi` instructs Xen to reboot the host using RESET_REG in the ACPI FADT. >>> + >>> ### sched >>> > `= credit | credit2 | sedf | arinc653` >>> >>> @@ -539,10 +690,20 @@ Defaults to booting secondary processors >>> Choose the default scheduler. >>> >>> ### sched\_credit2\_migrate\_resist >>> +> `= ` >>> + >>> ### sched\_credit\_default\_yield >>> +> `= ` >>> + >>> ### sched\_credit\_tslice\_ms >>> +> `= ` >>> + >>> ### sched\_ratelimit\_us >>> +> `= ` >>> + >>> ### sched\_smt\_power\_savings >>> +> `= ` >>> + >>> ### serial\_tx\_buffer >>> > `= ` >>> >>> @@ -551,7 +712,15 @@ Choose the default scheduler. >>> Set the serial transmit buffer size. >>> >>> ### smep >>> +> `= ` >>> + >>> +> Default: `true` >>> + >>> +Flag to enable Supervisor Mode Execution Protection >>> + >>> ### snb\_igd\_quirk >>> +> `= ` >>> + >>> ### sync\_console >>> > `= ` >>> >>> @@ -561,28 +730,80 @@ Flag to force synchronous console output >>> not suitable for production environments due to incurred overhead. >>> >>> ### tboot >>> +> `= 0x` >>> + >>> +Specify the physical address of the trusted boot shared page. >>> + >>> ### tbuf\_size >>> > `= ` >>> >>> Specify the per-cpu trace buffer size in pages. >>> >>> ### tdt >>> +> `= ` >>> + >>> +> Default: `true` >>> + >>> +Flag to enable TSC deadline as the APIC timer mode. >>> + >>> ### tevt\_mask >>> +> `= ` >>> + >>> +Specify a mask for Xen event tracing. This allows Xen tracing to be >>> +enabled at boot. Refer to the xentrace(8) documentation for a list of >>> +valid event mask values. In order to enable tracing, a buffer size (in >>> +pages) must also be specified via the tbuf\_size parameter. >>> + >>> ### tickle\_one\_idle\_cpu >>> +> `= ` >>> + >>> ### timer\_slop >>> +> `= ` >>> + >>> ### tmem >>> +> `= ` >>> + >>> ### tmem\_compress >>> +> `= ` >>> + >>> ### tmem\_dedup >>> +> `= ` >>> + >>> ### tmem\_lock >>> +> `= ` >>> + >>> ### tmem\_shared\_auth >>> +> `= ` >>> + >>> ### tmem\_tze >>> +> `= ` >>> + >>> ### tsc >>> +> `= unstable | skewed` >>> + >>> ### ucode >>> ### unrestricted\_guest >>> +> `= ` >>> + >>> ### vcpu\_migration\_delay >>> +> `= ` >>> + >>> +> Default: `0` >>> + >>> +Specify a delay, in microseconds, between migrations of a VCPU between >>> +PCPUs when using the credit1 scheduler. This prevents rapid fluttering >>> +of a VCPU between CPUs, and reduces the implicit overheads such as >>> +cache-warming. 1ms (1000) has been measured as a good value. >>> + >>> ### vesa-map >>> +> `= ` >>> + >>> ### vesa-mtrr >>> +> `= ` >>> + >>> ### vesa-ram >>> +> `= ` >>> + >>> ### vga >>> > `= ( ask | current | text-80x | gfx-xx | mode- )[,keep]` >>> >>> >>> _______________________________________________ >>> Xen-devel mailing list >>> Xen-devel@lists.xen.org >>> http://lists.xen.org/xen-devel -- Andrew Cooper - Dom0 Kernel Engineer, Citrix XenServer T: +44 (0)1223 225 900, http://www.citrix.com