XBUG is a firmware package containing cassette file handling routines,
plus a line-by-line assembler (translator) and disassembler. The
monitor TANBUG is directly linked to this package so that these facuities
can be accessed directly via monitor commands. XBUG is supplied as
a single 2 kilobyte 2716 EPROM. Installation is simple - merely plug
the XBUG EPROM into socket G2 on TANEX, then cut LK1 on TANEX, and XBUG
becomes part of the system monitor. The cassette handler and disassembler
can be run from the hexadecimal keypad, however a full ASCII keyboard is
required to run the line-by-Iine assembler.
WARNING: The translator and instruction disassembler should
NOT be used in the locations 0-5F or 1FO-IFF as these programs
will corrupt TANBUG's status locations and stack respectively.
This chapter should be read in conjunction with the TANEX manual, and replaces the section on dumping to and loading from cassette.
The software allows files to be dumped, verified with memory contents, and read back into memory. Files may be named with a filename consisting of up to 8 characters. Two tape speeds are available - a CUTS 300 baud rate, and a TANGERINE format which approximates to 2400 baud. Several error checks are incorporated. The software is written such that the polarity of input data is irrelevant (your cassette recorder may invert the recorded signal).
CHOICE OF TAPE SPEED
Two tape speeds are available, a 300 baud CUTS format, and an (approximate) 2400 baud format. The redundant information in the CUTS format is used to reduce the occurrence of tape errors should tape dropouts occur, and this format therefore gives more data protection. In general, use the CUTS rate if you are using low quality tape or cassette recorder, or of course if you are transferring data from another type of machine. Otherwise use the FAST rate.
The speed is selected by two TANBUG commands:
F < CR > selects
fast speed. C<CR> selects CUTS speed. Once selected, these speeds
remain set until the system is powered down. They must be reset
by the user on power-up. (On power-up, CUTS speed will always
SETTING UP THE CASSETTE RECORDER LEVELS
The following programs enable you to set up the recording levels for
the two tape formats (they may be different for each). Automatic
level recorders should also be checked to see that no errors are present.
a) Key-in the following program to record test data on cassette:-
100 A941 LDA #$41
102 48 PHA
% 103 2000FO R $FOOO I,-Ns
106 2027FO $FO27
IOA 48 PH@ S C-(
k IOB 2066FO $Fk
c c> rx
C S,@'a U L
c- lop 38 SEC
110 6900 ADC #$O
112 4COA01 JMP $IOA -
b) Set CUTS speed: C<CR>.
c) Start the recorder in record mode.
d) Start the program by typing GlOO<CR>. Allow the recorder
to record a few minutes of this test pattern.
e) Press RESET to escape.
Now repeat the procedure for fast speed.
To check the data:-
· Key-in the following verification program.
115 2000FO JSR $FOOO
1 18 AOOO LDY #$O
48 @A !6- C- fs
6 Clki As %&
11B 20CBFO-- JSR $FOCB
IIE AA TAX
120 9006 BCC $128
122 6900 ADC #$O
124 C551 CMP $51
126 F004 BEQ $12C
128 A942 LDA #$42
12A b )(002 BNE $12E
12C A947 LDA #$47
12E 990002 STA $200,
131 C8 INY
132 8A TXA
133 4ClAOl JMP $IIA
b) Rewind the tape to the start.
c) Start the tape running.
d) Type G115<CR> to start the program.
Now, in the top half of the VDU screen, the characters G (good data) or B (bad data) will be printed. When the actual signal starts, all G's should appear if the level is satisfactory. it may, on manual recording level recorders, be necessary to repeat the recording procedure at different levels to obtain optimum. RESET is necessary to exit from the test program.
DUMPING TO TAPE
The "D" command is used to dump an area of memory to tape. Its format it:
D<start address>,<end address>,<filename>
The filename nay be up to 8 characters long. Characters within it may be A-Z, 0-9, . or
To dump a program onto tape proceed as follows:
a) Use the "D" command but do not type <CR> yet.
b) Start tape running in record mode.
c) Hit < CR>.
The VDU will respond with the filename being dumped, with an added appendix
of A to distinguish this file as being an absolute file.
d) The cursor will disappear and the file will be dumped.
e) The cursor will reappear when the dump is complete - the program returns to TANBUG.
f) Stop the cassette.
Example: Type D400,410,FILE1 < CR> The display will appear as follows:
· instruction dumped locations 400 to 410 inclusive, and called
· file FILE1.
A question mark error will be generated if the command format is illegal,
if the filename contains an illegal character, or if it is more than 8
EXAMINING A TAPE
The "E" command allows you to examine a tape to see that the file has been dumped correctly, and that it can be read back. This command searches the tape for the named file, then compares what it reads with the memory content.
To examine a tape:
a) Position the cassette on a piece of blank tape (i.e. a section with
no recorded signal) somewhere before the file to be examined.
b) Type E, filename <CR>.
The VDU responds with the filename.
c) Start the tape in play mode.
d) When a file is encountered, the VDU will respond with the filename and dump start address.
e) If this filename is not identical with the one specified, go back to step d).
f) If a read error is encountered, the message F(n) is printed,
indicating a filename error. The program then goes to step d).
g) If the filename is identical, then the comparison will be initiated.
h) If the comparison is correct, the program will return a cursor prompt and return to TANBUG.
i) If the comparison is incorrect three types of error may occur.
M(n) - memory error - contents of tape do not agree with
(n) is the faulty location
P(n) - a parity error occurred when reading the data associated with location (n).
C (n) - a checksum error occurred at the end of the file - (n) indicates the file end address.
contents of memory.
all cases, after printing an error, the program continues to read data. Thus if only a few errors occur, they may be checked out by reference to their addresses.
Note that in FAST speed, a VDU scroll may induce a parity error due to the time taken for a scroll. It does mean, however, that there are more errors than acceptable and the file should be redumped until error-free.
There are two files on a tape, FILEI and FILE2. You wish to
examine FILE2, but position the tape at the blank leader.
FILE2 A ;prints your filename.
FILE1 A OAOO ;Prints first filename.
FILE2 A 0400 ;prints second filename.
Or, with one memory error:
FILE1 A OAOO
FILE2 A 0400
Location 0410 is at fault.
The "E" command may be used to obtain a complete listing of the tape
contents, by rewinding the tape to the start and looking for a non-existent
filename. Note that in this case it is necesssary to exit back to
TANBUG at the tape end by using the RESET key since interrupts are disabled
in the cassette software. This procedure may also be necessary if
the examine procedure gets very badly out of step due to a large number
FETCHING A FILE INTO MEMORY
To fetch (load) a file into memory, the "F" command is used as follows
For example, typing F,FILE1<CR> looks for FILE2 -A and loads it into memory. Operating procedures and errors are exactly as detailed in the section on the examine command. Should an "M" error occur, a hardware fault is indicated because the program loads the input data to the memory location and checks it immediately afterwards.
Do not mix tape speeds on a single cassette, otherwise filename errors will occur. Though this does not affect the operation of the search, it is not Dossible to list a filename directory with a single pass.
If one program uses several different areas of memory (e.g. one area for subroutines and another for main code) it is necessary either to dump the whole area in one file, thus encompassing some redundant locations, or to dump in two files.
M(n) when examining, memory location (n) contained a different value to that read from the tape.
'when fetching, memory location (n) failed to be updated with the I value read in (hardware error).
P (n) a parity error occurred when reading the byte for location (n).
C (n) a checksum error occurred during the tape read,
(n) indicates the end of file address. Since a parity check is not infallible and will not detect two bits in error, a checksum is an additional data validity test. A checksum error will nearly always occur if a parity error occurs.
If a cb,-rk-,iim error occurs, but no parity error, I : .6
the code must be listed and visually checked to determine where the error occurs.
F (n) an error occurred when reading the filenaine (n) is meaningless.
If errors do occur, you should first try reading the tape again in case the error was due to mains borne noise. If, however, the same error persistently occurs on re-trys, the tape is likely to be in error.
READING CASSETTES DUMPED BY RAM-BASED CASSETTE SOFTWARE
XBUG software will not read files dumped by the RAM-based program described
in the TANEX manual. However, you may recover these and dump them
in the new absolute format by following the procedure below:
a) Key in the RAM-based cassette software (locations 50 to 145).
b) Dump locations 60 to 145 to cassette tape using the XBUG "D" command (locations 50-60 are used by XBUG).
c) For each file to be converted use the XBUG "F" command to fetch the RAM-based software dumped in steps a) and
d) Enter locations 50-5F by hand from the TANEX manual.
e) Read in the file in old format by following the instructions in the TANEX manual.
f) Dump the file using XBUG's "D" command. Repeat steps (c-f) for each file.
To enter the translator, type "T", followed by the address at which
code is to be entered, followed by a carriage return. XBUG prints the current program counter, and a special prompt "!" to indicate that a sub-program is being used.
Type T400<CR> ; the di-splay will then be as follows:
T400 0400 DD
The exclamation mark indicates that XBUG is ready to accept input.
To enter code to be translated, type in the instruction followed by carriage return. If the instruction is legal, it is translated,
the machine code equivalent displayed, and the program counter updated.
If it is illegal a "?" is displayed, and the program
counter remains unaltered. For example if the user inputs the INX instruction the display will appear as below:
0400 E8 INX
On the completed line, the display format is:
(Program counter) (Opcode)
(Mnemonic) (ASCII equivalent of opcode)
@-)i- example, user next types LDA $FE73<CR>
0400 E8 INX
0401 AD73FE LDA $FE73
This time, the entered instruction was a multiple byte instruction,
so three bytes of machine code were generated, three byt es of ASCII equivalents
printed, and the users program counter incremented by 3. Note that the
translator does not allow labels to be used - all addresses must be entered
as absolute values. A complete list of 6502 instructions and the
modes in which they are legal appears in the Mictotan 65 manual on pages
5-35. Instructions must be in the following format:
for implied instructions, and for all others:
Where an operand contains a numeric value (that is, all modes OR except implied and accumulator), the numeric part of the operand must be either a hex value preceeded by a $ symbol, or a single ASCII value preceeded by a The hexadecimal operand must always contain at least one hexadecimal character, and never more than 4 (two for zero page, immediate, (Indirect,X) and (Indirect),Y The following table shows the required operand format for each mode. H indicates a hexadecimal digit; A an ASCII digit.
Mode Operand Format
Immediate #$HH or #'A
Zero Page $HH or 'A
Zero Page,X $HH,X or 'A,X
Zero Page,Y $HH,Y or 'A,Y
Absolute $HHHH or 'A
Ab solute, X $HHHH,X or 'A,X
Absolute,Y $HHHH,Y or 'A,Y
Relative $HHHH or 'A
(Indirect,X) ($HH,X) or ('A,X)
(Indirect),Y ($HH),Y or ('A),Y
Note that though four hexadecimal digits are shown, leading zeros need not be typed, for example typing JMP ($5) < CR> is legal, and equivalent to JMP ($0005)<CR>.
Examples of legal instructions:
LSR A ;shift acc left
LSR $A ;shift contents of location A left
LDA #'A ;load acc with 41 Hex (ASCII A)
LDA $FF ;load acc with contents of FF
STA $50 ;2-byte zero page instruction
STA $550 ;3-byte absolute instruction
LDA ($50), Y ; Indirect, Y
LDA $5 ;load acc with contents of location 5
INY ; implied
BNE $A ;jump to location A if test true
BNE $FOOO ;jump to location FOOO if test true
Exampler, of illegal instructions:
LSR BB ;no $ before Hex opcode
LDA #'AA ;more than I ASCII argument
LDA #FF ;no dollars in front of argument
LDA #$FFF ;more than 2 characters in immediate mode
LDA ($500), Y ;argument is not zero page
LDA $10001 ;more than 4 characters in abs mode operand
INL A ;illegal opcode
LDA A ;illegal operand for this opcode
Relative mode instructions (that is, branches) must always contain a
hexadecimal address as their argument. If the branch is within range,
the correct offset is calculated and entered in memory,
otherwise an error is displayed.
An error (?) is displayed if any of the following circumstances
Illegal instruct4.on/operand format.
Branch out of rance.
Invalid operand for opcode used.
Constants may also be entered directly into memory, for example to form tables. These constants may be entered in either Hex $HH or ASCII 'A format, and must be typed immediately after the prompt. For example, the user types $AA<CR> ; XBUG responds:
0410 AA $AA 0411 DD
User then types 'A<CR> and display becomes:
0410 AA $AA
0411 41 tA
An error print will occur if the format is illegal.
Comments may be entered by typing a ";" followed by the comment,
and are ignored by the translator. For example if the user types
;THIS IS A COMMENT<CR> the display will be:
0412 DD ;THIS IS A COMMENT
Comments are not allowed on the same line as instruction/opcode entry.
A memory error printout of the form M(address) is always displayed if you try and assemble a program into non-existent memory or into memory occupied by ROM. This message also occurs if RAM is faulty and the data is not written correctly.
Three further command in XBUG's translator allow you to manipulate the user program counter either to skip over locations which you do not wish to change, or to step backwards should you wish
to correct an error. or
The * = command allows you to set the program counter to any
desired location. For example, to change the program counter
to 500 the user must type $500<CR> and the resulting display will be:
0412 DD *=$500 0500 FF
indicating that the translator is ready to accept input of location 500.
The (up-arrow) single key command decrements the program counter by I each time it is depressed. If you have made a mistake and wish to correct it, you can easily step back to the required location.
The LF (line feed) single key command increments the program counter by 1 each time it is depressed. For example, suppose the following code has been entered:
0410 A9FF LDA #$FF
0412 8550 STA $50
and you wish to change the LDA #$FF instruction to AND #$FE, hit the t key 4 times, XBUG will display:
0410 A9FF LDA #$FF
0412 8550 STA $50
Now type in the new instruction and XBUG will display:
0410 29FE AND #$FE
Now hit LF twice to increment the program counter back to 2 : 5
The ESC key, when depressed, causes an exit from XBUG's translator, and returns to TANBUG.
The following program runs through the ASCII character set, displaying each character on the screen, and resides at memory location 0400. First, enter the translator by typing T400<CR> Enter the following lines of code:
The complete program with its addresses and assembled code is now displayed
on the screen. Exit from the translator by typing ESC. Start
the program by typing G400<CR>. The ASCII character set will now
gradually be built up on the screen.
To enter the Instruction Dis-assembler, type:
I< ADDRESS>< CR>
For example, 1400<CR> dis-assembles the program given as an example in chapter 2. When the VDU screen is full, the disassembler gives you a ! prompt. You may respond to this with either < CR> , < LF > or < ESC > . Escape exits from XBUG and returns to TANBUG. Carriage return displays the next VDU page of data and pauses with a prompt at the end. Line feed displays the next VDU page of data and inhibits the pause at the end of the page, so the dis-assembler continues to operate until the BREAK or RESET key is depressed.
There are some circumstances where the dis-assembler encounters stored numbers not corresponding to a leoal opcode, for example in RAM which contains random data generated on power-up, where programs contain data tables, or where the dis-assembler has been instructed to begin from the operand part of an instruction rather than the opcode part. In this case a single byte is printed, followed by a ? to indicate an illegal opcode. Sometimes, data bytes may be translated as legal opcodes, thus disassembling the first few bytes of a program incorrectly. For example, the example program previously discussed dis-assembles satisfactorily if the command 1400 is used. However, if 1401 is used, the data at location 401 is treated as an opcode. Because this is in fact the opcode for ORA, the program dis-assembles as:
0401 OD4820 ORA $2048
0404 75FE ADC $OOFE,X
0406 68 PLA
Thus location 406 is reached before the dis-assembler gets in step
and interprets the code correctly. Care should always be taken to start the dis-assembler at a known instruction address.