blockdev

package
v0.0.0-...-ede35a2 Latest Latest
Warning

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

 Go to latest Published: Jul 27, 2023 License: MIT Imports: 3 Imported by: 0

README

The QEMU block layer and the node graph have been described in a series of FOSDEM presentations:

These presentations are some of the best overview material available for how the QEMU block layer works. Many thanks to Red Hat, the presenters in each video, the FOSDEM staff that preserved the video, and everyone that worked on the QEMU block layer redesign.

Documentation

Overview

Package blockdev articulates the QEMU block layer.

The block layer in QEMU is formulated as a node graph that describes the bidirectional flow of data to and from underlying storage. Each node in the graph processes I/O requests from the host in some way.

Example 
package main

import (
	"fmt"

	"github.com/gentlemanautomaton/machina/qemu/qhost/blockdev"
)

func main() {
	// Create a node graph
	var graph blockdev.Graph

	// Add a guest OS file protocol node to the graph
	os := blockdev.NodeName("guest-os")
	osFile, err := blockdev.File{
		Name:         os.Child("file"),
		Path:         blockdev.FilePath("~/guest-os.raw"),
		Discard:      true,
		DetectZeroes: blockdev.DetectZeroesUnmap,
	}.Connect(&graph)
	if err != nil {
		panic(err)
	}

	// Add a guest OS raw format node to the graph
	_, err = blockdev.Raw{Name: os}.Connect(osFile)
	if err != nil {
		panic(err)
	}

	// Add a read-only guest data file protocol node to the graph
	data := blockdev.NodeName("guest-data")
	dataFile, err := blockdev.File{
		Name:     data.Child("file"),
		Path:     blockdev.FilePath("~/guest-data.raw"),
		ReadOnly: true,
	}.Connect(&graph)
	if err != nil {
		panic(err)
	}

	// Add a guest OS raw format node to the graph
	_, err = blockdev.Raw{Name: data}.Connect(dataFile)
	if err != nil {
		panic(err)
	}

	// Print the node graph options
	for _, option := range graph.Options() {
		fmt.Println(option.String())
	}

}

Output:

-blockdev driver=file,node-name=guest-os-file,discard=unmap,detect-zeroes=unmap,filename=~/guest-os.raw
-blockdev driver=raw,node-name=guest-os,file=guest-os-file
-blockdev driver=file,node-name=guest-data-file,read-only=on,filename=~/guest-data.raw
-blockdev driver=raw,node-name=guest-data,file=guest-data-file

Index

Examples

Constants

View Source 
const (
	DetectZeroesOn    = DetectZeroes("on")
	DetectZeroesOff   = DetectZeroes("off")
	DetectZeroesUnmap = DetectZeroes("unmap")
)

Drive discard options.

Variables

View Source 
var (
	// ErrNodeExists is returned when an attempt is made to attach a node
	// with a duplicate node name to a graph.
	ErrNodeExists = errors.New("a node with the given node name already exists")

	// ErrGraphMismatch is returned when an attempt is made to attach a node
	// to a graph that is not associated with that graph.
	ErrGraphMismatch = errors.New("the node must be associated with the graph before it can be attached")
)

Functions

This section is empty.

Types

type Cache 

type Cache struct {
	Direct  bool
	NoFlush bool
}

Cache defines I/O caching behavior for a node.

type DetectZeroes 

type DetectZeroes string

DetectZeroes specifies zero-detection behavior for a node.

type File 

type File struct {
	Name         NodeName
	Path         FilePath
	ReadOnly     bool
	Cache        Cache
	Discard      bool
	DetectZeroes DetectZeroes
	AIO          FileAIO
	Locking      FileLockMode
}

File holds configuration for a file protocol node.

func (File) Connect 

func (f File) Connect(graph NodeGraph) (FileNode, error)

Connect creates a new file protocol node with the given options and attaches it to the node graph.

The returned file protocol node is immutable and can safely be copied by value.

An error is returned if the node cannot be attached to the node graph or the file configuration is invalid.

type FileAIO 

type FileAIO string

FileAIO identifies the asynchronous I/O mode for a file.

type FileLockMode 

type FileLockMode string

FileLockMode identifies the file locking mode for a file.

type FileNode 

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

FileNode is a file protocol node in a block device node graph.

It implements the Protocol interface.

func (FileNode) Driver 

func (f FileNode) Driver() ProtocolDriver

Driver returns the name of the file protocol driver, file.

func (FileNode) Graph 

func (f FileNode) Graph() NodeGraph

Graph returns the node graph the file protocol node belongs to.

func (FileNode) Name 

func (f FileNode) Name() NodeName

Name returns the node name that uniquely identifies the file protocol node within its node graph.

func (FileNode) Properties 

func (f FileNode) Properties() Properties

Properties returns the properties of the file protocol node.

type FilePath 

type FilePath string

FilePath is the path of a file.

type Filter 

type Filter interface {
	Node
	Driver() ProtocolDriver
}

Filter is a filter node in a block graph.

type FilterDriver 

type FilterDriver string

FilterDriver identifies a QEMU block driver used by a filter node.

type Format 

type Format interface {
	Node
	Driver() FormatDriver
}

Format is a format node in a block graph.

type FormatDriver 

type FormatDriver string

FormatDriver identifies a QEMU block driver used by a format node.

type Graph 

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

Graph is a simple implementation of a NodeGraph.

The zero-value of a graph is ready for use, but it must not be copied by value once a node has been added to it.

func (*Graph) Add 

func (g *Graph) Add(node Node) error

Add adds the given node to the node graph.

It returns ErrNodeExists if a node with the same node name already exists in the graph.

func (*Graph) Find 

func (g *Graph) Find(name NodeName) Node

Find returns the node with the given node name in the graph.

It returns nil if a node with the given name is not present within the graph.

func (*Graph) Nodes 

func (g *Graph) Nodes() []Node

Nodes returns the set of all nodes present within the graph.

func (*Graph) Options 

func (g *Graph) Options() qemu.Options

Options returns a set of QEMU virtual machine options for defining the blockdevs that make up the node graph.

type Node 

type Node interface {
	Graph() NodeGraph
	Name() NodeName
	Properties() Properties
}

Node is a node in a QEMU block device graph.

type NodeGraph 

type NodeGraph interface {
	Add(node Node) error
	Find(name NodeName) Node
	Nodes() []Node
}

NodeGraph describes a block device node graph.

type NodeName 

type NodeName string

NodeName uniquely identifies a node in QEMU's block device layer.

func (NodeName) Child 

func (name NodeName) Child(sub string) NodeName

Child returns a child node name derived from name.

type Properties 

type Properties = qemu.Parameters

Properties hold a set of QEMU block device properties.

type Property 

type Property = qemu.Parameter

Property describes a QEMU block device property.

type Protocol 

type Protocol interface {
	Node
	Driver() ProtocolDriver
}

Protocol is a protocol node in a block graph.

type ProtocolDriver 

type ProtocolDriver string

ProtocolDriver identifies a QEMU block driver used by a protocol node.

type Raw 

type Raw struct {
	Name         NodeName
	ReadOnly     bool
	Cache        Cache
	Discard      bool
	DetectZeroes DetectZeroes
}

Raw holds configuration for a raw format node.

func (Raw) Connect 

func (r Raw) Connect(source Protocol) (RawNode, error)

Connect creates a new raw format node with the given options and attaches it to the node graph of the source protocol node.

The returned raw format node is immutable and can safely be copied by value.

An error is returned if the node cannot be attached to the node graph or the format configuration is invalid.

type RawNode 

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

RawNode is a raw format node in a block device node graph.

func (RawNode) Driver 

func (r RawNode) Driver() FormatDriver

Driver returns the name of the raw format driver, raw.

func (RawNode) Graph 

func (r RawNode) Graph() NodeGraph

Graph returns the node graph the raw format node belongs to.

func (RawNode) Name 

func (r RawNode) Name() NodeName

Name returns the node name.

func (RawNode) Properties 

func (r RawNode) Properties() Properties

Properties returns the properties of the raw format node.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.