Help us shape the future of Go! Take the 2026 Go Developer Survey

kernel

package
v0.57.29 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Overview

Package kernel runs Linux programs compiled to WebAssembly. Its host functions implement the Linux syscalls and WASI imports those programs call: processes, signals, pipes, sockets, the console and pseudo-terminals, and a filesystem over an optional root. No Linux kernel runs; the Go host is the kernel.

Index

Constants

View Source
const (
	// SIGHUP reports a hangup of the controlling terminal.
	SIGHUP = 1

	// SIGINT interrupts the foreground process: ^C.
	SIGINT = 2

	// SIGQUIT quits the foreground process: ^\.
	SIGQUIT = 3

	// SIGABRT aborts a process.
	SIGABRT = 6

	// SIGKILL kills a process and cannot be caught.
	SIGKILL = 9

	// SIGPIPE reports a write to a pipe with no reader.
	SIGPIPE = 13

	// SIGALRM reports the expiry of ITIMER_REAL.
	SIGALRM = 14

	// SIGTERM asks a process to terminate.
	SIGTERM = 15

	// SIGCHLD reports a child that changed state.
	SIGCHLD = 17

	// SIGSTOP stops a process and cannot be caught.
	SIGSTOP = 19

	// SIGTSTP stops the foreground process from the terminal: ^Z.
	SIGTSTP = 20

	// SIGWINCH reports a terminal window size change.
	SIGWINCH = 28
)

Linux signal numbers (asm-generic).

View Source
const (
	// EPERM reports an operation not permitted.
	EPERM = 1

	// ENOENT reports a missing file or directory.
	ENOENT = 2

	// ESRCH reports a missing process.
	ESRCH = 3

	// EINTR reports a call interrupted by a signal.
	EINTR = 4

	// EIO reports an input or output failure.
	EIO = 5

	// ENXIO reports a device that does not exist, such as /dev/tty for a
	// process without a terminal.
	ENXIO = 6

	// ENOEXEC reports a file that is neither a program nor a script.
	ENOEXEC = 8

	// EBADF reports a descriptor that is not open.
	EBADF = 9

	// ECHILD reports that there is no child to wait for.
	ECHILD = 10

	// EAGAIN reports a resource that is not ready yet.
	EAGAIN = 11

	// ENOMEM reports exhausted memory.
	ENOMEM = 12

	// EACCES reports denied permission.
	EACCES = 13

	// EFAULT reports a bad guest address.
	EFAULT = 14

	// EBUSY reports a resource in use, such as a mounted directory.
	EBUSY = 16

	// EEXIST reports a file that already exists.
	EEXIST = 17

	// ENODEV reports a filesystem type the kernel lacks.
	ENODEV = 19

	// ENOTDIR reports a path component that is not a directory.
	ENOTDIR = 20

	// EISDIR reports a directory where a file is required.
	EISDIR = 21

	// EINVAL reports an invalid argument.
	EINVAL = 22

	// ENOTTY reports a descriptor that is not a terminal.
	ENOTTY = 25

	// ENOSPC reports exhausted space, such as every pseudo-terminal in use.
	ENOSPC = 28

	// ESPIPE reports a seek on a pipe.
	ESPIPE = 29

	// EMLINK reports too many links.
	EMLINK = 31

	// EPIPE reports a write to a pipe with no reader.
	EPIPE = 32

	// ERANGE reports a result that does not fit its buffer.
	ERANGE = 34

	// ENAMETOOLONG reports a name longer than its limit, such as a socket
	// path.
	ENAMETOOLONG = 36

	// ENOSYS reports a function the kernel does not implement.
	ENOSYS = 38

	// ENOTEMPTY reports a directory that is not empty.
	ENOTEMPTY = 39

	// ELOOP reports too many levels of symbolic links.
	ELOOP = 40

	// ENODATA reports a missing extended attribute.
	ENODATA = 61

	// ENOTSOCK reports a socket call on a descriptor that is not a socket.
	ENOTSOCK = 88

	// EMSGSIZE reports a message call with more iovecs than the kernel takes.
	EMSGSIZE = 90

	// ENOPROTOOPT reports a socket option the kernel lacks.
	ENOPROTOOPT = 92

	// EPROTONOSUPPORT reports a socket type or protocol the kernel lacks.
	EPROTONOSUPPORT = 93

	// EOPNOTSUPP reports an operation the file does not support.
	EOPNOTSUPP = 95

	// EAFNOSUPPORT reports an address family without sockets.
	EAFNOSUPPORT = 97

	// EADDRINUSE reports a socket address that is already bound.
	EADDRINUSE = 98

	// EISCONN reports a socket that is already connected.
	EISCONN = 106

	// ENOTCONN reports a socket that is not connected.
	ENOTCONN = 107

	// ECONNREFUSED reports a socket address with no listener.
	ECONNREFUSED = 111
)

Linux errno values. wasm32 guests share the asm-generic numbering.

Variables

View Source
var (
	// ErrNilConfig is returned by New for a nil configuration.
	ErrNilConfig = errors.New("config is nil")
	// ErrNoInit is returned by Boot when the init program is missing or
	// empty.
	ErrNoInit = errors.New("init program not found")
	// ErrNoStart is returned for a program that exports no _start function.
	ErrNoStart = errors.New("program has no _start export")
	// ErrReboot is returned by Boot when the system restarted through the
	// reboot call. The caller boots a new kernel.
	ErrReboot = errors.New("the system restarted")
)

Functions

func BusyboxApplets

func BusyboxApplets(wasm []byte) map[string][]byte

BusyboxApplets returns a VFS file map installing wasm at /bin/busybox and common applet paths. All entries point to the same binary; busybox determines its behavior from argv[0].

Types

type Config

type Config struct {
	// Stdout receives the console's output. It defaults to os.Stdout.
	Stdout io.Writer
	// Stderr receives the console's error output. It defaults to os.Stderr.
	Stderr io.Writer
	// Stdin is the console's input. It defaults to os.Stdin.
	Stdin io.Reader

	// DebugSyscalls logs every syscall to Stderr.
	DebugSyscalls bool

	// TerminalFD is the host terminal behind the console. A positive
	// descriptor makes the console that terminal, and -1 makes it a plain
	// stream. 0 is standard input, and also a plain stream when Stdin is nil.
	TerminalFD int
	// VirtualTerminal makes the console a terminal the kernel emulates in
	// place of a host terminal, applying the termios line discipline itself:
	// echo, line editing and signal characters. Resize sets its window size.
	// It overrides TerminalFD.
	VirtualTerminal bool

	// RootFS is the root filesystem. In-memory nodes, such as /dev, /proc and
	// /tmp, overlay it, and writes to its files reach it. When nil, the
	// filesystem is held only in memory. The kernel does not close it.
	RootFS billy.Filesystem
	// Files adds in-memory files, keyed by absolute path such as
	// "/etc/hostname", creating their parent directories. A WebAssembly
	// program is installed executable and any other file read-write.
	Files map[string][]byte

	// Env is the processes' environment. When nil, it holds PATH, HOME, TERM
	// and SHELL.
	Env map[string]string

	// InitPath is the program Boot runs. It defaults to "/init".
	InitPath string
	// InitArgs are the arguments Boot passes after the program's path.
	InitArgs []string
}

Config configures a kernel.

type File

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

File is host code's reference to an open file passed over a Unix socket. It keeps the file open until Close, like a guest descriptor.

func (*File) Close

func (f *File) Close() error

Close drops the reference.

func (*File) ReadAt

func (f *File) ReadAt(b []byte, off int64) (int, error)

ReadAt reads the file at off as the guest's processes see it, including the writes in their writable shared mappings that no msync has written back. It returns io.EOF when it reads less than len(b).

type Kernel

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

Kernel is one running system: its WebAssembly runtime, filesystem, process table and console.

func New

func New(ctx context.Context, rt engine.Runtime, cfg *Config) (*Kernel, error)

New creates a kernel that runs its processes on rt. The kernel defines its host modules in rt, so rt serves this kernel alone.

func (*Kernel) Boot

func (k *Kernel) Boot(ctx context.Context) error

Boot runs the program at InitPath as PID 1 and waits for it, or until the reboot call ends the run. It returns ErrReboot when the system restarted and nil when it halted.

func (*Kernel) Close

func (k *Kernel) Close(ctx context.Context) error

Close stops reading the console, restores the host terminal and closes the runtime.

func (*Kernel) DialUnix

func (k *Kernel) DialUnix(ctx context.Context, socketPath string) (*UnixConn, error)

DialUnix connects host code to the Unix stream socket listening at the absolute path in the guest's filesystem, as a guest's connect does. It waits for a socket to listen there, or for ctx to end. The guest accepts the connection like any other.

func (*Kernel) ListenUnix

func (k *Kernel) ListenUnix(socketPath string) (*UnixListener, error)

ListenUnix binds a Unix stream socket for host code at the absolute path in the guest's filesystem, creating its directories, as a guest's bind and listen do. A socket node left there by a closed listener is replaced. Each guest connect arrives from Accept.

func (*Kernel) NewMemfd

func (k *Kernel) NewMemfd(name string, data []byte) *File

NewMemfd creates an anonymous in-memory file holding data, as a guest's memfd_create does, for host code to pass to the guest over a Unix socket.

func (*Kernel) Resize

func (k *Kernel) Resize(cols, rows uint32)

Resize sets the console's window size and sends SIGWINCH to its foreground processes when the size changed.

func (*Kernel) RunInteractive

func (k *Kernel) RunInteractive(ctx context.Context, wasm []byte, args ...string) error

RunInteractive runs a guest program like RunProcess, and forwards the host process's SIGINT to the kernel's foreground processes instead of letting it end the host. A host terminal in cooked mode turns Ctrl-C into SIGINT; in raw mode the console input reads it as a byte and signals the same way.

func (*Kernel) RunProcess

func (k *Kernel) RunProcess(ctx context.Context, wasm []byte, args ...string) error

RunProcess runs a guest program as a new process and waits for it and every child it started. A nonzero exit returns a ProcessExitError.

func (*Kernel) Signal

func (k *Kernel) Signal(sig uint32)

Signal sends sig to the console's foreground processes, as the host forwards a signal it received, such as SIGINT from a terminal in cooked mode.

type OpenFile

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

OpenFile represents an open file description. Descriptors made by dup, exec and fork share one OpenFile, and so share its offset and flags. The kernel lock guards its fields.

type Process

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

Process is a running guest program. Its syscall methods run on the program's goroutine and reach the shared kernel state through kernel.

type ProcessExitError

type ProcessExitError struct {
	// Code is the exit status.
	Code int
}

ProcessExitError is a process exit. RunProcess returns it for a nonzero exit code, and exit panics with it to unwind the guest.

func (*ProcessExitError) Error

func (e *ProcessExitError) Error() string

Error implements error.

type UnixConn

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

UnixConn is the host's end of a connection to a guest Unix socket. Its open file is never installed in a process, so only its pipes are shared.

func (*UnixConn) Close

func (c *UnixConn) Close() error

Close closes both directions, which the guest reads as end of file, and ends a waiting read or write.

func (*UnixConn) LocalAddr

func (c *UnixConn) LocalAddr() net.Addr

LocalAddr returns the host's end, which has no address.

func (*UnixConn) Read

func (c *UnixConn) Read(b []byte) (int, error)

Read reads from the guest, waiting for data, and closes any files the guest sent with it. It returns io.EOF once the guest closes its end.

func (*UnixConn) ReadMsg

func (c *UnixConn) ReadMsg(b []byte) (int, []*File, error)

ReadMsg reads from the guest like Read, stopping before bytes that carry other files, and returns the files sent with the first byte read. The caller closes each file.

func (*UnixConn) RemoteAddr

func (c *UnixConn) RemoteAddr() net.Addr

RemoteAddr returns the guest socket's path.

func (*UnixConn) SetDeadline

func (c *UnixConn) SetDeadline(time.Time) error

SetDeadline is unsupported; Close ends a waiting read or write.

func (*UnixConn) SetReadDeadline

func (c *UnixConn) SetReadDeadline(time.Time) error

SetReadDeadline is unsupported.

func (*UnixConn) SetWriteDeadline

func (c *UnixConn) SetWriteDeadline(time.Time) error

SetWriteDeadline is unsupported.

func (*UnixConn) Write

func (c *UnixConn) Write(b []byte) (int, error)

Write writes to the guest, waiting for room. It returns io.ErrClosedPipe once the guest closes its end.

func (*UnixConn) WriteMsg

func (c *UnixConn) WriteMsg(b []byte, files []*File) (int, error)

WriteMsg writes to the guest like Write and sends files with the first byte written. The caller keeps its references to files. A write of no bytes sends no files.

type UnixListener

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

UnixListener is host code's listening Unix socket in the guest's filesystem.

func (*UnixListener) Accept

func (l *UnixListener) Accept() (net.Conn, error)

Accept waits for a guest to connect and returns the host's end.

func (*UnixListener) AcceptUnix

func (l *UnixListener) AcceptUnix() (*UnixConn, error)

AcceptUnix waits for a guest to connect and returns the host's end. It fails with net.ErrClosed once the listener closes.

func (*UnixListener) Addr

func (l *UnixListener) Addr() net.Addr

Addr returns the socket's path.

func (*UnixListener) Close

func (l *UnixListener) Close() error

Close stops listening: later connects are refused, the connections not yet accepted close, and a waiting Accept returns.

type VFS

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

VFS is the kernel's filesystem: an in-memory tree over an optional root filesystem. A lookup that misses the tree loads the node from the same path in the root filesystem, so in-memory nodes overlay it.

type VNode

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

VNode is a file, directory, symlink or device in the VFS. A host-backed node mirrors the file at hostPath in the root filesystem, which holds its content; a host-backed directory loads its entries on demand.

Directories

Path Synopsis
Package engine defines the WebAssembly engine the kernel runs guests on.
Package engine defines the WebAssembly engine the kernel runs guests on.
browser
Package browser runs kernel guests on the browser's WebAssembly API.
Package browser runs kernel guests on the browser's WebAssembly API.
native
Package native runs kernel guests on wazero.
Package native runs kernel guests on wazero.

Jump to

Keyboard shortcuts

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