Re: [Qemu-devel] [PATCH v5] docs: add cpu-hotplug.txt

[Andrew Jones]

On Tue, Aug 16, 2016 at 03:54:26PM +0800, Dou Liyang wrote:
> This document describes how to use cpu hotplug in QEMU.
> 
> Signed-off-by: Andrew Jones <address@hidden>

I didn't give my s-o-b for this patch. I'm not sure where
you got that idea. Anyway, I wouldn't, I'd give an r-b.

> Signed-off-by: Dou Liyang <address@hidden>
> ---
> Change log v4 -> v5
>   1. add an example for sPAPR
>   From Bharata's advice
>     1. Fix the examples
> 
> Change log v3 -> v4
>   From David's advice
>     1. add spapr examples
>     2. Fix some comment
>   From drew's advice
>     1. Fix some syntax
> 
> Change log v2 -> v3:
>   From drew's advice:
>     1. modify the examples.
>     2. Fix some syntax.
> 
> Change log v1 -> v2:
>   From Fam's advice:
>     1. Fix some comment.
> 
> Change log v1:
>   From Igor's advice:
>     1. Remove any mentioning of apic-id from the document.
>     2. Remove the "device_del qom_path" from the CPU hot-unplug.
>     3. Fix some comment.
> 
>  docs/cpu-hotplug.txt | 141 
> +++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 141 insertions(+)
>  create mode 100644 docs/cpu-hotplug.txt
> 
> diff --git a/docs/cpu-hotplug.txt b/docs/cpu-hotplug.txt
> new file mode 100644
> index 0000000..d08111c
> --- /dev/null
> +++ b/docs/cpu-hotplug.txt
> @@ -0,0 +1,141 @@
> +QEMU CPU hotplug
> +================
> +
> +This document explains how to use the CPU hotplug feature in QEMU,
> +which regards the CPU as a device, using -device/device_add and
> +device_del.
> +
> +QEMU support was merged for 2.7.
> +
> +Guest support is required for CPU hotplug to work.
> +
> +CPU hot-plug
> +------------
> +
> +In order to be able to hotplug CPUs, QEMU has to be told the maximum
> +number of CPUs which the guest can have. This is done at startup time
> +by means of the -smp command-line option, which has the following
> +format:
> +
> + -smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads]
> +     [,sockets=sockets]
> +
> +Where,
> +
> + - "cpus"    sets the number of CPUs to 'n' [default=1].
> + - "maxcpus" sets the maximum number of CPUs, including offline VCPUs
> +   for hotplug.
> + - "sockets" sets the number of discrete sockets in the system.
> + - "cores"   sets the number of CPU cores on one socket.
> + - "threads" sets the number of threads on one CPU core.
> +
> +For example, the following command-line:
> +
> + qemu [...] -smp 4,maxcpus=8,sockets=2,cores=2,threads=2
> +
> +creates a guest with 4 VCPUs and supports up to 8 VCPUs. The CPU
> +topology is sockets (2) * cores (2) * threads (2) and can't be
> +greater than maxcpus. When the guest finishes loading, the guest

I think I've suggested something for this a few times. Here's
another try

 The CPU topology is sockets (2) * cores (2) * threads (2) and should
 compute a number of slots exactly equal to maxcpus. A computed number
 of slots greater than maxcpus will result in an error.

> +will see 4 VCPUs. More on this below.
> +
> +Query available CPU objects
> +---------------------------
> +
> +To add a VCPUs, it must be identified by socket-id, core-id, and/or

/VCPUs/VCPU/

> +thread-id parameters.
> +
> +Before adding the VCPUs, we should know those topology parameters,

/VCPUs/VCPU/
/those/the/

> +so that we can find the available location (socket,core,thread) for
> +a new VCPU.
> +
> +Using the corresponding HMP command "info hotpluggable-cpus" to obtain
> +them.
> +
> +For example, the following command-line:

Use the HMP command "info hotpluggable-cpus" to obtain them, for example:

> +
> +  (qemu) info hotpluggable-cpus
> +
> +lists all hot-pluggable CPUs. Such as this:
> +
> +  ...
> +  type: "qemu64-x86_64-cpu"
> +  vcpus_count: "1"
> +  CPUInstance Properties:
> +    socket-id: "1"
> +    core-id: "0"
> +    thread-id: "0"
> +  ...
> +
> +Or
> +
> +  ...
> +  type: "POWER7_v2.3-spapr-cpu-core"
> +  vcpus_count: "1"
> +  CPUInstance Properties:
> +    core-id: "2"
> +  ...
> +
> +Different platforms may have different "CPUInstance Properties", which
> +will be used in hot-plugging below.
> +
> +Hotplug CPUs
> +------------
> +
> +A monitor command can be used to hotplug CPUs:

/can/may/

> +
> + - "device_add": creates a CPU device and inserts it into the
> +     specific location.
> +
> +For example, the following command adds a VCPU, which has the id cpu1,
> +to a specific location in the topology (socket=1,core=0,thread=0):
> +
> +  (qemu) device_add 
> qemu64-x86_64-cpu,id=cpu1,socket-id=1,core-id=0,thread-id=0
> +
> +Where,
> +
> + - "qemu64-x86_64-cpu" is the CPU model.
> + - "id" is the unique identifier in the device set.
> + - "socket-id/core-id/thread-id" represent the designated location,
> +   which is obtained form the above possible list of CPUs.

/form/from/

> +
> +It's also possible to start a guest with a cpu cold-plugged into a
> +specific location (socket,core,thread).
> +
> +In the following command line example, a guest which has 3 VCPUs is
> +created:
> +
> + qemu  [...] -smp 2,maxcpus=8,sockets=2,cores=2,threads=2 \
> +     -device qemu64-x86_64-cpu,id=cpu1,socket-id=1,\
> +     core-id=1,thread-id=0 \
> +     -device qemu64-x86_64-cpu,id=cpu2,socket-id=1,\
> +     core-id=1,thread-id=1 \
> +
> +Two VCPUs are cold-plugged by "-device" parameter, which are in the

/by/by the/

> +same socket and core, but with different thread-ids. After that, the
> +guest has an additional four VCPUs to be hot-plugged when needed.

/to be hot-plugged/available for hot-plug/

> +
> +Above is about the x86-64 architecture. On other architectures, we
> +just need modify the command parameters based on the "CPUInstance
> +Properties".

I'd rewrite the above paragraph as

 The above example is for an x86 machine type. The topology parameters
 and resulting number of online VCPUs may not be suitable for other
 platforms. The "CPUInstance Properties" output described above lists
 the valid topology parameters.

> +
> +For example, the following command adds a VCPU in a sPAPR hardware
> +System:

/a sPAPR/an sPAPR/
/System/system/

> +
> +  (qemu) device_add POWER7_v2.3-spapr-cpu-core,id=cpu1,core-id=2
> +
> +CPU hot-unplug
> +--------------
> +
> +In order to be able to hot unplug a CPU device, QEMU removes CPU
> +devices by using the ids which were assigned when hotplugging the
> +CPU device.

Mixing singular and plural cases here. Suggesting changing to
singular.

/QEMU removes CPU devices/QEMU removes the device/
/ids/id/
/were/was/
/the CPU device./it./

> +
> +A monitor command can be used to hot unplug CPUs:

/can/may/

> +
> + - "device_del": deletes a CPU device
> +
> +For example, assuming that the CPU device with id "cpu1" exists,
> +then the following command tries to remove it.
> +
> +  (qemu) device_del cpu1
> +
> -- 
> 2.5.5
>

(still-not-yet-reviewed-by: drew :-)

Thanks,
drew