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/properties/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

This setting controls details of the CPU.

Name	Values	Default	Notes
`cpu.speed`	`0`, `1` or `2`	`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). Setting a value of `0` will cause the simulation to run as fast as it can.

Note: This 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`	`MONUK02` `CEGMON` or `filename`		This defines the monitor ROM that is installed. The value can be one of the built-in names `MONUK02` or `CEGMON`, or it can be the name of a file containing a replacement ROM. MONUK02 was the standard New Monitor ROM. 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.

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. The setting `uk` gives a UK101 keyboard and the setting `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 multicore 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 bits 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.

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
January 2014
tjb101@tinymail.co.uk