[v2] docs: add cpu-hotplug.txt

This document describes how to use cpu hotplug in QEMU.


Signed-off-by: Dou Liyang <douly.fnst@cn.fujitsu.com>
---
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 | 127 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)
 create mode 100644 docs/cpu-hotplug.txt

Hi Dou,

I'm catching up on mail after vacation so I reviewed the wrong
version of this patch first... Darn. I'll try again with this
version. Please still check my comments in that old version though,
as I'm going faster through this one and may miss things that are
here too (although not all comments are still applicable)

On Tue, Aug 09, 2016 at 06:24:54PM +0800, Dou Liyang wrote:
> This document describes how to use cpu hotplug in QEMU.
> 
> 
> Signed-off-by: Dou Liyang <douly.fnst@cn.fujitsu.com>
> ---
> 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 | 127 +++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 127 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..6a2f6f8
> --- /dev/null
> +++ b/docs/cpu-hotplug.txt
> @@ -0,0 +1,127 @@
> +QEMU CPU hotplug
> +================
> +
> +This document explains how to use the CPU hotplug feature in QEMU,
> +which regards the CPU as a divece.
> +
> +the -device/device_add and device_del based on CPUs are merged since
> +2.7

... the CPU as a device, using -device/device_add and device_del.

QEMU support was merged for 2.7.

(please use spell check)

> +
> +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
> +amount of CPUs which the guest can grow. This is done at startup time

/amount/number/
/grow/have/

> +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"    set the number of CPUs to 'n' [default=1].
/set/sets/
> + - "maxcpus" set the maximum number of CPUs, including offline VCPUs
/set/sets/
> +   for hotplug, etc.
> + - "cores"   set the number of CPU cores on one socket.
/set/sets/
> + - "threads  set the number of threads on one CPU core.
/set/sets/
> + - "sockets  set the number of discrete sockets in the system. On
/set/sets/
> +   sPAPR, sockets have no real meaning, And it has no real effect.
> +
> +For example, the following command-line:
> +
> + qemu [...] -smp 3,maxcpus=10,sockets=2,cores=2,threads=2

Same as my v0 comments. sockets*cores*threads must be exactly maxcpus

> +
> +Creates a guest with 3 VCPUs and it supports up to 10 VCPUs. The
> +CPU topology is sockets (2) * cores (2) * threads (2) and can't be
> +greater than maxcpus. When the guest is booted, the guest will see
> +3 VCPUs. More on this below.
> +
> +Query possible available CPU objects
> +------------------------------------
> +
> +The VCPUs should be hotplugged by socket/core/thread-ids parameters

/ids/id/

> +of the possible available CPUs objects.

describing the available...

> +
> +Before adding the VCPUs, we should know those topology parameters,
> +so that we can find out the available place (socket,core,thread)

/out//
/place/location/

> +for a new VCPU.
> +
> +There are two ways to obtain them:
> +
> +1. from the properties advertised by QEMU via the QMP command
> +query-hotpluggable-cpus.

space this over under the from

> +2. from the corresponding HMP command "info hotpluggable-cpus".
> +
> +For example, a monitor command can be used to list the possible CPU
> +objects:
> +
> +  (qemu) info hotpluggable-cpus
> +
> +Select the hotpluggable CPUs including "CPUInstance Properties" for
> +hotpluging. Such as this:
> +
> +  ...
> +  type: "qemu64-x86_64-cpu"
> +  vcpus_count: "1"
> +  CPUInstance Properties:
> +    socket-id: "0"
> +    core-id: "1"
> +    thread-id: "0"
> +  ...
> +
> +Hotplug CPUs
> +------------
> +
> +A monitor command can be used to hotplug CPUs:
> +
> + - "device_add": creates a VCPU device and inserts it into the
> +	specific place as a device
> +
> +For example, the following command adds a VCPU which has the id cpu1
> +in the last position of the guest's CPU sockets which was discussed
> +earlier by using the socket/core/thread-ids:

Instead of hotplugging to the last position of a previous example,
just create a new example. It's less complex and doesn't lose anything.

> +
> +  (qemu) device_add qemu64-x86_64-cpu,id=cpu9,socket-id=2,core-id=0,
> +	thread-id=1

Don't add newlines to example commands unless you can actually add them
when inputting the command. It's better to blow the 80 char limit.

> +
> +Where,
> +
> + - "qemu64-x86_64-cpu" is the CPU model.
> + - "id" is the unique identifier in the device sets. It is required.

/sets/set/

> + - "socket-id/core-id/thread-id" represent the designated position
> +   which is obtained form the above possible list of CPUs.
> +
> +It's also possible to start a guest with cpu cold-plugged into the
> +specific place (socket,core,thread).

a cpu

/the specific place/a specific location/

> +
> +In the following command-lines example, a guest which has 3 VCPUs is

/command-lines/command line/

> +created:
> +
> + qemu  [...] -smp 1,maxcpus=10,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 \

10 != 2*2*2

> +
> +Two VCPUs are cold-plugged by "-device" parameter. They are in the

by the "-device" parameter, which are in...

> +same socket and core with different thread-ids. After that, the

but with different...

> +guest has additional seven VCPUs to be hot-plugged when needed.

has an additional

> +
> +CPU hot-unplug
> +--------------
> +
> +In order to be able to hot unplug CPU device, QEMU removes CPUs device

a CPU device

QEMU removes CPU devices

> +by using the ids which were assigned when you hot plugged the CPUs.

/you hot plugged/when hotplugging/

> +
> +A monitor command can be used to hot unplug CPUs:
> +
> + - "device_del": deletes a CPU device
> +
> +For example, assuming that the CPU device with id "cpu1" exists and has
> +been offline, the following command tries to remove it.

offlined

> +
> +  (qemu) device_del cpu1
> +
> -- 
> 2.5.5
> 
> 
> 
>

Thanks,
drew

Hi drew,

在 2016年08月12日 23:44, Andrew Jones 写道:
>
> Hi Dou,
>
> I'm catching up on mail after vacation so I reviewed the wrong
> version of this patch first... Darn. I'll try again with this
> version. Please still check my comments in that old version though,
> as I'm going faster through this one and may miss things that are
> here too (although not all comments are still applicable)

Yes, I will.


>> +For example, the following command-line:
>> +
>> + qemu [...] -smp 3,maxcpus=10,sockets=2,cores=2,threads=2
>
> Same as my v0 comments. sockets*cores*threads must be exactly maxcpus

I see. I will modify the example.

However, when I executed the example in current QEMU, I can hotplug an
CPU device in the location(socket-id=2,core-id=0,thread-id=1) which was
not in the CPU topology successfully.

1: If we need a judgment: "maxcpus==sockets*cores*threads" when parsing 
the command line.

2: If replacing the maxcpus by the sockets*cores*threads in QEMU when a
complete topology is given.

Thanks,

Dou

On Mon, Aug 15, 2016 at 11:48:59AM +0800, Dou Liyang wrote:
> Hi drew,
> 
> 在 2016年08月12日 23:44, Andrew Jones 写道:
> > 
> > Hi Dou,
> > 
> > I'm catching up on mail after vacation so I reviewed the wrong
> > version of this patch first... Darn. I'll try again with this
> > version. Please still check my comments in that old version though,
> > as I'm going faster through this one and may miss things that are
> > here too (although not all comments are still applicable)
> 
> Yes, I will.
> 
> 
> > > +For example, the following command-line:
> > > +
> > > + qemu [...] -smp 3,maxcpus=10,sockets=2,cores=2,threads=2
> > 
> > Same as my v0 comments. sockets*cores*threads must be exactly maxcpus
> 
> I see. I will modify the example.
> 
> However, when I executed the example in current QEMU, I can hotplug an
> CPU device in the location(socket-id=2,core-id=0,thread-id=1) which was
> not in the CPU topology successfully.
> 
> 1: If we need a judgment: "maxcpus==sockets*cores*threads" when parsing the
> command line.

Yes, I have a patch [1] for this. We can't make things overly strict now
though, as that would risk breaking old command lines. (Eventually we
can fix it by changing to a new interface - see whole thread of that
patch [2])

> 
> 2: If replacing the maxcpus by the sockets*cores*threads in QEMU when a
> complete topology is given.

Yes, somewhere in that thread we had a lengthy discussion about it.
In the end, I think agreed to maxcpus being an optional parameter.
However, if it is given, then checking it's correct, and erroring out
when it isn't, is really the only sane course of action.

[1] https://www.mail-archive.com/qemu-devel@nongnu.org/msg376965.html
[2] https://www.mail-archive.com/qemu-devel@nongnu.org/msg376961.html

Thanks,
drew