Return to index

System Configuration

A number of aspects of the simulation can be changed to correspond with typical hardware and software changes that would have been made to real machines.

This configuration is controlled by a set of system properties that are processed when the simulator starts up. There are a number of different ways in which these properties may be provided. Combinations of these methods can also be used, with properties from later in the list taking precedence over those earlier in the list:

Do nothing. A default set of properties corresponding to a standard machine configuration will be used.
Load a machine image. The properties saved as part of the machine image will be applied.
Default properties file. A Java properties file called uk101.properties can be placed in the same directory as the program JAR file. This can be useful if you always want to set some specific property values.
Additional properties file. The command line parameter -configuration (or -c) can be used to point to an alternative properties file. This is useful if you want to keep a number of different configurations available.
Command line overrides. The command line parameter -properties (or -p) can be used to apply one or more property overrides from the command line. If more than one property is required a comma or semicolon should be used to separate them. This can be useful to temporarily try the effect of an individual property or two.

As an example the following start-up command could be used to start up the simulation temporarily with a large size, green display and a 2MHz CPU:

java -jar uk101-n.n.n.jar -p cpu.speed=2,screen.size=2,screen.colour=green

An example of a Java properties file that contains the default configuration can be found in the file:

samples/properties/uk101.properties

An example of a Java properties file that contains settings suitable for emulating an Ohio Scientific Superboard II can be found in the file:

samples/superboard/superboard.properties

The following sections list all the property names and property values that can be used. Note that property names and values are case-sensitive.

CPU

These settings control details of the CPU.

Name Values Default Notes

cpu.speed from 0 to 4 1 This defines the maximum simulated CPU speed in MHz. A standard 6502 ran at 1Mhz but most could be over-clocked to 2Mhz quite successfully, which doubles the speed of the machine (although some games may then run too fast). The simulation allows any speed from 1MHz to 4Mhz to be specified.

Setting a value of 0 will cause the simulation to run as fast as it can.

cpu.control

auto, sleep, yield or spin

auto

This determines the method used by the CPU emulation to manage instruction timings. Generally this is best left set to auto to let the system decide the method based on measured system performance. The other options are mainly for experimentation and debug.

`sleep`	causes the processor thread to sleep when possible. This uses least host system CPU but may give a less smooth emulation on some slow machines.
`yield`	uses spin-loops to manage timings but causes the processor thread to yield when spinning. This uses more host CPU but the rest of the system should remain fairly responsive.
`spin`	uses spin-loops to manage timings. This uses a lot of host CPU but should give a smooth emulation although the rest of the system may be less responsive.

Note: The cpu.speed setting represents a maximum simulation speed. It is possible that an older or slower PC will not be able reach the maximum requested.

RAM and ROM

These settings control details of the installed RAM and ROMs.

Name Values Default Notes

ram.size from 4 to 40 8 This defines amount of RAM installed in KBytes. the standard machine came with 4KB and there were sockets on the board to allow up to 8KB to be installed. In theory, with an expansion board, up to another 32KB could be installed giving an absolute maximum contiguous RAM of 40KB.

rom.monitor

MONUK01
MONUK02
CEGMON
or filename

This defines the monitor ROM that is installed. The value can be one of the built-in names MONUK01, MONUK02 or CEGMON, or it can be the name of a file containing a replacement ROM.

`MONUK01`	was the original monitor shipped with the early machines.
`MONUK02`	was the standard New Monitor shipped with later machines.
`CEGMON`	is the UK101 version of the popular replacement CEGMON monitor.

rom.basic BASUK101
or filename This defines the BASIC ROM that is installed. The value can be the built-in name BASUK101 or it can be the name of a file containing a replacement ROM.

rom.charset CHGUK101
or filename This defines the video character generator ROM that is installed. The value can be the built-in name CHGUK101 or it can be the name of a file containing a replacement ROM.

rom.XXXX filename This allows additional ROMs to be installed. The ROM is installed at address XXXX which must be a valid four digit hexadecimal address from 0000 to FFFF and the value should be the name of a file containing the ROM code.

Note: The additional ROMs are processed and installed after the system monitor and BASIC ROMs, so they can be used to replace some or all of the system ROM address spaces.

Patching ROM Images

When a ROM image is loaded it is possible to define a set of patches to be applied to the ROM data. This can be useful, for example, to force a ROM to default correctly for a 32 line screen, or to change timings such as typing auto-repeat rate for use with faster CPU clocks. Patching can also be done by creating a completly separate ROM image, but for quick testing and simple changes adding the patches to the configuration can often be easier.

Patches are defined using the following syntax appended to the name of the ROM to be loaded:

ROMNAME[ADDR/BB,BB,..;ADDR/BB,BB,...]

`ADDR`	Is a four-digit hexadecimal address at which to begin patching.
`BB`	Are one or more two-digit hexadecimal bytes used to update the ROM starting at the specified address.

Some useful patches include:

CEGMON[FBC0/D7]

Default CEGMON for a 32-line display.
CEGMON[FCE0/00]

Disables the CEGMON auto-repeat when typing. This can also be set to non-zero values to alter the auto-repeat rate, the default value being 10.
MONUK02[FACA/20;FAF1/20;FB2D/D8;FB61/D8;FB85/D7; FB8D/A9,1A,85,E4,AD,08,02,0A,0A,0A,0A,26,E4,0A,26,E4,0A,26,E4,6D,07,02,69,0D,85,E3,60]

Updates to the standard monitor for a 32-line screen. These changes were listed in Practical Electronics April 1982, page 57. This is quite a complex patch; a version of the ROM with these patches already applied can be found in the samples/roms> directory.

ACIA Baud Rate

This setting controls the default baud rate for the ACIA.

Name	Values	Default	Notes
`baud.rate`	`110`, `300`, `600`, `1200`, `2400`, `4800` or `9600`	`300`	This defines default baud rate of the ACIA. Some programs (in particular some games) relied on the ACIA control signals to generate accurate timings that were independent of the CPU speed.

Note: The ACIA baud rate setting is ignored when reading or writing to a simulated cassette tape, these operations simply run as fast as they can, however it is required if reading or writing a Kansas City Standard audio file.

Keyboard

These settings control the keyboard layout and available keys together with the default keyboard input mode.

Name Values Default Notes

keyboard.layout

uk or us

uk

This defines keyboard layout and the available keys.

`uk`	gives a UK101 keyboard layout.
`us`	gives an Ohio Scientific Superboard II keyboard.

keyboard.mode normal or game normal This defines the initial keyboard input mode. See keyboard mode for details.

Video Hardware

These settings control the details of the video hardware.

Name	Values	Default	Notes
`video.rows`	from `16` to `32`	`16`	This defines the number of rows in the video buffer.
`video.cols`	from `32` to `64`	`64`	This defines the number of columns in the video buffer.

Note: The settings of the video hardware define the amount of video RAM (rows x columns rounded up to the nearest 1K boundary) and the geometry of screen buffer. This is not quite the same as what gets displayed on the screen as real UK101's simple video hardware was not able to scan all of the memory locations to the TV output. Some characters we "lost" from the beginning and end of each scan line. The screen display section configures this.

Screen Display

These settings control the appearance of the video output.

Name Values Default Notes

screen.width from 16 to 64 50 This defines the number of characters visible on each screen line.

screen.offset from 0 to 63 12 This defines the offset of the first visible character on each row from the hardware video buffer.

screen.size 1 or 2 1 This defines the size of the video display: 1 is a smaller display, 2 is a larger display.

screen.colour
screen.color white, green or amber white This defines the colour of the screen display.

screen.update

async or sync

async

This defines how screen updates are performed.

`async`	performs all updates via the Java Swing event dispatch thread. This is a more correct way to update the screen but can give slower results on older PCs.
`sync`	performs updates to each character cell as they are written by the simulation - this may give faster output but can lead to some screen corruption if there are windows overlapping the video window.

Note: On any modern PC, especially anything with a dual or multi-core processor, the default async screen update option is likely to produce the best results. On older hardware the sync option may result in faster and/or smoother operation.

Kansas City Audio Encoding

These settings control the audio encoding when creating Kansas City Standard data files.

Name Values Default Notes

audio.rate from 8000 to 96000 48000 This defines the audio sample rate. Higher sample values give higher quality sound but larger files.

audio.bits 8 or 16 16 This defines the number of bits for each sample. Higher bit values give higher quality sound but larger files.

audio.lead from 0 to 10 5 This is the number of seconds of carrier tone played before the start and after the end of the data.

audio.wave

system or sine

system

This defines the shape of the audio waveform.

`system`	generates a waveform that closely matches that produced by the real UK101 hardware.
`sine`	encodes the audio as pure sine waves.

Note: The baud rate setting is also required when reading or writing audio data, however it is restricted to the values 300, 600 or 1200 only.

Tim Baldwin
November 2015
tjb101@tinymail.co.uk