Querying for existence¶

To find out if we’re running on KVM or not, we leverage the device tree. WhenLinux is running on KVM, a node /hypervisor exists. That node contains acompatible property with the value “linux,kvm”.

Once you determined you’re running under a PV capable KVM, you can now usehypercalls as described below.

KVM hypercalls¶

Inside the device tree’s /hypervisor node there’s a property called‘hypercall-instructions’. This property contains at most 4 opcodes that makeup the hypercall. To call a hypercall, just call these instructions.

The parameters are as follows:

Register	IN	OUT
r0		volatile
r3	1st parameter	Return code
r4	2nd parameter	1st output value
r5	3rd parameter	2nd output value
r6	4th parameter	3rd output value
r7	5th parameter	4th output value
r8	6th parameter	5th output value
r9	7th parameter	6th output value
r10	8th parameter	7th output value
r11	hypercall number	8th output value
r12		volatile

Hypercall definitions are shared in generic code, so the same hypercall numbersapply for x86 and powerpc alike with the exception that each KVM hypercallalso needs to be ORed with the KVM vendor code which is (42 << 16).

Return codes can be as follows:

Code	Meaning
0	Success
12	Hypercall not implemented
<0	Error

The magic page¶

To enable communication between the hypervisor and guest there is a new sharedpage that contains parts of supervisor visible register state. The guest canmap this shared page using the KVM hypercall KVM_HC_PPC_MAP_MAGIC_PAGE.

With this hypercall issued the guest always gets the magic page mapped at thedesired location. The first parameter indicates the effective address when theMMU is enabled. The second parameter indicates the address in real mode, ifapplicable to the target. For now, we always map the page to -4096. This way wecan access it using absolute load and store functions. The followinginstruction reads the first field of the magic page:

ld      rX, -4096(0)

The interface is designed to be extensible should there be need later to addadditional registers to the magic page. If you add fields to the magic page,also define a new hypercall feature to indicate that the host can give you moreregisters. Only if the host supports the additional features, make use of them.

The magic page layout is described by struct kvm_vcpu_arch_sharedin arch/powerpc/include/asm/kvm_para.h.

Magic page features¶

When mapping the magic page using the KVM hypercall KVM_HC_PPC_MAP_MAGIC_PAGE,a second return value is passed to the guest. This second return value containsa bitmap of available features inside the magic page.

The following enhancements to the magic page are currently available:

KVM_MAGIC_FEAT_SR	Maps SR registers r/w in the magic page
KVM_MAGIC_FEAT_MAS0_TO_SPRG7	Maps MASn, ESR, PIR and high SPRGs

For enhanced features in the magic page, please check for the existence of thefeature before using them!

Magic page flags¶

In addition to features that indicate whether a host is capable of a particularfeature we also have a channel for a guest to tell the guest whether it’s capableof something. This is what we call “flags”.

Flags are passed to the host in the low 12 bits of the Effective Address.

The following flags are currently available for a guest to expose:

MAGIC_PAGE_FLAG_NOT_MAPPED_NX Guest handles NX bits correctly wrt magic page

MSR bits¶

The MSR contains bits that require hypervisor intervention and bits that donot require direct hypervisor intervention because they only get interpretedwhen entering the guest or don’t have any impact on the hypervisor’s behavior.

The following bits are safe to be set inside the guest:

• MSR_EE
• MSR_RI

If any other bit changes in the MSR, please still use mtmsr(d).

Patched instructions¶

The “ld” and “std” instructions are transformed to “lwz” and “stw” instructionsrespectively on 32 bit systems with an added offset of 4 to accommodate for bigendianness.

The following is a list of mapping the Linux kernel performs when running asguest. Implementing any of those mappings is optional, as the instruction trapsalso act on the shared page. So calling privileged instructions still works asbefore.

Some instructions require more logic to determine what’s going on than a loador store instruction can deliver. To enable patching of those, we keep someRAM around where we can live translate instructions to. What happens is thefollowing:

1. copy emulation code to memory
2. patch that code to fit the emulated instruction
3. patch that code to return to the original pc + 4
4. patch the original instruction to branch to the new code

That way we can inject an arbitrary amount of code as replacement for a singleinstruction. This allows us to check for pending interrupts when setting EE=1for example.

Hypercall ABIs in KVM on PowerPC¶

1. KVM hypercalls (ePAPR)

These are ePAPR compliant hypercall implementation (mentioned above). Evengeneric hypercalls are implemented here, like the ePAPR idle hcall. These areavailable on all targets.

2. PAPR hypercalls

PAPR hypercalls are needed to run server PowerPC PAPR guests (-M pseries in QEMU).These are the same hypercalls that pHyp, the POWER hypervisor implements. Some ofthem are handled in the kernel, some are handled in user space. This is onlyavailable on book3s_64.

3. OSI hypercalls

Mac-on-Linux is another user of KVM on PowerPC, which has its own hypercall (longbefore KVM). This is supported to maintain compatibility. All these hypercalls getforwarded to user space. This is only useful on book3s_32, but can be used withbook3s_64 as well.