From 4ca9933fe8371d148731702ebbe677892f8bc426 Mon Sep 17 00:00:00 2001 From: Alyssa Ross Date: Wed, 16 Nov 2022 10:54:50 +0000 Subject: Documentation: rename "Getting Started" to "Using Spectrum" I clicked on "Getting Started" by mistake expecting to find the documentation about obtaining and installing a Spectrum image, but it actually contains documentation that explains how to use the system once it's installed. So I think it would be clearer if it were named "Using Spectrum". Signed-off-by: Alyssa Ross Cc: Jenni Nikolaenko Message-Id: <20221116105450.610594-1-alyssa.ross@unikie.com> --- Documentation/getting-started/creating-vms.adoc | 80 ------------------------- Documentation/getting-started/index.adoc | 13 ---- Documentation/getting-started/running-vms.adoc | 14 ----- Documentation/using-spectrum/creating-vms.adoc | 80 +++++++++++++++++++++++++ Documentation/using-spectrum/index.adoc | 13 ++++ Documentation/using-spectrum/running-vms.adoc | 14 +++++ 6 files changed, 107 insertions(+), 107 deletions(-) delete mode 100644 Documentation/getting-started/creating-vms.adoc delete mode 100644 Documentation/getting-started/index.adoc delete mode 100644 Documentation/getting-started/running-vms.adoc create mode 100644 Documentation/using-spectrum/creating-vms.adoc create mode 100644 Documentation/using-spectrum/index.adoc create mode 100644 Documentation/using-spectrum/running-vms.adoc diff --git a/Documentation/getting-started/creating-vms.adoc b/Documentation/getting-started/creating-vms.adoc deleted file mode 100644 index a2ad952..0000000 --- a/Documentation/getting-started/creating-vms.adoc +++ /dev/null @@ -1,80 +0,0 @@ -= Creating VMs -:page-parent: Getting Started -:page-nav_order: 1 - -// SPDX-FileCopyrightText: 2022 Alyssa Ross -// 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: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*. - -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. - -=== 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). diff --git a/Documentation/getting-started/index.adoc b/Documentation/getting-started/index.adoc deleted file mode 100644 index 10dde7f..0000000 --- a/Documentation/getting-started/index.adoc +++ /dev/null @@ -1,13 +0,0 @@ -= Getting Started -:description: Exploring Spectrum OS. Using (=How-To-Guides), Configuring (adding smth). -:page-nav_order: 3 -:page-has_children: true -:page-has_toc: false - -// SPDX-FileCopyrightText: 2022 Unikie -// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 - -Ready to get started with Spectrum? Here is what you can do next: - -* xref:../getting-started/creating-vms.adoc[Create your own VM] to use others applications. -* xref:../getting-started/running-vms.adoc[Start some applications]. diff --git a/Documentation/getting-started/running-vms.adoc b/Documentation/getting-started/running-vms.adoc deleted file mode 100644 index ca70835..0000000 --- a/Documentation/getting-started/running-vms.adoc +++ /dev/null @@ -1,14 +0,0 @@ -= Running VMs -:page-parent: Getting Started -:page-nav_order: 2 - -// SPDX-FileCopyrightText: 2022 Alyssa Ross -// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 - -Running VMs can be managed with the following commands, available in a -host terminal: - -`lsvm`:: List available VMs, along with whether they are currently running. -`vm-console `:: Open a terminal emulator for a VM's console. -`vm-start `:: Start a VM. -`vm-stop `:: Stop a VM. diff --git a/Documentation/using-spectrum/creating-vms.adoc b/Documentation/using-spectrum/creating-vms.adoc new file mode 100644 index 0000000..6847249 --- /dev/null +++ b/Documentation/using-spectrum/creating-vms.adoc @@ -0,0 +1,80 @@ += Creating VMs +:page-parent: Using Spectrum +:page-nav_order: 1 + +// SPDX-FileCopyrightText: 2022 Alyssa Ross +// 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: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*. + +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. + +=== 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). diff --git a/Documentation/using-spectrum/index.adoc b/Documentation/using-spectrum/index.adoc new file mode 100644 index 0000000..5ee5043 --- /dev/null +++ b/Documentation/using-spectrum/index.adoc @@ -0,0 +1,13 @@ += Using Spectrum +:description: Exploring Spectrum OS. Using (=How-To-Guides), Configuring (adding smth). +:page-nav_order: 3 +:page-has_children: true +:page-has_toc: false + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Ready to get started with Spectrum? Here is what you can do next: + +* xref:creating-vms.adoc[Create your own VM] to use others applications. +* xref:running-vms.adoc[Start some applications]. diff --git a/Documentation/using-spectrum/running-vms.adoc b/Documentation/using-spectrum/running-vms.adoc new file mode 100644 index 0000000..518b00e --- /dev/null +++ b/Documentation/using-spectrum/running-vms.adoc @@ -0,0 +1,14 @@ += Running VMs +:page-parent: Using Spectrum +:page-nav_order: 2 + +// SPDX-FileCopyrightText: 2022 Alyssa Ross +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Running VMs can be managed with the following commands, available in a +host terminal: + +`lsvm`:: List available VMs, along with whether they are currently running. +`vm-console `:: Open a terminal emulator for a VM's console. +`vm-start `:: Start a VM. +`vm-stop `:: Stop a VM. -- cgit 1.4.1