Documentation ¶
Overview ¶
Package kvm provides minimal wrappers for some KVM ioctls. It is pure Go: Instead of using Cgo to include linux/kvm.h, the package includes a magic.go file generated by kvm-gen-magic.
Passages from kvm/api.txt are marked with double quotes in the function docs.
https://www.kernel.org/doc/Documentation/virtual/kvm/api.txt https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/include/uapi/linux/kvm.h https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/arch/x86/include/uapi/asm/kvm.h
Index ¶
- Constants
- func CheckExtension(f interface{ ... }, cap Cap) (int, error)
- func CreateIRQChip(vm *VM) error
- func CreatePIT2(vm *VM, cfg *PITConfig) error
- func GetAPIVersion(sys *os.File) (int, error)
- func GetClock(vm *VM, data *ClockData) error
- func GetFPU(vcpu *VCPU, fpu *FPU) error
- func GetMSRFeatureIndexList(sys *os.File) (indices []int, err error)
- func GetMSRIndexList(sys *os.File) (indices []int, err error)
- func GetRegs(vcpu *VCPU, regs *Regs) error
- func GetSregs(vcpu *VCPU, sregs *Sregs) error
- func GetVCPUMmapSize(sys *os.File) (int, error)
- func IRQFD(vm *VM, cfg *IRQFDConfig) error
- func Run(vcpu *VCPU) error
- func SetCPUID2(vcpu *VCPU, entries []CPUIDEntry2) error
- func SetClock(vm *VM, data *ClockData) error
- func SetFPU(vcpu *VCPU, fpu *FPU) error
- func SetIdentityMapAddr(vm *VM, addr uint64) error
- func SetMSRs(vcpu *VCPU, entries []MSREntry) error
- func SetRegs(vcpu *VCPU, regs *Regs) error
- func SetSregs(vcpu *VCPU, sregs *Sregs) error
- func SetTSSAddr(vm *VM, addr uint64) error
- func SetUserMemoryRegion(vm *VM, region *UserspaceMemoryRegion) error
- type CPUIDEntry2
- type Cap
- type ClockData
- type Dtable
- type Exit
- type FPU
- type IOExitData
- type IRQFDConfig
- type MMIOExitData
- type MSREntry
- type PITConfig
- type Regs
- type Segment
- type Sregs
- type UserspaceMemoryRegion
- type VCPU
- type VCPUState
- type VM
Constants ¶
const ( CapIRQChip = Cap(0) CapHLT = Cap(1) CapMMUShadowCacheControl = Cap(2) CapUserMemory = Cap(3) CapSetTSSAddr = Cap(4) CapVAPIC = Cap(6) CapExtCPUID = Cap(7) CapClockSource = Cap(8) CapNrVCPUs = Cap(9) CapNrMemslots = Cap(10) CapPIT = Cap(11) CapNopIODelay = Cap(12) CapPVMMU = Cap(13) CapMPState = Cap(14) CapCoalescedMMIO = Cap(15) CapSyncMMU = Cap(16) CapIOMMU = Cap(18) CapDestroyMemoryRegionWorks = Cap(21) CapUserNMI = Cap(22) CapSetGuestDebug = Cap(23) CapReinjectControl = Cap(24) CapIRQRouting = Cap(25) CapIRQInjectStatus = Cap(26) CapAssignDevIRQ = Cap(29) CapJoinMemoryRegionsWorks = Cap(30) CapMCE = Cap(31) CapIRQFD = Cap(32) CapPIT2 = Cap(33) CapSetBootCPUID = Cap(34) CapPITState2 = Cap(35) CapIOEventFD = Cap(36) CapSetIdentityMapAddr = Cap(37) CapXenHVM = Cap(38) CapAdjustClock = Cap(39) CapInternalErrorData = Cap(40) CapVCPUEvents = Cap(41) CapS390PSW = Cap(42) CapPPCSegState = Cap(43) CapHyperV = Cap(44) CapHyperVVAPIC = Cap(45) CapHyperVSpin = Cap(46) CapPCISegment = Cap(47) CapPPCPairedSingles = Cap(48) CapIntrShadow = Cap(49) CapDebugRegs = Cap(50) CapX86RobustSingleStep = Cap(51) CapPPCOSI = Cap(52) CapPPCUnsetIRQ = Cap(53) CapEnableCap = Cap(54) CapXSave = Cap(55) CapXCRS = Cap(56) CapPPCGetPVInfo = Cap(57) CapPPCIRQLevel = Cap(58) CapAsyncPF = Cap(59) CapTSCControl = Cap(60) CapGetTSCKHz = Cap(61) CapPPCBookeSRegs = Cap(62) CapSPAPRTCE = Cap(63) CapPPCSMT = Cap(64) CapPPCRMA = Cap(65) CapMaxVCPUs = Cap(66) CapPPCHIOR = Cap(67) CapPPCPAPR = Cap(68) CapSWTLB = Cap(69) CapOneReg = Cap(70) CapS390GMap = Cap(71) CapTSCDeadlineTimer = Cap(72) CapS390UControl = Cap(73) CapSyncRegs = Cap(74) CapPCI23 = Cap(75) CapKVMClockCtrl = Cap(76) CapSignalMSI = Cap(77) CapPPCGetSMMUInfo = Cap(78) CapS390COW = Cap(79) CapPPCAllocHTAB = Cap(80) CapReadonlyMem = Cap(81) CapIRQFDResample = Cap(82) CapPPCBookeWatchdog = Cap(83) CapPPCHTABFD = Cap(84) CapS390CSSSupport = Cap(85) CapPPCEPR = Cap(86) CapARMPSCI = Cap(87) CapARMSetDeviceAddr = Cap(88) CapDeviceCtrl = Cap(89) CapIRQMPIC = Cap(90) CapPPCRTAS = Cap(91) CapIRQXICS = Cap(92) CapARMEL132Bit = Cap(93) CapSPAPRMultitce = Cap(94) CapExtEmulCPUID = Cap(95) CapHyperVTime = Cap(96) CapIOAPICPolarityIgnored = Cap(97) CapEnableCapVM = Cap(98) CapS390IRQChip = Cap(99) CapIOEventFDNoLength = Cap(100) CapVMAttributes = Cap(101) CapARMPSCI02 = Cap(102) CapPPCFixupHCall = Cap(103) CapPPCEnableHCall = Cap(104) CapCheckExtensionVM = Cap(105) CapS390UserSIGP = Cap(106) CapS390VectorRegisters = Cap(107) CapS390MemOp = Cap(108) CapS390UserSTSI = Cap(109) CapS390SKeys = Cap(110) CapMIPSFPU = Cap(111) CapMIPSMSA = Cap(112) CapS390InjectIRQ = Cap(113) CapS390IRQState = Cap(114) CapPPCHWRNG = Cap(115) CapDisableQuirks = Cap(116) CapX86SMM = Cap(117) CapMultiAddressSpace = Cap(118) CapGuestDebugHWBPS = Cap(119) CapGuestDebugHWWPS = Cap(120) CapSplitIRQChip = Cap(121) CapIOEventFDAnyLength = Cap(122) CapHyperVSYNIC = Cap(123) CapS390RI = Cap(124) CapSPAPRTCE64 = Cap(125) CapARMPMUv3 = Cap(126) CapVCPUAttributes = Cap(127) CapMaxVCPUID = Cap(128) CapX2APICAPI = Cap(129) CapS390UserInstr0 = Cap(130) CapMSIDevid = Cap(131) CapPPCHTM = Cap(132) CapSPAPRResizeHPT = Cap(133) CapPPCMMURadix = Cap(134) CapPPCMMUHashV3 = Cap(135) CapImmediateExit = Cap(136) CapMIPSVZ = Cap(137) CapMIPSTE = Cap(138) CapMIPS64Bit = Cap(139) CapS390GS = Cap(140) CapS390AIS = Cap(141) CapSPAPRTCEVFIO = Cap(142) CapX86DisableExits = Cap(143) CapARMUserIRQ = Cap(144) CapS390CMMAMigration = Cap(145) CapPPCFWNMI = Cap(146) CapPPCSMTPossible = Cap(147) CapHyperVSYNIC2 = Cap(148) CapHyperVVPIndex = Cap(149) CapS390AISMigration = Cap(150) CapPPCGetCPUChar = Cap(151) CapS390BPB = Cap(152) CapGetMSRFeatures = Cap(153) CapHyperVEventFD = Cap(154) CapHyperVTLBFlush = Cap(155) CapS390HPage1M = Cap(156) CapNestedState = Cap(157) CapARMINJECTSERRORESR = Cap(158) CapMSRPlatformInfo = Cap(159) CapPPCNestedHV = Cap(160) CapHyperVSendIPI = Cap(161) CapCoalescedPIO = Cap(162) CapHyperVEnlightenedVMCS = Cap(163) CapExceptionPayload = Cap(164) CapARMVMIPASize = Cap(165) CapManualDirtyLogProtect = Cap(166) CapHyperVCPUID = Cap(167) CapManualDirtyLogProtect2 = Cap(168) CapPPCIRQXIVE = Cap(169) CapARMSVE = Cap(170) CapARMPtrauthAddress = Cap(171) CapARMPtrauthGeneric = Cap(172) CapPMUEventFilter = Cap(173) CapARMIRQLineLayout2 = Cap(174) CapHyperVDirectTLBFlush = Cap(175) CapPPCGuestDebugSStep = Cap(176) CapARMNISVToUser = Cap(177) CapARMInjectExtDABT = Cap(178) CapS390VCPUResets = Cap(179) CapS390Protected = Cap(180) CapPPCSecureGuest = Cap(181) CapHaltPoll = Cap(182) CapAsyncPFInt = Cap(183) CapLastCPU = Cap(184) CapSmallerMaxPhyAddr = Cap(185) CapS390Diag318 = Cap(186) CapStealTime = Cap(187) CapX86UserSpaceMSR = Cap(188) CapX86MSRFilter = Cap(189) CapEnforcePVFeatureCPUID = Cap(190) CapSysHyperVCPUID = Cap(191) CapDirtyLogRing = Cap(192) CapX86BusLockExit = Cap(193) CapPPCDAWR1 = Cap(194) CapSetGuestDebug2 = Cap(195) CapSGXAttribute = Cap(196) CapVMCopyEncContextFrom = Cap(197) CapPTPKVM = Cap(198) CapHyperVEnforceCPUID = Cap(199) CapSRegs2 = Cap(200) CapExitHypercall = Cap(201) CapPPCRPTInvalidate = Cap(202) CapBinaryStatsFD = Cap(203) CapExitOnEmulationFailure = Cap(204) CapARMMTE = Cap(205) CapVMMoveEncContextFrom = Cap(206) CapVMGPABits = Cap(207) CapXSave2 = Cap(208) CapSysAttributes = Cap(209) CapPPCAILMode3 = Cap(210) CapS390MemOpExtension = Cap(211) CapPMUCapability = Cap(212) CapDisableQuirks2 = Cap(213) CapVMTSCControl = Cap(214) CapSystemEventData = Cap(215) CapARMSuspend = Cap(216) CapS390ProtectedDump = Cap(217) CapX86TripleFaultEvent = Cap(218) CapX86NotifyVMExit = Cap(219) CapVMDisableNXHugePages = Cap(220) CapS390ZPCIOp = Cap(221) CapS390CPUTopology = Cap(222) CapDirtyLogRingAcqRel = Cap(223) )
const ( ExitUnknown = Exit(0) ExitException = Exit(1) ExitIO = Exit(2) ExitHypercall = Exit(3) ExitDebug = Exit(4) ExitHLT = Exit(5) ExitMMIO = Exit(6) ExitIRQWindowOpen = Exit(7) ExitShutdown = Exit(8) ExitFailEntry = Exit(9) ExitIntr = Exit(10) ExitSetTPR = Exit(11) ExitTPRAccess = Exit(12) ExitS390SIEIC = Exit(13) ExitS390Reset = Exit(14) ExitDCR = Exit(15) ExitNMI = Exit(16) ExitInternalError = Exit(17) ExitOSI = Exit(18) ExitPAPRHCALL = Exit(19) ExitS390UControl = Exit(20) ExitWatchdog = Exit(21) ExitS390TSCH = Exit(22) ExitEPR = Exit(23) ExitSystemEvent = Exit(24) ExitS390STSI = Exit(25) ExitIOAPICEOI = Exit(26) ExitHyperV = Exit(27) ExitARMNISV = Exit(28) ExitX86RDMSR = Exit(29) ExitX86WRMSR = Exit(30) ExitDirtyRingFull = Exit(31) ExitAPResetHold = Exit(32) ExitX86BusLock = Exit(33) ExitXen = Exit(34) ExitRISCVSBI = Exit(35) ExitRISCVCSR = Exit(36) ExitNotify = Exit(37) )
const ( MemLogDirtyPages = 1 MemReadonly = 2 )
const ( CPUIDFlagSignificantIndex = 1 CPUIDFlagStatefulFunc = 2 CPUIDFlagStateReadNext = 4 )
const (
PITSpeakerDummy = 1
)
const StableAPIVersion = 12
StableAPIVersion is the expected return value of GetAPIVersion.
Variables ¶
This section is empty.
Functions ¶
func CheckExtension ¶
CheckExtension returns a non-zero value if the extension identified by the given capability is available. "Generally 0 means no and 1 means yes, but some extensions may report additional information in the integer return value."
If CheckExtension(dev, CapCheckExtensionVM) returns 1, then CheckExtension can also be used to test VM extensions.
func CreateIRQChip ¶
CreateIRQChip "creates an interrupt controller model in the kernel." This ioctl is available if CheckExtension(CapIRQChip) returns 1.
func CreatePIT2 ¶
CreatePIT2 "Creates an in-kernel device model for the i8254 PIT. This call is only valid after enabling in-kernel irqchip support via KVM_CREATE_IRQCHIP."
This ioctl is available if CheckExtension(CapPIT2) returns 1.
func GetAPIVersion ¶
GetAPIVersion returns the KVM API version, normally StableAPIVersion.
func GetClock ¶
GetClock returns "the current timestamp of kvmclock as seen by the current guest." This ioctl is available if CheckExtension(CapAdjustClock) returns a non-zero value.
func GetMSRFeatureIndexList ¶
GetMSRFeatureIndexList "returns the list of MSRs that can be passed to the KVM_GET_MSRS system ioctl. This lets userspace probe host capabilities and processor features that are exposed via MSRs (e.g., VMX capabilities). This list also varies by kvm version and host processor, but does not change otherwise."
This ioctl is available if CheckExtension(CapGetMSRFeatures) returns 1.
func GetMSRIndexList ¶
GetMSRIndexList "returns the guest msrs that are supported. The list varies by kvm version and host processor, but does not change otherwise."
func GetVCPUMmapSize ¶
GetVCPUMmapSize returns the byte size of the shared memory region used by the KVM_RUN ioctl.
func IRQFD ¶
func IRQFD(vm *VM, cfg *IRQFDConfig) error
IRQFD "allows setting an eventfd to directly trigger a guest interrupt. IRQFDConfig.Fd specifies the file descriptor to use as the eventfd and IRQFDConfig.GSI specifies the irqchip pin toggled by this event. When an event is triggered on the eventfd, an interrupt is injected into the guest using the specified gsi pin. The irqfd is removed using the KVM_IRQFD_FLAG_DEASSIGN flag, specifying both IRQFDConfig.Fd and IRQFDConfig.GSI."
func SetCPUID2 ¶
func SetCPUID2(vcpu *VCPU, entries []CPUIDEntry2) error
SetCPUID2 "defines the vcpu responses to the cpuid instruction." This ioctl is available if CheckExtension(CapExtCPUID) returns 1.
func SetClock ¶
SetClock "[s]ets the current timestamp of kvmclock to the value specified in its parameter." This ioctl is available if CheckExtension(CapAdjustClock) returns a non-zero value.
func SetIdentityMapAddr ¶
SetIdentityMapAddr "defines the physical address of a one-page region in the guest physical address space. The region must be within the first 4GB of the guest physical address space and must not conflict with any memory slot or any mmio address. The guest may malfunction if it accesses this memory region."
"Setting the address to 0 will result in resetting the address to its default (0xfffbc000)."
"This ioctl is required on Intel-based hosts. This is needed on Intel hardware because of a quirk in the virtualization implementation (see the internals documentation when it pops into existence)."
SetIdentityMapAddr fails if it is called after CreateVCPU.
func SetTSSAddr ¶
SetTSSAddr "defines the physical address of a three-page region in the guest physical address space. The region must be within the first 4GB of the guest physical address space and must not conflict with any memory slot or any mmio address. The guest may malfunction if it accesses this memory region."
"This ioctl is required on Intel-based hosts. This is needed on Intel hardware because of a quirk in the virtualization implementation (see the internals documentation when it pops into existence)."
This ioctl is available if CheckExtension(CapSetTSSAddr) returns 1.
func SetUserMemoryRegion ¶
func SetUserMemoryRegion(vm *VM, region *UserspaceMemoryRegion) error
SetUserMemoryRegion "allows the user to create, modify or delete a guest physical memory slot." This ioctl is available if CheckExtension(CapUserMemory) returns 1.
Types ¶
type CPUIDEntry2 ¶
type CPUIDEntry2 struct { Function uint32 Index uint32 Flags uint32 EAX uint32 EBX uint32 ECX uint32 EDX uint32 // contains filtered or unexported fields }
CPUIDEntry has the same layout as the C struct kvm_cpuid_entry2.
func GetSupportedCPUID ¶
func GetSupportedCPUID(sys *os.File) ([]CPUIDEntry2, error)
GetSupportedCPUID "returns x86 cpuid features which are supported by both the hardware and kvm in its default configuration. Userspace can use the information returned by this ioctl to construct cpuid information (for KVM_SET_CPUID2) that is consistent with hardware, kernel, and userspace capabilities, and with user requirements (for example, the user may wish to constrain cpuid to emulate older hardware, or for feature consistency across a cluster)."
See 4.46 KVM_GET_SUPPORTED_CPUID in kvm/api.txt for more.
This ioctl is available if CheckExtension(CapExtCPUID) returns 1.
type Cap ¶
type Cap int
Cap is a KVM_CHECK_EXTENSION identifier.
type FPU ¶
type FPU struct { FPR [8][16]byte FCW uint16 FSW uint16 FTWX uint8 LastOpcode uint16 LastIP uint64 LastDP uint64 XMM [16][16]byte MXCSR uint32 // contains filtered or unexported fields }
FPU holds a VCPU's floating-point state. It has the same layout as the C struct kvm_fpu.
type IOExitData ¶
IOExitData is the result of a KVM_EXIT_IO vmexit. It has the same layout as the "io" member of the union of vmexit data in struct kvm_run.
type IRQFDConfig ¶
type IRQFDConfig struct { Fd uint32 GSI uint32 Flags uint32 ResampleFD uint32 // contains filtered or unexported fields }
IRQFDConfig has the same layout as struct kvm_irqfd.
type MMIOExitData ¶
type MMIOExitData struct { PhysAddr uint64 Data [8]uint8 Len uint32 IsWrite bool // contains filtered or unexported fields }
MMIOExitData is the result of a KVM_EXIT_MMIO vmexit. It has the same layout as the "mmio" member of the union of vmexit data in struct kvm_run.
type MSREntry ¶
MSREntry has the same layout as the C struct kvm_msr_entry.
func GetMSRs ¶
GetMSRs reads model-specific registers from the VCPU. The given indices should come from GetMSRIndexList. If CheckExtension(CapSetMSRFeatures) returns 1, GetMSRs can also read the values of MSR-based features that are available from the system. In this case, the given indices should come from GetMSRFeatureIndexList.
type PITConfig ¶
type PITConfig struct { Flags uint32 // contains filtered or unexported fields }
PITConfig has the same layout as the C struct kvm_pit_config.
type Regs ¶
type Regs struct {
RAX, RBX, RCX, RDX uint64
RSI, RDI, RSP, RBP uint64
R8, R9, R10, R11 uint64
R12, R13, R14, R15 uint64
RIP, RFlags uint64
}
Regs holds a VCPU's general-purpose registers. It has the same layout as the C struct kvm_regs.
type Segment ¶
type Segment struct { Base uint64 Limit uint32 Selector uint16 Type uint8 Present, DPL, DB, S, L, G, Avl uint8 Unusable uint8 // contains filtered or unexported fields }
Segment has the same layout as the C struct kvm_segment.
type Sregs ¶
type Sregs struct {
CS, DS, ES, FS, GS, SS Segment
TR, LDT Segment
GDT, IDT Dtable
CR0, CR2, CR3, CR4, CR8 uint64
EFER uint64
APICBase uint64
InterruptBitmap [((nrInterrupts + 63) / 64)]uint64
}
Sregs holds a VCPU's special registers. It has the same layout as the C struct kvm_sregs.
type UserspaceMemoryRegion ¶
type UserspaceMemoryRegion struct { Slot uint32 Flags uint32 GuestPhysAddr uint64 MemorySize uint64 UserspaceAddr uint64 }
UserspaceMemoryRegion has the same layout as the C struct kvm_userspace_memory_region.
type VCPUState ¶
type VCPUState struct { ImmediateExit uint8 // in ExitReason Exit // contains filtered or unexported fields }
VCPUState has roughly the same layout as struct kvm_run.
func (*VCPUState) IOExitData ¶
func (s *VCPUState) IOExitData() *IOExitData
IOExitData returns data describing the present KVM_EXIT_IO vmexit. The result is undefined (but bad) if the exit reason is not KVM_EXIT_IO.
func (*VCPUState) MMIOExitData ¶
func (s *VCPUState) MMIOExitData() *MMIOExitData
MMIOExitData returns data describing the present KVM_EXIT_MMIO vmexit. The result is undefined (but bad) if the exit reason is not KVM_EXIT_MMIO.