papr_hcalls.rst 14 KB

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