blob: 9e378566476c478ac25e0b9423e0fc613b865ed6 (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
= Creating VMs
:page-parent: Using Spectrum
:page-nav_order: 2
// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
// SPDX-FileCopyrightText: 2022 Unikie
// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
== Configuration
Each VM is configured using a directory under svc/data/ on the
xref:../development/user-partition.adoc[user partition]. The name of the directory
determines the name of the VM.
The directory can contain the following files:
vmlinux:: An uncompressed Linux kernel image for the VM to boot.
*Required.*
blk:: A directory containing disk images (with file names ending in
".img") that will be provided to the guest as a virtio-blk device.
Order is not guaranteed. At least one image is *required*.
shared-dirs:: A directory whose *subdirectories* each describe a
directory to be shared with a VM. The name of each subdirectory is
used as the virtiofs tag, and the contents are as follows:
dir::: A symbolic link pointing to the directory to be shared with
the VM. The directory must be on the
xref:../development/user-partition.adoc[user data partition].
*Required.*
providers/net:: A directory containing a file named for each VM that
should provide networking to this VM. The contents of these files are
ignored.
wayland:: An empty file, whose presence indicates that the host should
set up a virtio-gpu device supporting the cross-domain context type,
for the VM to send Wayland messages over.
=== Example
A configuration directory for a VM called "appvm-lynx" dedicated to
the https://lynx.invisible-island.net[Lynx] web browser, set up to
have networking provided by a VM named "netvm" would look like this:
----
appvm-lynx
├── providers/
│ └── net/
│ └── netvm
├── blk/
│ └── root.img
└── vmlinux*
----
== Devices
The virtual devices described here are always created for Spectrum
VMs. It's important for guests to recognize these devices and use
them in the intended way so that they integrate into the rest of the
system.
=== Logging
Every VM has a serial console that is connected to the host system's
logging infrastructure. The console is write-only -- there will never
be any input to read from the console.
=== User interface
Every VM has a virtio-console device to use to interact with the user
of the Spectrum system.
=== Networking
The Spectrum host system can create network connections between VMs.
These take the form of virtio-net devices. Guests must support the
VIRTIO_NET_F_MAC feature.
A guest can distinguish between virtual inter-guest network
connections and hardware network connections through the MAC address
of the corresponding network interface: guest network interfaces for
inter-guest networking have the OUI `0A:B3:EC`.
Connections to *network provider VMs* have the IP address to use
encoded in the client interface's MAC address. The client guest
should configure an IPv4 address in `100.64.0.0/16`, where the final
two octets of the IP address are the final two octets of the
interface's MAC address. For example, an application VM where a
network interface named `eth0` has the MAC address `0A:B3:EC:00:A5:46`
should configure `eth0` with the IPv4 address `100.64.165.70` (because
`A5` in hexadecimal is `165` in decimal, and `46` in hexadecimal is
`70` in decimal).
|