vmimpl

Documentation

Overview

Package vmimpl provides an abstract test machine (VM, physical machine, etc) interface for the rest of the system. For convenience test machines are subsequently collectively called VMs. The package also provides various utility functions for VM implementations.

Index

• Variables
• func DiagnoseFreeBSD(w io.Writer) ([]byte, bool)
• func DiagnoseLinux(rep *report.Report, ssh func(args ...string) ([]byte, error)) (output []byte, wait, handled bool)
• func DiagnoseOpenBSD(w io.Writer) ([]byte, bool)
• func EscapeDoubleQuotes(inp string) string
• func MakeBootError(err error, output []byte) error
• func Multiplex(cmd *exec.Cmd, merger *OutputMerger, timeout time.Duration, ...) (<-chan []byte, <-chan error, error)
• func OpenAdbConsole(bin, dev string) (rc io.ReadCloser, err error)
• func OpenConsole(con string) (rc io.ReadCloser, err error)
• func OpenRemoteConsole(bin string, args ...string) (rc io.ReadCloser, err error)
• func OpenRemoteKernelLog(ip, console string) (rc io.ReadCloser, err error)
• func RandomPort() int
• func Register(typ string, desc Type)
• func SCPArgs(debug bool, sshKey string, port int, systemSSHCfg bool) []string
• func SSHArgs(debug bool, sshKey string, port int, systemSSHCfg bool) []string
• func SSHArgsForward(debug bool, sshKey string, port, forwardPort int, systemSSHCfg bool) []string
• func SleepInterruptible(d time.Duration) bool
• func UnusedTCPPort() int
• func WaitForSSH(debug bool, timeout time.Duration, addr, sshKey, sshUser, OS string, port int, ...) error
• type BootError
  • func (err BootError) BootError() (string, []byte)
  • func (err BootError) Error() string
• type CmdCloser
  • func (cc CmdCloser) Close() error
• type Env
• type Infoer
• type InfraError
  • func (err InfraError) Error() string
  • func (err InfraError) InfraError() (string, []byte)
• type Instance
• type MergerError
  • func (err MergerError) Error() string
• type MultiplexConfig
• type OutputMerger
  • func NewOutputMerger(tee io.Writer) *OutputMerger
  • func (merger *OutputMerger) Add(name string, r io.ReadCloser)
  • func (merger *OutputMerger) AddDecoder(name string, r io.ReadCloser, ...)
  • func (merger *OutputMerger) Wait()
• type Pool
• type Type

Variables

var (
	// Close to interrupt all pending operations in all VMs.
	Shutdown   = make(chan struct{})
	ErrTimeout = errors.New("timeout")

	Types = make(map[string]Type)
)

var WaitForOutputTimeout = 10 * time.Second

Functions

func DiagnoseFreeBSD

func DiagnoseFreeBSD(w io.Writer) ([]byte, bool)

DiagnoseFreeBSD sends the debug commands to the given writer which is expected to be connected to a panicked FreeBSD kernel. If kernel just hanged, we've lost connection or detected some non-panic error, console still shows normal login prompt.

func DiagnoseLinux

func DiagnoseLinux(rep *report.Report, ssh func(args ...string) ([]byte, error)) (output []byte, wait, handled bool)

DiagnoseLinux diagnoses some Linux kernel bugs over the provided ssh callback.

func DiagnoseOpenBSD

func DiagnoseOpenBSD(w io.Writer) ([]byte, bool)

DiagnoseOpenBSD sends the debug commands to the given writer which is expected to be connected to a paniced openbsd kernel. If kernel just hanged, we've lost connection or detected some non-panic error, console still shows normal login prompt.

func EscapeDoubleQuotes

func EscapeDoubleQuotes(inp string) string

Escapes double quotes(and nested double quote escapes). Ignores any other escapes. Reference: https://www.gnu.org/software/bash/manual/html_node/Double-Quotes.html

func MakeBootError

func MakeBootError(err error, output []byte) error

func Multiplex

func Multiplex(cmd *exec.Cmd, merger *OutputMerger, timeout time.Duration, config MultiplexConfig) (
	<-chan []byte, <-chan error, error)

func OpenAdbConsole

func OpenAdbConsole(bin, dev string) (rc io.ReadCloser, err error)

OpenAdbConsole provides fallback console output using 'adb shell dmesg -w'.

func OpenConsole

func OpenConsole(con string) (rc io.ReadCloser, err error)

Tested on Suzy-Q and BeagleBone.

func OpenRemoteConsole

func OpenRemoteConsole(bin string, args ...string) (rc io.ReadCloser, err error)

Open dmesg remotely.

func OpenRemoteKernelLog

func OpenRemoteKernelLog(ip, console string) (rc io.ReadCloser, err error)

OpenRemoteKernelLog accesses to the host where Android VM runs on, not Android VM itself. The host stores all kernel outputs of Android VM so in case of crashes nothing will be lost.

func RandomPort

func RandomPort() int

func Register

func Register(typ string, desc Type)

Register registers a new VM type within the package.

func SCPArgs

func SCPArgs(debug bool, sshKey string, port int, systemSSHCfg bool) []string

func SSHArgs

func SSHArgs(debug bool, sshKey string, port int, systemSSHCfg bool) []string

func SSHArgsForward

func SSHArgsForward(debug bool, sshKey string, port, forwardPort int, systemSSHCfg bool) []string

func SleepInterruptible

func SleepInterruptible(d time.Duration) bool

Sleep for d. If shutdown is in progress, return false prematurely.

func UnusedTCPPort

func UnusedTCPPort() int

func WaitForSSH

func WaitForSSH(debug bool, timeout time.Duration, addr, sshKey, sshUser, OS string, port int, stop chan error,
	systemSSHCfg bool) error

Types

type BootError

type BootError struct {
	Title  string
	Output []byte
}

BootError is returned by Pool.Create when VM does not boot. It should not be used for VMM intfrastructure errors, i.e. for problems not related to the tested kernel itself.

func (BootError) BootError

func (err BootError) BootError() (string, []byte)

func (BootError) Error

func (err BootError) Error() string

type CmdCloser

type CmdCloser struct {
	*exec.Cmd
}

func (CmdCloser) Close

func (cc CmdCloser) Close() error

type Env

type Env struct {
	// Unique name
	// Can be used for VM name collision resolution if several pools share global name space.
	Name      string
	OS        string // target OS
	Arch      string // target arch
	Workdir   string
	Image     string
	SSHKey    string
	SSHUser   string
	Timeouts  targets.Timeouts
	Snapshot  bool
	Debug     bool
	Config    []byte // json-serialized VM-type-specific config
	KernelSrc string
}

Env contains global constant parameters for a pool of VMs.

type Infoer

type Infoer interface {
	// MachineInfo returns additional info about the VM, e.g. VMM version/arguments.
	Info() ([]byte, error)
}

Infoer is an optional interface that can be implemented by Instance.

type InfraError

type InfraError struct {
	Title  string
	Output []byte
}

By default, all Pool.Create() errors are related to infrastructure problems. InfraError is to be used when we want to also attach output to the title.

func (InfraError) Error

func (err InfraError) Error() string

func (InfraError) InfraError

func (err InfraError) InfraError() (string, []byte)

type Instance

type Instance interface {
	// Copy copies a hostSrc file into VM and returns file name in VM.
	Copy(hostSrc string) (string, error)

	// Forward sets up forwarding from within VM to the given tcp
	// port on the host and returns the address to use in VM.
	Forward(port int) (string, error)

	// Run runs cmd inside of the VM (think of ssh cmd).
	// outc receives combined cmd and kernel console output.
	// errc receives either command Wait return error or vmimpl.ErrTimeout.
	// Command is terminated after timeout. Send on the stop chan can be used to terminate it earlier.
	Run(timeout time.Duration, stop <-chan bool, command string) (outc <-chan []byte, errc <-chan error, err error)

	// Diagnose retrieves additional debugging info from the VM
	// (e.g. by sending some sys-rq's or SIGABORT'ing a Go program).
	//
	// Optionally returns (some or all) of the info directly. If wait == true,
	// the caller must wait for the VM to output info directly to its log.
	//
	// rep describes the reason why Diagnose was called.
	Diagnose(rep *report.Report) (diagnosis []byte, wait bool)

	// Close stops and destroys the VM.
	io.Closer
}

Instance represents a single VM.

type MergerError

type MergerError struct {
	Name string
	R    io.ReadCloser
	Err  error
}

func (MergerError) Error

func (err MergerError) Error() string

type MultiplexConfig

type MultiplexConfig struct {
	Console     io.Closer
	Stop        <-chan bool
	Close       <-chan bool
	Debug       bool
	Scale       time.Duration
	IgnoreError func(err error) bool
}

type OutputMerger

type OutputMerger struct {
	Output chan []byte
	Err    chan error
	// contains filtered or unexported fields
}

func NewOutputMerger

func NewOutputMerger(tee io.Writer) *OutputMerger

func (*OutputMerger) Add

func (merger *OutputMerger) Add(name string, r io.ReadCloser)

func (*OutputMerger) AddDecoder

func (merger *OutputMerger) AddDecoder(name string, r io.ReadCloser,
	decoder func(data []byte) (start, size int, decoded []byte))

func (*OutputMerger) Wait

func (merger *OutputMerger) Wait()

type Pool

type Pool interface {
	// Count returns total number of VMs in the pool.
	Count() int

	// Create creates and boots a new VM instance.
	Create(workdir string, index int) (Instance, error)
}

Pool represents a set of test machines (VMs, physical devices, etc) of particular type.

type Type

type Type struct {
	Ctor ctorFunc
	// It's possible to create out-of-thin-air instances of this type.
	// Out-of-thin-air instances are used by syz-ci for image testing, patch testing, bisection, etc.
	Overcommit bool
	// Instances of this type can be preempted and lost connection as the result.
	// For preempted instances executor prints "SYZ-EXECUTOR: PREEMPTED" and then
	// the host understands that the lost connection was expected and is not a bug.
	Preemptible bool
}