1 package vm 2 3 import ( 4 "context" 5 "errors" 6 "net" 7 8 "github.com/Microsoft/hcsshim/cmd/containerd-shim-runhcs-v1/stats" 9 ) 10 11 var ( 12 ErrNotSupported = errors.New("virtstack does not support the operation") 13 ErrAlreadySet = errors.New("field has already been set") 14 ErrUnsupportedGuestOS = errors.New("virtstack does not support the guest operating system") 15 ErrUnknownGuestOS = errors.New("unknown guest operating system supplied") 16 ) 17 18 const ( 19 HCS = "hcs" 20 RemoteVM = "remotevm" 21 ) 22 23 // UVM is an abstraction around a lightweight virtual machine. It houses core lifecycle methods such as Create 24 // Start, and Stop and also several optional nested interfaces that can be used to determine what the virtual machine 25 // supports and to configure these resources. 26 type UVM interface { 27 // ID will return a string identifier for the Utility VM. 28 ID() string 29 30 // Start will power on the Utility VM and put it into a running state. This will boot the guest OS and start all of the 31 // devices configured on the machine. 32 Start(ctx context.Context) error 33 34 // Stop will shutdown the Utility VM and place it into a terminated state. 35 Stop(ctx context.Context) error 36 37 // Pause will place the Utility VM into a paused state. The guest OS will be halted and any devices will have be in a 38 // a suspended state. Save can be used to snapshot the current state of the virtual machine, and Resume can be used to 39 // place the virtual machine back into a running state. 40 Pause(ctx context.Context) error 41 42 // Resume will put a previously paused Utility VM back into a running state. The guest OS will resume operation from the point 43 // in time it was paused and all devices should be un-suspended. 44 Resume(ctx context.Context) error 45 46 // Save will snapshot the state of the Utility VM at the point in time when the VM was paused. 47 Save(ctx context.Context) error 48 49 // Wait synchronously waits for the Utility VM to shutdown or terminate. A call to stop will trigger this 50 // to unblock. 51 Wait() error 52 53 // Stats returns statistics about the Utility VM. This includes things like assigned memory, available memory, 54 // processor runtime etc. 55 Stats(ctx context.Context) (*stats.VirtualMachineStatistics, error) 56 57 // Supported returns if the virt stack supports a given operation on a resource. 58 Supported(resource Resource, operation ResourceOperation) bool 59 60 // ExitError will return any error if the Utility VM exited unexpectedly, or if the Utility VM experienced an 61 // error after Wait returned, it will return the wait error. 62 ExitError() error 63 } 64 65 // Resource refers to the type of a resource on a Utility VM. 66 type Resource uint8 67 68 const ( 69 VPMem = iota 70 SCSI 71 Network 72 VSMB 73 PCI 74 Plan9 75 Memory 76 Processor 77 CPUGroup 78 ) 79 80 // Operation refers to the type of operation to perform on a given resource. 81 type ResourceOperation uint8 82 83 const ( 84 Add ResourceOperation = iota 85 Remove 86 Update 87 ) 88 89 // GuestOS signifies the guest operating system that a Utility VM will be running. 90 type GuestOS string 91 92 const ( 93 Windows GuestOS = "windows" 94 Linux GuestOS = "linux" 95 ) 96 97 // SCSIDiskType refers to the disk type of the scsi device. This is either a vhd, vhdx, or a physical disk. 98 type SCSIDiskType uint8 99 100 const ( 101 SCSIDiskTypeVHD1 SCSIDiskType = iota 102 SCSIDiskTypeVHDX 103 SCSIDiskTypePassThrough 104 ) 105 106 // SCSIManager manages adding and removing SCSI devices for a Utility VM. 107 type SCSIManager interface { 108 // AddSCSIController adds a SCSI controller to the Utility VM configuration document. 109 AddSCSIController(id uint32) error 110 // AddSCSIDisk adds a SCSI disk to the configuration document if in a precreated state, or hot adds a 111 // SCSI disk to the Utility VM if the VM is running. 112 AddSCSIDisk(ctx context.Context, controller uint32, lun uint32, path string, typ SCSIDiskType, readOnly bool) error 113 // RemoveSCSIDisk removes a SCSI disk from a Utility VM. 114 RemoveSCSIDisk(ctx context.Context, controller uint32, lun uint32, path string) error 115 } 116 117 // VPMemImageFormat refers to the image type of the vpmem block device. This is either a vhd or vhdx. 118 type VPMemImageFormat uint8 119 120 const ( 121 VPMemImageFormatVHD1 VPMemImageFormat = iota 122 VPMemImageFormatVHDX 123 ) 124 125 // VPMemManager manages adding and removing virtual persistent memory devices for a Utility VM. 126 type VPMemManager interface { 127 // AddVPMemController adds a new virtual pmem controller to the Utility VM. 128 // `maximumDevices` specifies how many vpmem devices will be present in the guest. 129 // `maximumSizeBytes` specifies the maximum size allowed for a vpmem device. 130 AddVPMemController(maximumDevices uint32, maximumSizeBytes uint64) error 131 // AddVPMemDevice adds a virtual pmem device to the Utility VM. 132 AddVPMemDevice(ctx context.Context, id uint32, path string, readOnly bool, imageFormat VPMemImageFormat) error 133 // RemoveVpmemDevice removes a virtual pmem device from the Utility VM. 134 RemoveVPMemDevice(ctx context.Context, id uint32, path string) error 135 } 136 137 // NetworkManager manages adding and removing network adapters for a Utility VM. 138 type NetworkManager interface { 139 // AddNIC adds a network adapter to the Utility VM. `nicID` should be a string representation of a 140 // Windows GUID. 141 AddNIC(ctx context.Context, nicID string, endpointID string, macAddr string) error 142 // RemoveNIC removes a network adapter from the Utility VM. `nicID` should be a string representation of a 143 // Windows GUID. 144 RemoveNIC(ctx context.Context, nicID string, endpointID string, macAddr string) error 145 } 146 147 // PCIManager manages assiging pci devices to a Utility VM. This is Windows specific at the moment. 148 type PCIManager interface { 149 // AddDevice adds the pci device identified by `instanceID` to the Utility VM. 150 // https://docs.microsoft.com/en-us/windows-hardware/drivers/install/instance-ids 151 AddDevice(ctx context.Context, instanceID string, vmbusGUID string) error 152 // RemoveDevice removes the pci device identified by `instanceID` from the Utility VM. 153 RemoveDevice(ctx context.Context, instanceID string, vmbusGUID string) error 154 } 155 156 // VMSocketType refers to which hypervisor socket transport type to use. 157 type VMSocketType uint8 158 159 const ( 160 HvSocket VMSocketType = iota 161 VSock 162 ) 163 164 // VMSocketManager manages configuration for a hypervisor socket transport. This includes sockets such as 165 // HvSocket and Vsock. 166 type VMSocketManager interface { 167 // VMSocketListen will create the requested vmsocket type and listen on the address specified by `connID`. 168 // For HvSocket the type expected is a GUID, for Vsock it's a port of type uint32. 169 VMSocketListen(ctx context.Context, socketType VMSocketType, connID interface{}) (net.Listener, error) 170 } 171 172 // VSMBOptions 173 type VSMBOptions struct { 174 ReadOnly bool 175 CacheIo bool 176 NoDirectMap bool 177 PseudoOplocks bool 178 ShareRead bool 179 TakeBackupPrivilege bool 180 NoOplocks bool 181 PseudoDirnotify bool 182 } 183 184 // VSMBManager manages adding virtual smb shares to a Utility VM. 185 type VSMBManager interface { 186 // AddVSMB adds a virtual smb share to a running Utility VM. 187 AddVSMB(ctx context.Context, hostPath string, name string, allowedFiles []string, options *VSMBOptions) error 188 // RemoveVSMB removes a virtual smb share from a running Utility VM. 189 RemoveVSMB(ctx context.Context, name string) error 190 } 191 192 // Plan9Manager manages adding plan 9 shares to a Utility VM. 193 type Plan9Manager interface { 194 // AddPlan9 adds a plan 9 share to a running Utility VM. 195 AddPlan9(ctx context.Context, path, name string, port int32, flags int32, allowed []string) error 196 // RemovePlan9 removes a plan 9 share from a running Utility VM. 197 RemovePlan9(ctx context.Context, name string, port int32) error 198 } 199