[qemu.git] / docs / specs / acpi_mem_hotplug.txt

QEMU<->ACPI BIOS memory hotplug interface
--------------------------------------

ACPI BIOS GPE.3 handler is dedicated for notifying OS about memory hot-add
and hot-remove events.

Memory hot-plug interface (IO port 0xa00-0xa17, 1-4 byte access):
---------------------------------------------------------------
0xa00:
  read access:
      [0x0-0x3] Lo part of memory device phys address
      [0x4-0x7] Hi part of memory device phys address
      [0x8-0xb] Lo part of memory device size in bytes
      [0xc-0xf] Hi part of memory device size in bytes
      [0x10-0x13] Memory device proximity domain
      [0x14] Memory device status fields
          bits:
              0: Device is enabled and may be used by guest
              1: Device insert event, used to distinguish device for which
                 no device check event to OSPM was issued.
                 It's valid only when bit 1 is set.
              2: Device remove event, used to distinguish device for which
                 no device eject request to OSPM was issued.
              3-7: reserved and should be ignored by OSPM
      [0x15-0x17] reserved

  write access:
      [0x0-0x3] Memory device slot selector, selects active memory device.
                All following accesses to other registers in 0xa00-0xa17
                region will read/store data from/to selected memory device.
      [0x4-0x7] OST event code reported by OSPM
      [0x8-0xb] OST status code reported by OSPM
      [0xc-0x13] reserved, writes into it are ignored
      [0x14] Memory device control fields
          bits:
              0: reserved, OSPM must clear it before writing to register.
                 Due to BUG in versions prior 2.4 that field isn't cleared
                 when other fields are written. Keep it reserved and don't
                 try to reuse it.
              1: if set to 1 clears device insert event, set by OSPM
                 after it has emitted device check event for the
                 selected memory device
              2: if set to 1 clears device remove event, set by OSPM
                 after it has emitted device eject request for the
                 selected memory device
              3: if set to 1 initiates device eject, set by OSPM when it
                 triggers memory device removal and calls _EJ0 method
              4-7: reserved, OSPM must clear them before writing to register

Selecting memory device slot beyond present range has no effect on platform:
   - write accesses to memory hot-plug registers not documented above are
     ignored
   - read accesses to memory hot-plug registers not documented above return
     all bits set to 1.

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