Stefano Stabellini
2011-Nov-30 14:15 UTC
[PATCH XenDocDay 00/19] xl.pod.1 updates and fixes
Hi all,
this patch series containes few updates and fixes to xl.pod.1.
Stefano Stabellini (19):
xl.pod.1: add a barebone description of tmem commands
xl.pod.1: add a description of console options
xl.pod.1: improve create documentation
xl.pod.1: add a description of the global options
xl.pod.1: order subcommands alphabetically
xl.pod.1: remove the two FIXME
xl.pod.1: add a reference to create in the -e option
xl.pod.1: state when a command requires PV drivers installed
xl.pod.1: better description for the sysreq subcommand
xl.pod.1: state when a subcommand is only available to HVM guests
xl.pod.1: introduce a TO BE DOCUMENTED section
xl.pod.1: improve the debug-keys subcommand description
xl.pod.1: improve the description of the info subcommand
xl.pod.1: improve the description of pci-list-assignable-devices
xl.pod.1: remove dry-run option from create and cpupool-create
xl.pod.1: improve description of virtual device subcommands
xl.pod.1: remove AUTHORS section
xl.pod.1: add a refence to http://wiki.xen.org/xenwiki/ReportingBugs
xl.pod.1: add a note about autoballoon and dom0_mem
docs/man/xl.pod.1 | 317 ++++++++++++++++++++++++++++++++++++++---------------
1 files changed, 229 insertions(+), 88 deletions(-)
A git branch based on xen-unstable is available here:
git://xenbits.xen.org/people/sstabellini/xen-unstable.git docs
Cheers,
Stefano
<stefano.stabellini@eu.citrix.com>
2011-Nov-30 14:16 UTC
[PATCH XenDocDay 01/19] xl.pod.1: add a barebone description of tmem commands
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> --- docs/man/xl.pod.1 | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 66 insertions(+), 0 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index bd83192..92593a6 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -793,6 +793,72 @@ List pass-through pci devices for a domain. =back +=head2 TMEM + +=over 4 + +=item B<tmem-list> I[<-l>] I<domain-id> + +List tmem pools. If I<-l> is specified, also list tmem stats. + +=item B<tmem-freeze> I<domain-id> + +Freeze tmem pools. + +=item B<tmem-destroy> I<domain-id> + +Destroy tmem pools. + +=item B<tmem-thaw> I<domain-id> + +Thaw tmem pools. + +=item B<tmem-set> I<domain-id> [I<OPTIONS>] + +Change tmem settings. + +B<OPTIONS> + +=over 4 + +=item B<-w> I<WEIGHT> + +Weight (int) + +=item B<-c> I<CAP> + +Cap (int) + +=item B<-p> I<COMPRESS> + +Compress (int) + +=back + +=item B<tmem-shared-auth> I<domain-id> [I<OPTIONS>] + +De/authenticate shared tmem pool. + +B<OPTIONS> + +=over 4 + +=item B<-u> I<UUID> + +Specify uuid (abcdef01-2345-6789-1234-567890abcdef) + +=item B<-a> I<AUTH> + +0=auth,1=deauth + +=back + +=item B<tmem-freeable> + +Get information about how much freeable memory (MB) is in-use by tmem. + +=back + =head1 SEE ALSO L<xl.cfg(5)>, L<xlcpupool.cfg(5)>, B<xentop(1)> -- 1.7.2.5
<stefano.stabellini@eu.citrix.com>
2011-Nov-30 14:16 UTC
[PATCH XenDocDay 02/19] xl.pod.1: add a description of console options
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> --- docs/man/xl.pod.1 | 19 ++++++++++++++++++- 1 files changed, 18 insertions(+), 1 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index 92593a6..426b8e8 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -105,7 +105,7 @@ soon as it is run. =back -=item B<console> I<domain-id> +=item B<console> [I<OPTIONS>] I<domain-id> Attach to domain I<domain-id>''s console. If you''ve set up your domains to have a traditional log in console this will look much like a normal @@ -113,6 +113,23 @@ text log in screen. Use the key combination Ctrl+] to detach the domain console. +B<OPTIONS> + +=over 4 + +=item I<-t [pv|serial]> + +Connect to a PV console or connect to an emulated serial console. +PV consoles are the only consoles available for PV domains while HVM +domains can have both. If this option is not specified it defaults to +emulated serial for HVM guests and PV console for PV guests. + +=item I<-n NUM> + +Connect to console number I<NUM>. Console numbers start from 0. + +=back + =item B<vncviewer> [I<OPTIONS>] I<domain-id> Attach to domain''s VNC server, forking a vncviewer process. -- 1.7.2.5
<stefano.stabellini@eu.citrix.com>
2011-Nov-30 14:16 UTC
[PATCH XenDocDay 03/19] xl.pod.1: improve create documentation
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> --- docs/man/xl.pod.1 | 21 +++++++++++++++------ 1 files changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index 426b8e8..8cc9779 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -52,13 +52,14 @@ previously, most commands take I<domain-id> as the first parameter. =over 4 -=item B<create> [I<OPTIONS>] I<configfile> +=item B<create> [I<configfile>] [I<OPTIONS>] -The create subcommand requires a config file: see L<xl.cfg(5)> for -full details of that file format and possible options. +The create subcommand takes a config file as first argument: see +L<xl.cfg> for full details of that file format and possible options. +If I<configfile> is missing B<XL> creates the domain starting from the +default value for every option. -I<configfile> can either be an absolute path to a file, or a relative -path to a file located in /etc/xen. +I<configfile> has to be an absolute path to a file. Create will return B<as soon> as the domain is started. This B<does not> mean the guest OS in the domain has actually booted, or is @@ -88,7 +89,15 @@ Leave the domain paused after it is created. =item B<-c> Attach console to the domain as soon as it has started. This is -useful for determining issues with crashing domains. +useful for determining issues with crashing domains and just as a +general convenience since you often want to watch the +domain boot. + +=item B<key=value> + +It is possible to pass I<key=value> pairs on the command line to provide +options as if they were written in the configuration file; these override +whatever is in the I<configfile>. =back -- 1.7.2.5
<stefano.stabellini@eu.citrix.com>
2011-Nov-30 14:16 UTC
[PATCH XenDocDay 04/19] xl.pod.1: add a description of the global options
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> --- docs/man/xl.pod.1 | 16 ++++++++++++++++ 1 files changed, 16 insertions(+), 0 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index 8cc9779..292b3c6 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -45,6 +45,22 @@ Most B<xl> commands require root privileges to run due to the communications channels used to talk to the hypervisor. Running as non root will return an error. +=head1 GLOBAL OPTIONS + +Some global options are always available: + +=over 4 + +=item B<-v> + +Verbose. + +=item B<-N> + +Dry run: do not actually execute the command. + +=back + =head1 DOMAIN SUBCOMMANDS The following subcommands manipulate domains directly. As stated -- 1.7.2.5
<stefano.stabellini@eu.citrix.com>
2011-Nov-30 14:16 UTC
[PATCH XenDocDay 05/19] xl.pod.1: order subcommands alphabetically
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> --- docs/man/xl.pod.1 | 59 ++++++++++++++++++++++++++--------------------------- 1 files changed, 29 insertions(+), 30 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index 292b3c6..d860c00 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -68,6 +68,11 @@ previously, most commands take I<domain-id> as the first parameter. =over 4 +=item B<button-press> I<domain-id> I<button> + +Indicate an ACPI button press to the domain. I<button> is may be ''power'' or +''sleep''. + =item B<create> [I<configfile>] [I<OPTIONS>] The create subcommand takes a config file as first argument: see @@ -155,20 +160,6 @@ Connect to console number I<NUM>. Console numbers start from 0. =back -=item B<vncviewer> [I<OPTIONS>] I<domain-id> - -Attach to domain''s VNC server, forking a vncviewer process. - -B<OPTIONS> - -=over 4 - -=item I<--autopass> - -Pass VNC password to vncviewer via stdin. - -=back - =item B<destroy> I<domain-id> Immediately terminate the domain I<domain-id>. This doesn''t give the @@ -195,6 +186,10 @@ I<filename> specified, without pausing the domain. The dump file will be written to a distribution specific directory for dump files. Such as: /var/lib/xen/dump or /var/xen/dump. +=item B<getenforce> + +Returns the current enforcing mode of the Flask Xen security module. + =item B<help> [I<--long>] Displays the short help message (i.e. common commands). @@ -298,6 +293,10 @@ less utilized than a high CPU workload. Consider yourself warned. =back +=item B<loadpolicy> I<policyfile> + +Loads a new policy int the Flask Xen security module. + =item B<mem-max> I<domain-id> I<mem> Specify the maximum amount of memory the domain is able to use, appending ''t'' @@ -386,6 +385,10 @@ Enable debug messages. =back +=item B<setenforce> I<1|0|Enforcing|Permissive> + +Sets the current enforcing mode of the Flask Xen security module + =item B<save> [I<OPTIONS>] I<domain-id> I<CheckpointFile> [I<ConfigFile>] Saves a running domain to a state file so that it can be restored @@ -395,7 +398,6 @@ B<xl restore> restores from this checkpoint file. Passing a config file argument allows the user to manually select the VM config file used to create the domain. - =over 4 =item B<-c> @@ -433,6 +435,11 @@ Send a I<Magic System Request> signal to the domain. For more information on available magic sys req operations, see sysrq.txt in your Linux Kernel sources. +=item B<trigger> I<domain-id> I<nmi|reset|init|power|sleep> [I<VCPU>] + +Send a trigger to a domain, where the trigger can be: nmi, reset, init, power +or sleep. Optionally a specific vcpu number can be passed as an argument. + =item B<unpause> I<domain-id> Moves a domain out of the paused state. This will allow a previously @@ -472,27 +479,19 @@ different run state is appropriate. Pinning can be used to restrict this, by ensuring certain VCPUs can only run on certain physical CPUs. -=item B<button-press> I<domain-id> I<button> - -Indicate an ACPI button press to the domain. I<button> is may be ''power'' or -''sleep''. - -=item B<trigger> I<domain-id> I<nmi|reset|init|power|sleep> [I<VCPU>] - -Send a trigger to a domain, where the trigger can be: nmi, reset, init, power -or sleep. Optionally a specific vcpu number can be passed as an argument. +=item B<vncviewer> [I<OPTIONS>] I<domain-id> -=item B<getenforce> +Attach to domain''s VNC server, forking a vncviewer process. -Returns the current enforcing mode of the Flask Xen security module. +B<OPTIONS> -=item B<setenforce> I<1|0|Enforcing|Permissive> +=over 4 -Sets the current enforcing mode of the Flask Xen security module +=item I<--autopass> -=item B<loadpolicy> I<policyfile> +Pass VNC password to vncviewer via stdin. -Loads a new policy int the Flask Xen security module. +=back =back -- 1.7.2.5
<stefano.stabellini@eu.citrix.com>
2011-Nov-30 14:16 UTC
[PATCH XenDocDay 06/19] xl.pod.1: remove the two FIXME
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> --- docs/man/xl.pod.1 | 5 ++--- 1 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index d860c00..14c7433 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -263,7 +263,8 @@ scheduling by the Xen hypervisor. =item B<s - shutdown> -FIXME: Why would you ever see this state? +The guest OS has shut down (SCHEDOP_shutdown has been called) but the +domain is not dying yet. =item B<c - crashed> @@ -276,8 +277,6 @@ restart on crash. See L<xl.cfg(5)> for more info. The domain is in process of dying, but hasn''t completely shutdown or crashed. -FIXME: Is this right? - =back B<NOTES> -- 1.7.2.5
<stefano.stabellini@eu.citrix.com>
2011-Nov-30 14:16 UTC
[PATCH XenDocDay 07/19] xl.pod.1: add a reference to create in the -e option
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> Add a reference to the create subcommand in the description of the -e option to unpause and migrate. Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> --- docs/man/xl.pod.1 | 3 ++- 1 files changed, 2 insertions(+), 1 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index 14c7433..2895853 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -337,7 +337,7 @@ Use <sshcommand> instead of ssh. String will be passed to sh. If empty, run =item B<-e> On the new host, do not wait in the background (on <host>) for the death of the -domain. +domain. See the corresponding option of the I<create> subcommand. =item B<-C> I<config> @@ -377,6 +377,7 @@ Do not unpause domain after restoring it. =item B<-e> Do not wait in the background for the death of the domain on the new host. +See the corresponding option of the I<create> subcommand. =item B<-d> -- 1.7.2.5
<stefano.stabellini@eu.citrix.com>
2011-Nov-30 14:16 UTC
[PATCH XenDocDay 08/19] xl.pod.1: state when a command requires PV drivers installed
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> Remove an old incorrect comment about vcpu-set requiring cooperation from the guest. Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> --- docs/man/xl.pod.1 | 6 ++---- 1 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index 2895853..df0610b 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -357,6 +357,7 @@ Reboot a domain. This acts just as if the domain had the B<reboot> command run from the console. The command returns as soon as it has executed the reboot action, which may be significantly before the domain actually reboots. +It requires PV drivers installed in your guest OS. The behavior of what happens to a domain when it reboots is set by the B<on_reboot> parameter of the domain configuration file when the @@ -414,6 +415,7 @@ to perform graceful shutdown, so there is no guarantee that it will succeed, and may take a variable length of time depending on what services must be shutdown in the domain. The command returns immediately after signally the domain unless that B<-w> flag is used. +For HVM domains it requires PV drivers to be installed in your guest OS. The behavior of what happens to a domain when it reboots is set by the B<on_shutdown> parameter of the domain configuration file when the @@ -459,10 +461,6 @@ Attempting to set the VCPUs to a number larger than the initially configured VCPU count is an error. Trying to set VCPUs to < 1 will be quietly ignored. -Because this operation requires cooperation from the domain operating -system, there is no guarantee that it will succeed. This command will -not work with a full virt domain. - =item B<vcpu-list> [I<domain-id>] Lists VCPU information for a specific domain. If no domain is -- 1.7.2.5
<stefano.stabellini@eu.citrix.com>
2011-Nov-30 14:16 UTC
[PATCH XenDocDay 09/19] xl.pod.1: better description for the sysreq subcommand
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> --- docs/man/xl.pod.1 | 8 +++++--- 1 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index df0610b..c9b2f44 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -433,9 +433,11 @@ Wait for the domain to complete shutdown before returning. =item B<sysrq> I<domain-id> I<letter> -Send a I<Magic System Request> signal to the domain. For more -information on available magic sys req operations, see sysrq.txt in -your Linux Kernel sources. +Send a <Magic System Request> to the domain, each type of request is +represented by a different letter. +It can be used to send SysRq requests to Linux guests, see sysrq.txt in +your Linux Kernel sources for more information. +It requires PV drivers to be installed in your guest OS. =item B<trigger> I<domain-id> I<nmi|reset|init|power|sleep> [I<VCPU>] -- 1.7.2.5
<stefano.stabellini@eu.citrix.com>
2011-Nov-30 14:16 UTC
[PATCH XenDocDay 10/19] xl.pod.1: state when a subcommand is only available to HVM guests
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> --- docs/man/xl.pod.1 | 3 ++- 1 files changed, 2 insertions(+), 1 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index c9b2f44..b9927a4 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -71,7 +71,7 @@ previously, most commands take I<domain-id> as the first parameter. =item B<button-press> I<domain-id> I<button> Indicate an ACPI button press to the domain. I<button> is may be ''power'' or -''sleep''. +''sleep''. This command is only available for HVM domains. =item B<create> [I<configfile>] [I<OPTIONS>] @@ -443,6 +443,7 @@ It requires PV drivers to be installed in your guest OS. Send a trigger to a domain, where the trigger can be: nmi, reset, init, power or sleep. Optionally a specific vcpu number can be passed as an argument. +This command is only available for HVM domains. =item B<unpause> I<domain-id> -- 1.7.2.5
<stefano.stabellini@eu.citrix.com>
2011-Nov-30 14:16 UTC
[PATCH XenDocDay 11/19] xl.pod.1: introduce a TO BE DOCUMENTED section
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> --- docs/man/xl.pod.1 | 16 ++++++++++++++++ 1 files changed, 16 insertions(+), 0 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index b9927a4..2344f4d 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -901,6 +901,22 @@ Get information about how much freeable memory (MB) is in-use by tmem. =back +=head1 TO BE DOCUMENTED + +We need better documentation for: + +=over 4 + +=item B<tmem> + +Trascendent Memory. + +=item B<Flask> + +Xen Flask security module. + +=back + =head1 SEE ALSO L<xl.cfg(5)>, L<xlcpupool.cfg(5)>, B<xentop(1)> -- 1.7.2.5
<stefano.stabellini@eu.citrix.com>
2011-Nov-30 14:16 UTC
[PATCH XenDocDay 12/19] xl.pod.1: improve the debug-keys subcommand description
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> --- docs/man/xl.pod.1 | 3 ++- 1 files changed, 2 insertions(+), 1 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index 2344f4d..ab8a2f3 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -502,7 +502,8 @@ Pass VNC password to vncviewer via stdin. =item B<debug-keys> I<keys> -Send debug I<keys> to Xen. +Send debug I<keys> to Xen. It is the same as pressing the Xen +"conswitch" (Ctrl-A by default) three times and then pressing "keys". =item B<dmesg> [B<-c>] -- 1.7.2.5
<stefano.stabellini@eu.citrix.com>
2011-Nov-30 14:16 UTC
[PATCH XenDocDay 13/19] xl.pod.1: improve the description of the info subcommand
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> also update the example Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> --- docs/man/xl.pod.1 | 55 +++++++++++++++++++++++++++------------------------- 1 files changed, 29 insertions(+), 26 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index ab8a2f3..a765a11 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -526,39 +526,41 @@ Clears Xen''s message buffer. Print information about the Xen host in I<name : value> format. When reporting a Xen bug, please provide this information as part of the -bug report. +bug report. See I<http://wiki.xen.org/xenwiki/ReportingBugs> on how to +report Xen bugs. -Sample output looks as follows (lines wrapped manually to make the man -page more readable): +Sample output looks as follows: - host : talon - release : 2.6.12.6-xen0 - version : #1 Mon Nov 14 14:26:26 EST 2005 - machine : i686 - nr_cpus : 2 + host : scarlett + release : 3.1.0-rc4+ + version : #1001 SMP Wed Oct 19 11:09:54 UTC 2011 + machine : x86_64 + nr_cpus : 4 nr_nodes : 1 - cores_per_socket : 1 + cores_per_socket : 4 threads_per_core : 1 - cpu_mhz : 696 - hw_caps : 0383fbff:00000000:00000000:00000040 - total_memory : 767 - free_memory : 37 - xen_major : 3 - xen_minor : 0 - xen_extra : -devel - xen_caps : xen-3.0-x86_32 + cpu_mhz : 2266 + hw_caps : bfebfbff:28100800:00000000:00003b40:009ce3bd:00000000:00000001:00000000 + virt_caps : hvm hvm_directio + total_memory : 6141 + free_memory : 4274 + free_cpus : 0 + xen_major : 4 + xen_minor : 2 + xen_extra : -unstable + xen_caps : xen-3.0-x86_64 xen-3.0-x86_32p hvm-3.0-x86_32 hvm-3.0-x86_32p hvm-3.0-x86_64 xen_scheduler : credit xen_pagesize : 4096 - platform_params : virt_start=0xfc000000 - xen_changeset : Mon Nov 14 18:13:38 2005 +0100 - 7793:090e44133d40 - cc_compiler : gcc version 3.4.3 (Mandrakelinux - 10.2 3.4.3-7mdk) - cc_compile_by : sdague - cc_compile_domain : (none) - cc_compile_date : Mon Nov 14 14:16:48 EST 2005 + platform_params : virt_start=0xffff800000000000 + xen_changeset : Wed Nov 02 17:09:09 2011 +0000 24066:54a5e994a241 + xen_commandline : com1=115200,8n1 guest_loglvl=all dom0_mem=750M console=com1 + cc_compiler : gcc version 4.4.5 (Debian 4.4.5-8) + cc_compile_by : sstabellini + cc_compile_domain : uk.xensource.com + cc_compile_date : Tue Nov 8 12:03:05 UTC 2011 xend_config_format : 4 + B<FIELDS> Not all fields will be explained here, but some of the less obvious @@ -570,7 +572,8 @@ ones deserve explanation: A vector showing what hardware capabilities are supported by your processor. This is equivalent to, though more cryptic, the flags -field in /proc/cpuinfo on a normal Linux machine. +field in /proc/cpuinfo on a normal Linux machine: they both derive from +the feature bits returned by the cpuid command on x86 platforms. =item B<free_memory> -- 1.7.2.5
<stefano.stabellini@eu.citrix.com>
2011-Nov-30 14:16 UTC
[PATCH XenDocDay 14/19] xl.pod.1: improve the description of pci-list-assignable-devices
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> --- docs/man/xl.pod.1 | 3 +++ 1 files changed, 3 insertions(+), 0 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index a765a11..7620a2b 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -614,6 +614,9 @@ Prints the current uptime of the domains running. =item B<pci-list-assignable-devices> List all the assignable PCI devices. +These are devices in the system which are configured to be +available for passthrough and are bound to a suitable PCI +backend driver in domain 0 rather than a real driver. =back -- 1.7.2.5
<stefano.stabellini@eu.citrix.com>
2011-Nov-30 14:16 UTC
[PATCH XenDocDay 15/19] xl.pod.1: remove dry-run option from create and cpupool-create
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> there is already a global dry-run option, there is no point in adding another one for each subcommand Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> --- docs/man/xl.pod.1 | 9 --------- 1 files changed, 0 insertions(+), 9 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index 7620a2b..3b1407f 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -98,11 +98,6 @@ No console output. Use the given configuration file. -=item B<-n>, B<--dryrun> - -Dry run - prints the resulting configuration in SXP but does not create -the domain. - =item B<-p> Leave the domain paused after it is created. @@ -684,10 +679,6 @@ B<OPTIONS> Use the given configuration file. -=item B<-n>, B<--dryrun> - -Dry run - prints the resulting configuration. - =back =item B<cpupool-list> [I<-c|--cpus>] [I<cpu-pool>] -- 1.7.2.5
<stefano.stabellini@eu.citrix.com>
2011-Nov-30 14:16 UTC
[PATCH XenDocDay 16/19] xl.pod.1: improve description of virtual device subcommands
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> Add a reference to xl-disk-configuration and xl-network-configuration. Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> --- docs/man/xl.pod.1 | 21 +++++++++++++++------ 1 files changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index 3b1407f..8348cd4 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -716,8 +716,8 @@ Splits up the machine into one cpu-pool per numa node. =head1 VIRTUAL DEVICE COMMANDS Most virtual devices can be added and removed while guests are -running. The effect to the guest OS is much the same as any hotplug -event. +running, assuming that the necessary support exists in the guest. The +effect to the guest OS is much the same as any hotplug event. =head2 BLOCK DEVICES @@ -739,7 +739,8 @@ The domain id of the guest domain that the device will be attached to. =item I<disc-spec-component> A disc specification in the same format used for the B<disk> variable in -the domain config file. See F<xl-disk-configuration>. +the domain config file. See +L<http://xenbits.xen.org/docs/unstable/misc/xl-disk-configuration.txt>. =back @@ -794,8 +795,9 @@ I<VirtualDevice> is the cdrom device in the guest to eject. Creates a new network device in the domain specified by I<domain-id>. I<network-device> describes the device to attach, using the same format as the -B<vif> string in the domain config file. See L<xl.cfg(5)> for the -description. +B<vif> string in the domain config file. See L<xl.cfg> and +L<http://xenbits.xen.org/docs/unstable/misc/xl-network-configuration.html> +for more informations. =item B<network-detach> I<domain-id> I<devid|mac> @@ -917,7 +919,14 @@ Xen Flask security module. =head1 SEE ALSO -L<xl.cfg(5)>, L<xlcpupool.cfg(5)>, B<xentop(1)> +The following man pages: + +L<xl.cfg>(5), L<xlcpupool.cfg>(5), B<xentop>(1) + +And the following documents on the xen.org website: + +L<http://xenbits.xen.org/docs/unstable/misc/xl-network-configuration.html> +L<http://xenbits.xen.org/docs/unstable/misc/xl-disk-configuration.txt> =head1 AUTHOR -- 1.7.2.5
<stefano.stabellini@eu.citrix.com>
2011-Nov-30 14:16 UTC
[PATCH XenDocDay 17/19] xl.pod.1: remove AUTHORS section
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> --- docs/man/xl.pod.1 | 7 ------- 1 files changed, 0 insertions(+), 7 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index 8348cd4..54e0f51 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -928,13 +928,6 @@ And the following documents on the xen.org website: L<http://xenbits.xen.org/docs/unstable/misc/xl-network-configuration.html> L<http://xenbits.xen.org/docs/unstable/misc/xl-disk-configuration.txt> -=head1 AUTHOR - - Stefano Stabellini <stefano.stabellini@eu.citrix.com> - Vincent Hanquez <vincent.hanquez@eu.citrix.com> - Ian Jackson <ian.jackson@eu.citrix.com> - Ian Campbell <Ian.Campbell@citrix.com> - =head1 BUGS Send bugs to xen-devel@lists.xensource.com. -- 1.7.2.5
<stefano.stabellini@eu.citrix.com>
2011-Nov-30 14:16 UTC
[PATCH XenDocDay 18/19] xl.pod.1: add a refence to http://wiki.xen.org/xenwiki/ReportingBugs
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> --- docs/man/xl.pod.1 | 3 ++- 1 files changed, 2 insertions(+), 1 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index 54e0f51..e8a5d21 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -930,4 +930,5 @@ L<http://xenbits.xen.org/docs/unstable/misc/xl-disk-configuration.txt> =head1 BUGS -Send bugs to xen-devel@lists.xensource.com. +Send bugs to xen-devel@lists.xensource.com, see +http://wiki.xen.org/xenwiki/ReportingBugs on how to send bug reports. -- 1.7.2.5
<stefano.stabellini@eu.citrix.com>
2011-Nov-30 14:16 UTC
[PATCH XenDocDay 19/19] xl.pod.1: add a note about autoballoon and dom0_mem
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> --- docs/man/xl.pod.1 | 16 ++++++++++++++++ 1 files changed, 16 insertions(+), 0 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index e8a5d21..eb85ca0 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -32,19 +32,35 @@ each of those subcommands. =head1 NOTES +=over 4 + +=item start the script B</etc/init.d/xencommons> at boot time + Most B<xl> operations rely upon B<xenstored> and B<xenconsoled>: make sure you start the script B</etc/init.d/xencommons> at boot time to initialize all the daemons needed by B<xl>. +=item setup a B<xenbr0> bridge in dom0 + In the most common network configuration, you need to setup a bridge in dom0 named B<xenbr0> in order to have a working network in the guest domains. Please refer to the documentation of your Linux distribution to know how to setup the bridge. +=item B<autoballoon> + +If you specify the amount of memory dom0 has, passing B<dom0_mem> to +Xen, it is highly reccomended to disable B<autoballoon>. Edit +B</etc/xen/xl.conf> and set it to 0. + +=item run xl as B<root> + Most B<xl> commands require root privileges to run due to the communications channels used to talk to the hypervisor. Running as non root will return an error. +=back + =head1 GLOBAL OPTIONS Some global options are always available: -- 1.7.2.5
Ian Campbell
2011-Nov-30 14:46 UTC
Re: [PATCH XenDocDay 03/19] xl.pod.1: improve create documentation
On Wed, 2011-11-30 at 14:16 +0000, stefano.stabellini@eu.citrix.com wrote:> From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> > > Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> > --- > docs/man/xl.pod.1 | 21 +++++++++++++++------ > 1 files changed, 15 insertions(+), 6 deletions(-) > > diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 > index 426b8e8..8cc9779 100644 > --- a/docs/man/xl.pod.1 > +++ b/docs/man/xl.pod.1 > @@ -52,13 +52,14 @@ previously, most commands take I<domain-id> as the first parameter. > > =over 4 > > -=item B<create> [I<OPTIONS>] I<configfile> > +=item B<create> [I<configfile>] [I<OPTIONS>]I think this is actually: [I<OPTIONS>] [I<configfile>] [I<config-statements>] <OPTIONS> are things like -c and -e etc. <config-statements> are any statement you might write into I<configfile> and you could even build a guest entirely by passing stuff on the command line. I''m not sure if there is any ordering constraints, e.g. I''m not sure if you can mix all these arbitrarily, but the above would be the natural/normal ordering.> > -The create subcommand requires a config file: see L<xl.cfg(5)> for > -full details of that file format and possible options. > +The create subcommand takes a config file as first argument: see > +L<xl.cfg> for full details of that file format and possible options. > +If I<configfile> is missing B<XL> creates the domain starting from the > +default value for every option.n.b. there is no default for "name" and so it must be given somewhere.> > -I<configfile> can either be an absolute path to a file, or a relative > -path to a file located in /etc/xen. > +I<configfile> has to be an absolute path to a file. > > Create will return B<as soon> as the domain is started. This B<does > not> mean the guest OS in the domain has actually booted, or is > @@ -88,7 +89,15 @@ Leave the domain paused after it is created. > =item B<-c> > > Attach console to the domain as soon as it has started. This is > -useful for determining issues with crashing domains. > +useful for determining issues with crashing domains and just as a > +general convenience since you often want to watch the > +domain boot. > + > +=item B<key=value>Ah, this is what I was calling <config-statements> above. Ian.> + > +It is possible to pass I<key=value> pairs on the command line to provide > +options as if they were written in the configuration file; these override > +whatever is in the I<configfile>. > > =back >
Ian Campbell
2011-Nov-30 14:48 UTC
Re: [PATCH XenDocDay 13/19] xl.pod.1: improve the description of the info subcommand
On Wed, 2011-11-30 at 14:16 +0000, stefano.stabellini@eu.citrix.com wrote:> From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> > > also update the example > > Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> > --- > docs/man/xl.pod.1 | 55 +++++++++++++++++++++++++++------------------------- > 1 files changed, 29 insertions(+), 26 deletions(-) > > diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 > index ab8a2f3..a765a11 100644 > --- a/docs/man/xl.pod.1 > +++ b/docs/man/xl.pod.1 > @@ -526,39 +526,41 @@ Clears Xen''s message buffer. > > Print information about the Xen host in I<name : value> format. When > reporting a Xen bug, please provide this information as part of the > -bug report. > +bug report. See I<http://wiki.xen.org/xenwiki/ReportingBugs> on how toPlease link to the new wiki.> +report Xen bugs. > > -Sample output looks as follows (lines wrapped manually to make the man > -page more readable): > +Sample output looks as follows: > > - host : talon > - release : 2.6.12.6-xen0 > - version : #1 Mon Nov 14 14:26:26 EST 2005 > - machine : i686 > - nr_cpus : 2 > + host : scarlett > + release : 3.1.0-rc4+ > + version : #1001 SMP Wed Oct 19 11:09:54 UTC 2011 > + machine : x86_64 > + nr_cpus : 4 > nr_nodes : 1 > - cores_per_socket : 1 > + cores_per_socket : 4 > threads_per_core : 1 > - cpu_mhz : 696 > - hw_caps : 0383fbff:00000000:00000000:00000040 > - total_memory : 767 > - free_memory : 37 > - xen_major : 3 > - xen_minor : 0 > - xen_extra : -devel > - xen_caps : xen-3.0-x86_32 > + cpu_mhz : 2266 > + hw_caps : bfebfbff:28100800:00000000:00003b40:009ce3bd:00000000:00000001:00000000 > + virt_caps : hvm hvm_directio > + total_memory : 6141 > + free_memory : 4274 > + free_cpus : 0 > + xen_major : 4 > + xen_minor : 2 > + xen_extra : -unstable > + xen_caps : xen-3.0-x86_64 xen-3.0-x86_32p hvm-3.0-x86_32 hvm-3.0-x86_32p hvm-3.0-x86_64 > xen_scheduler : credit > xen_pagesize : 4096 > - platform_params : virt_start=0xfc000000 > - xen_changeset : Mon Nov 14 18:13:38 2005 +0100 > - 7793:090e44133d40 > - cc_compiler : gcc version 3.4.3 (Mandrakelinux > - 10.2 3.4.3-7mdk) > - cc_compile_by : sdague > - cc_compile_domain : (none) > - cc_compile_date : Mon Nov 14 14:16:48 EST 2005 > + platform_params : virt_start=0xffff800000000000 > + xen_changeset : Wed Nov 02 17:09:09 2011 +0000 24066:54a5e994a241 > + xen_commandline : com1=115200,8n1 guest_loglvl=all dom0_mem=750M console=com1 > + cc_compiler : gcc version 4.4.5 (Debian 4.4.5-8) > + cc_compile_by : sstabellini > + cc_compile_domain : uk.xensource.com > + cc_compile_date : Tue Nov 8 12:03:05 UTC 2011 > xend_config_format : 4 > > + > B<FIELDS> > > Not all fields will be explained here, but some of the less obvious > @@ -570,7 +572,8 @@ ones deserve explanation: > > A vector showing what hardware capabilities are supported by your > processor. This is equivalent to, though more cryptic, the flags > -field in /proc/cpuinfo on a normal Linux machine. > +field in /proc/cpuinfo on a normal Linux machine: they both derive from > +the feature bits returned by the cpuid command on x86 platforms. > > =item B<free_memory> >
Ian Campbell
2011-Nov-30 14:49 UTC
Re: [PATCH XenDocDay 15/19] xl.pod.1: remove dry-run option from create and cpupool-create
On Wed, 2011-11-30 at 14:16 +0000, stefano.stabellini@eu.citrix.com wrote:> From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> > > there is already a global dry-run option, there is no point in adding > another one for each subcommandI thin we actually deprecated these individual ones so it is correct (or at least acceptable) to not document them IMHO.> Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> > --- > docs/man/xl.pod.1 | 9 --------- > 1 files changed, 0 insertions(+), 9 deletions(-) > > diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 > index 7620a2b..3b1407f 100644 > --- a/docs/man/xl.pod.1 > +++ b/docs/man/xl.pod.1 > @@ -98,11 +98,6 @@ No console output. > > Use the given configuration file. > > -=item B<-n>, B<--dryrun> > - > -Dry run - prints the resulting configuration in SXP but does not create > -the domain. > - > =item B<-p> > > Leave the domain paused after it is created. > @@ -684,10 +679,6 @@ B<OPTIONS> > > Use the given configuration file. > > -=item B<-n>, B<--dryrun> > - > -Dry run - prints the resulting configuration. > - > =back > > =item B<cpupool-list> [I<-c|--cpus>] [I<cpu-pool>]
Ian Campbell
2011-Nov-30 14:50 UTC
Re: [PATCH XenDocDay 18/19] xl.pod.1: add a refence to http://wiki.xen.org/xenwiki/ReportingBugs
On Wed, 2011-11-30 at 14:16 +0000, stefano.stabellini@eu.citrix.com wrote:> From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> > > Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> > --- > docs/man/xl.pod.1 | 3 ++- > 1 files changed, 2 insertions(+), 1 deletions(-) > > diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 > index 54e0f51..e8a5d21 100644 > --- a/docs/man/xl.pod.1 > +++ b/docs/man/xl.pod.1 > @@ -930,4 +930,5 @@ L<http://xenbits.xen.org/docs/unstable/misc/xl-disk-configuration.txt> > > =head1 BUGS > > -Send bugs to xen-devel@lists.xensource.com. > +Send bugs to xen-devel@lists.xensource.com, see > +http://wiki.xen.org/xenwiki/ReportingBugs on how to send bug reports.Should be new wiki... Ian.
Ian Campbell
2011-Nov-30 14:52 UTC
Re: [PATCH XenDocDay 19/19] xl.pod.1: add a note about autoballoon and dom0_mem
On Wed, 2011-11-30 at 14:16 +0000, stefano.stabellini@eu.citrix.com wrote:> From: Stefano Stabellini <stefano.stabellini@eu.citrix.com> > > Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com> > --- > docs/man/xl.pod.1 | 16 ++++++++++++++++ > 1 files changed, 16 insertions(+), 0 deletions(-) > > diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 > index e8a5d21..eb85ca0 100644 > --- a/docs/man/xl.pod.1 > +++ b/docs/man/xl.pod.1 > @@ -32,19 +32,35 @@ each of those subcommands. > > =head1 NOTES > > +=over 4 > + > +=item start the script B</etc/init.d/xencommons> at boot time > + > Most B<xl> operations rely upon B<xenstored> and B<xenconsoled>: make > sure you start the script B</etc/init.d/xencommons> at boot time to > initialize all the daemons needed by B<xl>. > > +=item setup a B<xenbr0> bridge in dom0 > + > In the most common network configuration, you need to setup a bridge in dom0 > named B<xenbr0> in order to have a working network in the guest domains. > Please refer to the documentation of your Linux distribution to know how to > setup the bridge.You could also reference http://wiki.xen.org/wiki/HostConfiguration/Networking here.> +=item B<autoballoon> > + > +If you specify the amount of memory dom0 has, passing B<dom0_mem> to > +Xen, it is highly reccomended to disable B<autoballoon>. Editrecommended> +B</etc/xen/xl.conf> and set it to 0. > + > +=item run xl as B<root> > + > Most B<xl> commands require root privileges to run due to the > communications channels used to talk to the hypervisor. Running as > non root will return an error.probably ;-)> > +=back > + > =head1 GLOBAL OPTIONS > > Some global options are always available:
On Wed, 2011-11-30 at 14:15 +0000, Stefano Stabellini wrote:> Hi all, > this patch series containes few updates and fixes to xl.pod.1.Thanks. I made a few (mostly incidental) comments. Rather than send ~19 acked-by you can consider anything I didn''t comment on: Acked-by: Ian Campbell <ian.campbell@citrix.com>> > Stefano Stabellini (19): > xl.pod.1: add a barebone description of tmem commands > xl.pod.1: add a description of console options > xl.pod.1: improve create documentation > xl.pod.1: add a description of the global options > xl.pod.1: order subcommands alphabetically > xl.pod.1: remove the two FIXME > xl.pod.1: add a reference to create in the -e option > xl.pod.1: state when a command requires PV drivers installed > xl.pod.1: better description for the sysreq subcommand > xl.pod.1: state when a subcommand is only available to HVM guests > xl.pod.1: introduce a TO BE DOCUMENTED section > xl.pod.1: improve the debug-keys subcommand description > xl.pod.1: improve the description of the info subcommand > xl.pod.1: improve the description of pci-list-assignable-devices > xl.pod.1: remove dry-run option from create and cpupool-create > xl.pod.1: improve description of virtual device subcommands > xl.pod.1: remove AUTHORS section > xl.pod.1: add a refence to http://wiki.xen.org/xenwiki/ReportingBugs > xl.pod.1: add a note about autoballoon and dom0_mem > > docs/man/xl.pod.1 | 317 ++++++++++++++++++++++++++++++++++++++--------------- > 1 files changed, 229 insertions(+), 88 deletions(-) > > > A git branch based on xen-unstable is available here: > > git://xenbits.xen.org/people/sstabellini/xen-unstable.git docs > > Cheers, > > Stefano > > _______________________________________________ > Xen-devel mailing list > Xen-devel@lists.xensource.com > http://lists.xensource.com/xen-devel