Terminology

Installation host is the machine where installation is performed using the hypervisor.
Target machine is the machine where ETH Oberon is to be used after installation is completed. This can be the bare x86 PC or a hypervisor presenting an x86 PC environment.
Target device is the device where Oberon is to be installed and used. When ETH Oberon works on the hypervisor, any device it supports can be used. When ETH Oberon works directly on the bare machine, devices are limited to available device drivers. Consequently, for ETH Oberon on the bare machine, a disk drive or Compact Flash card connected by PATA or a USB flash store connected by OHCI will work. With ETH Oberon lacking drivers for SATA, UHCI, EHCI and xHCI, devices with these interfaces will not work on the bare machine. QEMU supports most devices.
Target volume is a volume of a partitioned target device.

Generalities

To illustrate, the following example refers to QEMU running on Linux with installer /home/me/OberonCF0.Dsk. Device names are illustrative. Do not attempt to use this example verbatim; adapt to your requirements.

In the installation host, the target device is /dev/sdc. Alternatively, it might have the name /dev/KingstonCF, a SYMLINK assigned with a udev rule.^[1]

KERNEL=="sd?", ATTR{size}=="1018080", SYMLINK+="KingstonCF", \ 
 OWNER="me", GROUP="mygroup"

Where systemd is used, the name can be assigned by a systemd .link file.

The Oberon0 installer uses PATA device names. The target device is IDE0 and target volume is IDE0#05. Again, these are examples only. In another case, the device can be IDE1; the volume can be IDE1#02.
CAUTION: a typographical error in the device identifier can allow catastrophic damage to the file system of the installation host. Identify devices carefully. Type carefully.

Hardware

Specific hardware is addressed in the Hardware compatibility List.

If the target machine is not the installation host, move the target device to the installation host. The connection should be the same as in the target machine. In most cases the target device will connect via a 40 or 44 conductor ribbon cable. A 44 pin laptop drive can be connected to a desktop machine using an adapter. Native Oberon has limited support for USB. In many cases the installation will not succeed for a USB target device. That includes a disk drive or CF card connected by a USB adapter.

Storage

In this installation method, Native Oberon requires a dedicated target volume of the target device. In Linux, a volume can be created with fdisk, parted or gparted. In other systems, other disk manipulators are available. For the complete stock Native Oberon system, at least 50 MiB should be allocated.

Video

By direct inspection or by using software, determine the video capabilities of the target machine. In Linux, lspci identifies most video hardware. In addition to the video chipset, knowledge of the VESA BIOS Extensions capability can be helpful.

Hypervisor

Install QEMU on the host where the installation process is to be performed. Complete system emulation is used. In Debian jessie install the qemu-system-x86 package.

Installer Image

Retrieve an Oberon0 installer image from Sourceforge. OberonCF0.Dsk includes support for Compact Flash and is recommended. Oberon0.Dsk, also there, is the last image published at ETH. It lacks support for CF; otherwise the two images are identical.

Installer Execution

Start the installer.
CAUTION: "sdc" and "KingstonCF" are illustrative. Adjust according to your specific requirement. This command is for installer image file OberonCF0.Dsk. The user ownership of KingstonCF assigned by udev (see above) allows success of this command without root privilege.

qemu-system-i386 \
 -drive file=/home/me/OberonCF0.Dsk,index=0,if=floppy,format=raw \
 -drive file=/dev/KingstonCF,index=1,media=disk,format=raw \
 -vga std -boot order=a

This for a real diskette, write-protected.

qemu-system-i386 \
 -drive file=/dev/fd0,index=0,if=floppy,format=raw,readonly \
 -drive file=/dev/KingstonCF,index=1,media=disk,format=raw \
 -vga std -boot order=a

Risk of damage to a file system in the installation host is mitigated by the condition that QEMU restricts access to devices specified in the qemu command. Refer to the QEMU manual page in the installation host or to the QEMU manual. Access to a host drive is also discussed in a Linux Suse page. If "format=raw" is omitted, QEMU will produce an error message.

Oberon0 Installer Usage

The Oberon0 installer after executing Partitions.Show detail ~. Oberon0 is running on a virtual x86 PC provided by QEMU in Debian Wheezy. ^[2]

Oberon0 will present a sequence of commands, each of which can be executed with a click of the middle mouse button. Text is selected by dragging with the right mouse button. Consult the original installation instructions for details. In InstallFiles.Tool type the option "detail" and execute Partitions.Show detail ~. The intended target volume should be visible in the partition table displayed. In the present example the target volume is IDE0#05; not IDE0#00. Sensible type codes should appear in the fifth column. The type code for the whole target device and for each unallocated area will be "---". Any other volume should have a numerical type code. If "---" appears where a type code should be in the fifth column, the installer failed to read the partition table of the target device properly and successful installation will be impossible. In this case, exit QEMU, correct the problem and try again.

Video Configuration

In the System.Configure viewer, choose a video mode according to the established information. If no chipset-specific driver is suitable, set a VESA mode. In case the chosen mode fails, another mode is easily tested.

Boot Configuration Settings During Installation

MM on

Config.BootPartition menu ~

to record system configuration in the target volume.

MM on

System.Quit

to exit QEMU.

Testing and Troubleshooting

If the hypervisor (QEMU) supports the configured video, the newly installed system can be tested directly.

qemu-system-i386 \
  -drive file=/dev/KingstonCF,index=1,media=disk,format=raw \
  -vga std -boot order=c

Otherwise test in the target machine. If installation was successful and configuration was correct, Native Oberon will appear momentarily. Otherwise, refer to troubleshooting instructions. The discussion under Partition management with Oberon, subheading "Troubleshooting a boot problem with this command" is also relevant. To revise the video configuration, run QEMU again and mount the target volume. In this example MM on

FileSystem.Mount DST AosFS IDE0#05 ~

MM on

Edit.Open Configure.Tool

try another

Config.Display ...

and MM on

Config.BootPartition menu ~

again. If using VESA video, test again under the hypervisor. The BIOS might allow booting from a device other than the primary master. Where the drive is installed in the machine as IDE1 and is recognized in the installer as IDE0 the value for the BootVol config string can be edited when the machine boots. To troubleshoot a more difficult problem, record a trace in a file.

qemu-system-i386 \
 -hda file=/dev/KingstonCF,index=1,media=disk,format=raw \
 -serial file:QemuOberonTrace \
 -vga std -boot order=c,menu=on

Boot option "menu=on" allows interaction. After grabbing the QEMU screen, set <Scroll Lock> and set these Trace config strings.

TracePort=1
TraceBPS=115200

For additional details, refer to Tracing. The most powerful troubleshooting method is with the terminal emulator connected by a serial crossover cable.

If the installation host is not the target machine, replace the target device in the target machine and test again. ETH Oberon is a very robust software. With a little persistence it can run on almost any i386 or later PC.

Boot Manager

If the target machine, real or virtual, has more than one operating system, a boot manager will be needed.

System Configuration

Fundamental configurations are represented by configuration strings allowing specification of the display driver for example. The boot loader allows access to these strings.

At a higher level, system configuration is in the file Oberon.Text. In the freshly installed base system this file is specifically SYS:Oberon.Text. Two subtleties can confuse the novice.
  * Syntax in Oberon.Text is critical. If a closing bracket "}" is inadvertently removed, some information following the error will be ineffective. Take care in editing Oberon.Text.
  * A storage volume additional to SYS can contain an Oberon.Text. Only the first-prioritized copy of the file has effect. For example, consider a system installed and configured with HOME prioritized before SYS. The first execution of ET.Open Oberon.Text will open SYS:Oberon.Text. After editing, ET.Store will store HOME:Oberon.Text. After reboot, SYS:Oberon.Text will remain but HOME:Oberon.Text will have effect; HOME:Oberon.Text will mask SYS:Oberon.Text. Ambiguity can be avoided by specifying a volume.

ET.Open SYS:Oberon.Text
ET.Open HOME:Oberon.Text

Communications Environment

Oberon on a native machine can connect to the Internet through a wired router. A more flexible connection can be provided by a Linux router. In any case the LAN should have a firewall. With a Linux router, Shorewall is recommended. ETH Oberon supports these communications.

Network Connection on a Real Machine

With the base system working, configure a network connection. ETH Oberon supports wired Ethernet with a ststic IP address. Wireless and DHCP are not supported. In absence of an Ethernet connection, PPP over an RS-232 crossover cable (null modem) is also possible. Configurations are in Oberon.Text.

Network Connection on a Virtual Machine

A TAP interface is invoked by the hypervisor as in this example.

sudo qemu-system-i386 -drive file=$Sysdev,format=raw \
  -netdev tap,id=t0 \
  -device ne2k_pci,netdev=t0

Root privilege is required for creation of the interface.

In a Linux host, subnet routing is required. A stanza such as this in /etc/network/interfaces.

# Interface to ETH Oberon guest.
auto tap0
allow-hotplug tap0
iface tap0 inet static
  address  172.23.8.1
  netmask  255.255.255.0

Shorewall is recommendable and will allow source network address translation.

In the Oberon guest, configuration is in Oberon.Text.

NetSystem = {
  Hosts = {
  ...
      Device0 = { "NetNe2000.InstallDevice", "" }
  ...
  Route0 = {
    Device = "Device0"
    Mode = "arp"
    Host = { "OberonSystem", "172.23.8.2" }
    Gateway = { "HypervisorHostSystem", "172.23.8.1" }
    Netmask = { "netmask", "255.255.255.0" }
  }
}

Observe that in the subnet 172.23.8.0 the hypervisor host has address 172.23.8.1 and the Oberon guest has address 172.23.8.2.

Additional Software

Software beyond Oberon0 is distributed in Zip archive files Apps1.zip, Apps2.zip, Docu.zip, Gadgets.zip, Pr3Fonts.zip, Pr6Fonts.zip, Source1.zip, Source2.zip and Source3.zip. Also, for the specific task of rebuilding the system, files Build.zip, SourceB.zip and System.zip. For the Alpha release, all of these are in archive NativeOberon_2.3.7.tar.gz, available in Sourceforge. In a Unix-like system, the following procedure will obtain these zip files. Commands are executed in a console.

mkdir <somewhere>/Oberon2.3.7

Using any Web browser, retrieve NativeOberon_2.3.7.tar.gz, approximately 12 MiB, from Sourceforge into the Oberon2.3.7 directory.

cd <somewhere>/Oberon2.3.7
# Confirm existence of the gz archive.
ls
# Unzip and untar. 
gunzip NativeOberon_2.3.7.tar.gz
tar -xvf NativeOberon_2.3.7.tar.gz
# Read the ETH license.
more readme.txt

Copy all the zip files to the SYS volume of the Oberon system. If a Compact Flash card with a FAT file system can be connected to the Oberon system, that is the most efficient means. If the system hosting the zip files has a FTP server, the Oberon0 system can retrieve the files by FTP. The files can also be transferred one by one via diskette.

In Oberon, MM on these commands to unpack the archives into the SYS volume.

FileSystem.SetDefault SYS
ZipTool.ExtractAll
  Apps1.zip Apps2.zip
  Docu.zip Gadgets.zip
  Pr3Fonts.zip Pr6Fonts.zip
  Source1.zip Source2.zip Source3.zip ~

And the optional files, needed only to rebuild the system.

ZipTool.ExtractAll Build.zip SourceB.zip System.zip ~

Then revert to the working volume.

FileSystem.SetDefault YourWorkingVolume ~

Installation Complete

Further assistance is available via the mailing list.

Texts.FindPiece and the cache

For a given Text, T, and offset pos in [0, T.len), procedure Texts.FindPiece has the task of locating the piece containing pos. At each execution, FindPiece could begin at offset 0 and add lengths of pieces until the piece containing pos is located. A cache based upon T.pce and T.org allows better efficiency. When FindPiece completes a search, the pointer to the found piece is recorded in T.pce; the offset of the first character of that piece is recorded in T.org. The next execution of FindPiece begins at that cached location. With a result from FindPiece often being near the preceeding result, this strategy avoids repeated summation of lengths from the beginning of the first piece.

Text Dataflow in ETH Oberon

This dataflow example illustrates relationships between Oberon Text, HTML and ASCII text.

Text color and style, images and hyperlinks are lost by conversion of browser text to ASCII. Consequently the rightmost Oberon Text has the same appearance as plain ASCII text. Text color and style can assist with reading and understanding a source but compilation is not influenced by color and style.