Site index: [ Native home | Release History | Technical Info | Screenshots | Installation | Registry ]

Page index: [ Module SYSTEM | Writing a display driver | Writing a disk driver | Trap information | Low-level tracing | Creating a boot diskette | Setting configuration strings | Configuration string definitions | Object file format | Heap format | Recommendations ]

PC Native Oberon: Technical Notes

This page contains Native Oberon technical information. Feel free to mail muller@inf.ethz.ch for further information or to contribute something.

PC Native Oberon Compiler information.

Module SYSTEM

The SYSTEM module contains definitions used to program low-level operations referring directly to resources particular to a given computer and/or implementation. These include, for example, facilities for accessing devices that are controlled by the computer, and facilities to break the type compatibility rules otherwise imposed by the language definition. It is recommended that their use be restricted to specific low-level modules. Such modules are inherently non-portable, but are easily recognised due to the identifier SYSTEM appearing in their import lists. SYSTEM is implemented directly in the compiler.

The following definitions are available in the Native Oberon SYSTEM module.

ADR, BIT, LSH, ROT, VAL, GET, PUT, MOVE, NEW and BYTE are defined in "Programming in Oberon" by Reiser and Wirth. They should be available on most Oberon implementations. CC is defined in the book, but not in Native Oberon.

Importing the SYSTEM module also enables the built-in assembler.

Writing a display driver

Here are some guidelines when writing a new display driver. This table summarizes the capabilities of the current display drivers:

Driver Truecolor TransferBlock
GD54xx no no
Permedia2 (new beta) yes yes
S3C805 no no
S3C924 no no
S3Trio yes yes
SVGA no no
VGA no no
W32 no no

Writing a disk driver

This is similar to writing a new display driver, except that the Disk driver is statically linked with the boot image. Lets assume you are writing a new SCSI driver.

Trap information

When a run-time error is detected, the system generates a numbered trap. The information included with the trap can be used to diagnose the problem. Especially useful is the module and procedure name and PC location where the trap occured. This allows a programmer to find the exact location in the source code using the \f option of the compiler. Here is an example of a trap viewer:

TRAP 7  Index out of range 
TestHalt2.Index  PC =   352 
  a = "" 
  i = 3 
Oberon.Call  PC =  4646 
etc...

It can be interpreted as follows:

Trap numbers fall into the following ranges: More detailed information about specific traps:

Low-level tracing

Native Oberon provides Kernel.Write* procedures, which can be used to trace low-level code like device drivers. This trace output can be displayed on a serial terminal connected to the PC (this could be a second PC running the V24.Panel in Oberon). Set configuration string TracePort to the number of the serial port (1 or 2) and TraceBPS to the speed (default 19200 bps). After version 2.3.0 the trace information is also stored in a buffer that can be retrieved with the System.OpenKernelLog command. See Configuration Strings below for more information.

Creating a boot diskette

Setting configuration strings

Native Oberon uses configuration strings for setting low-level configuration options. These strings are (name, value) ASCII string pairs which are stored in a table on the boot device (diskette or hard disk). Permanent values for these strings are normally set during installation using the Install or FDInstall programs in Oberon-0. The strings are read by low-level modules in the system using the Kernel.GetConfig procedure. Higher-level modules should use the more flexible Oberon.Text and the Oberon.OpenScanner procedure for configuration information.

Sometimes it is necessary to temporarily override the setting of some configuration strings. The OBL bootstrap loader provides a facility for doing this:

When booting the system, before the message "Oberon Bootstrap Loader" appears, activate ScrollLock, or hold down any shift key. The "OBL>" prompt should appear and the current values of the configuration strings are displayed. There are some options at this prompt:

The DOS-based boot loader, noboot.exe, uses a DOS file for the configuration information. The latest version of the boot loader also supports the ScrollLock or shift key method of changing the configuration strings. Instead of a built-in editor, it invokes any DOS editor, using the command line specified by the EDITOR environment variable (default "edit"). When invoking the editor, noboot.exe appends the name of the configuration file to the command line.

Configuration string definitions

The following are the configuration strings currently defined (note the version numbers displayed below; some strings are only defined for some versions of the system).

Display drivers

Input drivers

File system and disk driver

Memory management

Compatibility

Customization

Tracing

Obsolete

Object file format

The reference block part of the .Obj file format of Native Oberon is documented here. The reference block is used by System.Trap and System.State to display information on variables for debugging purposes. The format was extended in such a way that existing object files in the old format remain compatible with the trap handler. The "Proc" type was added for procedure variables. Bit 7 of "VarType" now indicates if an array dimension, "dimNum", is present for arrays of simple types. For open array parameters, "dimNum" is zero. "String" is deprecated. As the reference block is only intended for simple debugging, and has to be compact, more complicated structured types are not supported.

In the following BNF syntax non-terminal symbols start with an upper case letter and terminal symbols start with a lower-case letter. Non-terminals ending in "Str" are 0X-terminated strings and those ending in "Num" are numbers in Files.WriteNum format. The meaning of a symbol should be apparent from its name.

References = 08BX { ProcRef } . 
ProcRef = 0F8X ofsNum nameStr { VarMode VarType [ dimNum ] ofsNum nameStr } . 
VarMode = Direct | Indirect . 
Direct = 1X . 
Indirect = 3X . 
VarType = Byte | Bool | Char | SInt | Int | LInt | Real | LReal | Set | Pointer | Proc | String . 
Byte = 1X | 81X . 
Bool = 2X | 82X . 
Char = 3X | 83X . 
SInt = 4X | 84X . 
Int = 5X | 85X . 
LInt = 6X | 86X . 
Real = 7X | 87X . 
LReal = 8X | 88X . 
Set = 9X | 89X . 
Pointer = 0DX | 8DX . 
Proc = 0EX | 8EX . 
String = 0FX .

Heap format

In ETH Oberon systems there are three main types of heap blocks: RecBlk, ArrBlk and SysBlk. RecBlks are used for POINTER TO RECORD variables allocated with NEW. ArrBlks are used for POINTER TO ARRAY OF Type variables allocated with NEW, where type is a pointer type, or a record type containing pointers. SysBlks are used for blocks allocated with SYSTEM.NEW, or for POINTER TO ARRAY OF Type variable allocated with NEW, where Type does not contain any pointers. Special SysBlks are also used for the type descriptors and modules.

The mark phase of the garbage collector distinguishes heap blocks by the address alignment of the pointers pointing to them, and the tag word in front of them. RecBlk and ArrBlk pointer addresses are always directly divisible by 32 (adr MOD 32 = 0). SysBlk pointer addresses have a remainder of 8 when divided by 16 (adr MOD 16 = 8). A RecBlk has a tag word at adr-4, with bit 1 clear. An ArrBlk also has a tag word at adr-4, but with bit 1 set. Bit 0 is the mark bit, and is set by the mark phase when a block is reached. It is cleared by the Sweep phase. A SysBlk has an indirect tag at adr-4, which points to the real tag of the block. Type descriptors are special SysBlks.

The heap block format was originally documented in an unpublished diagram by Régis Crelier at the ETH. The diagram was redrawn by Thomas Burri and is available as gzipped PostScript or GIF.

Recommendations

The following software and documentation may be useful when installing the system or writing device drivers. The following firms are generous with providing technical information: S3, 3Com, Chips & Technologies (ftp), ATI Technologies, Intel.

The following firms provided technical information to us under non-disclosure agreement: 3DLabs, Adaptec.


Pieter Muller April 28, 1999 (page created with HTML.Tool on Oberon)
ETH Zürich: Departement of Computer Science