...

Source file src/github.com/Microsoft/hcsshim/internal/vm/vm.go

Documentation: github.com/Microsoft/hcsshim/internal/vm

     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  

View as plain text