[libvirt] [PATCHv4 1/4] vcpupin: inroduce a new libvir API (virDomainPinVcpuFlags)

[Adam Litke]

On 05/20/2011 04:08 AM, Taku Izumi wrote:
>  /**
> + * virDomainPinVcpuFlags:
> + * @domain: pointer to domain object, or NULL for Domain0
> + * @vcpu: virtual CPU number
> + * @cpumap: pointer to a bit map of real CPUs (in 8-bit bytes) (IN)
> + *      Each bit set to 1 means that corresponding CPU is usable.
> + *      Bytes are stored in little-endian order: CPU0-7, 8-15...
> + *      In each byte, lowest CPU number is least significant bit.
> + * @maplen: number of bytes in cpumap, from 1 up to size of CPU map in
> + *      underlying virtualization system (Xen...).
> + *      If maplen < size, missing bytes are set to zero.
> + *      If maplen > size, failure code is returned.
> + * @flags: an OR'ed subset of virDomainVcpuFlags
> + *
> + * Dynamically change the real CPUs which can be allocated to a virtual CPU.
> + * This function requires privileged access to the hypervisor.
> + *
> + * @flags may include VIR_DOMAIN_VCPU_LIVE or VIR_DOMAIN_VCPU_CONFIG.
> + * Both flags may be set, but VIR_DOMAIN_VCPU_MAXIMUM cannot be set.
> + * If VIR_DOMAIN_VCPU_LIVE is set, the change affects a running domain
> + * and may fail if domain is not alive.
> + * If VIR_DOMAIN_VCPU_CONFIG is set, the change affects persistent state,
> + * and will fail for transient domains.
> + * If neither flag is specified (that is, @flags is VIR_DOMAIN_VCPU_CURRENT),
> + * then an inactive domain modifies persistent setup, while an active domain
> + * is hypervisor-dependent on whether just live or both live and persistent
> + * state is changed.
> + * Not all hypervisors can support all flag combinations.

I am really confused about what the default flags
(VIR_DOMAIN_VCPU_CURRENT) actually means.  It doesn't seem like I can
ever know what it means from an API perspective (since it's behavior is
arbitrary depending on the hypervisor).  Wouldn't it be better to
require _either_ VIR_DOMAIN_VCPU_LIVE _or_ VIR_DOMAIN_VCPU_CONFIG to be
set so that the intended behavior can be set with specificity?

Also, shouldn't these flags be named
VIR_DOMAIN_PIN_VCPU_FLAGS_{LIVE|CONFIG} since they are meant only for
the virDomainPinVcpuFlags() API?

-- 
Adam Litke
IBM Linux Technology Center