PowerPC Hypercall ABI
Embedded Hypervisor ABI (draft)
The Embedded Hypervisor workgroup decided to use a BEAT style ABI.
Hypercall Instruction
The hypercall instruction on legacy Book E implementations shall be the pattern 0x44000022 (SC with LEVEL=1).
Programming Note: When running on implementations which implement the "embedded hypervisor" architecture, the guest or host may replace the guest hypercall instructions with the architecturally defined hypercall instruction at runtime.
Parameter Passing
The hypercall number shall be contained in r11 (like system calls in BEAT ABIs).
Input parameters shall be contained in r3 through r10, inclusive.
Hypercalls shall return a success code and place this value in r3.
Further output parameters shall be contained in r4 through r11, inclusive.
If more data must be transferred in either direction in a single hypercall, that data must be placed into memory, and that must be specified by the hypercall API (the ABI does not define this behavior).
Summary of Register Usage
Contents of registers that are considered "Volatile" will not be preserved across a hypercall invocation:
| Register | Description |
|---|---|
| r0 | Volatile |
| r1-r2 | Non-Volatile |
| r3 | Volatile input parameter and return value |
| r4 - r10 | Volatile input parameters and output values |
| r11 | Hypercall Token and output value |
| r12 | Volatile |
| r13 - r31 | Non-Volatile |
| LR | Non-Volatile |
| CTR | Non-Volatile |
| XER | Non-Volatile |
| CR2-CR4 Fields | Non-Volatile |
| Remaining CR fields | Volatile |
| Other Registers | Non-Volatile |
Contents of registers that are considered "Non-Volatile" shall be preserved across hypercalls.
/!\ The content of non-volatile registers must be completely preserved, regardless of the size the register and the state of the processor at the time of hypercall invocation. For example, all 64 bits of a 64-bit register must be preserved even if MSR[SF] or MSR[CM] specifies 32-bit mode.
TODO
Endianness
Background
Introduction to Hypervisor Calls
This page describes the existing hcall ABI defined by the various Hypervisors available for the PowerPC platform.
Known Hypervisor `hcall()` ABIs are:
- PAPR ABI, as used by IBM PHYP Hypervisor and Xen on POWER
- BEAT ABI, as used by Toshiba CellEB
- PS3 ABI, as used by Sony PS3
The Hypervisor Call Mechanism
Calls to the hypervisor layer are performed by executing an instruction that causes an exception, in much the same way as a Unix System Call is performed. The first argument is a token that designates that actual function to perform. The remaining arguments and there interpretation is specific to the function of the `hcall()`.
The `hcall` function depends on an instruction that can "trap" to the hypervisor. Some chip implementations have a modified system call (LEVEL=1) that traps directly to the processor mode that the hypervisor runs in. In the case where the there the processor does not have this special form it is suggest that the system call instruction is used where `r0` is `-1`.
The definition for HSC is as follows:
#ifdef SC_LEVEL
#define HSC .long 0x44000022 /* SC with LEVEL=1 */
#elseif
#define HSC li r0,-1; sc
#endif
/!\ In order to safely use `r0` the `hcall` definition must have full binding and not be inlined. This way the ABI shall guarantee the volatility of `r0`.
C Language Calling Convention
int hcall_func(unsigned long opcode, unsigned long ret[], unsigned long arg<n>, ...)
/!\ Assumes that unsigned long contains the same number of bit as a `GPR`
- `ret[]`, This is an array of return values that the `hcall_func()` gives back to the caller.
- `arg<n>`, The input arguments where `n` is 1 thru 8.
Example Usage
The following is a C function using a C language binding for an `hcall`
void
example(unsigned long arg1, unsigned long arg2)
{
int rc;
unsigned long results[2];
rc = hcall_ex(results, arg1, arg2);
if (rc != H_Success) {
... Failure Case ...
}
... return values are in results array ...
}
PAPR ABI
The PAPR Spec is available thru Power.org.
Inputs
The PAPR ABI expects when the call is placed requires the token for the specific `hcall` to be place in `r3`, the remaining parameters for the `hcall` occupy `r4` thru `r11`.
Outputs
Upon completion of the `hcall`, a return code indicating status will be placed `r3` and subsequent registers `r4` thru `r11` will contain additional returned values if any.
Volatile State
The native function calling ABI is respected with respect to non-volatiles and typically guarantees extra non-volatiles, specifically:
| Register | Description | |||
|---|---|---|---|---|
| r0-r1 | Non-Volatile | |||
| r3 | Volatile parameter and return value for status | |||
| r4 - r11 | Volatile | |||
| r12 | Volatile | |||
| r13 - r31 | Non-Volatile | |||
| LR | Non-Volatile | |||
| CTR | Non-Volatile | XER | Non-Volatile | |
| CR0-CR7 | Non-Volatile |
(!) Xen `hcall()s` that are not inherited from the PAPR continue to use `r3` for return code but use memory references for additional return information. :o
Example Definition
Example of creating a C callable function that perform an `hcall()` called `H_EX` for PowerPC 64 bit ELF ABI:
hcall_ex_64.s
.align 3
.globl hcall_ex
# Insert ABI specific instruction to make symbol callable by C hcall_ex:
std r3,-8(1) # r3 (array of values) stored in stack
li r3,H_EX # load r3 with hypervisor code
HSC # Hypervisor Trap
ld r12,-8(1) # reload array into r12
cmpi 0,12,0 # only store return regs if array is non-NULL
bne ret2 # this hcall() only returns contents of r4,r5
blr # return no values
ret8: std r11,(7 * 8)(r12)
ret7: std r10,(6 * 8)(r12)
ret6: std r9,(5 * 8)(r12)
ret5: std r8,(4 * 8)(r12)
ret4: std r7,(3 * 8)(r12)
ret3: std r6,(2 * 8)(r12)
ret2: std r5,(1 * 8)(r12)
ret1: std r4,(0 * 8)(r12)
blr
(!) 32-bit variant of this function would use `lwz` and `stw` /!\ `r11` on the hypervisor side will require to be placed in the stack when switching back to C, please see the PowerPC ELF ABI for details
BEAT ABI
The BEAT ABI is used by CellEB Hypervisor from Toshiba
Inputs
The BEAT ABI expects when the call is placed requires the token for the specific `hcall` to be place in `r11`, the remaining parameters for the `hcall` occupy `r3` thru `r10`.
Outputs
Upon completion of the `hcall`, a return code indicating status will be placed `r3` and subsequent registers `r4` thru `r11` will contain additional returned values if any.
Volatile State
The native function calling ABI is respected with respect to non-volatiles and typically guarantees extra non-volatiles, specifically:
| Register | Description |
|---|
PS3 ABI
The PS3 ABI is used by Playstation 3 Hypervisor from Sony
Inputs
The BEAT ABI expects when the call is placed requires the token for the specific `hcall` to be place in `r11`, the remaining parameters for the `hcall` occupy `r3` thru `r10`.
Outputs
Upon completion of the `hcall`, a return code indicating status will be placed `r3` and subsequent registers `r4` thru `r11` will contain additional returned values if any.
Volatile State
The native function calling ABI is respected with respect to non-volatiles and typically guarantees extra non-volatiles, specifically:
| Register | Description |
|---|