DEBUG Window
Output of Assembler debug messages.
These are invoked using a special mnemonic DBG
this one naturally does not exist.

To Invoke use DB 01 as debug message invoker.
The following byte is an identifier of the message to output
to the debug window (00 - 09).
The debug messages are defined in the vectrex ini file:

DEBUG_STRING_1 - DEBUG_STRING_0 (10 Strings)
The String will be printed as is, EXCEPT below defined Labels
enclosed in '%' signs, these will be interpreted as the
labels below and the corresponding values will be printed.

Thus a Message defined like:
DEBUG_STRING_1             :"Y Pos: %6809_A%"

Will be printed as:
Y Pos: 0f

If Register A has a value of 0x0f at that precise position.

Assuming some sourcecode:

############
INVOKE_DEBUG_MESSAGE macro
 DB 1
endm

DEBUG_MESSAGE_1 macro
 DB 1
endm

PRINT_Y_POS macro
 INVOKE_DEBUG_MESSAGE
 DEBUG_MESSAGE_1
endm
                ...
handle_input:
                JSR     Joy_Digital       ; read joystick positions
                LDA     Vec_Joy_1_Y       ; load joystick 1 position Y to A
                BEQ     no_joy
                BMI     moved_down
moved_up:
; SOUTH
                LDA     pos_y           ; load current y position

                PRINT_Y_POS

                INCA                    ; look at next wall, not
                                        ; at current position

                LDB     #MAZE_X         ; times X position (position in maze)
                MUL
                ADDB    pos_x           ; add current X position
                LDX     #maze1          ; and load maze address
                LEAU    D,X             ; add them
                ...

#####################

The "PRINT_Y_POS" Makro resolves finally to:
DB 01, 01
Which are illegal opcodes. But with the emulator you can
use the above method to print messages to DBG-Out like a
ordanary printf() ...  in C.
(The most used Debug method in the whole world I guess)
The Illegal codes do NOT have any side effects.
You can use ANY of the below LABELS.

Of course the program thus created does NOT work on a real
Vectrex -> use other compiler options to circumvent that...



VOL + Ini Option
CHECK_START
CHECK_END

Ini Option
CREDITS_ENABLED

Monitor Window
--------------
The Monitor window is the most powerfull tool inside DVE for tracking
errors during development of new vectrex programs. Though it is sometimes
a hazzle to enter all the commands, they nonetheless do their job nicely.
From DVE 2.0 onwards many new features entered DVE, this probably has to do
with myself doing some programming on vectrex, so I could better judge what
was needed. I still have many ideas I might implement some day.
But that is what they are now... ideas.

You can right click within dissassembled output, to get some small help
on things, usefull or not, depends on how much I have entered yet!
(or you entered!)

The commands use sometimes arguments as STRING, you can enter a known string
instead of an address. STRINGs which are in an appropriate *.cnt file in the
DEV directory will be known. This is usefull for function/variable names.
You can enter a watch for a variable name for example.
You can generate *.cnt files for your source automatially if it is written to
be compiled with the assembler I use, since I wrote a tool for that :-)

Some of the commands below aren't overly usefull, some got stuck in some
beta phase, without stepping into a usefull phase, because at the time there
was suddenly something much more important to do... and I never went back...


Following is a list of all Monitor commands, as they are given while
typeing HELP:


Monitor Commands
BSET xxxx,yyyy           - Set processor breakpoint for addr <xxxx> after <yyyy> (optional) passes
BCLR [i]                 - Clear all breakpoints (or optional variable breakpoint <i>)
BSHOW                    - Show breakpoints
DEBUG                    - Toggle debug window
D(UMP) xxxx,yyyy         - Memory Dump from <xxxx> to (<yyyy>) optional
DR                       - Dump 6809 registers
F(IND) xxxx,yyyy <key>   - Find <key> hex or string between xxxx and yyyy
H(ELP)                   - Print this text
R(UN) xxxx               - Run the emulator from xxxx (optional)
RESET <ALL|CPU|VIDEO>    - Reset vectrex hardware
S(TEP) xx                - Single step the CPU <xx> instructions
SRUN xxxx                - Slow run & debug trace from <xxxx> (optional) (SPACE to stop)
SEQ s,yy                 - Exec <yy> steps of <s> (T=System,C=CPU,D=Display,S=Sound)
T(ICKS)                  - Display system tick counts
QUIT                     - Quit from the Vectrex emulator back to DOS
U xxxx,yy                - U xxxx yy  Un-assemble 6809 code from xxxx, yy instructions
EXIT|X                   - Exit the debug monitor
REGWIN                   - Open Register information Window
ANAWIN                   - Open Analog information Window
6522WIN                  - Open 6522 information Window
PSGWIN                   - Open AY-3-8192 information Window
SOURCE                   - Output Source code, USAGE: SOURCE xxxx, yy
B_SET string|addr ,value - Set breakpoint for reg<string>|mem<addr> on value <value>
PAUSE                    - Toggles PAUSE state
REFRESH                  - refresh windows
RECAL_CHECK [addr]       - Get number of cycles between exit and enter of wait_recal
CYCLES [set_value]       - Set or get cycles since last set
WATCH string|addr        - Create watch window for reg<string>|mem<addr>
POKE string|addr, value  - Poke <value> to reg<string>|mem<addr>
LABELS                   - Lists all valid <strings>
OVERSTEP                 - Overstep next instruction (execute, till next address reached)

To some commands I must say some additional words:

SOURCE
does it's output to stdio. So if you use it without redirecting the output
the screen becomes garbled, and... overall it isn't nice.

REGWIN
ANAWIN
6522WIN
PSGWIN
Windows pop up, which show the current information about the chip.
The information is updated constantly, so you can watch you program run.
(but some heavy slowdown must be taken)
You can point the mouse to any part of the windows and press RIGHT/MOUSEBUTTON
to get a small help on the current chip/location.

CYCLES
With no argument gives the cycles since last CYCLE reset was issued.
Otherwise (re)sets the cycle counter.
Usefull command to measure how many cycles some instructions take.

RECAL_CHECK
If called without parameter, it gets number of cycles between exit and enter
of wait_recal BIOS function. This is very usefull if you use that function
to stabilize the screen output.
If called with an address it gives the cycles one 'round' from that address to
again that address takes. (You must give a 'usefull' address)

B_SET
Second breakpount functionality, breaks also upon change of an address
or if an address contains a specific value, great for debugging!
Also, some chip parameters can be entered to be used for breakpointing,
like:
B_SET 6809_DP
The program will change the next time the DP register changes...

B_SET 6522_SHFT
The program will change the next time the SHIFT Register in VIA changes
Use LABELS for a list of known strings!

WATCH
Creates a watch window for an 8 bit memory address, the window is updated
constantly so you can allways see what's in there ...

POKE
Change the memory of the vectrex with this one...

OVERSTEP
Execute, till next address is reached!
Beware of
0 ...
1 JMP
2 ...
if you overstep jmp, the emulator waits for 2 to be reached, which may be
never!

LABELS
Here a list of hardwired labels:

CASE SENSITIVE for everything
all values unsigned for now!

6809_X                6522_ORB_0           6522_AT1C       PSG_8
6809_Y                6522_ORB_1           6522_AT2C       PSG_9
6809_D                6522_ORB_2           6522_ASHFTC     PSG_a
6809_A                6522_ORB_3           6522_APALE      PSG_b
6809_B                6522_ORB_4           6522_APBLE      PSG_c
6809_DP               6522_ORB_5           6522_PCRB1      PSG_d
6809_PC               6522_ORB_6           6522_PCRB2      PSG_imager
6809_CC               6522_ORB_7           6522_PCRA1
6809_USP              6522_IRB_0           6522_PCRA2
6809_HSP              6522_IRB_1           6522_IE
6809_NMI              6522_IRB_2           6522_I
6809_IRQ              6522_IRB_3           6522_CA1
6809_FIRQ             6522_IRB_4           6522_CA2
---------------       6522_IRB_5           6522_CB1
ANA_SIGDEF_SAMPHOLD   6522_IRB_6           6522_CB2
ANA_SIGDEF_AMUXSEL    6522_IRB_7           6522_T1L
ANA_SIGDEF_AMUXSEL    6522_IRB_0L          6522_T1C
ANA_SIGDEF_COMPARE    6522_IRB_1L          6522_T2L
ANA_SIGDEF_RAMPB      6522_IRB_2L          6522_T2C
ANA_SIGDEF_XOUTPUT    6522_IRB_3L          ----------------
ANA_SIGDEF_YOUTPUT    6522_IRB_4L          SIGDEF_AY3BC1
ANA_SIGDEF_ZOUTPUT    6522_IRB_5L          SIGDEF_AY3BDIR
ANA_SIGDEF_BLANKB     6522_IRB_6L          PSG_0
ANA_SIGDEF_ZEROB      6522_IRB_7L          PSG_1
ANA_SIGDEF_DACBUS     6522_ORA             PSG_2
ANA_XSampleHold       6522_IRA             PSG_3
ANA_YSampleHold       6522_IRAL            PSG_4
ANA_ZSampleHold       6522_DBRA            PSG_5
ANA_LastRamp          6522_DBRB            PSG_6
ANA_IntegratorOffset  6522_SHFT            PSG_7

Editing/Refreshing CNT
----------------------
The *.cnt files for a cartridge are looked for in the DEV (default) directory,
the name must be constructed like CARTRIDGE_NAME.CNT.

Syntax:

Definition from constants
#########################
EQU "snd_two" 0x43b0

code like
     LDD        #0x43b0
will look like:
     LDD        #snd_two

Definition of labels
####################
LABEL   0x0018 "start"

will do 2 things, label the given address (0x0018) with the string in "start",
and jump/branches will show "start" instead of 0x0018 (or branch offsets).

Definition of comments after code (on the same line)
#################################
COMMENT   0x0018 "; branch always to init code"

Definition of extra comment lines
#################################
COMMENT_LINE   0x0018 "; *****************************"

Define a memory region as code
##############################
CODE 0x0000 0x1000
or
RANGE 0x0000 0x1000

Define a memory region as binary
################################
DATA_BIN 0x0000 0x0020

Define a memory region as ascii
###############################
DATA_ASCII 0x0010 0x001f

The last region definition will stay active, that means:
CODE 0x0000 0x1000
DATA_BIN 0 0x039
DATA_ASCII  0 9
DATA_ASCII  0x11 0x1f
DATA_ASCII  0x25 0x37

Will first define the whole cartridge as code, than exclude region 0 to 0x39
as binary and exclude than from that region some ascii stuff.

You can edit the *.cnt file online, however you must use the refresh button
for the system to accept the changes. Overly long *.cnt files take some time
to load however...

Using the Step Window
---------------------
A new feature from 2.0b7 onward is the Step Window.
Formerly the window showed 'only' the dissassembled output of the
current cartridge. It used to be editable, not anymore so...
Since everything is beta (and perhaps will stay so) it is accessed at
some highly unlogical position :-)
To enter the step window, you have to click the small button with the
Screwdriver (if you can make it out :-)).
Than click the option create "*.as_", this will create a window which will
show the current dissassembled cartridge.

For now I have added some further buttons to the window to make
debugging a bit 'easier'.
The current location is shown in green. The current active breakpoint is
shown in red. You can navigate in the window with the usual cursor keys.
On top is a status bar, which will show some info about the current position.

The meanings of the buttons from right to left is:

Step
Overstep (execute till PC is on next instruction)
Stop/Start (toggle)
Steprun
Set Breakpoint (on current cursor position)
Go to current PC location
Open 6522 Window (toggle)
Open Analog Window (toggle)
Open Register Window (toggle)
Open PSG Window (toggle)

The monitor window will be opened and hidden, for the step-window to work,
a monitor window must in some way be active. Help is available as
in the monitor window. The dissassembled source is generated on the fly,
using the *.cnt file found in /dev.
You can also edit the *.cnt file online, you must reinit it and reopen the
step window in order for the changes to work. (beta ...)

Using the Dump Window
---------------------
In nearly the same way as the above described window, a dump window can be
opened. The dump window is updated on the fly during execution (takes time).
Shown are allways 4*16 bytes of continues memory location. You can move the
memory location using cursor and page keys. Further you can set the
'thousands' using the buttons located in the status display of the window,
editing is (as yet) not possible, use the POKE command described above.

!!!!!!!
NOTICE:
!!!!!!!
Using the (Monitor) WATCH command, uses internally a pointer to SYSTEM_MEMORY
(0-65536) of vectrex (-> not correct on chip memory, D000-D00F e.g.).

Using DUMP (window) reads memory locations thru a memory handler, this
MIGHT affect execution of the emulator in case of some HOT memory locations
(D000 -D00F).

Using the REGWIN, ANAWIN, PSGWIN, 6522WIN gives the correct current state
of the registers WITHOUT influencing them!

-> so output of these windows might be different when watching
HOT locations.


REGWIN
------

ANAWIN
------

6522WIN
-------

PSGWIN
------

SAVE/LOAD
---------
Can be done like described in the manual.
Some day I'll add some feature which will allow stepping 'backward' thru
a program, some day... perhaps...