1 .. SPDX-License-Identifier: GPL-2.0
2
3 ===========================
4 Hypercall Op-codes (hcalls)
5 ===========================
6
7 Overview
8 =========
9
10 Virtualization on 64-bit Power Book3S Platform
11 specification [1]_ which describes the run-tim
12 operating system and how it should interact wi
13 privileged operations. Currently there are two
14
15 - **IBM PowerVM (PHYP)**: IBM's proprietary hy
16 IBM-i and Linux as supported guests (termed
17 or LPARS). It supports the full PAPR specifi
18
19 - **Qemu/KVM**: Supports PPC64 linux guests ru
20 Though it only implements a subset of PAPR s
21
22 On PPC64 arch a guest kernel running on top of
23 a *pSeries guest*. A pseries guest runs in a s
24 issue hypercalls to the hypervisor whenever it
25 that is hypervisor privileged [3]_ or for othe
26 hypervisor.
27
28 Hence a Hypercall (hcall) is essentially a req
29 asking hypervisor to perform a privileged oper
30 guest issues a with necessary input operands.
31 the privilege operation returns a status code
32 guest.
33
34 HCALL ABI
35 =========
36 The ABI specification for a hcall between a ps
37 is covered in section 14.5.3 of ref [2]_. Swit
38 done via the instruction **HVCS** that expects
39 and any in-arguments for the hcall are provide
40 have to be passed through a memory buffer, the
41 in Big-endian byte order.
42
43 Once control returns back to the guest after h
44 'HVCS' instruction the return value of the hca
45 out values are returned in registers *r4-r12*.
46 any out values stored in a memory buffer will
47
48 Powerpc arch code provides convenient wrappers
49 in a arch specific header [4]_ to issue hcalls
50 running as pseries guest.
51
52 Register Conventions
53 ====================
54
55 Any hcall should follow same register conventi
56 of "64-Bit ELF V2 ABI Specification: Power Arc
57 summarizes these conventions:
58
59 +----------+----------+-----------------------
60 | Register |Volatile | Purpose
61 | Range |(Y/N) |
62 +==========+==========+=======================
63 | r0 | Y | Optional-usage
64 +----------+----------+-----------------------
65 | r1 | N | Stack Pointer
66 +----------+----------+-----------------------
67 | r2 | N | TOC
68 +----------+----------+-----------------------
69 | r3 | Y | hcall opcode/return v
70 +----------+----------+-----------------------
71 | r4-r10 | Y | in and out values
72 +----------+----------+-----------------------
73 | r11 | Y | Optional-usage/Enviro
74 +----------+----------+-----------------------
75 | r12 | Y | Optional-usage/Functi
76 | | | global entry point
77 +----------+----------+-----------------------
78 | r13 | N | Thread-Pointer
79 +----------+----------+-----------------------
80 | r14-r31 | N | Local Variables
81 +----------+----------+-----------------------
82 | LR | Y | Link Register
83 +----------+----------+-----------------------
84 | CTR | Y | Loop Counter
85 +----------+----------+-----------------------
86 | XER | Y | Fixed-point exception
87 +----------+----------+-----------------------
88 | CR0-1 | Y | Condition register fi
89 +----------+----------+-----------------------
90 | CR2-4 | N | Condition register fi
91 +----------+----------+-----------------------
92 | CR5-7 | Y | Condition register fi
93 +----------+----------+-----------------------
94 | Others | N |
95 +----------+----------+-----------------------
96
97 DRC & DRC Indexes
98 =================
99 ::
100
101 DR1 Gues
102 +--+ +------------+ +-----
103 | | <----> | | | Use
104 +--+ DRC1 | | DRC | Spa
105 | PAPR | Index +-----
106 DR2 | Hypervisor | |
107 +--+ | | <-----> | Ker
108 | | <----> | | Hcall |
109 +--+ DRC2 +------------+ +-----
110
111 PAPR hypervisor terms shared hardware resource
112 available for use by LPARs as Dynamic Resource
113 an LPAR, PHYP creates a data-structure called
114 to manage LPAR access. An LPAR refers to a DRC
115 called DRC-Index. The DRC-index value is provi
116 where its present as an attribute in the devic
117 DR.
118
119 HCALL Return-values
120 ===================
121
122 After servicing the hcall, hypervisor sets the
123 success or failure of the hcall. In case of a
124 the cause for error. These codes are defined a
125 header [4]_.
126
127 In some cases a hcall can potentially take a l
128 multiple times in order to be completely servi
129 accept an opaque value *continue-token* within
130 return value of *H_CONTINUE* indicates that hy
131 servicing the hcall yet.
132
133 To make such hcalls the guest need to set *con
134 initial call and use the hypervisor returned v
135 for each subsequent hcall until hypervisor ret
136 return value.
137
138 HCALL Op-codes
139 ==============
140
141 Below is a partial list of HCALLs that are sup
142 corresponding opcode values please look into t
143
144 **H_SCM_READ_METADATA**
145
146 | Input: *drcIndex, offset, buffer-address, nu
147 | Out: *numBytesRead*
148 | Return Value: *H_Success, H_Parameter, H_P2,
149
150 Given a DRC Index of an NVDIMM, read N-bytes f
151 associated with it, at a specified offset and
152 The metadata area stores configuration informa
153 bad-blocks etc. The metadata area is located o
154 area hence a separate access semantics is prov
155
156 **H_SCM_WRITE_METADATA**
157
158 | Input: *drcIndex, offset, data, numBytesToWr
159 | Out: *None*
160 | Return Value: *H_Success, H_Parameter, H_P2,
161
162 Given a DRC Index of an NVDIMM, write N-bytes
163 associated with it, at the specified offset an
164
165 **H_SCM_BIND_MEM**
166
167 | Input: *drcIndex, startingScmBlockIndex, num
168 | *targetLogicalMemoryAddress, continue-token*
169 | Out: *continue-token, targetLogicalMemoryAdd
170 | Return Value: *H_Success, H_Parameter, H_P2,
171 | *H_Too_Big, H_P5, H_Busy*
172
173 Given a DRC-Index of an NVDIMM, map a continuo
174 *(startingScmBlockIndex, startingScmBlockIndex
175 at *targetLogicalMemoryAddress* within guest p
176 case *targetLogicalMemoryAddress == 0xFFFFFFFF
177 assigns a target address to the guest. The HCA
178 an active PTE entry to the SCM block being bou
179
180 **H_SCM_UNBIND_MEM**
181 | Input: drcIndex, startingScmLogicalMemoryAdd
182 | Out: numScmBlocksUnbound
183 | Return Value: *H_Success, H_Parameter, H_P2,
184 | *H_Busy, H_LongBusyOrder1mSec, H_LongBusyOrd
185
186 Given a DRC-Index of an NVDimm, unmap *numScmB
187 at *startingScmLogicalMemoryAddress* from gues
188 HCALL can fail if the Guest has an active PTE
189 unbound.
190
191 **H_SCM_QUERY_BLOCK_MEM_BINDING**
192
193 | Input: *drcIndex, scmBlockIndex*
194 | Out: *Guest-Physical-Address*
195 | Return Value: *H_Success, H_Parameter, H_P2,
196
197 Given a DRC-Index and an SCM Block index retur
198 which the SCM block is mapped to.
199
200 **H_SCM_QUERY_LOGICAL_MEM_BINDING**
201
202 | Input: *Guest-Physical-Address*
203 | Out: *drcIndex, scmBlockIndex*
204 | Return Value: *H_Success, H_Parameter, H_P2,
205
206 Given a guest physical address return which DR
207 to that address.
208
209 **H_SCM_UNBIND_ALL**
210
211 | Input: *scmTargetScope, drcIndex*
212 | Out: *None*
213 | Return Value: *H_Success, H_Parameter, H_P2,
214 | *H_LongBusyOrder1mSec, H_LongBusyOrder10mSec
215
216 Depending on the Target scope unmap all SCM bl
217 or all SCM blocks belonging to a single NVDIMM
218 from the LPAR memory.
219
220 **H_SCM_HEALTH**
221
222 | Input: drcIndex
223 | Out: *health-bitmap (r4), health-bit-valid-b
224 | Return Value: *H_Success, H_Parameter, H_Har
225
226 Given a DRC Index return the info on predictiv
227 the PMEM device. The asserted bits in the heal
228 (described in table below) of the PMEM device
229 which bits in health-bitmap are valid. The bit
230 reverse bit ordering for example a value of 0x
231 indicates bits 0, 1, and 5 are valid.
232
233 Health Bitmap Flags:
234
235 +------+--------------------------------------
236 | Bit | Definition
237 +======+======================================
238 | 00 | PMEM device is unable to persist memo
239 | | If the system is powered down, nothin
240 +------+--------------------------------------
241 | 01 | PMEM device failed to persist memory
242 | | not saved successfully on power down
243 | | power up.
244 +------+--------------------------------------
245 | 02 | PMEM device contents are persisted fr
246 | | the last boot were successfully resto
247 +------+--------------------------------------
248 | 03 | PMEM device contents are not persiste
249 | | data to restore from the last boot.
250 +------+--------------------------------------
251 | 04 | PMEM device memory life remaining is
252 +------+--------------------------------------
253 | 05 | PMEM device will be garded off next I
254 +------+--------------------------------------
255 | 06 | PMEM device contents cannot persist d
256 | | status. A hardware failure may preven
257 | | restored.
258 +------+--------------------------------------
259 | 07 | PMEM device is unable to persist memo
260 +------+--------------------------------------
261 | 08 | PMEM device is encrypted
262 +------+--------------------------------------
263 | 09 | PMEM device has successfully complete
264 | | erase procedure.
265 +------+--------------------------------------
266 |10:63 | Reserved / Unused
267 +------+--------------------------------------
268
269 **H_SCM_PERFORMANCE_STATS**
270
271 | Input: drcIndex, resultBuffer Addr
272 | Out: None
273 | Return Value: *H_Success, H_Parameter, H_Un
274
275 Given a DRC Index collect the performance stat
276 to the resultBuffer.
277
278 **H_SCM_FLUSH**
279
280 | Input: *drcIndex, continue-token*
281 | Out: *continue-token*
282 | Return Value: *H_SUCCESS, H_Parameter, H_P2,
283
284 Given a DRC Index Flush the data to backend NV
285
286 The hcall returns H_BUSY when the flush takes
287 to be issued multiple times in order to be com
288 *continue-token* from the output to be passed
289 subsequent hcalls to the hypervisor until the
290 at which point H_SUCCESS or other error is ret
291
292 References
293 ==========
294 .. [1] "Power Architecture Platform Reference"
295 https://en.wikipedia.org/wiki/Power_Arc
296 .. [2] "Linux on Power Architecture Platform R
297 https://members.openpowerfoundation.org
298 .. [3] "Definitions and Notation" Book III-Sec
299 https://openpowerfoundation.org/?resour
300 .. [4] arch/powerpc/include/asm/hvcall.h
301 .. [5] "64-Bit ELF V2 ABI Specification: Power
302 https://openpowerfoundation.org/?resour
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.