docs/specs/acpi_nvdimm.txt

   1 QEMU<->ACPI BIOS NVDIMM interface
   2 ---------------------------------
   3
   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.
   6
   7 NVDIMM ACPI Background
   8 ----------------------
   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.
  13
  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.
  18
  19 This is an example from ACPI 6.0, a platform contains one NVDIMM:
  20
  21 Scope (\_SB){
  22    Device (NVDR) // Root device
  23    {
  24       Name (_HID, “ACPI0012”)
  25       Method (_STA) {...}
  26       Method (_FIT) {...}
  27       Method (_DSM, ...) {...}
  28       Device (NVD)
  29       {
  30          Name(_ADR, h) //where h is NFIT Device Handle for this NVDIMM
  31          Method (_DSM, ...) {...}
  32       }
  33    }
  34 }
  35
  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
  42
  43    Arguments:
  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
  49
  50    Return Value:
  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.
  54
  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
  58    Type Structure.
  59
  60    Arguments: None
  61
  62    Return Value:
  63    A Buffer containing a list of NFIT Type structure entries.
  64
  65    The detailed definition of the structure can be found at ACPI 6.0: 5.2.25
  66    NVDIMM Firmware Interface Table (NFIT).
  67
  68 QEMU NVDIMM Implementation
  69 ==========================
  70 QEMU uses 4 bytes IO Port starting from 0x0a18 and a RAM-based memory page
  71 for NVDIMM ACPI.
  72
  73 Memory:
  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.
  76
  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.
  81
  82    ACPI writes _DSM Input Data (based on the offset in the page):
  83    [0x0 - 0x3]: 4 bytes, NVDIMM Device Handle.
  84
  85                 The handle is completely QEMU internal thing, the values in
  86                 range [1, 0xFFFF] indicate nvdimm device. Other values are
  87                 reserved for other purposes.
  88
  89                 Reserved handles:
  90                 0 is reserved for nvdimm root device named NVDR.
  91                 0x10000 is reserved for QEMU internal DSM function called on
  92                 the root device.
  93
  94    [0x4 - 0x7]: 4 bytes, Revision ID, that is the Arg1 of _DSM method.
  95    [0x8 - 0xB]: 4 bytes. Function Index, that is the Arg2 of _DSM method.
  96    [0xC - 0xFFF]: 4084 bytes, the Arg3 of _DSM method.
  97
  98    QEMU Writes Output Data (based on the offset in the page):
  99    [0x0 - 0x3]: 4 bytes, the length of result
 100    [0x4 - 0xFFF]: 4092 bytes, the DSM result filled by QEMU
 101
 102 IO Port 0x0a18 - 0xa1b:
 103    ACPI writes the address of the memory page allocated by BIOS to this
 104    port then QEMU gets the control and fills the result in the memory page.
 105
 106    write Access:
 107    [0x0a18 - 0xa1b]: 4 bytes, the address of the memory page allocated
 108                      by BIOS.
 109
 110 _DSM process diagram:
 111 ---------------------
 112 "MEMA" indicates the address of memory page allocated by BIOS.
 113
 114  +----------------------+      +-----------------------+
 115  |    1. OSPM           |      |    2. OSPM            |
 116  | save _DSM input data |      |  write "MEMA" to      | Exit to QEMU
 117  | to the page          +----->|  IO port 0x0a18       +------------+
 118  | indicated by "MEMA"  |      |                       |            |
 119  +----------------------+      +-----------------------+            |
 120                                                                     |
 121                                                                     v
 122  +-------------   ----+       +-----------+      +------------------+--------+
 123  |      5 QEMU        |       | 4 QEMU    |      |        3. QEMU            |
 124  | write _DSM result  |       |  emulate  |      | get _DSM input data from  |
 125  | to the page        +<------+ _DSM      +<-----+ the page indicated by the |
 126  |                    |       |           |      | value from the IO port    |
 127  +--------+-----------+       +-----------+      +---------------------------+
 128           |
 129           | Enter Guest
 130           |
 131           v
 132  +--------------------------+      +--------------+
 133  |     6 OSPM               |      |   7 OSPM     |
 134  | result size is returned  |      |  _DSM return |
 135  | by reading  DSM          +----->+              |
 136  | result from the page     |      |              |
 137  +--------------------------+      +--------------+
 138
 139 NVDIMM hotplug
 140 --------------
 141 ACPI BIOS GPE.4 handler is dedicated for notifying OS about nvdimm device
 142 hot-add event.
 143
 144 QEMU internal use only _DSM function
 145 ------------------------------------
 146 1) Read FIT
 147    _FIT method uses _DSM method to fetch NFIT structures blob from QEMU
 148    in 1 page sized increments which are then concatenated and returned
 149    as _FIT method result.
 150
 151    Input parameters:
 152    Arg0 – UUID {set to 648B9CF2-CDA1-4312-8AD9-49C4AF32BD62}
 153    Arg1 – Revision ID (set to 1)
 154    Arg2 - Function Index, 0x1
 155    Arg3 - A package containing a buffer whose layout is as follows:
 156
 157    +----------+--------+--------+-------------------------------------------+
 158    |  Field   | Length | Offset |                 Description               |
 159    +----------+--------+--------+-------------------------------------------+
 160    | offset   |   4    |   0    | offset in QEMU's NFIT structures blob to  |
 161    |          |        |        | read from                                 |
 162    +----------+--------+--------+-------------------------------------------+
 163
 164    Output layout in the dsm memory page:
 165    +----------+--------+--------+-------------------------------------------+
 166    |  Field   | Length | Offset |                 Description               |
 167    +----------+--------+--------+-------------------------------------------+
 168    | length   |   4    |   0    | length of entire returned data            |
 169    |          |        |        | (including this header)                   |
 170    +----------+-----------------+-------------------------------------------+
 171    |          |        |        | return status codes                       |
 172    |          |        |        | 0x0 - success                             |
 173    |          |        |        | 0x100 - error caused by NFIT update while |
 174    | status   |   4    |   4    | read by _FIT wasn't completed, other      |
 175    |          |        |        | codes follow Chapter 3 in DSM Spec Rev1   |
 176    +----------+-----------------+-------------------------------------------+
 177    | fit data | Varies |   8    | contains FIT data, this field is present  |
 178    |          |        |        | if status field is 0;                     |
 179    +----------+--------+--------+-------------------------------------------+
 180
 181    The FIT offset is maintained by the OSPM itself, current offset plus
 182    the size of the fit data returned by the function is the next offset
 183    OSPM should read. When all FIT data has been read out, zero fit data
 184    size is returned.
 185
 186    If it returns status code 0x100, OSPM should restart to read FIT (read
 187    from offset 0 again).