FOREWORD
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
be selected).
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
S)
% 103 2000FO R $FOOO I,-Ns
106 2027FO $FO27
109 68
-,Ntt
IOA 48 PH@ S C-(
k IOB 2066FO $Fk
c c> rx
IIF 68
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
Aco
6 Clki As %&
11B 20CBFO-- JSR $FOCB
IIE AA TAX
@@LA
11F 68
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:
D400,410,FILE1
FILE1 A
3
· 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
characters long.
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.
address.
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.
Example
There are two files on a tape, FILEI and FILE2.
You wish to
examine FILE2, but position the tape at the blank leader.
E,PILF,2
FILE2 A ;prints your filename.
FILE1 A OAOO ;Prints first filename.
FILE2 A 0400 ;prints second filename.
;comparison correct.
Or, with one memory error:
E,FILE2
FILE2 A
FILE1 A OAOO
FILE2 A 0400
M0410
Location 0410 is at fault.
Ta-
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
of errors.
FETCHING A FILE INTO MEMORY
To fetch (load) a file into memory, the "F" command is used as follows
F,<FILENAME><CR>
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.
ADDITIONAL REMARKS
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.
ERROR MESSAGES
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
b).
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:
T400
0400 E8 INX
0401 DD
On the completed line, the display format is:
(Program counter) (Opcode)
(Mnemonic) (ASCII equivalent of opcode)
@-)i- example, user next types LDA $FE73<CR>
T400
0400 E8 INX
0401 AD73FE LDA $FE73
0404 DD
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-9 to
5-35. Instructions must be in the following format:
<OPCODE><CARRIAGE RETURN>
for implied instructions, and for all others:
<OPCODE><SPACE><OPERAND><CARRIAGE RETURN>
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
(Indirect)
($HHHH) or
('A)
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
occur:
Illegal instruct4.on/operand format.
Branch out of rance.
Invalid opcode.
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
0412 DD
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
0412 DD
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
0414 DD
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
0414 00
0413 50
0412 85
0411 FF
0410 A9
Now type in the new instruction and XBUG will display:
0412 85
0411 FF
0410 29FE AND #$FE
0412 85
Now hit LF twice to increment the program counter back to 2 : 5
location 0414.
The ESC key, when depressed, causes an exit from XBUG's translator,
and returns to TANBUG.
Example Program
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:
LDA #$D
PHA
JSR $FE75
PLA
SEC
ADC #$O
LDX #$FF
LDY #$FF
DEY
BNE $40E
DEX
BNE $40E
BEQ $402
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.