Re: [Xen-devel] [PATCH DOCDAY v3] docs: improve documentation of Xen command line parameters

[Ian Campbell <Ian.Campbell@xxxxxxxxxx>]

On Tue, 2012-08-07 at 04:24 +0100, Matt Wilson wrote:
> On Tue, Jul 31, 2012 at 08:36:40AM -0700, 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.
> >
> > Changes since v2:
> >  * Change *bi prefixes to GiB, MiB, KiB
> >
> > Signed-off-by: Matt Wilson <msw@xxxxxxxxxx>
> > Acked-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
> 
> George's concerns were adressed in this version, and Andrew gave an
> Ack. Anything else keeping this from landing in staging?

Keir, do you want to apply this sort of thing or shall I (it's not
really a tools doc so I haven't touched it)


> 
> Matt
> 
> > diff -r bf922651da96 -r 1809175cdc9b 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`: GiB (2^30)
> > +* `M` or `m`: MiB (2^20)
> > +* `K` or `k`: KiB (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
> > +> `= <integer>`
> >
> >  ### acpi\_skip\_timer\_override
> > +> `= <boolean>`
> >
> >  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
> >  > `= <boolean>`
> >
> > @@ -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
> >  > `= <size>`
> >
> >  > 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 [ <integer> | <integer>-<integer> ]`
> > @@ -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
> >  > `= <size>`
> > @@ -227,7 +233,6 @@ Both option `com1` and `com2` follow the
> >
> >  A typical setup for most situations might be `com1=115200,8n1`
> >
> > -
> >  ### conring\_size
> >  > `= <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
> >  > `= <integer>`
> >
> >  > 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
> > +> `= <boolean>`
> > +
> >  ### cpuinfo
> > +> `= <boolean>`
> > +
> >  ### crashinfo_maxaddr
> >  > `= <size>`
> >
> > @@ -328,17 +338,42 @@ Specify the maximum address to allocate
> >  combination with the `low_crashinfo` command line option.
> >
> >  ### crashkernel
> > +> `= <ramsize-range>:<size>[,...][@<offset>]`
> > +
> >  ### credit2\_balance\_over
> > +> `= <integer>`
> > +
> >  ### credit2\_balance\_under
> > +> `= <integer>`
> > +
> >  ### credit2\_load\_window\_shift
> > +> `= <integer>`
> > +
> >  ### debug\_stack\_lines
> > +> `= <integer>`
> > +
> > +> Default: `20`
> > +
> > +Limits the number lines printed in Xen stack traces.
> > +
> >  ### debugtrace
> > +> `= <integer>`
> > +
> > +> 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
> >  > `= <integer>`
> >
> >  Specify the bit width of the DMA heap.
> >
> >  ### dom0\_ioports\_disable
> > +> `= List of <hex>-<hex>`
> > +
> > +Specify a list of IO ports to be excluded from dom0 access.
> > +
> >  ### dom0\_max\_vcpus
> >  > `= <integer>`
> >
> > @@ -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
> > +> `= <boolean>`
> > +
> >  ### dom0\_vcpus\_pin
> >  > `= <boolean>`
> >
> > @@ -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
> > +> `= <boolean>`
> > +
> > +Flag that specifies if RAM should be clipped to the highest cacheable
> > +MTRR.
> > +
> > +> Default: `true` on Intel CPUs, otherwise `false`
> > +
> >  ### e820-verbose
> > +> `= <boolean>`
> > +
> > +> 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
> >  > `= <number>`
> >
> >  Increase the number of PIRQs available for the guest. The default is 32.
> >
> >  ### flask\_enabled
> > +> `= <integer>`
> > +
> >  ### flask\_enforcing
> > +> `= <integer>`
> > +
> >  ### font
> > +> `= <height>` where height is `8x8 | 8x14 | 8x16 '`
> > +
> > +Specify the font size when using the VESA console driver.
> > +
> >  ### gdb
> > +> `= 
> > <baud>[/<clock_hz>][,DPS[,<io-base>[,<irq>[,<port-bdf>[,<bridge-bdf>]]]] | 
> > pci | amt ] `
> > +
> > +Specify the serial parameters for the GDB stub.
> > +
> >  ### gnttab\_max\_nr\_frames
> > +> `= <integer>`
> > +
> > +Specify the maximum number of frames per grant table operation.
> > +
> >  ### guest\_loglvl
> >  > `= <level>[/<rate-limited level>]` where level is `none | error | 
> > warning | info | debug | all`
> >
> > @@ -420,15 +483,41 @@ The optional `<rate-limited level>` opti
> >  should be rate limited.
> >
> >  ### hap\_1gb
> > +> `= <boolean>`
> > +
> > +> Default: `true`
> > +
> > +Flag to enable 1 GB host page table support for Hardware Assisted
> > +Paging (HAP).
> > +
> >  ### hap\_2mb
> > +> `= <boolean>`
> > +
> > +> Default: `true`
> > +
> > +Flag to enable 1 GB host page table support for Hardware Assisted
> > +Paging (HAP).
> > +
> >  ### hpetbroadcast
> > +> `= <boolean>`
> > +
> >  ### hvm\_debug
> > +> `= <integer>`
> > +
> >  ### hvm\_port80
> > +> `= <boolean>`
> > +
> >  ### idle\_latency\_factor
> > +> `= <integer>`
> > +
> >  ### ioapic\_ack
> >  ### iommu
> >  ### iommu\_inclusive\_mapping
> > +> `= <boolean>`
> > +
> >  ### irq\_ratelimit
> > +> `= <integer>`
> > +
> >  ### irq\_vector\_map
> >  ### lapic
> >
> > @@ -437,7 +526,11 @@ if left disabled by the BIOS.  This opti
> >  all.
> >
> >  ### lapic\_timer\_c2\_ok
> > +> `= <boolean>`
> > +
> >  ### ler
> > +> `= <boolean>`
> > +
> >  ### loglvl
> >  > `= <level>[/<rate-limited level>]` 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
> > +> `= <integer>`
> > +
> >  ### max\_gsi\_irqs
> > +> `= <integer>`
> > +
> >  ### maxcpus
> > +> `= <integer>`
> > +
> >  ### mce
> > +> `= <integer>`
> > +
> >  ### mce\_fb
> > +> `= <integer>`
> > +
> >  ### mce\_verbosity
> > +> `= verbose`
> > +
> > +Specify verbose machine check output.
> > +
> >  ### mem
> >  > `= <size>`
> >
> > -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
> > +> `= <boolean>[,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
> > +> `= <boolean>`
> > +
> >  ### noirqbalance
> >  > `= <boolean>`
> >
> > @@ -501,11 +616,15 @@ systems such as Dell 1850/2850 that have
> >  IRQ routing issues.
> >
> >  ### nolapic
> > +> `= <boolean>`
> > +
> > +> 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)
> > +> `= <boolean>`
> >
> >  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
> > +> `= <boolean>`
> > +
> > +Disable CPU serial number reporting.
> > +
> >  ### nosmp
> >  > `= <boolean>`
> >
> > @@ -526,11 +649,39 @@ Disable SMP support.  No secondary proce
> >  Defaults to booting secondary processors.
> >
> >  ### nr\_irqs
> > +> `= <integer>`
> > +
> >  ### numa
> > -### pervcpu\_vhpt
> > +> `= on | off | fake=<integer> | noacpi`
> > +
> > +Default: `on`
> > +
> >  ### ple\_gap
> > +> `= <integer>`
> > +
> >  ### ple\_window
> > +> `= <integer>`
> > +
> >  ### 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
> > +> `= <integer>`
> > +
> >  ### sched\_credit\_default\_yield
> > +> `= <boolean>`
> > +
> >  ### sched\_credit\_tslice\_ms
> > +> `= <integer>`
> > +
> >  ### sched\_ratelimit\_us
> > +> `= <integer>`
> > +
> >  ### sched\_smt\_power\_savings
> > +> `= <boolean>`
> > +
> >  ### serial\_tx\_buffer
> >  > `= <size>`
> >
> > @@ -551,7 +712,15 @@ Choose the default scheduler.
> >  Set the serial transmit buffer size.
> >
> >  ### smep
> > +> `= <boolean>`
> > +
> > +> Default: `true`
> > +
> > +Flag to enable Supervisor Mode Execution Protection
> > +
> >  ### snb\_igd\_quirk
> > +> `= <boolean>`
> > +
> >  ### sync\_console
> >  > `= <boolean>`
> >
> > @@ -561,28 +730,80 @@ Flag to force synchronous console output
> >  not suitable for production environments due to incurred overhead.
> >
> >  ### tboot
> > +> `= 0x<phys_addr>`
> > +
> > +Specify the physical address of the trusted boot shared page.
> > +
> >  ### tbuf\_size
> >  > `= <integer>`
> >
> >  Specify the per-cpu trace buffer size in pages.
> >
> >  ### tdt
> > +> `= <boolean>`
> > +
> > +> Default: `true`
> > +
> > +Flag to enable TSC deadline as the APIC timer mode.
> > +
> >  ### tevt\_mask
> > +> `= <integer>`
> > +
> > +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
> > +> `= <boolean>`
> > +
> >  ### timer\_slop
> > +> `= <integer>`
> > +
> >  ### tmem
> > +> `= <boolean>`
> > +
> >  ### tmem\_compress
> > +> `= <boolean>`
> > +
> >  ### tmem\_dedup
> > +> `= <boolean>`
> > +
> >  ### tmem\_lock
> > +> `= <integer>`
> > +
> >  ### tmem\_shared\_auth
> > +> `= <boolean>`
> > +
> >  ### tmem\_tze
> > +> `= <integer>`
> > +
> >  ### tsc
> > +> `= unstable | skewed`
> > +
> >  ### ucode
> >  ### unrestricted\_guest
> > +> `= <boolean>`
> > +
> >  ### vcpu\_migration\_delay
> > +> `= <integer>`
> > +
> > +> 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
> > +> `= <integer>`
> > +
> >  ### vesa-mtrr
> > +> `= <integer>`
> > +
> >  ### vesa-ram
> > +> `= <integer>`
> > +
> >  ### vga
> >  > `= ( ask | current | text-80x<rows> | gfx-<width>x<height>x<depth> | 
> > mode-<mode> )[,keep]`
> >
> >
> > _______________________________________________
> > Xen-devel mailing list
> > Xen-devel@xxxxxxxxxxxxx
> > http://lists.xen.org/xen-devel
> 
> _______________________________________________
> Xen-devel mailing list
> Xen-devel@xxxxxxxxxxxxx
> http://lists.xen.org/xen-devel



_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel