[Xen-devel] [RFC] xm interface proposed changes

[Sean Dague <sean@xxxxxxxxx>]

In order to have this discussion in a structured way, we should figure out
how we want commands structured in general (i.e. where is the verb).

It seems the following policy would be mostly in line with the existing
command set.

If the command direct object is a xen domain (it does something directly to
a domain core) then we use "verb" (i.e. create, destroy, save...).  If the
command direct object is a part of a domain, like a block device or memory,
we use "object-verb", mostly so the object commands cluster in a directly
command listing.  Examples today would be "vbd-list" for instance.  If there
is a difference of opinion here, we should hammer that out first, because
the rest of the discussion is pretty pointless without at least these ground
rules. :)

To make this easier, here is the command help today (with attributes added
in to each command).

=========================================================================
---------XM HELP TODAY---------------------------------------------------
call                Call xend api functions
help                Print help.

Commands related to consoles:

console <DomainId>  Open a console to a domain.
consoles            Get information about domain consoles.

Commands on domains:

balloon <DomainId> <Mem>  Set the domain's memory footprint using the balloon 
driver.
create <ConfigFile>       Create a domain.
destroy <DomainId>        Terminate a domain immediately.
domid   <DomainName>      Convert a domain name to a domain id.
domname <DomainId>        Convert a domain id to a domain name.
list                      List information about domains.
maxmem <DomainId> <Mem>   Set domain memory limit.
migrate [options] <DomId> <Host> Migrate a domain to another machine.
pause  <DomainId>         Pause execution of a domain.
pincpu <DomId> <VCpu> <CPUS>    Set which cpus a VCPU can use. 
restore <File>            Create a domain from a saved state.
save    <DomId> <File>    Save domain state (and config) to file.
shutdown [options] <DomId>  Shutdown a domain.
sysrq   <DomId> <letter>    Send a sysrq to a domain.
unpause <DomId>           Unpause a paused domain.
vcpu-hotplug <DomId> <VCPU> <0|1> Enable or disable a VCPU in a domain.

Commands related to the xen host (node):

dmesg   [--clear]         Read or clear Xen's message buffer.
info                      Get information about the xen host.
log                       Print the xend log.

Comands controlling scheduling:

bvt DOM MCUADV WARPBACK WARPVALUE WARPL WARPU   Set BVT scheduler parameters.
bvt_ctxallow CTX_ALLOW                          Set the BVT scheduler context 
switch allowance.
sedf DOM PERIOD SLICE LATENCY EXTRATIME WEIGHT  Set simple EDF parameters.

Commands related to virtual block devices:

vbd-create <DomId> <BackDev> <FrontDev> <Mode> [BackDomId]    Create a new 
virtual block device for a domain
vbd-destroy <DomId> <DevId>  Destroy a domain's virtual block device
vbd-list    <DomId>          List virtual block devices for a domain.
vbd-refresh <DomId> <DevId>  Refresh a virtual block device for a domain

Commands related to virtual network interfaces:

vif-limit   <DomId> <Vif> <Credit> <Period> Limit the transmission rate of a 
virtual network interface.
vif-list    <DomId> List virtual network interfaces for a domain.

Try '/usr/sbin/xm help CMD' for help on CMD
-------------------------------------------------------------------



The following is a proposed set of changes based on the "obj-verb" paradigm,
plus trying to make commands make more sense to a user that may not know
things about Xen internals.  Commands that have renames are marked with (*),
commands that are "new" to create what seems like a complete interface are
marked with (+).

===================================================================
---------XM Proposed-----------------------------------------------
help                Print help.

Commands related to consoles:

console <DomId>  Open a console to a domain.
* console-list        Get information about domain consoles.

Commands on domains:

domid   <DomName>         Convert a domain name to a domain id.
domname <DomId>           Convert a domain id to a domain name.

create  <ConfigFile>      Create a domain.
destroy <DomId>           Terminate a domain immediately.
restore <File>            Create a domain from a saved state.
save    <DomId> <File>    Save domain state (and config) to file.
* shutdown [-w|-a] <DomId>  Shutdown a domain.
+ reboot   [-w|-a] <DomId>  Reboot a domain.

list                      List information about domains.

* mem-max <DomId> <Mem>             Set domain maximum memory limit.
* mem-set <DomId> <Mem>             Set the domain's memory dynamically.
* cpus-set <DomId> <VCpu> <CPUS>    Set which cpus a VCPU can use. 
+ cpus-list <DomId> <VCpu>          Get the list of cpus for a VCPU
* vcpu-enable <DomId> <VCPU>        Disable VCPU in a domain.
+ vcpu-disable <DomId> <VCPU>       Enable VCPU in a domain
+ vcpu-list <DomId>                 Get the list of VCPUs for a domain

migrate [options] <DomId> <Host> Migrate a domain to another machine.

sysrq   <DomId> <letter>    Send a sysrq to a domain.
pause   <DomId>           Pause execution of a domain.
unpause <DomId>           Unpause a paused domain.

Commands related to the xen host (node):

dmesg   [--clear]         Read or clear Xen's message buffer.
info                      Get information about the xen host.
log                       Print the xend log.

Comands controlling scheduling:

bvt DOM MCUADV WARPBACK WARPVALUE WARPL WARPU   Set BVT scheduler parameters.
bvt_ctxallow CTX_ALLOW                          Set the BVT scheduler context 
switch allowance.
sedf DOM PERIOD SLICE LATENCY EXTRATIME WEIGHT  Set simple EDF parameters.

Commands related to virtual block devices:

* block-create <DomId> <BackDev> <FrontDev> <Mode> [BackDomId]    Create a new 
virtual block device for a domain
* block-destroy <DomId> <DevId>  Destroy a domain's virtual block device
* block-list    <DomId>          List virtual block devices for a domain.
* block-refresh <DomId> <DevId>  Refresh a virtual block device for a domain

Commands related to virtual network interfaces:

* network-limit   <DomId> <Vif> <Credit> <Period> Limit the transmission rate 
of a virtual network interface.
* network-list    <DomId> List virtual network interfaces for a domain.

Try '/usr/sbin/xm help CMD' for help on CMD
-----------------------------------------------------------------



Additionally, if we are to move to a model where command aliasing can easily
be done (for backwards compatibility), I actually think we need to majorly
restructure main.py from an object based model to a declaritive model, where
main() would be a dispatcher to possibly many functions that would be the
equiv of the main methods in each object today.  I also believe that this is
the only way to get 'xm help' to run as non-root, which I consider a goal. 
I'd like at least tenative approval for this idea before I code it up, but I
am *willing to volunteer* for this conversion of main.py from object based
-> declaritive structure.

Comments welcome, flame away.

        -Sean

-- 
__________________________________________________________________

Sean Dague                                       Mid-Hudson Valley
sean at dague dot net                            Linux Users Group
http://dague.net                                 http://mhvlug.org

There is no silver bullet.  Plus, werewolves make better neighbors
than zombies, and they tend to keep the vampire population down.
__________________________________________________________________

Attachment: pgpl_xiqKN87e.pgp
Description: PGP signature

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-devel