Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) ===========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) Hypercall Op-codes (hcalls)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) ===========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) Overview
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) Virtualization on 64-bit Power Book3S Platforms is based on the PAPR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) specification [1]_ which describes the run-time environment for a guest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) operating system and how it should interact with the hypervisor for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) privileged operations. Currently there are two PAPR compliant hypervisors:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) - **IBM PowerVM (PHYP)**: IBM's proprietary hypervisor that supports AIX,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16)   IBM-i and  Linux as supported guests (termed as Logical Partitions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17)   or LPARS). It supports the full PAPR specification.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) - **Qemu/KVM**: Supports PPC64 linux guests running on a PPC64 linux host.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20)   Though it only implements a subset of PAPR specification called LoPAPR [2]_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) On PPC64 arch a guest kernel running on top of a PAPR hypervisor is called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) a *pSeries guest*. A pseries guest runs in a supervisor mode (HV=0) and must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) issue hypercalls to the hypervisor whenever it needs to perform an action
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) that is hypervisor priviledged [3]_ or for other services managed by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) hypervisor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) Hence a Hypercall (hcall) is essentially a request by the pseries guest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) asking hypervisor to perform a privileged operation on behalf of the guest. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) guest issues a with necessary input operands. The hypervisor after performing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) the privilege operation returns a status code and output operands back to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) guest.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) HCALL ABI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) The ABI specification for a hcall between a pseries guest and PAPR hypervisor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) is covered in section 14.5.3 of ref [2]_. Switch to the  Hypervisor context is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) done via the instruction **HVCS** that expects the Opcode for hcall is set in *r3*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) and any in-arguments for the hcall are provided in registers *r4-r12*. If values
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) have to be passed through a memory buffer, the data stored in that buffer should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) in Big-endian byte order.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) Once control is returns back to the guest after hypervisor has serviced the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) 'HVCS' instruction the return value of the hcall is available in *r3* and any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) out values are returned in registers *r4-r12*. Again like in case of in-arguments,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) any out values stored in a memory buffer will be in Big-endian byte order.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) Powerpc arch code provides convenient wrappers named **plpar_hcall_xxx** defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) in a arch specific header [4]_ to issue hcalls from the linux kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) running as pseries guest.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) Register Conventions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) Any hcall should follow same register convention as described in section 2.2.1.1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) of "64-Bit ELF V2 ABI Specification: Power Architecture"[5]_. Table below
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) summarizes these conventions:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) +----------+----------+-------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) | Register |Volatile  |  Purpose                                  |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) | Range    |(Y/N)     |                                           |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) +==========+==========+===========================================+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) |   r0     |    Y     |  Optional-usage                           |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) +----------+----------+-------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) |   r1     |    N     |  Stack Pointer                            |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) +----------+----------+-------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) |   r2     |    N     |  TOC                                      |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) +----------+----------+-------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) |   r3     |    Y     |  hcall opcode/return value                |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) +----------+----------+-------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) |  r4-r10  |    Y     |  in and out values                        |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) +----------+----------+-------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) |   r11    |    Y     |  Optional-usage/Environmental pointer     |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) +----------+----------+-------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) |   r12    |    Y     |  Optional-usage/Function entry address at |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) |          |          |  global entry point                       |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) +----------+----------+-------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) |   r13    |    N     |  Thread-Pointer                           |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) +----------+----------+-------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) |  r14-r31 |    N     |  Local Variables                          |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) +----------+----------+-------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) |    LR    |    Y     |  Link Register                            |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) +----------+----------+-------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) |   CTR    |    Y     |  Loop Counter                             |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) +----------+----------+-------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) |   XER    |    Y     |  Fixed-point exception register.          |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) +----------+----------+-------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) |  CR0-1   |    Y     |  Condition register fields.               |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) +----------+----------+-------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) |  CR2-4   |    N     |  Condition register fields.               |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) +----------+----------+-------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) |  CR5-7   |    Y     |  Condition register fields.               |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) +----------+----------+-------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) |  Others  |    N     |                                           |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95) +----------+----------+-------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) DRC & DRC Indexes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)      DR1                                  Guest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)      +--+        +------------+         +---------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)      |  | <----> |            |         |  User   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)      +--+  DRC1  |            |   DRC   |  Space  |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)                  |    PAPR    |  Index  +---------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)      DR2         | Hypervisor |         |         |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)      +--+        |            | <-----> |  Kernel |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)      |  | <----> |            |  Hcall  |         |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)      +--+  DRC2  +------------+         +---------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) PAPR hypervisor terms shared hardware resources like PCI devices, NVDIMMs etc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) available for use by LPARs as Dynamic Resource (DR). When a DR is allocated to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) an LPAR, PHYP creates a data-structure called Dynamic Resource Connector (DRC)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) to manage LPAR access. An LPAR refers to a DRC via an opaque 32-bit number
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) called DRC-Index. The DRC-index value is provided to the LPAR via device-tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) where its present as an attribute in the device tree node associated with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) DR.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) HCALL Return-values
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) After servicing the hcall, hypervisor sets the return-value in *r3* indicating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) success or failure of the hcall. In case of a failure an error code indicates
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) the cause for error. These codes are defined and documented in arch specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) header [4]_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) In some cases a hcall can potentially take a long time and need to be issued
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) multiple times in order to be completely serviced. These hcalls will usually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) accept an opaque value *continue-token* within there argument list and a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) return value of *H_CONTINUE* indicates that hypervisor hasn't still finished
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) servicing the hcall yet.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) To make such hcalls the guest need to set *continue-token == 0* for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) initial call and use the hypervisor returned value of *continue-token*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) for each subsequent hcall until hypervisor returns a non *H_CONTINUE*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) return value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) HCALL Op-codes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) Below is a partial list of HCALLs that are supported by PHYP. For the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) corresponding opcode values please look into the arch specific header [4]_:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) **H_SCM_READ_METADATA**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) | Input: *drcIndex, offset, buffer-address, numBytesToRead*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) | Out: *numBytesRead*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) | Return Value: *H_Success, H_Parameter, H_P2, H_P3, H_Hardware*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) Given a DRC Index of an NVDIMM, read N-bytes from the the metadata area
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) associated with it, at a specified offset and copy it to provided buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) The metadata area stores configuration information such as label information,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) bad-blocks etc. The metadata area is located out-of-band of NVDIMM storage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) area hence a separate access semantics is provided.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) **H_SCM_WRITE_METADATA**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) | Input: *drcIndex, offset, data, numBytesToWrite*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) | Out: *None*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) | Return Value: *H_Success, H_Parameter, H_P2, H_P4, H_Hardware*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) Given a DRC Index of an NVDIMM, write N-bytes to the metadata area
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) associated with it, at the specified offset and from the provided buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) **H_SCM_BIND_MEM**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) | Input: *drcIndex, startingScmBlockIndex, numScmBlocksToBind,*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) | *targetLogicalMemoryAddress, continue-token*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) | Out: *continue-token, targetLogicalMemoryAddress, numScmBlocksToBound*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) | Return Value: *H_Success, H_Parameter, H_P2, H_P3, H_P4, H_Overlap,*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) | *H_Too_Big, H_P5, H_Busy*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) Given a DRC-Index of an NVDIMM, map a continuous SCM blocks range
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) *(startingScmBlockIndex, startingScmBlockIndex+numScmBlocksToBind)* to the guest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) at *targetLogicalMemoryAddress* within guest physical address space. In
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) case *targetLogicalMemoryAddress == 0xFFFFFFFF_FFFFFFFF* then hypervisor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) assigns a target address to the guest. The HCALL can fail if the Guest has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) an active PTE entry to the SCM block being bound.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) **H_SCM_UNBIND_MEM**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) | Input: drcIndex, startingScmLogicalMemoryAddress, numScmBlocksToUnbind
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) | Out: numScmBlocksUnbound
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) | Return Value: *H_Success, H_Parameter, H_P2, H_P3, H_In_Use, H_Overlap,*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) | *H_Busy, H_LongBusyOrder1mSec, H_LongBusyOrder10mSec*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) Given a DRC-Index of an NVDimm, unmap *numScmBlocksToUnbind* SCM blocks starting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) at *startingScmLogicalMemoryAddress* from guest physical address space. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) HCALL can fail if the Guest has an active PTE entry to the SCM block being
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) unbound.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) **H_SCM_QUERY_BLOCK_MEM_BINDING**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) | Input: *drcIndex, scmBlockIndex*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) | Out: *Guest-Physical-Address*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) | Return Value: *H_Success, H_Parameter, H_P2, H_NotFound*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) Given a DRC-Index and an SCM Block index return the guest physical address to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) which the SCM block is mapped to.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) **H_SCM_QUERY_LOGICAL_MEM_BINDING**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) | Input: *Guest-Physical-Address*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) | Out: *drcIndex, scmBlockIndex*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) | Return Value: *H_Success, H_Parameter, H_P2, H_NotFound*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) Given a guest physical address return which DRC Index and SCM block is mapped
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) to that address.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) **H_SCM_UNBIND_ALL**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) | Input: *scmTargetScope, drcIndex*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) | Out: *None*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) | Return Value: *H_Success, H_Parameter, H_P2, H_P3, H_In_Use, H_Busy,*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) | *H_LongBusyOrder1mSec, H_LongBusyOrder10mSec*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) Depending on the Target scope unmap all SCM blocks belonging to all NVDIMMs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) or all SCM blocks belonging to a single NVDIMM identified by its drcIndex
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) from the LPAR memory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) **H_SCM_HEALTH**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) | Input: drcIndex
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) | Out: *health-bitmap (r4), health-bit-valid-bitmap (r5)*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) | Return Value: *H_Success, H_Parameter, H_Hardware*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) Given a DRC Index return the info on predictive failure and overall health of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) the PMEM device. The asserted bits in the health-bitmap indicate one or more states
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) (described in table below) of the PMEM device and health-bit-valid-bitmap indicate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) which bits in health-bitmap are valid. The bits are reported in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) reverse bit ordering for example a value of 0xC400000000000000
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) indicates bits 0, 1, and 5 are valid.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) Health Bitmap Flags:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) +------+-----------------------------------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) |  Bit |               Definition                                              |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) +======+=======================================================================+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) |  00  | PMEM device is unable to persist memory contents.                     |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) |      | If the system is powered down, nothing will be saved.                 |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) +------+-----------------------------------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) |  01  | PMEM device failed to persist memory contents. Either contents were   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) |      | not saved successfully on power down or were not restored properly on |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) |      | power up.                                                             |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) +------+-----------------------------------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) |  02  | PMEM device contents are persisted from previous IPL. The data from   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) |      | the last boot were successfully restored.                             |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) +------+-----------------------------------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) |  03  | PMEM device contents are not persisted from previous IPL. There was no|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) |      | data to restore from the last boot.                                   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) +------+-----------------------------------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) |  04  | PMEM device memory life remaining is critically low                   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) +------+-----------------------------------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) |  05  | PMEM device will be garded off next IPL due to failure                |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) +------+-----------------------------------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) |  06  | PMEM device contents cannot persist due to current platform health    |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) |      | status. A hardware failure may prevent data from being saved or       |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) |      | restored.                                                             |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) +------+-----------------------------------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) |  07  | PMEM device is unable to persist memory contents in certain conditions|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) +------+-----------------------------------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) |  08  | PMEM device is encrypted                                              |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) +------+-----------------------------------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) |  09  | PMEM device has successfully completed a requested erase or secure    |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) |      | erase procedure.                                                      |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) +------+-----------------------------------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) |10:63 | Reserved / Unused                                                     |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) +------+-----------------------------------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) **H_SCM_PERFORMANCE_STATS**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) | Input: drcIndex, resultBuffer Addr
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) | Out: None
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) | Return Value:  *H_Success, H_Parameter, H_Unsupported, H_Hardware, H_Authority, H_Privilege*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) Given a DRC Index collect the performance statistics for NVDIMM and copy them
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) to the resultBuffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) References
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) ==========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) .. [1] "Power Architecture Platform Reference"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)        https://en.wikipedia.org/wiki/Power_Architecture_Platform_Reference
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) .. [2] "Linux on Power Architecture Platform Reference"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283)        https://members.openpowerfoundation.org/document/dl/469
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) .. [3] "Definitions and Notation" Book III-Section 14.5.3
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285)        https://openpowerfoundation.org/?resource_lib=power-isa-version-3-0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) .. [4] arch/powerpc/include/asm/hvcall.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) .. [5] "64-Bit ELF V2 ABI Specification: Power Architecture"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288)        https://openpowerfoundation.org/?resource_lib=64-bit-elf-v2-abi-specification-power-architecture