1 QEMU<->ACPI BIOS NVDIMM interface
2 ---------------------------------
4 QEMU supports NVDIMM via ACPI. This document describes the basic concepts of
5 NVDIMM ACPI and the interface between QEMU and the ACPI BIOS.
9 NVDIMM is introduced in ACPI 6.0 which defines an NVDIMM root device under
10 _SB scope with a _HID of “ACPI0012”. For each NVDIMM present or intended
11 to be supported by platform, platform firmware also exposes an ACPI
12 Namespace Device under the root device.
14 The NVDIMM child devices under the NVDIMM root device are defined with _ADR
15 corresponding to the NFIT device handle. The NVDIMM root device and the
16 NVDIMM devices can have device specific methods (_DSM) to provide additional
17 functions specific to a particular NVDIMM implementation.
19 This is an example from ACPI 6.0, a platform contains one NVDIMM:
22 Device (NVDR) // Root device
24 Name (_HID, “ACPI0012”)
27 Method (_DSM, ...) {...}
30 Name(_ADR, h) //where h is NFIT Device Handle for this NVDIMM
31 Method (_DSM, ...) {...}
36 Method supported on both NVDIMM root device and NVDIMM device
37 _DSM (Device Specific Method)
38 It is a control method that enables devices to provide device specific
39 control functions that are consumed by the device driver.
40 The NVDIMM DSM specification can be found at:
41 http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf
44 Arg0 – A Buffer containing a UUID (16 Bytes)
45 Arg1 – An Integer containing the Revision ID (4 Bytes)
46 Arg2 – An Integer containing the Function Index (4 Bytes)
47 Arg3 – A package containing parameters for the function specified by the
48 UUID, Revision ID, and Function Index
51 If Function Index = 0, a Buffer containing a function index bitfield.
52 Otherwise, the return value and type depends on the UUID, revision ID
53 and function index which are described in the DSM specification.
55 Methods on NVDIMM ROOT Device
56 _FIT(Firmware Interface Table)
57 It evaluates to a buffer returning data in the format of a series of NFIT
63 A Buffer containing a list of NFIT Type structure entries.
65 The detailed definition of the structure can be found at ACPI 6.0: 5.2.25
66 NVDIMM Firmware Interface Table (NFIT).
68 QEMU NVDIMM Implemention
69 ========================
70 QEMU uses 4 bytes IO Port starting from 0x0a18 and a RAM-based memory page
74 QEMU uses BIOS Linker/loader feature to ask BIOS to allocate a memory
75 page and dynamically patch its into a int32 object named "MEMA" in ACPI.
77 This page is RAM-based and it is used to transfer data between _DSM
78 method and QEMU. If ACPI has control, this pages is owned by ACPI which
79 writes _DSM input data to it, otherwise, it is owned by QEMU which
80 emulates _DSM access and writes the output data to it.
82 ACPI writes _DSM Input Data (based on the offset in the page):
83 [0x0 - 0x3]: 4 bytes, NVDIMM Device Handle, 0 is reserved for NVDIMM
85 [0x4 - 0x7]: 4 bytes, Revision ID, that is the Arg1 of _DSM method.
86 [0x8 - 0xB]: 4 bytes. Function Index, that is the Arg2 of _DSM method.
87 [0xC - 0xFFF]: 4084 bytes, the Arg3 of _DSM method.
89 QEMU Writes Output Data (based on the offset in the page):
90 [0x0 - 0x3]: 4 bytes, the length of result
91 [0x4 - 0xFFF]: 4092 bytes, the DSM result filled by QEMU
93 IO Port 0x0a18 - 0xa1b:
94 ACPI writes the address of the memory page allocated by BIOS to this
95 port then QEMU gets the control and fills the result in the memory page.
98 [0x0a18 - 0xa1b]: 4 bytes, the address of the memory page allocated
101 _DSM process diagram:
102 ---------------------
103 "MEMA" indicates the address of memory page allocated by BIOS.
105 +----------------------+ +-----------------------+
106 | 1. OSPM | | 2. OSPM |
107 | save _DSM input data | | write "MEMA" to | Exit to QEMU
108 | to the page +----->| IO port 0x0a18 +------------+
109 | indicated by "MEMA" | | | |
110 +----------------------+ +-----------------------+ |
113 +------------- ----+ +-----------+ +------------------+--------+
114 | 5 QEMU | | 4 QEMU | | 3. QEMU |
115 | write _DSM result | | emulate | | get _DSM input data from |
116 | to the page +<------+ _DSM +<-----+ the page indicated by the |
117 | | | | | value from the IO port |
118 +--------+-----------+ +-----------+ +---------------------------+
123 +--------------------------+ +--------------+
124 | 6 OSPM | | 7 OSPM |
125 | result size is returned | | _DSM return |
126 | by reading DSM +----->+ |
127 | result from the page | | |
128 +--------------------------+ +--------------+
132 ACPI BIOS GPE.4 handler is dedicated for notifying OS about nvdimm device
135 Device Handle Reservation
136 -------------------------
137 As we mentioned above, byte 0 ~ byte 3 in the DSM memory save NVDIMM device
138 handle. The handle is completely QEMU internal thing, the values in range
139 [0, 0xFFFF] indicate nvdimm device (O means nvdimm root device named NVDR),
140 other values are reserved by other purpose.
142 Current reserved handle:
143 0x10000 is reserved for QEMU internal DSM function called on the root
146 QEMU internal use only _DSM function
147 ------------------------------------
148 UUID, 648B9CF2-CDA1-4312-8AD9-49C4AF32BD62, is reserved for QEMU internal
151 There is the function introduced by QEMU and only used by QEMU internal.
154 As we only reserved one page for NVDIMM ACPI it is impossible to map the
155 whole FIT data to guest's address space. This function is used by _FIT
156 method to read a piece of FIT data from QEMU.
159 Arg0 – UUID {set to 648B9CF2-CDA1-4312-8AD9-49C4AF32BD62}
160 Arg1 – Revision ID (set to 1)
161 Arg2 - Function Index, 0x1
162 Arg3 - A package containing a buffer whose layout is as follows:
164 +----------+-------------+-------------+-----------------------------------+
165 | Filed | Byte Length | Byte Offset | Description |
166 +----------+-------------+-------------+-----------------------------------+
167 | offset | 4 | 0 | the offset of FIT buffer |
168 +----------+-------------+-------------+-----------------------------------+
171 +----------+-------------+-------------+-----------------------------------+
172 | Filed | Byte Length | Byte Offset | Description |
173 +----------+-------------+-------------+-----------------------------------+
174 | | | | return status codes |
175 | | | | 0x100 indicates fit has been |
176 | status | 4 | 0 | updated |
177 | | | | other follows Chapter 3 in DSM |
179 +----------+-------------+-------------+-----------------------------------+
180 | fit data | Varies | 4 | FIT data |
182 +----------+-------------+-------------+-----------------------------------+
184 The FIT offset is maintained by the caller itself, current offset plugs
185 the length returned by the function is the next offset we should read.
186 When all the FIT data has been read out, zero length is returned.
188 If it returns 0x100, OSPM should restart to read FIT (read from offset 0