UK101
Return to index

Utility Applications

The simulator contains a number of utility programs that can be used for various off-line tasks.

To run any of these utility programs you must ensure the simulator JAR file is on the Java CLASSPATH.


Code Disassembler

Command

java uk101.utils.PrintCode [options] bytesfile [address]

Parameters

bytesfile
A file containing the code to be disassembled.
address
The code starting address. Defaults to 0. This can be provided in hexadecimal by preceding the digits with a $ or 0x characters.

Options

-output outputfile
A file to save the output. Defaults to standard out.

This command will disassemble a block of 6502 instruction code such as a ROM image. The starting address of the first instruction will need to be provided as there is no way to determine this from the 6502 bytes alone. Code is displayed in standard 6502 assembler format, for example:

FF96:  48         PHA
FF97:  A9 01      LDA #$01
FF99:  D0 F6      BNE $FF91
FF9B:  AD 12 02   LDA $0212
FF9E:  D0 19      BNE $FFB9
FFA0:  A9 FE      LDA #$FE
FFA2:  8D 00 DF   STA $DF00
FFA5:  2C 00 DF   BIT $DF00
FFA8:  70 0F      BVS $FFB9
FFAA:  A9 FB      LDA #$FB
FFAC:  8D 00 DF   STA $DF00
FFAF:  2C 00 DF   BIT $DF00
FFB2:  70 05      BVS $FFB9
FFB4:  A9 03      LDA #$03
FFB6:  4C 36 A6   JMP $A636
FFB9:  60         RTS

Data Display

Command

java uk101.utils.PrintBytes [options] bytesfile [address]

Parameters

bytesfile
A file containing the data to be displayed.
address
The data starting address. Defaults to 0. This can be provided in hexadecimal by preceding the digits with a $ or 0x characters.

Options

-output outputfile
A file to save the output. Defaults to standard out.

This command will print a formatted hexadecimal dump of a block of data such as ROM image. The starting address of the first data byte will need to be provided as there is no way to determine this from the data bytes alone. Data is printed in hexadecimal and as ASCII characters, for example:

FF30:  06 20 4E FF 4C 11 BD C9 57 D0 06 20 4E FF 4C 00  [. N.L...W.. N.L.]
FF40:  00 C9 4D D0 06 20 4E FF 4C 00 FE 4C 00 FF A9 0C  [..M.. N.L..L....]
FF50:  4C 57 FA 8A 48 BA BD 03 01 C9 A3 F0 05 68 AA 4C  [LW..H........h.L]
FF60:  EB FF A2 05 4C 7F FE 55 F9 7E F9 FF 48 AD 05 02  [....L..U.~..H...]
FF70:  F0 22 68 20 B1 FC C9 0D D0 1B 48 8A 48 A2 0A A9  [."h ......H.H...]
FF80:  00 20 B1 FC CA D0 FA 68 AA 68 60 48 CE 03 02 A9  [. .....h.h`H....]
FF90:  00 8D 05 02 68 60 48 A9 01 D0 F6 AD 12 02 D0 19  [....h`H.........]
FFA0:  A9 FE 8D 00 DF 2C 00 DF 70 0F A9 FB 8D 00 DF 2C  [.....,..p......,]
FFB0:  00 DF 70 05 A9 03 4C 36 A6 60 2C 03 02 10 19 A9  [..p...L6.`,.....]
FFC0:  FD 8D 00 DF A9 10 2C 00 DF F0 0A AD 00 F0 4A 90  [......,.......J.]
FFD0:  EE AD 01 F0 60 EE 03 02 AD 0F 02 F0 03 4C 00 FD  [....`........L..]
FFE0:  A9 50 8D 10 02 4C EA FC FF FF FF 6C 18 02 6C 1A  [.P...L.....l..l.]
FFF0:  02 6C 1C 02 6C 1E 02 6C 20 02 22 02 00 FF 25 02  [.l..l..l ."...%.]

Dump File Formatter

Command

java uk101.utils.PrintDump [options] dumpfile

Parameters

dumpfile
The name of a simulator memory dump file.

Options

-output outputfile
A file to save the output. Defaults to standard out.
-hex
Format the dump as hex bytes. This is the default format.
-code
Format the dump as disassembled code.

This will format and print the output of a simulator memory dump file. The memory dump files usually have a name like uk101‑yyyyMMdd‑HHmmss‑SSS.ram. The memory dump can be formatted either as disassembled instructions or as hexadecimal data display.

Memory dump files can be produced by using the special simulator control instruction, or by pressing the Dump button on the Machine view window.


Trace File Formatter

Command

java uk101.utils.PrintTrace [options] tracefile

Parameters

tracefile
The name of a simulator instruction trace file.

Options

-output outputfile
A file to save the output. Defaults to standard out.

This will format and print the output of a simulator instruction trace file. The instruction trace files usually have a name like uk101‑yyyyMMdd‑HHmmss‑SSS.trace

The output of the trace formatter will be something like this:

F9B3:  CA         DEX           ; A=00    X=06 Y=1E S=F5  P=nv-bdiZc
F9B4:  D0 F8      BNE $F9AE     ; A=00    X=05 Y=1E S=F5  P=nv-bdizc
F9AE:  20 E7 F9   JSR $F9E7     ; A=00    X=05 Y=1E S=F5  P=nv-bdizc  EA=F9E7,A9
F9E7:  A9 01      LDA #$01      ; A=00    X=05 Y=1E S=F3  P=nv-bdizc
F9E9:  8D 00 DF   STA $DF00     ; A=01    X=05 Y=1E S=F3  P=nv-bdizc  EA=DF00,FF
F9EC:  AD 00 DF   LDA $DF00     ; A=01    X=05 Y=1E S=F3  P=nv-bdizc  EA=DF00,FF
F9EF:  49 FF      EOR #$FF      ; A=FF    X=05 Y=1E S=F3  P=Nv-bdizc
F9F1:  60         RTS           ; A=00    X=05 Y=1E S=F3  P=nv-bdiZc

This shows the address of each traced instruction followed by the bytes of that instruction and its disassembled form.

Following the instruction is the state of the various CPU registers and flags as they were before execution of the instruction. If the instruction addresses memory the effective address of the instruction operand is also given - this is the address after any indirection and indexing has been performed - along with the data byte at that address.

Trace files can be produced by using the special simulator control instructions, or by selecting the Trace action on the CPU view window.


ROM Image Eraser

Command

java uk101.utils.EraseROM [options] romfile

Parameters

romfile
The name of a ROM image file that is to be erased or created.

Options

-fill byte
The byte value to use when filling the ROM image. Defaults to 0. This can be provided in hexadecimal by preceding the digits with a $ or 0x characters.
-new size
Force the creation of a new ROM image of the specified size. This can be provided in hexadecimal by preceding the digits with a $ or 0x characters.

This will erase an existing ROM image or create a new ROM image of a given size.

In either case the final size of the ROM will be rounded up to the next multiple of 256 bytes and the image will be filled with the specified fill value (or 0). Typically an empty ROM image would be created to be installed as an EPROM in order to generate a new ROM.


Binary and Audio Tape Reader

Command

java uk101.utils.TapeRead [options] inputtape [outputfile]

Parameters

inputtape
The name of a binary or ASCII tape file or a Kansas City Standard encoded audio WAV file.
outputfile
The name of an ASCII format output file. Defaults to standard out.

Options

-binary
Input should be processed as a binary file. This is not normally required as the system will automatically detect the type of input.
-baud baud_rate
The baud rate of an audio encoding. Supported baud rates are 300, 600 or 1200; this defaults to the standard 300 baud.
-phase phase_angle
The phase angle of an audio encoding. Supported values are 0, 90, 180 or 270; this defaults to 90°.

This program will write an ASCII format version of input file. The ASCII format is useful for viewing and editing on the PC.

It may be necessary to experiment with the -phase parameter to get accurate decoding of audio files, although the default value is correct for any tapes written using the Tape Recorder utility.

See tape formats for details on the differences between the binary, audio and ASCII forms of program tapes.


Binary Tape Writer

Command

java uk101.utils.TapeWrite [options] inputfile(s) outputtape

Parameters

inputfile(s)
The names of one or more binary or ASCII tape files or a Kansas City Standard encoded audio WAV files
outputtape
The name of a binary format output file.

Options

-baud baud_rate
The baud rate of an audio encoding. Supported baud rates are 300, 600 or 1200; this defaults to the standard 300 baud.
-phase phase_angle
The phase angle of an audio encoding. Supported values are 0, 90, 180 or 270; this defaults to 90°.

This program will write a single binary format version of all the provided input files. The binary format is the best format to use when archiving UK101 programs and data on the PC. The input files may be in binary, ASCII or audio encoded formats or a mix of the three.

See tape formats for details on the differences between the binary, audio and ASCII forms of program tapes.


Audio Recorder

Command

java uk101.utils.TapeRecord [options] inputfile(s) outputwav

Parameters

inputfile(s)
The names of one or more binary or ASCII tape files or a Kansas City Standard encoded audio WAV files
outputwav
The name of a Kansas City Standard audio WAV output file.

Options

-binary
Input should be processed as a binary files. This is not normally required as the system will automatically detect the type of input.
-sineWave
Generate audio files using pure sine waves rather than the system hardware wave shape.
-sampleRate sample_rate
The audio sample rate for the WAV encoded file. Values can be between 8000 and 96000, including the CD standard 44100. The default is high quality 48000Hz.
-sampleSize sample_size
The audio sample size for the WAV encoded file. Values can be 8 or 16. The default is high quality 16-bit samples
-baud baud_rate
The baud rate of the WAV encoded file. Supported baud rates are 300, 600 or 1200; this defaults to the standard 300 baud.
-leadIn lead_in
The number of seconds of lead-in carrier tone. Default value is 5 seconds.
-leadOut lead_out
The number of seconds of lead-out carrier tone. Default value is the same as the lead-in.
-leadGap segment_gap
The number of seconds of blank carrier tone between output file segments. Default value is 2 seconds.
-inputBaud input_baud_rate
The baud rate of the inputfile if it is audio encoded and if it differs from the output baud rate.
-inputPhase input_phase_angle
The phase angle of the inputfile if it is audio encoded. Supported values are 0, 90, 180 or 270; this defaults to 90°.

This program will write a single Kansas City Standard audio format WAV file of all the provided input files. A small segment gap of blank carrier tone will be left between eaxh file written. The input files may be in binary, ASCII or audio encoded formats or a mix of the three.

See tape formats for details on the differences between the binary, audio and ASCII forms of program tapes.

Note: this program can take an audio format tape as input and can rewrite the tape in a different audio baud rate or quality level if required.


Audio Player

Command

java uk101.utils.TapePlay [options] inputfile(s)

Parameters

inputfile(s)
The names of one or more binary or ASCII tape files or a Kansas City Standard encoded audio WAV files

Options

-binary
Input should be processed as a binary files. This is not normally required as the system will automatically detect the type of input.
-sineWave
Generate audio files using pure sine waves rather than the system hardware wave shape.
-sampleRate sample_rate
The audio sample rate for the WAV encoded file. Values can be between 8000 and 96000, including the CD standard 44100. The default is high quality 48000Hz.
-sampleSize sample_size
The audio sample size for the WAV encoded file. Values can be 8 or 16. The default is high quality 16-bit samples
-baud baud_rate
The baud rate of the WAV encoded file. Supported baud rates are 300, 600 or 1200; this defaults to the standard 300 baud.
-leadIn lead_in
The number of seconds of lead-in carrier tone. Default value is 5 seconds.
-leadOut lead_out
The number of seconds of lead-out carrier tone. Default value is the same as the lead-in.
-leadGap segment_gap
The number of seconds of blank carrier tone between output file segments. Default value is 2 seconds.
-inputBaud input_baud_rate
The baud rate of the inputfile if it is audio encoded and if it differs from the output baud rate.
-inputPhase input_phase_angle
The phase angle of the inputfile if it is audio encoded. Supported values are 0, 90, 180 or 270; this defaults to 90°.

This program will take one or more ASCII, binary or audio tape file and play them in Kansas City Standard audio format to the system sound device. This might be useful if you wanted to connect the PC's audio output to a real cassette player or real UK101 machine.

Note: this program can be used to play audio format files but it is not a general media player - it works by decoding the input tape and recoding it for output. Different output audio baud rate or quality settings can be used for playback if required.


Tim Baldwin
February 2017
tjb101@tinymail.co.uk
Return to index

© Tim Baldwin 2010,2017