initx

package
v0.0.1 Latest Latest
Warning

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

 Go to latest Published: Jan 11, 2026 License: GPL-3.0 Imports: 27 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddDefaultRoute 

func AddDefaultRoute(ifName string, gateway uint32, errLabel ir.Label, errVar ir.Var) ir.Fragment

func Build 

func Build(cfg BuilderConfig) (*ir.Program, error)

Build builds the init program using the RTG compiler. This is the main entry point for building init programs.

func BuildContainerInitProgram 

func BuildContainerInitProgram(cfg ContainerInitConfig) (*ir.Program, error)

BuildContainerInitProgram builds the container init program using RTG source code. The source code is embedded from container_init_source.go which is a valid Go file for IDE completion support. Most helpers are pure RTG, with complex ones injected at IR level.

func BuildFromRTG 

func BuildFromRTG(cfg BuilderConfig) (*ir.Program, error)

BuildFromRTG builds the init program from RTG source code. The source code is embedded from init_source.go which is a valid Go file for IDE completion support.

func Chroot 

func Chroot(path string, errLabel ir.Label, errVar ir.Var) ir.Fragment

func ClearRunResults 

func ClearRunResults(mailbox ir.Var) ir.Fragment

ClearRunResults zeros the run/start result slots so the host observes a clean state once the payload completes.

func ConfigureInterface 

func ConfigureInterface(ifName string, ip uint32, mask uint32, errLabel ir.Label, errVar ir.Var) ir.Fragment

func ConfigureLoopback 

func ConfigureLoopback(errLabel ir.Label, errVar ir.Var) ir.Fragment

ConfigureLoopback brings up the loopback interface (lo) with IP 127.0.0.1. This is needed for localhost networking (e.g., tests that use TCP on localhost).

func CreateFileFromStdin 

func CreateFileFromStdin(path string, length int64, mode uint32, errLabel ir.Label, errVar ir.Var) ir.Fragment

CreateFileFromStdin reads length bytes from stdin and writes them into path.

func Exec 

func Exec(path string, argv []string, envp []string, errLabel ir.Label, errVar ir.Var) ir.Fragment

func ForkExecWait 

func ForkExecWait(path string, argv []string, envp []string, errLabel ir.Label, errVar ir.Var) ir.Fragment

func GetInterfaceIndex 

func GetInterfaceIndex(ifName string, errLabel ir.Label, errVar ir.Var) ir.Fragment

GetInterfaceIndex gets the interface index for a given interface name using SIOCGIFINDEX. Returns the ifindex in errVar on success, negative errno on failure.

func LogKmsg 

func LogKmsg(msg string) ir.Block

func Mkdir 

func Mkdir(path string, mode uint32, errLabel ir.Label, errVar ir.Var) ir.Fragment

func Mount 

func Mount(
	source, target, fstype string,
	flags uintptr,
	data string,
	errLabel ir.Label,
	errVar ir.Var,
) ir.Fragment

func ReportRunResult 

func ReportRunResult(stage any, detail any) ir.Fragment

ReportRunResult stores the provided detail/stage pair into the mailbox so the host can decode the error reason.

func RequestSnapshot 

func RequestSnapshot() ir.Fragment

RequestSnapshot asks the host to capture a snapshot by writing the dedicated doorbell value to the mailbox.

func SendProfilingEvent 

func SendProfilingEvent(basePtr ir.Var, name string) ir.Fragment

func SetClock 

func SetClock(sec int64, nsec int64, errLabel ir.Label, errVar ir.Var) ir.Fragment

func SetHostname 

func SetHostname(name string, errLabel ir.Label, errVar ir.Var) ir.Fragment

func SetHosts 

func SetHosts(hostname string, errLabel ir.Label, errVar ir.Var) ir.Fragment

SetHosts sets up /etc/hosts with localhost entries.

func SetHostsOptional 

func SetHostsOptional(hostname string) ir.Fragment

SetHostsOptional is like SetHosts but doesn't fail if the file can't be written.

func SetResolvConf 

func SetResolvConf(dnsServer string, errLabel ir.Label, errVar ir.Var) ir.Fragment

func SetupProfiling 

func SetupProfiling(basePtr ir.Var, errLabel ir.Label, errVar ir.Var) ir.Fragment

func SyncClockFromPTP 

func SyncClockFromPTP(ptpPath string, errLabel ir.Label, errVar ir.Var) ir.Fragment

Types

type BuilderConfig 

type BuilderConfig struct {
	Arch hv.CpuArchitecture

	PreloadModules []kernel.Module
}

type ContainerInitConfig 

type ContainerInitConfig struct {
	Arch          hv.CpuArchitecture
	Cmd           []string
	Env           []string
	WorkDir       string
	EnableNetwork bool
	Exec          bool

	Hostname    string // default: tinyrange
	DNS         string // default: 10.42.0.1
	GuestIP     string // default: 10.42.0.2
	GuestMask   string // default: 255.255.255.0
	GuestIFName string // default: eth0
}

type ExitError 

type ExitError struct {
	Code int
}

ExitError represents a non-zero exit code returned from an initx payload.

func (*ExitError) Error 

func (e *ExitError) Error() string

Error implements the error interface.

type KernelLoader 

type KernelLoader interface {
	// GetKernel returns a reader for the kernel image, its size, and an error if any.
	GetKernel() (io.ReaderAt, int64, error)
}

type Module 

type Module struct {
	Name string
	Data []byte
}

type Option 

type Option interface {
	// contains filtered or unexported methods
}

func WithConsoleOutput 

func WithConsoleOutput(w io.Writer) Option

WithConsoleOutput redirects the VM console output (virtio-console) to w. If nil, the default (stderr) is used.

func WithDebugLogging 

func WithDebugLogging(enabled bool) Option

func WithDeviceTemplate 

func WithDeviceTemplate(dev hv.DeviceTemplate) Option

func WithDmesgLogging 

func WithDmesgLogging(enabled bool) Option

func WithFileFromBytes 

func WithFileFromBytes(guestPath string, data []byte, mode os.FileMode) Option

func WithGPUEnabled 

func WithGPUEnabled(enabled bool) Option

func WithStdin 

func WithStdin(r io.Reader) Option

type Session 

type Session struct {
	VM   *VirtualMachine
	Done <-chan error

	// Stop cancels the session and waits up to timeout for completion.
	Stop func(timeout time.Duration) error
	// Wait blocks until the session completes and returns the terminal error.
	Wait func() error
}

Session is a small orchestration handle for booting a VM and running a payload. It is intentionally UI-agnostic; callers own any window/terminal resources.

func StartSession 

func StartSession(parent context.Context, vm *VirtualMachine, prog *ir.Program, cfg SessionConfig) *Session

StartSession boots vm and then runs prog until completion or cancellation. It returns immediately with a handle; the boot+run work happens in a goroutine.

type SessionConfig 

type SessionConfig struct {
	// BootTimeout controls how long we wait for the initial boot program to run.
	// If zero, a default of 10 seconds is used.
	BootTimeout time.Duration

	// SkipBoot skips the boot phase. Use this when restoring from a snapshot.
	SkipBoot bool

	// OnBootComplete is called after boot completes successfully but before
	// the payload runs. Use this to capture a snapshot after boot.
	OnBootComplete func() error
}

type SnapshotCache 

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

SnapshotCache manages boot snapshots in a cache directory.

func NewSnapshotCache 

func NewSnapshotCache(cacheDir string, io SnapshotIO) *SnapshotCache

NewSnapshotCache creates a cache manager for the given directory.

func (*SnapshotCache) EnsureDir 

func (c *SnapshotCache) EnsureDir() error

EnsureDir creates the cache directory if it doesn't exist.

func (*SnapshotCache) GetSnapshotPath 

func (c *SnapshotCache) GetSnapshotPath(configHash hv.VMConfigHash) string

GetSnapshotPath returns the path to the snapshot file for a given config hash.

func (*SnapshotCache) HasValidSnapshot 

func (c *SnapshotCache) HasValidSnapshot(configHash hv.VMConfigHash, referenceTime time.Time) bool

HasValidSnapshot checks if a valid snapshot exists. Returns true if snapshot exists and is newer than referenceTime (typically kernel mod time).

func (*SnapshotCache) InvalidateAll 

func (c *SnapshotCache) InvalidateAll() error

InvalidateAll removes all cached snapshots.

func (*SnapshotCache) InvalidateCache 

func (c *SnapshotCache) InvalidateCache(configHash hv.VMConfigHash) error

InvalidateCache removes the cached snapshot for a config hash.

func (*SnapshotCache) LoadSnapshot 

func (c *SnapshotCache) LoadSnapshot(configHash hv.VMConfigHash) (hv.Snapshot, error)

LoadSnapshot loads a snapshot from the cache.

func (*SnapshotCache) SaveSnapshot 

func (c *SnapshotCache) SaveSnapshot(configHash hv.VMConfigHash, snap hv.Snapshot) error

SaveSnapshot saves a snapshot to the cache.

type SnapshotIO 

type SnapshotIO interface {
	SaveSnapshot(path string, snap hv.Snapshot) error
	LoadSnapshot(path string) (hv.Snapshot, error)
}

SnapshotIO provides platform-specific snapshot serialization. This interface allows the cache to work with different hypervisor backends.

func GetSnapshotIO 

func GetSnapshotIO() SnapshotIO

GetSnapshotIO returns the platform-specific snapshot IO implementation.

type VirtualMachine 

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

func NewVirtualMachine 

func NewVirtualMachine(
	h hv.Hypervisor,
	numCPUs int,
	memSizeMB uint64,
	kernelLoader kernel.Kernel,
	options ...Option,
) (*VirtualMachine, error)

func (*VirtualMachine) Architecture 

func (vm *VirtualMachine) Architecture() hv.CpuArchitecture

func (*VirtualMachine) Boot 

func (vm *VirtualMachine) Boot(ctx context.Context) error

Boot runs a minimal program to ensure the initx loop is running and devices are ready. This should be called before running the real payload program.

func (*VirtualMachine) CaptureSnapshot 

func (vm *VirtualMachine) CaptureSnapshot() (hv.Snapshot, error)

CaptureSnapshot captures a snapshot of the VM state.

func (*VirtualMachine) Close 

func (vm *VirtualMachine) Close() error

func (*VirtualMachine) DumpStackTrace 

func (vm *VirtualMachine) DumpStackTrace(vcpu hv.VirtualCPU) (int64, error)

func (*VirtualMachine) GPU 

func (vm *VirtualMachine) GPU() *virtio.GPU

GPU returns the virtio-gpu device if GPU is enabled, nil otherwise.

func (*VirtualMachine) HVVirtualMachine 

func (vm *VirtualMachine) HVVirtualMachine() hv.VirtualMachine

HVVirtualMachine returns the underlying hv.VirtualMachine for low-level operations.

func (*VirtualMachine) Keyboard 

func (vm *VirtualMachine) Keyboard() *virtio.Input

Keyboard returns the virtio-input keyboard device if GPU is enabled, nil otherwise.

func (*VirtualMachine) RestoreSnapshot 

func (vm *VirtualMachine) RestoreSnapshot(snap hv.Snapshot) error

RestoreSnapshot restores a VM from a snapshot.

func (*VirtualMachine) Run 

func (vm *VirtualMachine) Run(ctx context.Context, prog *ir.Program) error

func (*VirtualMachine) SetConsoleSize 

func (vm *VirtualMachine) SetConsoleSize(cols, rows int)

SetConsoleSize updates the virtio-console configuration so the guest can see the correct terminal size. This is best-effort (no-op if console is unavailable).

func (*VirtualMachine) Spawn 

func (vm *VirtualMachine) Spawn(ctx context.Context, path string, args ...string) error

Spawn executes path inside the guest using fork/exec, waiting for it to complete.

func (*VirtualMachine) StartStdinForwarding 

func (vm *VirtualMachine) StartStdinForwarding()

StartStdinForwarding activates stdin forwarding to the guest console. This should be called after the VM has booted and before the user command runs, to ensure stdin data is delivered to the user command rather than the init process.

func (*VirtualMachine) Tablet 

func (vm *VirtualMachine) Tablet() *virtio.Input

Tablet returns the virtio-input tablet device if GPU is enabled, nil otherwise.

func (*VirtualMachine) VirtualCPUCall 

func (vm *VirtualMachine) VirtualCPUCall(id int, f func(vcpu hv.VirtualCPU) error) error

func (*VirtualMachine) WriteFile 

func (vm *VirtualMachine) WriteFile(ctx context.Context, in io.Reader, size int64, guestPath string) error

WriteFile copies data from in into the guest at guestPath using a shared buffer handshake between host and guest.

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.