2. File descriptors

The kvm API is centered around file descriptors. An initial open(“/dev/kvm”) obtains a handle to the kvm subsystem; this handle can be used to issue system ioctls. A KVM_CREATE_VM ioctl on this handle will create a VM file descriptor which can be used to issue VM ioctls. A KVM_CREATE_VCPU or KVM_CREATE_DEVICE ioctl on a VM fd will create a virtual cpu or device and return a file descriptor pointing to the new resource. Finally, ioctls on a vcpu or device fd can be used to control the vcpu or device. For vcpus, this includes the important task of actually running guest code.

In general file descriptors can be migrated among processes by means of fork() and the SCM_RIGHTS facility of unix domain socket. These kinds of tricks are explicitly not supported by kvm. While they will not cause harm to the host, their actual behavior is not guaranteed by the API. See “General description” for details on the ioctl usage model that is supported by KVM.

It is important to note that althought VM ioctls may only be issued from the process that created the VM, a VM’s lifecycle is associated with its file descriptor, not its creator (process). In other words, the VM and its resources, including the associated address space, are not freed until the last reference to the VM’s file descriptor has been released. For example, if fork() is issued after ioctl(KVM_CREATE_VM), the VM will not be freed until both the parent (original) process and its child have put their references to the VM’s file descriptor.

Because a VM’s resources are not freed until the last reference to its file descriptor is released, creating additional references to a VM via via fork(), dup(), etc… without careful consideration is strongly discouraged and may have unwanted side effects, e.g. memory allocated by and on behalf of the VM’s process may not be freed/unaccounted when the VM is shut down.