Home
Up
Quick Guide
Main Manual
Tanex Manual
XBUG Manual
BASIC Manual
Magazines

This manual was scanned and OCRed by Fabrice Frances.  I will tidy it up and add diagrams when I get time! 

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.
 

Chapter 1

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.
 
 

Chapter 2

The translator program allows you to enter programs in 6502 mnemonic assembly language.  The translator verifies that the
entered instruction is legal, and if so transfers it into machine code and puts it into memory.  The user program counter is auto-
matically incremented by the correct amount for the instruction entered.
 

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.
 

Chapter 3

The instruction dis-assembler performs the converse function to that performed by the translator, that is it reads machine code locations stored in memory and displays them as mnemonic instructions and opcodes.

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.