]>
Commit | Line | Data |
---|---|---|
5ecee4ba CO |
1 | *** BIG FAT WARNING *** |
2 | The kvm module is currently in EXPERIMENTAL state for s390. This means that | |
3 | the interface to the module is not yet considered to remain stable. Thus, be | |
4 | prepared that we keep breaking your userspace application and guest | |
5 | compatibility over and over again until we feel happy with the result. Make sure | |
6 | your guest kernel, your host kernel, and your userspace launcher are in a | |
7 | consistent state. | |
8 | ||
9 | This Documentation describes the unique ioctl calls to /dev/kvm, the resulting | |
10 | kvm-vm file descriptors, and the kvm-vcpu file descriptors that differ from x86. | |
11 | ||
12 | 1. ioctl calls to /dev/kvm | |
13 | KVM does support the following ioctls on s390 that are common with other | |
14 | architectures and do behave the same: | |
15 | KVM_GET_API_VERSION | |
16 | KVM_CREATE_VM (*) see note | |
17 | KVM_CHECK_EXTENSION | |
18 | KVM_GET_VCPU_MMAP_SIZE | |
19 | ||
20 | Notes: | |
21 | * KVM_CREATE_VM may fail on s390, if the calling process has multiple | |
22 | threads and has not called KVM_S390_ENABLE_SIE before. | |
23 | ||
24 | In addition, on s390 the following architecture specific ioctls are supported: | |
25 | ioctl: KVM_S390_ENABLE_SIE | |
26 | args: none | |
27 | see also: include/linux/kvm.h | |
28 | This call causes the kernel to switch on PGSTE in the user page table. This | |
29 | operation is needed in order to run a virtual machine, and it requires the | |
30 | calling process to be single-threaded. Note that the first call to KVM_CREATE_VM | |
31 | will implicitly try to switch on PGSTE if the user process has not called | |
32 | KVM_S390_ENABLE_SIE before. User processes that want to launch multiple threads | |
33 | before creating a virtual machine have to call KVM_S390_ENABLE_SIE, or will | |
34 | observe an error calling KVM_CREATE_VM. Switching on PGSTE is a one-time | |
35 | operation, is not reversible, and will persist over the entire lifetime of | |
36 | the calling process. It does not have any user-visible effect other than a small | |
37 | performance penalty. | |
38 | ||
39 | 2. ioctl calls to the kvm-vm file descriptor | |
40 | KVM does support the following ioctls on s390 that are common with other | |
41 | architectures and do behave the same: | |
42 | KVM_CREATE_VCPU | |
43 | KVM_SET_USER_MEMORY_REGION (*) see note | |
44 | KVM_GET_DIRTY_LOG (**) see note | |
45 | ||
46 | Notes: | |
47 | * kvm does only allow exactly one memory slot on s390, which has to start | |
48 | at guest absolute address zero and at a user address that is aligned on any | |
49 | page boundary. This hardware "limitation" allows us to have a few unique | |
50 | optimizations. The memory slot doesn't have to be filled | |
51 | with memory actually, it may contain sparse holes. That said, with different | |
52 | user memory layout this does still allow a large flexibility when | |
53 | doing the guest memory setup. | |
54 | ** KVM_GET_DIRTY_LOG doesn't work properly yet. The user will receive an empty | |
55 | log. This ioctl call is only needed for guest migration, and we intend to | |
56 | implement this one in the future. | |
57 | ||
58 | In addition, on s390 the following architecture specific ioctls for the kvm-vm | |
59 | file descriptor are supported: | |
60 | ioctl: KVM_S390_INTERRUPT | |
61 | args: struct kvm_s390_interrupt * | |
62 | see also: include/linux/kvm.h | |
63 | This ioctl is used to submit a floating interrupt for a virtual machine. | |
64 | Floating interrupts may be delivered to any virtual cpu in the configuration. | |
65 | Only some interrupt types defined in include/linux/kvm.h make sense when | |
66 | submitted as floating interrupts. The following interrupts are not considered | |
67 | to be useful as floating interrupts, and a call to inject them will result in | |
68 | -EINVAL error code: program interrupts and interprocessor signals. Valid | |
69 | floating interrupts are: | |
70 | KVM_S390_INT_VIRTIO | |
71 | KVM_S390_INT_SERVICE | |
72 | ||
73 | 3. ioctl calls to the kvm-vcpu file descriptor | |
74 | KVM does support the following ioctls on s390 that are common with other | |
75 | architectures and do behave the same: | |
76 | KVM_RUN | |
77 | KVM_GET_REGS | |
78 | KVM_SET_REGS | |
79 | KVM_GET_SREGS | |
80 | KVM_SET_SREGS | |
81 | KVM_GET_FPU | |
82 | KVM_SET_FPU | |
83 | ||
84 | In addition, on s390 the following architecture specific ioctls for the | |
85 | kvm-vcpu file descriptor are supported: | |
86 | ioctl: KVM_S390_INTERRUPT | |
87 | args: struct kvm_s390_interrupt * | |
88 | see also: include/linux/kvm.h | |
89 | This ioctl is used to submit an interrupt for a specific virtual cpu. | |
90 | Only some interrupt types defined in include/linux/kvm.h make sense when | |
91 | submitted for a specific cpu. The following interrupts are not considered | |
92 | to be useful, and a call to inject them will result in -EINVAL error code: | |
93 | service processor calls and virtio interrupts. Valid interrupt types are: | |
94 | KVM_S390_PROGRAM_INT | |
95 | KVM_S390_SIGP_STOP | |
96 | KVM_S390_RESTART | |
97 | KVM_S390_SIGP_SET_PREFIX | |
98 | KVM_S390_INT_EMERGENCY | |
99 | ||
100 | ioctl: KVM_S390_STORE_STATUS | |
101 | args: unsigned long | |
102 | see also: include/linux/kvm.h | |
103 | This ioctl stores the state of the cpu at the guest real address given as | |
104 | argument, unless one of the following values defined in include/linux/kvm.h | |
105 | is given as arguement: | |
106 | KVM_S390_STORE_STATUS_NOADDR - the CPU stores its status to the save area in | |
107 | absolute lowcore as defined by the principles of operation | |
108 | KVM_S390_STORE_STATUS_PREFIXED - the CPU stores its status to the save area in | |
109 | its prefix page just like the dump tool that comes with zipl. This is useful | |
110 | to create a system dump for use with lkcdutils or crash. | |
111 | ||
112 | ioctl: KVM_S390_SET_INITIAL_PSW | |
113 | args: struct kvm_s390_psw * | |
114 | see also: include/linux/kvm.h | |
115 | This ioctl can be used to set the processor status word (psw) of a stopped cpu | |
116 | prior to running it with KVM_RUN. Note that this call is not required to modify | |
117 | the psw during sie intercepts that fall back to userspace because struct kvm_run | |
118 | does contain the psw, and this value is evaluated during reentry of KVM_RUN | |
119 | after the intercept exit was recognized. | |
120 | ||
121 | ioctl: KVM_S390_INITIAL_RESET | |
122 | args: none | |
123 | see also: include/linux/kvm.h | |
124 | This ioctl can be used to perform an initial cpu reset as defined by the | |
125 | principles of operation. The target cpu has to be in stopped state. |