Re: [Qemu-devel] [PATCH v5 1/7] docs: update documentation for memory hot unplug

[Igor Mammedov <imammedo@redhat.com>]

On Fri, 27 Mar 2015 17:20:34 +0800
Zhu Guihua <zhugh.fnst@cn.fujitsu.com> wrote:

> Add specification about how to use memory hot unplug, and add
> a flow diagram to explain memory hot unplug process.
> 
> Signed-off-by: Zhu Guihua <zhugh.fnst@cn.fujitsu.com>
> ---
>  docs/memory-hotplug.txt         | 24 ++++++++++++++++++++----
>  docs/specs/acpi_mem_hotplug.txt | 16 +++++++++++++++-
>  2 files changed, 35 insertions(+), 5 deletions(-)
> 
> diff --git a/docs/memory-hotplug.txt b/docs/memory-hotplug.txt
> index f70571d..0de7f1b 100644
> --- a/docs/memory-hotplug.txt
> +++ b/docs/memory-hotplug.txt
> @@ -1,12 +1,10 @@
>  QEMU memory hotplug
>  ===================
>  
> -This document explains how to use the memory hotplug feature in QEMU,
> +This part explains how to use the memory hotplug feature in QEMU,
>  which is present since v2.1.0.
not related change? It's better to leave as it was.

>  
> -Please, note that memory hotunplug is not supported yet. This means
> -that you're able to add memory, but you're not able to remove it.
> -Also, proper guest support is required for memory hotplug to work.
> +And, proper guest support is required for memory hotplug to work.
reword it like:
Guest support is required for memory hotplug to work.

>  
>  Basic RAM hotplug
>  -----------------
> @@ -74,3 +72,21 @@ comes from regular RAM, 1GB is a 1GB hugepage page and 256MB is from
>     -device pc-dimm,id=dimm1,memdev=mem1 \
>     -object memory-backend-file,id=mem2,size=256M,mem-path=/mnt/hugepages-2MB \
>     -device pc-dimm,id=dimm2,memdev=mem2
> +
> +
> +QEMU memory hot unplug
> +======================
s/^^^/
RAM hot-unplug
--------------
/

> +This part explains how to use the memory hot unplug feature in QEMU.
unnecessary, drop it.

> +
> +In order to be able to hot unplug pc-dimm device, QEMU has to be told the id
> +of pc-dimm device. The id was assigned when you hot plugged memory.
> +
> +One monitor command is used to hot unplug memory:
s/One/Two/

Haven't you forgotten about object_del ???
In typical use-case backend will be deleted as well

> +
> + - "device_del": deletes a front-end pc-dimm device
> +
> +For example, assuming that the pc-dimm device with id "dimm1"   
> +into the guest, the following command deletes the pc-dimm device from the
> +guest.
s/was hotplugged into the guest/exists/
s/deletes the pc-dimm device from the guest/tries to remove it/

> +
> +  (qemu) device_del dimm1
remove associated backend as well

> diff --git a/docs/specs/acpi_mem_hotplug.txt b/docs/specs/acpi_mem_hotplug.txt
> index 1290994..a88b286 100644
> --- a/docs/specs/acpi_mem_hotplug.txt
> +++ b/docs/specs/acpi_mem_hotplug.txt
> @@ -2,7 +2,7 @@ QEMU<->ACPI BIOS memory hotplug interface
>  --------------------------------------
>  
>  ACPI BIOS GPE.3 handler is dedicated for notifying OS about memory hot-add
> -events.
> +and hot-remove events.
>  
>  Memory hot-plug interface (IO port 0xa00-0xa17, 1-4 byte access):
>  ---------------------------------------------------------------
> @@ -42,3 +42,17 @@ Selecting memory device slot beyond present range has no effect on platform:
>       ignored
>     - read accesses to memory hot-plug registers not documented above return
>       all bits set to 1.
> +
> +Memory hot remove process diagram:
> +----------------------------------


> +Memory hot unplug is rather complicated multi-stage process, it is asynchronous
> +procedures. The follwoing diagram describes memory hot unplug process.
drop ^^^ hunk


> +
> +             QEMU             |             Guest OS
> +-------------------------------------------------------------------------------
> +     unplug request cb ->     |
> +                              |  OSPM processes ejection request
> +                              |  <- OSPM clears device remove event
> +    clear remove event ->     |
> +                              |  <- OSPM issues _EJ0 and initiates device eject
> +  unplug cb (eject device)    |
perhaps something like below would be better

 +-------------+     +-----------------------+      +------------------+     
 |  1. QEMU    |     | 2. QEMU               |      |3. QEMU           |     
 |  device_del +---->+ device unplug request +----->+Send SCI to guest,|     
 |             |     |         cb            |      |return control to |     
 +-------------+     +-----------------------+      |management        |     
                                                    +------------------+     
                                                                             
 +---------------------------------------------------------------------+     
                                                                             
 +---------------------+              +-------------------------+            
 | OSPM:               | remove event | OSPM:                   |            
 | send Eject Request, |              | Scan memory devices     |            
 | clear remove event  +<-------------+ for event flags         |            
 |                     |              |                         |            
 +---------------------+              +-------------------------+            
           |                                                                 
           |                                                                 
 +---------v--------+            +-----------------------+                   
 | Guest OS:        |  success   | OSPM:                 |                   
 | process Ejection +----------->+ Execute _EJ00 method, |                   
 | request          |            | set eject bit in flags|                   
 +------------------+            +-----------------------+                   
           |failure                         |                                
           v                                v                                
 +------------------------+      +-----------------------+                   
 | OSPM:                  |      | QEMU:                 |                   
 | set OST event & status |      | call device unplug cb |                   
 | fields                 |      |                       |                   
 +------------------------+      +-----------------------+                   
          |                                  |                               
          v                                  v                               
 +------------------+              +-------------------+                     
 |QEMU:             |              |QEMU:              |                     
 |Send OST QMP event|              |Send device deleted|                     
 |                  |              |QMP event          |                     
 +------------------+              |                   |                     
                                   +-------------------+