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
- Variables
- func BusyboxApplets(wasm []byte) map[string][]byte
- type Config
- type File
- type Kernel
- func (k *Kernel) Boot(ctx context.Context) error
- func (k *Kernel) Close(ctx context.Context) error
- func (k *Kernel) DialUnix(ctx context.Context, socketPath string) (*UnixConn, error)
- func (k *Kernel) ListenUnix(socketPath string) (*UnixListener, error)
- func (k *Kernel) NewMemfd(name string, data []byte) *File
- func (k *Kernel) Resize(cols, rows uint32)
- func (k *Kernel) RunInteractive(ctx context.Context, wasm []byte, args ...string) error
- func (k *Kernel) RunProcess(ctx context.Context, wasm []byte, args ...string) error
- func (k *Kernel) Signal(sig uint32)
- type OpenFile
- type Process
- type ProcessExitError
- type UnixConn
- func (c *UnixConn) Close() error
- func (c *UnixConn) LocalAddr() net.Addr
- func (c *UnixConn) Read(b []byte) (int, error)
- func (c *UnixConn) ReadMsg(b []byte) (int, []*File, error)
- func (c *UnixConn) RemoteAddr() net.Addr
- func (c *UnixConn) SetDeadline(time.Time) error
- func (c *UnixConn) SetReadDeadline(time.Time) error
- func (c *UnixConn) SetWriteDeadline(time.Time) error
- func (c *UnixConn) Write(b []byte) (int, error)
- func (c *UnixConn) WriteMsg(b []byte, files []*File) (int, error)
- type UnixListener
- type VFS
- type VNode
Constants ¶
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).
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 ¶
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 ¶
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.
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 ¶
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 ¶
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 ¶
Close stops reading the console, restores the host terminal and closes the runtime.
func (*Kernel) DialUnix ¶
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 ¶
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 ¶
Resize sets the console's window size and sends SIGWINCH to its foreground processes when the size changed.
func (*Kernel) RunInteractive ¶
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 ¶
RunProcess runs a guest program as a new process and waits for it and every child it started. A nonzero exit returns a ProcessExitError.
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.
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 ¶
Close closes both directions, which the guest reads as end of file, and ends a waiting read or write.
func (*UnixConn) Read ¶
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 ¶
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 ¶
RemoteAddr returns the guest socket's path.
func (*UnixConn) SetDeadline ¶
SetDeadline is unsupported; Close ends a waiting read or write.
func (*UnixConn) SetReadDeadline ¶
SetReadDeadline is unsupported.
func (*UnixConn) SetWriteDeadline ¶
SetWriteDeadline is unsupported.
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) Close ¶
func (l *UnixListener) Close() error
Close stops listening: later connects are refused, the connections not yet accepted close, and a waiting Accept returns.
Source Files
¶
- clock.go
- config.go
- consts.go
- counter.go
- cred.go
- epoll-entry.go
- epoll-set.go
- epoll.go
- errno.go
- errors.go
- eventfd.go
- fd-io.go
- fd.go
- fork.go
- fsops.go
- guest-module.go
- host-file.go
- host.go
- interval-timer.go
- ioctl.go
- jmp-table.go
- kernel.go
- mmap.go
- mount.go
- onlcr-writer.go
- open-file.go
- pipe.go
- posix.go
- prepare-guest.go
- process-table.go
- process.go
- procfs.go
- pty.go
- reboot.go
- rlimit.go
- run-native.go
- run.go
- sched.go
- seals.go
- session.go
- signal.go
- signalfd.go
- sysfs.go
- terminal-native.go
- termios.go
- timerfd.go
- tty-input.go
- tty.go
- unix-conn.go
- unix-listener.go
- unix-socket.go
- uts.go
- vfs.go
- vnode.go
- wasi-fs.go
- wasi.go
- wasm-reader.go
- wasm-section.go
- xattr.go
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. |