Oberon/S3

From Wikibooks, open books for an open world
Jump to navigation Jump to search

Installing S3 on a bare PC using QEMU[edit]

S3 on a bare PC has also been referred to as "PC Native Oberon". Originally this installation was performed using an Oberon0 diskette and that procedure may still interest an enthusiast.

In a contemporary system the Oberon0 installer can run under a hypervisor. The hypervisor is installed once and can be used for any number of installations. With this method, no time is spent recording and booting from a diskette and the unreliability of diskettes and drives is avoided. The installer runs faster under the hypervisor than it does from a diskette. The method has proven successful in installing S3 to a variety of laptop and desktop machines including a Micron Trek 2, AGP laptop.

Terminology[edit]

Installation host is the machine where installation is performed using the hypervisor.
Target machine is the machine where the Oberon system is to be used after installation is completed.
Target device is the device where Oberon is to be installed. It is a disk drive or Compact Flash card connected by PATA or a USB flash store connected by OHCI. SATA, UHCI, EHCI and XHCI are not supported.
Target volume is a volume of a partitioned target device.

Generalities[edit]

To make a specific example, the following instructions refer to QEMU running on Linux with installer /home/me/OberonCF0.Dsk. In the installation host, the target device, /dev/KingstonCF, is a SYMLINK created with a udev rule.

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

In the Oberon installer the target device is IDE0 and target volume is IDE0#07.
CAUTION: a small typographical error in the device identifier can allow catastrophic damage to the file system of the installation host. Identify devices carefully. Type carefully.

Hardware[edit]

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[edit]

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[edit]

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[edit]

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[edit]

Retrieve an Oberon0 image such as OberonCF0.Dsk. The latest genuine ETHZ image is the alpha release from 2003. Image OberonCF0.Dsk with support for Compact Flash is available in the SourceForge.

Installer Execution[edit]

Start the installer.
CAUTION: "/dev/KingstonCF" here is an example. Adjust according to your specific requirement. This command is for image file OberonCF0.Dsk.

sudo 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.

sudo 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 [1]. If "format=raw" is omitted, QEMU will produce an error message.

Installer Usage[edit]

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 installation instructions at the ETHZ 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#07; 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. Oberon0UnderQEMU.png

Video Configuration[edit]

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

Boot Configuration[edit]

MM on

Config.BootPartition menu ~

to record system configuration in the target volume and MM on

System.Quit

to exit QEMU.

Testing and Troubleshooting[edit]

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

sudo 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, mount the target volume, in this example MM on

FileSystem.Mount DST AosFS IDE0#07 ~

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.

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

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

TracePort=1
TraceBPS=115200

For additional details, refer to Tracing.

If the installation host is not the target machine, replace the target device in the target machine and test. In this case the best troubleshooting method is with the terminal emulator connected by serial crossover cable.

Boot Manager[edit]

If the target machine has more than one operating system, a boot manager will be needed. The Bluebottle/AOS BootManager is recommended.

System Configuration[edit]

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. Ambiguity can be avoided by specifying a volume.

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

Network Connection[edit]

With the base system working, configure a network connection. Preferably using Ethernet and TCP/IP. Otherwise using a RS-232 crossover cable (null modem) and PPP. Configuration is in Oberon.Text.

Additional Software[edit]

In Oberon, a command in any text can be executed by a click of the middle mouse button. This includes a command in a Web page. To open this page for example, MM on

Desktops.OpenDoc "http://www.loband.org/loband/filter/org/wikibooks/en/%20/wiki/Oberon/S3" [1]

and then MM on each of these commands to retrieve the package archives. After each file is retrieved "Transfer complete." should appear in the System.Log. If the system freezes during a transfer, strike <Ctrl>+<Break> twice, execute System. Reboot and try again to retrieve the failed zip file. In some cases more than one failure can occur before a file is retrieved successfully. Build.zip, SourceB.zip and System.zip are required only to rebuild the system or installer.

FileSystem.SetDefault SYS    <== To retrieve into the SYS volume of storage.
FTP.Open ftp.ethoberon.ethz.ch ~
FTP.ChangeDir "ETHOberon/Native/Update/Alpha/" ~
FTP.Dir ~
FTP.GetFiles Apps1.zip ~
FTP.GetFiles Apps2.zip ~
FTP.GetFiles Docu.zip ~
FTP.GetFiles Gadgets.zip ~
FTP.GetFiles Pr3Fonts.zip ~
FTP.GetFiles Pr6Fonts.zip ~
FTP.GetFiles Source1.zip ~
FTP.GetFiles Source2.zip ~
FTP.GetFiles Source3.zip ~
FTP.GetFiles readme.txt ~
 
FTP.ChangeDir "Build" ~
FTP.Dir ~
FTP.GetFiles Build.zip ~
FTP.GetFiles SourceB.zip ~
FTP.GetFiles System.zip ~
 
FTP.Close ~
ET.OpenAscii readme.txt ~    <== Please read.

MM on this command to unpack the archives,

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

and the optional system building files, needed only to rebuild the system.

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

Revert to the working volume.

FileSystem.SetDefault YourWorkingVolume ~

Installation Complete[edit]

Further assistance is available via the mailing list.

FAQ[edit]

Q.: I am interested to understand the cryptic Init config strings. Is there any alternative to being an expert in Intel machine code and video programming?

A.: When the system is installed with Oberon0, the Init string is provided by Config.Mod. A long VESA string such as "Init=b8024fbb1441cd10b8014fb91401cd10268b4d28268b552a" is built up in sections.

To understand a specific string, apply a disassembler. Then google to understand what is done with the video processor. Here are some links to documents describing the VESA 2.0 and VESA 3.0 standards.

Let's assume you're interested in Init="b81200cd10". There are three methods to disassemble the Init string:

1) You can use the following web-based disassembler online: https://www.onlinedisassembler.com/odaweb/. Select "i8086" as "Arch" and paste the hex bytes of the Init string (b81200cd10) to the window below the platform setting. On the right hand side, you'll find the disassembled code.

.data:00000000 b81200      mov $0x12,%ax
.data:00000003 cd10        int $0x10

2) We want a file Init.o containing these bytes. An obvious if not efficient method is to use Edit or ET to put any 5 characters in Init.o. Then Hex.Open Init.o, replace the characters with B8 12 00 CD 10 and Store. Move Init.o to a Linux system. There apply objdump.

objdump -b binary -m i8086 -D Init.o

Init.o:     file format binary

Disassembly of section .data:

0000000000000000 <.data>: 
  0:   b8 12 00                mov    $0x12,%ax 
  3:   cd 10                   int    $0x10

3) Kees C. proposes to use libdisasm's x86dis tool.

$ echo -e '\xb8\x12\x00\xcd\x10' | x86dis -r 0 5 -s att 
00000000 B8 12 00             mov     $0x0012, %ax 
00000003 CD 10                int     $0x10

All three methods can be applied to any of the strings.

Observe that 0x12 is put into register ax and then interrupt 0x10 is invoked. Googling "vga 12 ax 10" or "vga 12h ax 10h" finds several pages explaining that this sets VGA graphics mode 640 x 480 x 24 colors, the default for PC Native Oberon.

Module Sources and Tools in S3 (ETH Oberon, PC-Native)[edit]

The last release of S3 at the ETHZ was described as Alpha. The directory in the server has a file named CURRENT-IS-05.01.03.

ETHZ Alpha Release
2003-01-05[2]
Variant Notes
ATADisks.Mod ATADisks.Mod Support for Compact Flash added.
Compiler.Mod    
HTML.Mod    
Mail.Mod    
  MediaWiki.Mod  
Objects.Mod    
Sort.Mod    
Texts.Mod    

Footnotes[edit]

  1. The loband filter allows Oberon to use HTTP while the Wikimedia server provides HTTPS.
  2. ISO 8601 date format.