qmp

package
v7.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 1, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrMonitorBadConsole = errors.New("Requested console couldn't be found")

ErrMonitorBadConsole is returned when the requested console doesn't exist.

View Source
var ErrMonitorDisconnect = errors.New("Monitor is disconnected")

ErrMonitorDisconnect is returned when interacting with a disconnected Monitor.

View Source
var ErrNotARingbuf = errors.New("Requested device isn't a ring buffer")

ErrNotARingbuf is returned when the requested device isn't a ring buffer.

View Source
var EventAgentStarted = "AGENT-STARTED"

EventAgentStarted is the event sent once the agent has started.

View Source
var EventAgentStopped = "AGENT-STOPPED"

EventAgentStopped is the event sent once the agent has stopped.

View Source
var EventBlockJobCompleted = "BLOCK_JOB_COMPLETED"

EventBlockJobCompleted is emitted when a block job has completed.

View Source
var EventBlockJobError = "BLOCK_JOB_ERROR"

EventBlockJobError is emitted when a block job has errored.

View Source
var EventDiskEjected = "DEVICE_TRAY_MOVED"

EventDiskEjected is used to indicate that a disk device was ejected by the guest.

View Source
var EventRTCChange = "RTC_CHANGE"

EventRTCChange is used to get RTC adjustment.

View Source
var EventVMReset = "RESET"

EventVMReset is the event sent when VM guest reboots.

View Source
var EventVMShutdown = "SHUTDOWN"

EventVMShutdown is the event sent when VM guest shuts down.

View Source
var EventVMShutdownReasonDisconnect = "disconnect"

EventVMShutdownReasonDisconnect is used as the reason when the shutdown event is triggered by a QMP disconnect.

View Source
var EventVMShutdownReasonGuestShutdown = "guest-shutdown"

EventVMShutdownReasonGuestShutdown is set when the guest cleanly shut down (e.g. ACPI powerdown honored).

View Source
var EventVMShutdownReasonQuit = "quit"

EventVMShutdownReasonQuit is set when QEMU exits as a result of the host issuing a QMP quit command.

View Source
var ExcludedCommands = []string{"ringbuf-read"}

ExcludedCommands is used to filter verbose commands from the QMP logs.

View Source
var RingbufSize = 16

RingbufSize is the size of the agent serial ringbuffer in bytes.

Functions

This section is empty.

Types

type AMDSEVCapabilities

type AMDSEVCapabilities struct {
	PDH             string `json:"pdh"`               // Platform Diffie-Hellman key (base64-encoded)
	CertChain       string `json:"cert-chain"`        // PDH certificate chain (base64-encoded)
	CPU0Id          string `json:"cpu0-id"`           // Unique ID of CPU0 (base64-encoded)
	CBitPos         int    `json:"cbitpos"`           // C-bit location in page table entry
	ReducedPhysBits int    `json:"reduced-phys-bits"` // Number of physical address bit reduction when SEV is enabled
}

AMDSEVCapabilities represents the SEV capabilities of QEMU.

type AddFdInfo

type AddFdInfo struct {
	ID int `json:"fdset-id"`
	FD int `json:"fd"`
}

AddFdInfo contains information about a file descriptor that was added to an fd set.

type BlockDeviceInfo

type BlockDeviceInfo struct {
	NodeName     string           `json:"node-name"`
	DirtyBitmaps []BlockDirtyInfo `json:"dirty-bitmaps"`
}

BlockDeviceInfo contains information about the backing device for a block device.

type BlockDirtyInfo

type BlockDirtyInfo struct {
	Name         string `json:"name"`
	Count        int    `json:"count"`
	Granularity  int    `json:"granularity"`
	Recording    bool   `json:"recording"`
	Busy         bool   `json:"busy"`
	Persistent   bool   `json:"persistent"`
	Inconsistent bool   `json:"inconsistent"`
}

BlockDirtyInfo contains dirty bitmap information.

type BlockExport

type BlockExport struct {
	NodeName string `json:"node-name"`
	Type     string `json:"type"`
}

BlockExport contains information about the exported block.

type BlockInfo

type BlockInfo struct {
	Device   string          `json:"device"`
	Inserted BlockDeviceInfo `json:"inserted"`
}

BlockInfo contains information about a virtual block device.

type BlockStats

type BlockStats struct {
	BytesWritten    int `json:"wr_bytes"`
	WritesCompleted int `json:"wr_operations"`
	BytesRead       int `json:"rd_bytes"`
	ReadsCompleted  int `json:"rd_operations"`
}

BlockStats represents block device stats.

type CPU

type CPU struct {
	Index    int    `json:"cpu-index,omitempty"`
	QOMPath  string `json:"qom-path,omitempty"`
	ThreadID int    `json:"thread-id,omitempty"`
	Target   string `json:"target,omitempty"`

	Props CPUInstanceProperties `json:"props"`
}

CPU contains information about a CPU.

type CPUInstanceProperties

type CPUInstanceProperties struct {
	NodeID    int `json:"node-id,omitempty"`
	SocketID  int `json:"socket-id,omitempty"`
	DieID     int `json:"die-id,omitempty"`
	ClusterID int `json:"cluster-id,omitempty"`
	CoreID    int `json:"core-id,omitempty"`
	ThreadID  int `json:"thread-id,omitempty"`
}

CPUInstanceProperties contains CPU instance properties.

type CPUModel

type CPUModel struct {
	Name  string         `json:"name"`
	Flags map[string]any `json:"props"`
}

CPUModel contains information about a CPU model.

type ChardevChangeInfo

type ChardevChangeInfo struct {
	Type   string   `json:"type"`
	File   *os.File `json:"file,omitempty"`
	FDName string   `json:"fdname,omitempty"`
}

ChardevChangeInfo contains information required to change the backend of a chardev.

type Event

type Event struct {
	Name string
	Data map[string]any
}

Event represents a QMP event.

type FdsetFdInfo

type FdsetFdInfo struct {
	FD     int    `json:"fd"`
	Opaque string `json:"opaque"`
}

FdsetFdInfo contains information about a file descriptor that belongs to an FD set.

type FdsetInfo

type FdsetInfo struct {
	ID  int           `json:"fdset-id"`
	FDs []FdsetFdInfo `json:"fds"`
}

FdsetInfo contains information about an FD set.

type HotpluggableCPU

type HotpluggableCPU struct {
	Type       string `json:"type"`
	VCPUsCount int    `json:"vcpus-count"`
	QOMPath    string `json:"qom-path,omitempty"`

	Props CPUInstanceProperties `json:"props"`
}

HotpluggableCPU contains information about a hotpluggable CPU.

type MemDev

type MemDev struct {
	ID        string `json:"id"`
	Size      int    `json:"size"`
	Merge     bool   `json:"merge"`
	Dump      bool   `json:"dump"`
	Prealloc  bool   `json:"prealloc"`
	Share     bool   `json:"share"`
	Reserve   bool   `json:"reserve"`
	HostNodes []int  `json:"host-nodes"`
}

MemDev contains information about a memory device.

type MemoryDevice

type MemoryDevice struct {
	Type string          `json:"type"`
	Data json.RawMessage `json:"data"`
}

MemoryDevice contains information about a memory device.

type MigrationStatus

type MigrationStatus struct {
	Status string `json:"status"`
	RAM    struct {
		Transferred             int64   `json:"transferred"`
		Remaining               int64   `json:"remaining"`
		Total                   int64   `json:"total"`
		Duplicate               int64   `json:"duplicate"`
		Normal                  int64   `json:"normal"`
		NormalBytes             int64   `json:"normal-bytes"`
		DirtyPagesRate          int64   `json:"diry-pages-rate"`
		MBps                    float64 `json:"mbps"`
		DirtySyncCount          int64   `json:"diry-sync-count"`
		PostcopyRequests        int64   `json:"postcopy-requests"`
		PageSize                int64   `json:"page-size"`
		MultiFDBytes            int64   `json:"multifd-bytes"`
		PagesPerSecond          int64   `json:"pages-per-second"`
		PrecopyBytes            int64   `json:"precopy-bytes"`
		DowntimeBytes           int64   `json:"downtime-bytes"`
		PostcopyBytes           int64   `json:"postcopy-bytes"`
		DirtySyncMissedZeroCopy int64   `json:"diry-sync-missed-zero-copy"`
	} `json:"ram"`
	TotalTime                      int64   `json:"total-time"`
	DownTime                       int64   `json:"down-time"`
	ExpectedDowntime               int64   `json:"expected-downtime"`
	SetupTime                      int64   `json:"setup-time"`
	CPUThrottlePercentage          int64   `json:"cpu-throttle-percentage"`
	PostcopyBlocktime              int64   `json:"postcopy-blocktime"`
	PostcopyVCPUBlocktime          []int64 `json:"postcopy-vcpu-blocktime"`
	DirtyLimitThrottleTimePerRound int64   `json:"dirty-limit-throttle-time-per-round"`
	DirtyLimitRingFullTime         int64   `json:"dirty-limit-ring-full-time"`
}

MigrationStatus contains information about the ongoing migration.

type Monitor

type Monitor struct {
	// contains filtered or unexported fields
}

Monitor represents a QMP monitor.

func Connect

func Connect(path string, serialCharDev string, eventHandler func(name string, data map[string]any), logFile string, detachDisk func(name string) error) (*Monitor, error)

Connect creates or retrieves an existing QMP monitor for the path.

func (*Monitor) AddBlockDevice

func (m *Monitor) AddBlockDevice(blockDev map[string]any, device map[string]any, usb bool) error

AddBlockDevice adds a block device.

func (*Monitor) AddCharDevice

func (m *Monitor) AddCharDevice(device map[string]any) error

AddCharDevice adds a new character device.

func (*Monitor) AddDevice

func (m *Monitor) AddDevice(device map[string]any) error

AddDevice adds a new device.

func (*Monitor) AddDirtyBitmap

func (m *Monitor) AddDirtyBitmap(deviceNames []string, bitmapName string, granularity int, persistent bool, disabled bool) error

AddDirtyBitmap creates a dirty bitmap for a block device.

func (*Monitor) AddNIC

func (m *Monitor) AddNIC(netDev map[string]any, device map[string]any, connected bool) error

AddNIC adds a NIC device.

func (*Monitor) AddObject

func (m *Monitor) AddObject(args map[string]any) error

AddObject adds a new object.

func (*Monitor) AddSecret

func (m *Monitor) AddSecret(id string, secret string) error

AddSecret adds a secret object with the given ID and secret. This function won't return an error if the secret object already exists.

func (*Monitor) AgenStarted

func (m *Monitor) AgenStarted() bool

AgenStarted indicates whether an agent has been detected.

func (*Monitor) BlockCommit

func (m *Monitor) BlockCommit(deviceNodeName string, top string, base string) error

BlockCommit merges a snapshot device back into its parent device.

func (*Monitor) BlockDevMirror

func (m *Monitor) BlockDevMirror(deviceNodeName string, targetNodeName string) error

BlockDevMirror mirrors the top device to the target device.

func (*Monitor) BlockDevSnapshot

func (m *Monitor) BlockDevSnapshot(deviceNodeName string, snapshotNodeName string) error

BlockDevSnapshot creates a snapshot of a device using the specified snapshot device.

func (*Monitor) BlockJobCancel

func (m *Monitor) BlockJobCancel(deviceNodeName string) error

BlockJobCancel cancels an ongoing block job.

func (*Monitor) BlockJobComplete

func (m *Monitor) BlockJobComplete(deviceNodeName string) error

BlockJobComplete completes a block job that is in reader state.

func (*Monitor) ChangeBackingFile

func (m *Monitor) ChangeBackingFile(deviceNodeName string, imageNodeName string, backingFilename string) error

ChangeBackingFile changes backing file name for node.

func (*Monitor) ChardevChange

func (m *Monitor) ChardevChange(device string, info ChardevChangeInfo) error

ChardevChange changes the backend of a specified chardev. Currently supports the socket and ringbuf backends.

func (*Monitor) CheckPCIDevice

func (m *Monitor) CheckPCIDevice(deviceID string) (bool, error)

CheckPCIDevice checks if the deviceID exists as a bridged PCI device.

func (*Monitor) CleanupEventChannel

func (m *Monitor) CleanupEventChannel(deviceName string)

CleanupEventChannel removes the event channel associated with the given device.

func (*Monitor) CloseFile

func (m *Monitor) CloseFile(name string) error

CloseFile closes an existing file descriptor in the QMP fd table associated to name.

func (*Monitor) CreateEventChannel

func (m *Monitor) CreateEventChannel(deviceName string) (chan Event, error)

CreateEventChannel creates and registers a new event channel for the given device.

func (*Monitor) Disconnect

func (m *Monitor) Disconnect()

Disconnect forces a disconnection from QEMU.

func (*Monitor) DumpGuestMemory

func (m *Monitor) DumpGuestMemory(path string, format string) error

DumpGuestMemory dumps guest memory to a file.

func (*Monitor) ExpectReset

func (m *Monitor) ExpectReset()

ExpectReset marks the monitor as expecting a single RESET event triggered by us (for example the deliberate system_reset issued during VM startup). The next RESET event observed by the handler can be consumed via HandleReset.

func (*Monitor) GetBlockStats

func (m *Monitor) GetBlockStats() (map[string]BlockStats, error)

GetBlockStats return block device stats.

func (*Monitor) GetCPUs

func (m *Monitor) GetCPUs() ([]int, error)

GetCPUs fetches the vCPU information for pinning.

func (*Monitor) GetDimmDevices

func (m *Monitor) GetDimmDevices() ([]PCDimmDevice, error)

GetDimmDevices returns a list of memory devices of type pc-dimm.

func (*Monitor) GetMemdev

func (m *Monitor) GetMemdev() ([]MemDev, error)

GetMemdev retrieves memory devices by executing the query-memdev QMP command.

func (*Monitor) GetMemoryBalloonSizeBytes

func (m *Monitor) GetMemoryBalloonSizeBytes() (int64, error)

GetMemoryBalloonSizeBytes returns effective size of the memory in bytes (considering the current balloon size).

func (*Monitor) GetMemoryDevices

func (m *Monitor) GetMemoryDevices() ([]MemoryDevice, error)

GetMemoryDevices retrieves memory devices by executing the query-memory-devices QMP command.

func (*Monitor) GetMemorySizeBytes

func (m *Monitor) GetMemorySizeBytes() (int64, error)

GetMemorySizeBytes returns the current size of the base memory in bytes.

func (*Monitor) HandleReset

func (m *Monitor) HandleReset() bool

HandleReset returns true and clears the flag if a deliberate reset was previously announced via ExpectReset. It returns false otherwise.

func (*Monitor) IncreaseID

func (m *Monitor) IncreaseID() uint32

IncreaseID returns on auto increment uint32 id.

func (*Monitor) IsInitialized

func (m *Monitor) IsInitialized() bool

IsInitialized reports whether the monitor believes the VM has been fully initialized.

func (*Monitor) MachineDefinition

func (m *Monitor) MachineDefinition() (string, error)

MachineDefinition returns the current QEMU machine definition name.

func (*Monitor) MemoryConfiguration

func (m *Monitor) MemoryConfiguration() (int64, int64, int64, error)

MemoryConfiguration returns the current QEMU machine memory configuration (current, max, slots).

func (*Monitor) Migrate

func (m *Monitor) Migrate(name string) error

Migrate starts a migration stream.

func (*Monitor) MigrateContinue

func (m *Monitor) MigrateContinue(fromState string) error

MigrateContinue continues a migration stream.

func (*Monitor) MigrateIncoming

func (m *Monitor) MigrateIncoming(ctx context.Context, name string) error

MigrateIncoming starts the receiver of a migration stream.

func (*Monitor) MigrateSetCapabilities

func (m *Monitor) MigrateSetCapabilities(caps map[string]bool) error

MigrateSetCapabilities sets the capabilities used during migration.

func (*Monitor) MigrateSetParameters

func (m *Monitor) MigrateSetParameters(parameters map[string]any) error

MigrateSetParameters sets the parameters used during migration.

func (*Monitor) MigrateWait

func (m *Monitor) MigrateWait(ctx context.Context, state string) error

MigrateWait waits until migration job reaches the specified status. Returns nil if the migraton job reaches the specified status or an error if the migration job is in the failed status.

func (*Monitor) NBDBlockExportAdd

func (m *Monitor) NBDBlockExportAdd(deviceNodeName string, writable bool, bitmapNames []string) error

NBDBlockExportAdd exports a writable device via the NBD server.

func (*Monitor) NBDServerStart

func (m *Monitor) NBDServerStart() (net.Conn, error)

NBDServerStart starts internal NBD server and returns a connection to it.

func (*Monitor) NBDServerStop

func (m *Monitor) NBDServerStop() error

NBDServerStop stops the internal NBD server.

func (*Monitor) NBDUnixServerStart

func (m *Monitor) NBDUnixServerStart(path string) error

NBDUnixServerStart starts an internal NBD server listening on the specified Unix socket.

func (*Monitor) Pause

func (m *Monitor) Pause() error

Pause tells QEMU to temporarily stop the emulation.

func (*Monitor) Powerdown

func (m *Monitor) Powerdown() error

Powerdown tells the VM to gracefully shutdown.

func (*Monitor) PushEvent

func (m *Monitor) PushEvent(event string, data map[string]any)

PushEvent publishes an event to the registered channel for the given device.

func (*Monitor) Query9pDevice

func (m *Monitor) Query9pDevice() error

Query9pDevice checks whether virtio-9p-pci support is available in QEMU.

func (*Monitor) QueryBlock

func (m *Monitor) QueryBlock() ([]BlockInfo, error)

QueryBlock returns a list of all virtual block devices.

func (*Monitor) QueryBlockExports

func (m *Monitor) QueryBlockExports() ([]BlockExport, error)

QueryBlockExports returns exported blocks.

func (*Monitor) QueryCPUModel

func (m *Monitor) QueryCPUModel(model string) (*CPUModel, error)

QueryCPUModel returns a CPUModel for the specified model name.

func (*Monitor) QueryCPUs

func (m *Monitor) QueryCPUs() ([]CPU, error)

QueryCPUs returns a list of CPUs.

func (*Monitor) QueryHotpluggableCPUs

func (m *Monitor) QueryHotpluggableCPUs() ([]HotpluggableCPU, error)

QueryHotpluggableCPUs returns a list of hotpluggable CPUs.

func (*Monitor) QueryMigrate

func (m *Monitor) QueryMigrate() (*MigrationStatus, error)

QueryMigrate gets the current migration status.

func (*Monitor) QueryNBDBlockExports

func (m *Monitor) QueryNBDBlockExports() ([]BlockExport, error)

QueryNBDBlockExports returns exported blocks of type 'nbd'.

func (*Monitor) QueryNamedBlockNodes

func (m *Monitor) QueryNamedBlockNodes() ([]string, error)

QueryNamedBlockNodes returns block nodes names.

func (*Monitor) QueryPCI

func (m *Monitor) QueryPCI() ([]PCIDevice, error)

QueryPCI returns info about PCI devices.

func (*Monitor) QuerySpice

func (m *Monitor) QuerySpice() error

QuerySpice checks whether SPICE support is available in QEMU.

func (*Monitor) QueryVirtioSoundDevice

func (m *Monitor) QueryVirtioSoundDevice() error

QueryVirtioSoundDevice checks whether virtio-sound-pci support is available in QEMU.

func (*Monitor) Quit

func (m *Monitor) Quit() error

Quit tells QEMU to exit immediately.

func (*Monitor) RemoveBlockDevice

func (m *Monitor) RemoveBlockDevice(blockDevName string) error

RemoveBlockDevice removes a block device.

func (*Monitor) RemoveCharDevice

func (m *Monitor) RemoveCharDevice(deviceID string) error

RemoveCharDevice removes a character device.

func (*Monitor) RemoveDevice

func (m *Monitor) RemoveDevice(deviceID string) error

RemoveDevice removes a device.

func (*Monitor) RemoveDirtyBitmap

func (m *Monitor) RemoveDirtyBitmap(deviceName string, bitmapName string) error

RemoveDirtyBitmap removes a dirty bitmap for a block device.

func (*Monitor) RemoveFDFromFDSet

func (m *Monitor) RemoveFDFromFDSet(name string) error

RemoveFDFromFDSet removes an FD with the given name from an FD set.

func (*Monitor) RemoveNIC

func (m *Monitor) RemoveNIC(netDevID string) error

RemoveNIC removes a NIC device.

func (*Monitor) Reset

func (m *Monitor) Reset() error

Reset VM.

func (*Monitor) RingbufRead

func (m *Monitor) RingbufRead(device string) (string, error)

RingbufRead returns the complete contents of the specified ring buffer.

func (*Monitor) Run

func (m *Monitor) Run(cmd string, args any, resp any) error

run executes a command.

func (*Monitor) RunJSON

func (m *Monitor) RunJSON(request []byte, resp any, logCommand bool, id uint32) error

RunJSON executes a JSON-formatted command.

func (*Monitor) RunTransaction

func (m *Monitor) RunTransaction(actions []TransactionAction) error

RunTransaction executes a series of commands as a single transaction.

func (*Monitor) SEVCapabilities

func (m *Monitor) SEVCapabilities() (AMDSEVCapabilities, error)

SEVCapabilities is used to get the SEV capabilities, and is supported on AMD X86 platforms only.

func (*Monitor) Screendump

func (m *Monitor) Screendump(filename string) error

Screendump takes a screenshot of the current VGA console. The screendump is stored to the filename provided as argument.

func (*Monitor) SendFile

func (m *Monitor) SendFile(name string, file *os.File) error

SendFile adds a new file descriptor to the QMP fd table associated to name.

func (*Monitor) SendFileWithFDSet

func (m *Monitor) SendFileWithFDSet(name string, file *os.File, readonly bool) (*AddFdInfo, error)

SendFileWithFDSet adds a new file descriptor to an FD set.

func (*Monitor) SetAction

func (m *Monitor) SetAction(actions map[string]string) error

SetAction sets the actions the VM will take for certain scenarios.

func (*Monitor) SetBlockThrottle

func (m *Monitor) SetBlockThrottle(id string, bytesRead int, bytesWrite int, iopsRead int, iopsWrite int) error

SetBlockThrottle applies an I/O limit on a disk.

func (*Monitor) SetInitialized

func (m *Monitor) SetInitialized(enable bool)

SetInitialized enables or disables the on disconnect event.

func (*Monitor) SetMemoryBalloonSizeBytes

func (m *Monitor) SetMemoryBalloonSizeBytes(sizeBytes int64) error

SetMemoryBalloonSizeBytes sets the size of the memory in bytes (which will resize the balloon as needed).

func (m *Monitor) SetNICLink(id string, connected bool) error

SetNICLink sets the link status of the given device.

func (*Monitor) Start

func (m *Monitor) Start() error

Start tells QEMU to start the emulation.

func (*Monitor) Status

func (m *Monitor) Status() (string, error)

Status returns the current VM status.

func (*Monitor) UpdateBlockSize

func (m *Monitor) UpdateBlockSize(id string, size int64) error

UpdateBlockSize updates the size of a disk.

func (*Monitor) Wait

func (m *Monitor) Wait() (chan struct{}, error)

Wait returns a channel that will be closed on disconnection.

type PCDimmDevice

type PCDimmDevice struct {
	ID           string `json:"id"`
	Addr         uint64 `json:"addr"`
	Slot         int    `json:"slot"`
	Node         int    `json:"node"`
	Memdev       string `json:"memdev"`
	Hotpluggable bool   `json:"hotpluggable"`
	Hotplugged   bool   `json:"hotplugged"`
}

PCDimmDevice contains information about a memory device of type pc-dimm.

type PCIBridge

type PCIBridge struct {
	Devices []PCIDevice `json:"devices"`
}

PCIBridge represents a PCI bridge.

type PCIClassInfo

type PCIClassInfo struct {
	Class       int    `json:"class"`
	Description string `json:"desc"`
}

PCIClassInfo info about a device's class.

type PCIDevice

type PCIDevice struct {
	DevID    string       `json:"qdev_id"`
	Bus      int          `json:"bus"`
	Slot     int          `json:"slot"`
	Function int          `json:"function"`
	Devices  []PCIDevice  `json:"devices"`
	Class    PCIClassInfo `json:"class_info"`
	Bridge   PCIBridge    `json:"pci_bridge"`
}

PCIDevice represents a PCI device.

type TransactionAction

type TransactionAction struct {
	Type string         `json:"type"`
	Data map[string]any `json:"data"`
}

TransactionAction represents a single action within a QMP transaction.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL