ftp.whtech.com/ftp.whtech.com.tar/ftp.whtech.com/Geneve/9640news/CAT14/SBUGMC.ARK

Text File | 2006-10-19 | 16KB | 283 lines

?
Using SBUG to DEBUG your Assembly Programs

    This tutorial will describe how to use the TI SBUG program to debug your
assembly language programs. Although specificly written for SBUG the principles
apply to the other debugers on the market. As I am sure you have already
discovered, the familiar error messages and helps are not available from
Assembler that you are accustomed to from BASIC.  I know many of you have typed
in my first tutorial or used one of the beginning assembly language books on
the market and had difficulty getting the program to run properly.  Take heart,
we all had the same problems when we were learning and until you master the use
of one of the debuging programs your you can pull your hair out and may
eventually give up.
    As I have already mentioned there are several very good debug programs
available for the TI. Here they are briefly. DEBUG is the program supplied with
your editor assembler cartridge.  It has many helpful features particularly the
ones that allow you to set CRU bits, move memory, and compare memory. My main
criticism of DEBUG is it's inability to single step through instructions.
BUGOUT written by Gregg Wonderly is also very good. It offers multiple fields
of information on the screen at the same time. Many advanced features like
dumping to disk. Without a doubt the most advanced that I have used. My main
criticism is that it maps the VDP to text mode which interferes with VDP
mapping for the screen image table and color table if you need to inspect these
locations in your program.  The one I use the most is SBUG. This is the super
debuger released by TI to users groups after the pull out. If you need a copy
I'll upload it to access.  SBUG allows you to operate from graphics or bit map
mode, single step, and output to printer or disk.  Let's get down to how to use
it.
    First you should print out the instructions supplied with SBUG on the disk.
Since this is a display/variable 80 file you may print it out with TI-Writer or
Editor/Assembler editor.  This help file covers all of the instructions
available. I intend to cover only the ones of greatest interest to us.
    It's important to know where your assembly program loads into memory.  With
some few exceptions which won't be discussed now, your program will load into
high memory expansion at >A000.  That's the first address in high memory. You
can make your program load in other places but that is beyond the scope of this
tutorial. SBUG is what we call relocatable object code. It loads on top (not
over) of the last program entered. In other words, if your program is 500 bytes
long it would load from >A000 to >A500. SBUG when loaded will load beginning at
>A502.
    I've included a brief program in this tutorial which puts characters on the
screen. We'll use it to illustrate how to use SBUG. Go ahead at this time and
type it in using the editor, save it, load the assembler except this time at
the LIST FILE NAME prompt enter your printer description. Remember if you are
using a PIO printer it should be entered with a period following PIO. At the
OPTIONS prompt enter RLS. R to tell the assembler that you used R in front of
your registers in the source code, L to give you a source listing to your
printer, and S to give you a table of the symbols you used. This source list is
necessary for using SBUG effectively.
    Let's examine the source listing columns for a moment. Here's an example
line from the source listing:

0049 006C 0201      LI  R1,>5500
     006E 5500

Here's what that tells us. 0049 means this statement is number 0049 in our
source code. That means if we received the message invalid register in line
0049 when we were assembling the code we could look at line 0049 and see what
was wrong with R1. The next field over is the most important one to us when
using SBUG. This gives us the exact location in memory where this instruction
resides. If this was the first program you loaded into memory then this
instruction would reside at >A06C. Remember I told you that the program loads
at >A000 by default? In other words >A000 plus >006C=>A06C.  We'll come back to
this field shortly.  The next field >0201, is the machine language mnemonic for
Load Immediate (LI). Look on page 5 of your blue editor/assembler card. See the
opcode >0200? This tells us the instruction for this OPCODE is LI. The 1 in
>0201 tells us to load immediate R1 with the value in the next word of memory.
In this case Load Immediate R1 with >5500.  See how easy that is? For a
detailed description see section 15.4 in the E/A manual.
    We're ready to get down to business. First load the object code for the
program I have given you into the computer. You should *always* load your
program before you load SBUG. Next before you press enter after you have loaded
the demo program load SBUG. One note here. As long as you are not using the X/B
cartridge to load with, it is much faster to load the compressed version of
SBUG or SBUGC as it is listed on your disk. Both do the exact same job. Press
enter and for the program name enter SBUG. The SBUG title screen should come
up. The message on the screen will ask you if you are using a bit map screen?
Enter N at this prompt.  Next you will be asked for your list device. Enter
your printer description here (you could enter DSK1.FILENAME instead if you
wanted output to disk). The input prompt is a '.' . At the prompt enter L to
turn off the list device. Our program runs from SBUG's control so we need to
set up SBUG to run our program so we may interact with it. To do this we must
tell SBUG where the first executable instruction (entry point) to our program
is and what address we are using for a workspace.  You may remember there are
three hardware registers used by the 9900 CPU in the TI-99. These are the
program counter, workspace register, and status register. The program counter
always points to the next instruction to be executed in memory. The workspace
register points to the current 32 bytes (16 words) of memory we are using for
workspace. The status register contains the current status of the computer as a
result of the last instruction executed. Given that, we now need to find the
entry point to our program.  There are two basic ways to do this.  Perhaps the
easiest is to look on the source listing at the label (in the example program
START) we placed in the DEF statement at the beginning of the program and get
the address directly from the source listing. The alternate way is to use the M
command of SBUG to examine memory. The memory we need to examine is the
Reference/Definition (REF/DEF) table approximately from >3F30 to >4000. This
table lists the entry point to the program and the utilities we referenced.
Here's how to examine this table.
M 3F30,3FFF  <enter>
This command will scroll the contents of these memory locations to the screen.
In this case we are looking for the program name which is START. When you see
START press any key to stop the scroll. You should see a line of memory which
looks like:

3F30=5354 4152 5420  START
3F36=A058 .... ....

Press FCTN X to abort the listing or any command. Since labels may be up to 6
characters (bytes) long, the seventh and eighth bytes contain the program entry
point.  In this case >A058. This should be the same address on the source
listing.  *Remember* SBUG always displays and only accepts HEX numbers.
    Next we need the workspace address.  We obtain that from the source
listing.  In this case it is >A05C. We get this by finding the label for our
workspace, in this case WS. We look at the second column and there is the
beginning of the workspace.
    We're now ready to set up the hardware registers to run our program.  We do
this by entering a R at the prompt. SBUG responds with W=0000. W is the
workspace address. In this case type A05C and press the <space bar>.  That
calls up the prompt P=0000 for program counter address which in this case is
A058. If you press space again you could set the status register but this is
unnecessary in this case so just press enter. We've now told SBUG where our
program resides in memory and where the workspace is.
    To make it easy to figure the offset of our instructions we have a bias
command. Press X and the computer displays 0000 press A000 <enter>.  This sets
the value of X to >A000. Now let's get down to examining our program in memory.
To do this we set breakpoints (just like BASIC) at the instruction where we
want to stop.  Ready to set one? At the prompt press B 68X <enter>.  This
automatically adds the A000 offset to the instruction at 0068. You could have
just entered it as B A068 if you wanted to add the offset yourself.  This tells
SBUG to interrupt the program before it executes LI R0,>390.  See where I got
that? Look at the second column on your source listing and go down it until you
find memory location 0068. Now if you want to see where your current
breakpoints are press B <enter>. Now to execute the program up to that
instruction press E <enter>. The screen will show three addresses across the
screen. From left to right they are the workspace address, program counter
address, and status register. Now we're ready to single step through some
instructions.  Enter S for single step at the prompt.  This displays the
following:
A068=0200  LI R00,>0390

A068 is the memory address for the instruction. Remember what 0200 is? LI R0.
Then there is the plain text instruction. What value should be in R0? >0390 of
course. To check this press W 0 <enter>. This shows the current contents of R0.
If you ever have the need you may change this value by entering another value
before pressing enter. If you press the space bar you see the next register R1
and so on. One important point. Never try to single step thru VDP, GROM, or
KSCAN routines.  There is a good chance you will lock up the computer. When you
encounter one of these instructions just set a breakpoint (B) on the other side
of it and execute (E) around it.  Now press B 80X or B A080 <enter> at the
prompt.  This sets the breakpoint at the INC R0 instruction.  Press E <enter>.
What's the value in R0? It should be >383 from instruction >A082.  Now press S.
The INC R0 instruction appears. Again check the value in R0 (remember W0), it
should be >384.  See how you may interact directly with the computer? Press S
again and you see the CI instruction.  Press S again and you get:
JNE      $+>00FA
   JMP TO A07C
This says to jump to A07C (LOOP2) if R3 is not equal to zero. Now set B A0CE.
Press E <enter> to execute. The program stops at the MOV @SAVRTN,R11
instruction. Let's examine some VDP RAM. To do this we use the M command again
but proceed the address with a V for VDP access. Press M V168,1AF . This shows
the screen image table from decimal 360 to 431 where we put our text and ball.
Examine the bytes carefully and you should see the border characters. Note: The
screen is not exactly as we had it because SBUG shares the same screen with us
and we're seeing some of SBUGs screen also.  Now press M VBF8,C00 <enter>. This
is the pattern descriptor table where the shape of our ball is stored. Compare
it with PATRN from the source listing and ten press M A022,A028 to see the
pattern description as it resides in CPU RAM.
    Well I've gone long again but there is so much to cover. You really need to
get the hang of using SBUG, it allows you to interact with your program to see
exactly what is going wrong when you have a problem. It will save you many
hours of grief.

*****************************************
*                                       *
* This program accompanies tutorial #4  *
*   on using SBUG. It also shows you    *
*   how to redefine characters, place   *
*   them on the screen, and change the  *
*   color of each character set         *
* Entry Point -> START                  *
* Must be run from E/A or MM Load & Run *
* R0-R2 Used for general VDP access     *
* R3 Used as a general purpose counter  *
* R11 contains the return address on    *
*     entry.                            *
*                                       *
*****************************************

       DEF  START        DEFINE THE ENTRY POINT OF THE PROGRAM
       REF  VMBW,VSBW,VWTR SYSTEM UTILITIES WE WILL USE

* DATA STATEMENTS *

SAVRTN DATA 0            SET ASIDE A WORD OF MEMORY TO SAVE THE RETURN ADDRESS
BORDER DATA >8080,>2020,>2020,>2020 CHAR >80 WILL BE OUR BORDER
       DATA >2020,>2020,>2020,>2020
       DATA >2020,>2020,>2020,>2020
       DATA >2020,>2020,>2020,>8080
PATRN  DATA >3C7E,>FFFF,>FFFF,>7E3C

STATUS EQU  >837C        LOCATION OF THE GPL STATUS BYTE
*                        THIS EQUATES THE LABLE STATUS TO THIS ADDRESS
WS     BSS  >20          SET ASIDE 32 BYTES OF MEMORY FOR OUR WORKSPACE

MSG    TEXT 'THIS IS A TEST' 14 BYTES LONG
       EVEN              FORCES THE PROGRAM COUNTER TO AN EVEN MEMORY ADDRESS.
* AS A GENERAL RULE ALWYS USE EVEN AFTER THE LAST BYTE, BSS, OR TEXT OPCODE.

START  MOV  R11,@SAVRTN  MOV THE ADDR IN R11 TO THE WORD OF MEMORY AT SAVRTN
       LWPI WS           TELL THE HARDWARE WORKSPACE REGISTER WHERE YOUR WS IS

*--PUT A BLUE BORDER AROUND THE SCREEN--*

       LI   R0,>0705     07 IS VDP REG 7 OR THE SCREEN BACKGROUND COLOR
       BLWP @VWTR        05 IS THE BACKGROUND COLOR. (LT BLUE)
* THIS SETS THE TOP AND BOTTOM OF THE SCREEN TO LT BLUE.
* SEE SECTION 16.1 E/A MANUAL FOR MORE INFORMATION ON VWTR.

* NOW SET CHAR >80 (128 decimal) TO A BLUE ON BLUE SQUARE
       LI   R0,>390    THIS IS THE POS IN VDP RAM COLOR TABLE FOR CHARS >80->87
       LI   R1,>5500   BLUE FOREGROUND/BACKGROUND IN MSB OF R1
       BLWP @VSBW      REMEMBER R0 ALWAYS IS THE ADDR IN VDP. R1 ALWAYS CPU.
* SEE SECTION 21.2.2 FOR MORE INFORMATION ON THE COLOR TABLE

* NOW LET'S MAKE ALL THE CHARACTER SETS BLACK ON WHITE

       LI   R0,>383      START WITH CHAR SET >18
       LI   R1,>1F00     1=BLACK FG, F=WHITE BKGND
LOOP2  BLWP @VSBW
       INC  R0           POINT TO NEXT VDP RAM COLOR TABLE ADDRESS
       CI   R0,>390      LAST COLOR TABLE ADDRESS (CHARS >78->7F)
       JNE  LOOP2

* NOW WRITE THE BORDER TO THE SCREEN AND CLEAR THE SCREEN AT THE SAME TIME

       LI   R3,24        24 ROWS TO WRITE
       CLR  R0           BEGINNING OF SCREEN IMAGE TABLE
       LI   R1,BORDER    ADDRESS OF ONE ROW OF BORDER DATA
       LI   R2,32        32 BYTES TO WRITE
LOOP   BLWP @VMBW        WRITE A ROW
       AI   R0,32        POINT TO BEGINNING OF NEXT ROW
       DEC  R3
       JNE  LOOP

* NOW WE'LL PUT THE MESSAGE ON THE SCREEN CENTERED
* REMEMBER THAT THE SCREEN IMAGE TABLE IS FROM 0 TO 767 IN VDP RAM
* TO DETERMINE THE ADDRESS FROM ROW AND COLUMN WE USE THE FOLLOWING FORMULA
* ADDR=((ROW-1)*32)+(COLUMN-1) IF WE WANT OUR MESSAGE AT ROW 12 COLUMN 9 THE VDP
* ADDRESS WOULD BE 360

       LI   R0,360       VDP ADDRESS IN SCREEN IMAGE TABLE
       LI   R1,MSG       ADDRESS OF THE DATA IN CPU RAM
       LI   R2,14        14 BYTES LONG
       BLWP @VMBW        WRITE IT TO THE SCREEN

* NOW SUPPOSE WE WANT TO MAKE CHAR >7F A BALL SHAPE AND PLACE IT UNDER THE TEXT
* THE PATTERN TABLE IN E/A IS LOCATED AT >0800. TO CALCULATE THE LOCATION OF A
* PARTICULAR CHARACTER MULTIPLY IT'S HEX VALUE BY 8 AND ADD THE RESULT TO >800.

       LI   R0,>0BF8     (>7F*8)+>800=>BF8
       LI   R1,PATRN     PATTERN TO DEFINE >81 TO FROM CPU RAM
       LI   R2,8         PATTERNS ALWAYS 8 BYTES
       BLWP @VMBW        >81 IS NOW THE SHAPE OF A BALL

       LI   R0,431       SCREEN IMAGE TABLE TWO ROWS BELOW TEXT CENTERED
       LI   R1,>7F00     WRITE >81 (BALL) TO THE SCREEN
       BLWP @VSBW        PUT IT UP

* EXPERIMENT WITH THIS PROGRAM UNTIL YOU ARE COMFORTABLE WITH VDP RAM ACCESS

       MOV  @SAVRTN,R11  RESTORE R11 TO THE ADDRESS YOU WISH TO RETURN
       LIMI 2            ENABLE INTERRUPTS SO QUIT KEY WILL WORK
       JMP  $            LOCK UP THE COMPUTER (SAME AS 100 GOTO 100)
       RT
       END




Download complete.  Turn off Capture File.