Merge tag 'pull-target-arm-20220812' of https://git.linaro.org/people/pmaydell/qemu...
[qemu.git] / 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                                      +-------------------+