Debugger in Emu48/Tools/Debugger...

----------------------------------This is a short description of the internal assembly debugger of Emu48.

The debugger was designed to help customers inspecting assembler code objects, a
part that cannot be handled satisfactorily by the JAZZ package. Thanks to Mika
Heiskanen and all the others supporting this great program.
After starting the debugger the emulation will stop at the current program count
er position. The emulation will continue after closing the debugger window. Plea
se remember that the clock now shows the wrong time.
1.) System Menu / Debugger Settings
This is the configuration dialog for the debugger.
In the "Disassembler" section you can switch between HP and Class Mnemonics for
the disassembler. This switch is exactly the same like in the main Settings dial
og.
In the "Symbolic" section you can setup the debugger for symbolic debugging. The
refore the debugger needs a reference file. The reference file must contain a ta
ble for converting an absolute address into a symbolic name. I decided to use th
e HP-TOOLS object files (file extension *.o) with the supported entries. These o
bject files are usually provided by HP for the HP48 and HP49 series and are nece
ssary for linking object files. In the case of older calculators you have to mak
e them by your own. Using the object file for the linker as reference has two di
sadvantages. First such an object file has an assembler specific output format,
in our case the debugger only understands the output format of HP SASM v3.x. Sec
ond, in some cases an entries has two or more different names and I cannot contr
ol which name is returned.
Example from ENTRIES.A (HP48 Supported ROM Entry Points)
=UNROT
EQU #60FAC *
=3UNROLL EQU #60FAC *
=XYZ>ZXY EQU #60FAC *
My implementation returns the last name inside the linker object file to the cho
sen address.
If you don't have the linker object file, the HP28S entry point list for example
is only distributed as assembler source file SUPROM28.A, you can simply generat
e it with
sasm -N SUPROM28.A
- Enable
With an unchecked Enable check box you can disable the symbolic debugging withou
t removing the reference file.
- Model
Each calculator model needs his own symbol reference file. The given models exac
tly corresponds to the one used in the KML script. When you opening the settings
dialog automatically the actual model is chosen in the combo box. You can switc
h to all other possible calculator models to enter the corresponding reference f
iles. When you exit the dialog with the Ok button all filenames are saved.

- Edit field
The edit field must contain the filename to the model specific symbol reference
file which is chosen by the combo box.
2.) Menu Debug
- Run F5
Continue calculator emulation under debugger control. The emulation will stop at
a breakpoint. Please remember that the emulation speed is slower than without d
ebugger control.
- Run to Cursor F6
Execute program until address at cursor position is reached. Breakpoints are sti
ll active and may stop execution before.
- Step Into F7
Execute one code instruction.
- Step Over F8
Execute a GOSUB, GOSUBL or GOSBVL as one instruction. Normally the instruction c
ursor will set to the position behind the GOSUB instruction.
But this makes trouble in the following code part:

GOSUB +
NIBASC /Hello world/
C=RSTK

The program counter will never reach the address behind the GOSUB instruction. T
he debugger solve this problem by breaking the emulation when the stack has the
same level before the GOSUB instruction. In this example the single step executi
on will continue after the C=RSTK instruction.
- Step Out F9
Continue the program until a RTI, RTN, RTNC, RTNCC, RTNNC, RTNSC, RTNSXN, RTNYES
instruction is found above the current stack level.
At some code constructions (mostly used to save space on the hardware stack) lik
e
C=RSTK
PC=C
and
C=RSTK
RSTK=C
RTN
the stop address will be wrong. The problem in both code fragments is the C=RSTK
opcode. In the first example there is no RTN instruction to stop. In the second
one the C=RSTK instruction purge the original return address and then the RSTK=

C instruction is interpreted as a GOSUB instruction.

In opposite the following code will work fine:
RSTK=C
..
code
..
GOSUB C=RSTK
RTN
RTN

<- F9 was pressed here

<- emulation will stop after this instruction

So be careful using the F9 key.

- Break F11
Stops the emulation at the current program counter position.
3.) Menu Breakpoints
- Set Breakpoint F2
Toggle a code breakpoint at the cursor position in the Code window.
- Edit Breakpoints...
You get a sorted list of all current breakpoints. When the breakpoint is checked
it's enabled otherwise it's disabled. With "Add" you can add a new or enable an
existing breakpoint, with "Delete" you can delete the selected ones. Addresses
greater than #FFFFF are cut after the fifths nibble. When adding a new breakpoin
t, you must select if this is a "Code", "RPL", "Memory Access", "Memory Read" or
"Memory Write" breakpoint.
-

"Code" stop before opcode execution on this address

"RPL" stop on the first opcode of the selected RPL address
"Memory Access" stop before reading or writing to the selected address
"Memory Read" stop before reading the selected address
"Memory Write" stop before writing to the selected address

With a left mouse button double click on a breakpoint you can toggle the check b
ox inside. When you use the space key instead, on all selected breakpoints the c
heck box is toggled.
- Clear All Breakpoints
Clear all address specific breakpoints.
- NOP3 Code Breakpoints
What are NOP3 code breakpoints? As you know user programs are loaded somewhere i
n memory and can be moved after a garbage collection. So it's very difficult to
break a user program at a hard set breakpoint with F2. To solve this problem the
debugger will stop emulation at a NOP3 opcode. So you can easily add a NOP3 com
mand into your sources to force a break condition. To enable this you have to ch
eck this item.
NOP3 and NOP3, what's the difference? The Saturn CPU has no NOP command, so NOP3
is an opcode that is three nibbles long and doesn't change a register. In the H

P SASM.DOC document two different opcodes are defined for NOP3:

Opcode 820 for HST=0 0
and
Opcode 420 for GOC + (next line)
In the assembler of the HPTOOLS 3.x package NOP3 is defined as opcode 820. The a
dvantage of the opcode is that the execution time is always the same, independen
t from the carry flag. This code is used in the HP48 ROM as well. So I decided t
o use the GOC opcode for a code breakpoint condition.
A short example how to use a NOP3 Code breakpoint:
ASSEMBLE
NIBASC /HPHP48-E/
BREAK

MACRO
CON(3) #024
ENDM

NOP3

BREAK

code breakpoint

GOSBVL =SAVPTR

save register

GOSUB +
NIBASC /Hello world/
C=RSTK

problem for step over

RPL
CODE

GOVLNG =GETPTRLOOP
ENDCODE
- CODE Object Breakpoints
If this item is checked, the debugger stops program execution at the first instr
uction of every DOCODE object which isn't located in ROM. For inspecting DOCODE
objects in ROM use address CODE breakpoints instead please.
- RPL Breakpoints
If this item is checked, the debugger stops program execution on every instructi
on called after a PC=(A) or PC=(C) opcode. This is normally the begin of a new R
PL command. RPL breakpoints use a "-R" marker instead of the assembler "->" PC p
osition marker.
4.) Menu Interrupts
- Step Over Interrupts
If this item is checked, interrupt handler code will be skipped. This option is
useful when you don't want to debug the interrupt handler. But be careful, when
you disable the interrupts all code until interrupt enable belong to the interru
pt handler code and couldn't executed in single step any more. Enabled breakpoin
ts are still active.
You can also use this option if you want to quit the interrupt handler. Just che

ck this option, press F7 for "Step Into" for stopping the debugger behind the RT
I instruction, and uncheck this option again.
5.) Menu Info
- Last Instructions...
This is a short viewer for the last 255 executed CPU addresses. The disassembled
opcode maybe wrong, because only the CPU address of each command was saved and
memory mapping may have changed meanwhile. In the "Last Instructions" dialog you
can copy selected lines to the clipboard or clear this list.
- Profiler...
This opens a small toolbox window which shows the number of CPU cycles and the c
orresponding execution time of the instruction sequence between the last two bre
akpoints. The CPU cycles are only approximate values, the real cycles are depend
ing mostly on the used ROM to Saturn CPU core interface.
- Write Only Registers...
Some of the display registers have a different meaning on reading and writing. T
his dialog shows the data written to the write only I/O registers.
6.) Code window
This windows shows you the disassembled code. The line with the current PC is ma
rked with a "->" or "-R" between the address and the disassembly.
You can use the UP, PAGE UP, DOWN and PAGE DOWN keys to scroll the window conten
t. There is one strange behavior, when you move to higher addresses the debugger
is able to disassemble the next line correctly, but when you move to cursor to
lower addresses the debugger does not know if this address is at the begin or in
side of an opcode. In result you get wrong disassembled lines.
Context menu pressing the right mouse button:
- Go to address... G
Moves the cursor to the specified code address. Therefore you can enter a hexade
cimal number or the symbolic reference name.
- Go to PC
Sets the cursor to the actual position of the PC.
- Set breakpoint F2
Toggle a code breakpoint at the cursor position in the Code window.
- Set PC to selection
Set the PC to the cursor position. Be careful with this command, you change the
execution order of the commands!
- Find
Search in the mapped CPU address area for an address which contain a PCO (Primit

ive Code Object) header. The disassembled code of this address is shown in the C
ode window.
- Previous PCO
Search for a PCO before the address shown in the first line of the Code window.
- Next PCO
Search for a PCO behind the address shown in the first line of the Code window.
7.) Register window
Here you can see the actual contents of the CPU registers. The values are only u
pdated at a program execution stop. All changed CPU registers are highlighted.
With the left mouse button you change the content of the register. On bit regist
ers, like CY and Mode, the state change immediately without any request.
8.) Memory window
This windows shows the memory content in the selected context.
You can use the arrow, PAGE UP and PAGE DOWN keys to move the cursor to a memory
position, the + and - keys change the memory position by one nibble under the c
ursor. With a double click on the left mouse button (only in Map mode) you can c
hange the content of the two addresses. When the memory position is read only (R
OM or write protected RAM) the content wouldn't change.
Context menu pressing the right mouse button:
- Go to address... G
Moves the cursor to the specified memory address. Therefore you can enter a hexa
decimal number or the symbolic reference name.
- Go to PC
Sets the cursor to the actual position of the PC.
- Go to D0
Sets the cursor to the actual position of the D0 register.
- Go to D1
Sets the cursor to the actual position of the D1 register.
- Go to Stack
Sets the cursor to the return address placed in the top level of the stack.
- Follow
Follow is a Pop-up menu to change the address behavior of the memory window. Nor
mally the address of the memory window is static and only change by entering a n
ew address. With Follow the memory window view follow the content of a selected
address or register. In follow mode the memory window is only updated after an e

mulation step.
- Follow none
This is the default mode. The address of the memory window is static.
- Follow Address Content
This is a special mode of indirect addressing. You can specify an address which
content will we interpreted as memory pointer. The memory window follow this mem
ory pointer.
- Follow Register PC/D0/D1
The Memory window follow the content of the selected register.
- Find... F
Calls the "Find" dialog box, allowing you to search for a data sequence in hexad
ecimal or ASCII mode. The search area is selected by the memory view Mapping mod
e described in the following section. If the data sequence is found the Memory w
indow and an opened "RPL Object Viewer" window will be updated.
With the button "Previous" you can search for the previous and with the button "
Next" you can search for the next occurrence of the data sequence.
When you close the "Find" dialog box, you will loose all saved strings in the da
ta combo box.
- Mapping
Mapping is a Pop-up menu to select the memory view of the Memory window. Normall
y the CPU see only 512KB of the total memory, the rest is banked or covered by o
ther modules. The following menu entries select the memory chip connected with t
he chosen Chip Select signal of the MMU. The connections are calculator model de
pendent.
- Mapping Map
This is the default mode. Here the Memory window shows what the CPU see. In this
mode you can also change the memory content of writeable memory.
- Mapping NCE1/NCE2/CE1/CE2/NCE3
Here the Memory window shows the content of the selected Chip Select signal. The
content is showed in a linear address model and it's content can't be changed i
n this mode.
Here's a comparison of the mapping of the emulated calculator models:
Abbreviations: ROM
RAM
Flash
Slt
BS
nc.

=
=
=
=
=
=

Read Only Memory

Random Access Memory
electrical reprogramming ROM
Memory Card Slot
Bank Switcher (no memory)
not connected

| HP38G
| HP39/40G | HP48S/SX
| HP48G/G+/GX |
HP49G
----------------------------------------------------------------------------NCE1 | ROM 512KB | ROM 1024KB | ROM
256KB | ROM
512KB | Flash 2048KB

NCE2
CE1
CE2
NCE3

|
|
|
|

RAM 32KB | RAM 128KB

nc.
| BS
nc.
| nc.
nc.
| RAM 128KB

|
|
|
|

RAM
32KB | RAM 32/128KB | RAM
Slt1 32/128KB | BS
| BS
Slt2 32/128KB | Slt1 32/128KB | RAM
nc.
| Slt2 32KB-4MB | RAM

256KB
128KB
128KB

- Load Memory Data...

The "Load Memory Data" dialog box allows loading memory dump files to the specif
ied address inside the Saturn address area. The specified address must point to
RAM, writing into ROM areas isn't possible. The memory dump file must be in pack
ed data format, meaning each byte in file contain two Saturn data nibbles with t
he low nibble containing the even and the high nibble the following odd address.
The disadvantage of packed files is that you cannot load memory files with an o
dd number of data nibbles, but the advantage is that you can directly load an as
sembler output to memory.
- Save Memory Data...
The "Save Memory Data" dialog box allows saving the data of the specified Saturn
address area into a memory dump file. The memory dump file contain the data in
packed data format, meaning each byte in file contain two Saturn data nibbles wi
th the low nibble containing the even and the high nibble the following odd addr
ess.
- RPL Object Viewer...
This opens a small toolbox window showing the decompiled RPL object in the selec
ted memory map mode at the memory address marked by the cursor. If the toolbox w
indow is already open the content will be updated. There's a problem if you want
to select an address inside the marked two addresses. The easiest way to switch
the address is the use of the + and - keys changing the memory position by one
nibble under the cursor.
9.) Stack window
The content of the hardware stack is viewed here. In "1:" is the current return
address. A double click on an item shows the address content in the Code window.
Context menu pressing the right mouse button:
- Push
Push a new element before the current selection onto the stack.
- Pop
Pop the selected element from the stack.
- Modify
Modifies the stack content of the current selection.
10.) MMU window
The configuration of the memory controllers is viewed here. The viewed addresses
are the first address of each module area and may differ from the given address
in the CONFIG command.

This example
LC(5) #C0000
CONFIG
LC(5) #98765
CONFIG

128KB size
start address of module

will config a 128KB module at address #80000 and not at the given address. So th
e MMU viewer will show you the address #80000.
11.) Miscellaneous window
The Miscellaneous window show you the internal state of the interrupt flag, the
1ms keyboard handler and the contents of the Bank Switcher latch. The Bank Switc
her item is only enabled on calculators with a latch inside. You see the loaded
value of the address lines A6-A0. You have to ignore the last bit (A0), because
it isn't wired to the six bit latch.
You can change the values by pressing the left mouse button over the old content
.
01/09/13 (c) by Christoph Gieelink