docs/specs/acpi_mem_hotplug.rst

   1 QEMU<->ACPI BIOS memory hotplug interface
   2 =========================================
   3
   4 ACPI BIOS GPE.3 handler is dedicated for notifying OS about memory hot-add
   5 and hot-remove events.
   6
   7 Memory hot-plug interface (IO port 0xa00-0xa17, 1-4 byte access)
   8 ----------------------------------------------------------------
   9
  10 Read access behavior
  11 ^^^^^^^^^^^^^^^^^^^^
  12
  13 [0x0-0x3]
  14   Lo part of memory device phys address
  15 [0x4-0x7]
  16   Hi part of memory device phys address
  17 [0x8-0xb]
  18   Lo part of memory device size in bytes
  19 [0xc-0xf]
  20   Hi part of memory device size in bytes
  21 [0x10-0x13]
  22   Memory device proximity domain
  23 [0x14]
  24   Memory device status fields
  25
  26   bits:
  27
  28   0:
  29     Device is enabled and may be used by guest
  30   1:
  31     Device insert event, used to distinguish device for which
  32     no device check event to OSPM was issued.
  33     It's valid only when bit 1 is set.
  34   2:
  35     Device remove event, used to distinguish device for which
  36     no device eject request to OSPM was issued.
  37   3-7:
  38     reserved and should be ignored by OSPM
  39
  40 [0x15-0x17]
  41   reserved
  42
  43 Write access behavior
  44 ^^^^^^^^^^^^^^^^^^^^^
  45
  46
  47 [0x0-0x3]
  48   Memory device slot selector, selects active memory device.
  49   All following accesses to other registers in 0xa00-0xa17
  50   region will read/store data from/to selected memory device.
  51 [0x4-0x7]
  52   OST event code reported by OSPM
  53 [0x8-0xb]
  54   OST status code reported by OSPM
  55 [0xc-0x13]
  56   reserved, writes into it are ignored
  57 [0x14]
  58   Memory device control fields
  59
  60   bits:
  61
  62   0:
  63     reserved, OSPM must clear it before writing to register.
  64     Due to BUG in versions prior 2.4 that field isn't cleared
  65     when other fields are written. Keep it reserved and don't
  66     try to reuse it.
  67   1:
  68     if set to 1 clears device insert event, set by OSPM
  69     after it has emitted device check event for the
  70     selected memory device
  71   2:
  72     if set to 1 clears device remove event, set by OSPM
  73     after it has emitted device eject request for the
  74     selected memory device
  75   3:
  76     if set to 1 initiates device eject, set by OSPM when it
  77     triggers memory device removal and calls _EJ0 method
  78   4-7:
  79     reserved, OSPM must clear them before writing to register
  80
  81 Selecting memory device slot beyond present range has no effect on platform:
  82
  83 - write accesses to memory hot-plug registers not documented above are ignored
  84 - read accesses to memory hot-plug registers not documented above return
  85   all bits set to 1.
  86
  87 Memory hot remove process diagram
  88 ---------------------------------
  89
  90 ::
  91
  92    +-------------+     +-----------------------+      +------------------+
  93    |  1. QEMU    |     | 2. QEMU               |      |3. QEMU           |
  94    |  device_del +---->+ device unplug request +----->+Send SCI to guest,|
  95    |             |     |         cb            |      |return control to |
  96    |             |     |                       |      |management        |
  97    +-------------+     +-----------------------+      +------------------+
  98
  99    +---------------------------------------------------------------------+
 100
 101    +---------------------+              +-------------------------+
 102    | OSPM:               | remove event | OSPM:                   |
 103    | send Eject Request, |              | Scan memory devices     |
 104    | clear remove event  +<-------------+ for event flags         |
 105    |                     |              |                         |
 106    +---------------------+              +-------------------------+
 107              |
 108              |
 109    +---------v--------+            +-----------------------+
 110    | Guest OS:        |  success   | OSPM:                 |
 111    | process Ejection +----------->+ Execute _EJ0 method,  |
 112    | request          |            | set eject bit in flags|
 113    +------------------+            +-----------------------+
 114              |failure                         |
 115              v                                v
 116    +------------------------+      +-----------------------+
 117    | OSPM:                  |      | QEMU:                 |
 118    | set OST event & status |      | call device unplug cb |
 119    | fields                 |      |                       |
 120    +------------------------+      +-----------------------+
 121             |                                  |
 122             v                                  v
 123    +------------------+              +-------------------+
 124    |QEMU:             |              |QEMU:              |
 125    |Send OST QMP event|              |Send device deleted|
 126    |                  |              |QMP event          |
 127    +------------------+              |                   |
 128                                      +-------------------+