RApid I nteractive Debugger

RApid Interactive Debugger
RAID - RAPID INrERAcrIVE DEBf]G;ER
version 1.1
REFERENCE MANUAL
Revision A
May 30, 1980
Copyright 1980 vector Graphic Inc.
Copyright 1980 by Vector Graphic Inc.
All rights reserved.
DisclaiIrer
Vector Graphic makes no representations or warranties with respect to the
contents of this manual itself, whether or not the product it describes is
covered by a wa rran ty or repair agreerrent. Further, Vector Graphic reserves
the right to revise this publication and to nake changes from time to time in
the content hereof without obligation of Vector Graphic to notify any person of
such revision or changes, except when an agreement to the contrat:y exists.
Revisions
The reV1SlOO letter such as A or B changes if the MANUAL has been improved but
the POODUcr itself has not been significantly rrodified. The date and revis ion
on the Ti tle Page corresp::>nds to that of the page rrost recently revised. When
the product itself is modified significantly, the product will get a new
revision number, as shown on the manual's title page, and the manual will
revert to revision A, as if it were treating a brand new product. EACH MANUAL
SHOULD ONLY BE USED wrm THE PRODUcr IDENI'IFIED CN 'IHE TITLE PAGE.
FOREWJRD
Audience
S<:q?e
Organization
This manual is intended for ASSEMBLY
LANGUAGE progranurers. It assurres an in
depth kncwledge of t..l)e ZaD CPU and the
Vector Graphic computer, as well as
familiarity with the CP/M operating system.
This manual will describe the features
and canmands of Vector Graphic I s RAID Rapid Interactive Debugger - an advanced
full-screen simulator/debugger.
As a reference manual, it is not intended to
be a training nanual for novice programrrers.
Chapter I reviews the implications of
RAID in the context of the Vector canputer
system and of the CP/M operating system.
Chapter 2 discusses the structure of the
deoogger in general. Chapter 3 gives
each of the commands offered by RAID,
listing them alphabetically.
Vector
RAID
Loading
RAID
Reference Manual
RAID
[<d:filename>.HEX]
Load RAID for screen at FOOOH and load
<filename> as in Disk operations below.
Load file operations
L
<d:filename.file~>
L
<d:filename>.HEX
Load file fram disk at OIOOH.
Load HEX file fran disk at its cwn load
address (not necessarily OIOOH) and
convert to executable format.
Transitions
Set PC to <address>.
Go to <address> and execute (RAID not in
control) •
Qui t RAID; return to calling system.
Go to Extended Systems Monitor executive.
Initialize screen (clear off extraneous
material) •
P <address>
G <address>
Q
<ESC>
I
Execute under RAID control
XS [<rate>]
XF [<rate>]
XP
[<rate>]
XN
[<address> <address> ••• ]
Execute slow and refresh entire screen.
Higher <rate> slows execution speed.
Execute fast and refresh entire screen.
Higher <rate> speeds execution.
Execute fast and refresh partially (only
registers and stack).
Higher <rate> speeds execution.
Execute with refresh only at given addresses
(4 max).
XD [<address> <address> ••• ]'
XI <hex instruction>
maximum. )
Single step: execute instruction at PC with
full screen refresh.
Execute direct and return
<TAB>
<LF>
Rev. l.l-A
Execute direct (no simulation), with hard
breakpoints at given addresses (max 6).
ExeOJte <hex instruction~ imrrediately (4 bytes
5/30/80
Vector RAID Reference Manual
Halts during simulation
-
HM <address> <byte>
Halt when PC = <address>.
Hal t when exeOlted cpcode = <opcode>.
Halt when <register> or <register pair> =
<value>.
Halt when contents of <address> =.<byte>.
DA <address> [<line>[-]]
Dump
HP <address>
HO <opcode>
HR <register or pair> <value>
ASCII, beginning at <address> in
<line> [-] limits
applicable portion of display area.
Dump hex, as described for DA.
rrerrory display area.
DH <address> [<line>[-]]
Enter
<address> <byte> <byte>
<address> <char> <char>
ER <register or pair> <byte
or 'WOrd>
EH
EA
Put <byte>s in mem:>ry <address>.
Put ASCII characters in rrerrory <address>.
Put <byte or word> in <register or register
pair>.
Stack
SS <address>
SC
SH <2 byte word>
Set start of stack displayed on screen.
Clear extranecus naterial fran stack display.
Pop word (2 bytes) off stack.
Push 'WOrd onto stack.
?
Display HELP screen at any time.
SP
Fill
F <start address> <end
address> <byte>
Fills working memory fram the start address to
the end address wi th the byte specified.
Rev. l.l-A 5/30/80
Vector RAID Reference Manual
P flags****
canmand
instruction area:
2 instructions just exeOlted, then
Olrrent instruction, then the
4 follcwir¥!1 instructions
A
B
C
0
E
format of each line is:
instr ASCII address code
H
c;:erands ·L
*
contents
of regs.
and of
IIeIlOrJ
p:>inted
to
P' flags
AI
*
BI contents
C' of regs.
D' and of
E' m:mory
H' pointed
L' to
halt area:
O:opcode
dlJItt) area:
~
of 6 different blocks of nerory
Each line can be ei ther ~CII or Hex dump.
P: instr.
M:rrem:)l:Y
X
stack
reg.
pter.
stack
Y
reg.
I
reg.
(**)
halt
cause
refresh area:
Rf: refresh
addrs's
***
* contents of the A and AI registers include the ASCII equivalent
(di) ITeans interrupts are disabled. (ei) ItEaIlS they are enabled.
*** address of current refresh is highlighted.
**** flag syni:lol appears when flag is set •.
**
RAID Display
Rev. l.l-A 5/30/80
vector RAID Reference Manual
Rev. l.l-A 5/30/80
Vector RAID Reference Manual
TABLE OF CCNTENTS
. Page
Section
SUImal:Y of RAID Ccnmmds
RAID Display
Table of Contents
I•
Perspective
1.1
1.2
1.3
II.
The value of RAID
The ra.n;e of RAID
Protocol used in this manual
1-1
1-3
1-4
The Structure of RAID
2.1
2.2
2.3
2.4
2.5
2.6
2. 7
2.8
2 •.9
2.10
Wading RAID
A RAID
session
'!he RAID display
Comrand area
Instruction area
rump area
Flags and registers
Stack pJinter arx1 stack
Halt area
Refresh area
III. RAID Commands
Rev. 1.1-A
5/30/80
2-1
2-3
2-4
2-5
2-6
2-7
2-8
2-9
2-10
2-11
Vector RAID Reference Manual
Rev. l.l-A 5/30/80
Vector RAID Reference Manual
I. PERSPECrIVE
1.1 The value of RAID
Vector Graphic's rrem:)l:Y rrapped systems, such as the System B, offer p:JWerful
capabili ties for the assembly lan:Juage pro;jtdlllUer, capabili ties' not available
on other small general purpose computers. SCOPE, Vector's sophisticated
screen-oriented prcxjram editor is a lmiquely efficient teol. With the addition
of RAID - the Rapid Interactive Cebugger -, Vector IS nerot:y mapped systems reach
a level of sophistication for assembly language software development that
rivals true micrcprocessor develcprrent systems.
The program to be deblgged is called the "target program". RAID can deblg a
target consisting of any valid Z-80 operations. The use of MID allcws the
programmer to execute the target program instruction-by-instruction, while
viewing the effect on the CPU and memory. The status of the CPU and
significant parts of remory are displayed constantly on the screen. This
process is called "simulation'" because RAID takes each instruction out of the
target program in order, executes it, and then displays the result of the
operation in the status display on the screen. RAID is actually in control of
the systan, but the user only sees on the screen what ~uld l:e happening if the
target program were running by itself in the system. During simulation The
presence of RAID in the system is transparent to the cperator, except for the
t::eriodic refresh~ of the status display on the screen.
S:i.Irulation is the heart of RAID., All RAID operations revolve aromd the use
of simulation to debug progams. By seeing the state of the CPU and m:nory
after each instruction is executed, the PLOgtdlllUer can firo the instruction or
routine which causes unexpected effects. There are also RAID commands for
changing small sections of PLCYldlll" memory in general" or CPU registers, in
order to determine the effect·, but simulation is the main purpose for using
RAID.
The fast menoz:y-rtapped screen used- in Vector Graphic systems enables RAIDI s
tmique fom of full-screen status display. After the exeOltion of each target
instruction is simulated, the current state of all registers, alternate
register, flags, alternate flags, index registers, the stack, the stack
pointer, six selectable blocks of rnenory, the last b.o instructions silnulated,
the instruction abcut to be simulated, and the four following ins tructions.
The user can re-define the location of each of the six selected blocks of
merrcry at any tilre, and can also cause each of them to appear in either hex or
ASCII representation. The portion of the stack displayed can also be
selected.
Further, instructions are disassembled as they are displayed, using Vector's
8080-superset Z-80 mnerronics. The ASCII equivalent of each opcode and q;:erand
also appears, in case the codes in fact- represent ASCII characters.
Rev. l.l-A
5/30/80
1-1
Vector RAID Reference Manual
The most significant aspect of this simulation process is that the entirety
of ~is information is refreshed on the screen instantaneously (unless
supressed) after each instruction I s simulated exeOJtion. Most of the screen is
used, except for the lcwer 6 lines which are reserved for the target program to
display video massages.
This use of the full screen for system status can only J:::e accanplished with
rnenory-mapped video, a Vector Graphic hallmark. It is a pJWerful departure
from the single line status display of development systems using serial
tenninals. Since the status of rrost. important asr:ects of the system are on the
screen all the t.iIre, the user does not have to repeatedly request status on
various aspects e This significantly reduces the development time of new
software.
The user is given a I'l\.lll'Cer of ways to siIrulate exeOltion of a program under
control of RAID: sirx11e s~ing, slew (one instruction each 1/2 second), fast
with full status display refresh, faster with partial status refresh, and
faster yet with status refresh occuring only when program simulation passes
selected' addresses in rierorye. A progtam can also be· exeaJted "directly", with
no siIrulation, as if RAID were not present. 'llle user can halt the simulated
execution at preselected points. Such a halt. can take place when the program
passes a selected a::1dress., when a. selected cpcode is executed, when a selected
register contains a certain value, or when a selected rrenory location contains
a certain byte. These features are useful during the debugging process,
particularly when it is necessary to execute rapidly during certain parts. of
the target" program, l::ut to slew doNn or step at' certain places or tmder certain
conditions in order to isolate an event.
As further aides to detugg.ing·, the user can simulate execution of single
instructions (not part· of. a. program) to view the affect", can change' the value
of any location in IIe10ry or of ar'¥ register wj. thout writing a program to do
so, and can pop words, off of or push. words. onto the. stack withc:ut writing a
pro;raru.
The asserrbly language. prograrmer- will find RAID an indispensible tool which
dramatically reduces the. de1:uggirxJ effort,. particularly in cc:mparison with the
less· scphisticated. 8080 deblggers· already available for Vector Graphic systems.
De.tuggin3 nore quickly neans a. pt"Cqram available· at an earlier date e· In this
way RAID significantly increases the· value of sof.tware· written on Vector
Graphic· systems.
1-2
Rev. l.l-A
5/30/80
Vector FAID Reference Manual
.2
'lbe range of· RAID
UPon entering RAID, the user is asked where RAID will be located in this
session. RAID can be located anywhere in m=rrory having space for a 6K program.
RAID does not reserve for itself the use of aIr:! registers or flags, nor the
system scratch pad area. 'lberefore, the cperation of l105t . target programs is
not generally limited by the presence of RAID in the system.
Al though RAID is loaded tmder the -CP1M q;lerating system, and though it has
facilities for loading a target program from a CP/M compatible disk, RAID
cperates independently of aI¥ cperating system durin:J the s imula tion process.
Once the user has succeeded in loading both RAID and a target PLogLaxu into
system nenory, RAID can 1:e used to del::.ug prcgx:ams running in conjunction with
~ cperatirx.; system.
'!he limitations of RAID are as follows:
It cannot be used to sinulate real-ti.ne software such as disk drivers and
connnunications programs. However, RAID can simulate those parts of such
ptQ3tams which are not tine-dependent, and can execute directly (no sinuIation)
those parts which ~ tine dependent.
Interrupts cannot be simulated Cecause an interrupt will interrupt RAID as
as the target prcgrarn. ~r, the interrupt service rcutine can usually
1:e simulated if it is entered wi thoot using a real interrupt.
~ll
RAID carmot usually jump fran simulation rrode, to direct execution, then
back to sinru.lation, if during the direct exeOltion r;x:>rtion the stack p::>inter is
moved more than a few locations. This combination of events will cause
tmdesirable effects.
RAID cannot sinru.late RAID itself •.
The Extended Systems Monitor fi:r:rrMare included in all Vector systems must
not be removed or replaced, unless the replacement has exactly the same
keyboard and video I/O routines-. RAID does its console I/O through the
Monitor •.
Rev. l.l-A
5/30/80
1-3
Vector. RAID Reference Manual
1.3
Protocol used in this manual
Underlined naterial is naterial ycu have to type, except where under lining
is used for ~is. '!he use· will be clear fran the context.
Material enclcsed in an;le brackets, such as <file narre), describes what is
to be typed rather than giving it literally. Angle brackets satet.iJres enclose
the nane of a key to be depressed, such as <TAB>.
Square brackets, such as [N]
not type the enclosed riaterial.
1-4
I
indicate that the user can cptionally .type or
Rev. 1.I-A 5/30/80
Vector RAID, Reference Manual
II. THE ST.RUcruRE OF RAID
2.1
IDading RAID
The disk on which RAID comes contains the program which is designed to be
used in 56K systans only whose screen rrerrory is located at add~ss FOOOH.
To load RAID, first get into the CP/M cc:mmand exealtive, as indicated by the
Load the RAID diskette in drive A and type:
A> pranpt.
!VRAIn [<d: filename. filetype> J <REIURN>
The filenane is cptional., If typed, it can include a drive designator and a
filetype extension, usin; the standard CP/M format. I t causes the selected
unambiguous file to be loaded from disk into memory. IMPORTANT: if the
filetype is .HEX, then RAID will first convert the file into bincu:y format, and
then load it at the load address of the file specified when the file was
asserbled. 'Ibis enables you to assemble and debug programs that run at any
location, rather than OlOOH as is nonral for CP/M. If the filetype is anything
else, the RAID will assune the file is already in bincu:y fonnat (having passed
thrcugh the CP/M LOAD procedure) am will load it at OIOOH.
After yen depress RE'IURN, ycu will see the foliGNing on the screen •••
Rea:::mn:mded Location Range is:
3000' to', 8000 for- a 48K system
3000 to AOOO for- a 56K' system
Deb.lg McXlu.le Relocaticn Address:
Type 4 digits, following the colon,> giving the desired start address for
It can be art!:! address 1:et::ween the re<:ClTlItend locations, rut it nust start
on an even page bolmdary" in other words, end in •• aOH. Addresses greater than
the aJ:x7ve are not re<:ClTlItended because this walld cause RAID to overlay CP1M ,
which is not normally desired. However, ym may overlay sate or all of CP/M if
RAID.
the target program does not use the overlayed part of CP/M.
It is not
recommended to use the lower part of the TPA (Transient Program Area) tecause
this is the usual area for the target pro;:J:tam.
With the exception of the HELP screen, the bulk of the RAID pt:03ram will load
from the specified load address upwards. The HELP screen occupies
approximately 1440 bytes fran the load address downwards. Thus the simulated
prcg:tam nay overlay the help area in nerory and, if so, the help screen will
'not be displayed when the help camrand is input. If the HELP screen data has
been disturbed the phrase "HELP SCREEN ID1' AVAIIABLE" will be displayed in the
Rev. l.l-A
5/30/80
2-1
Vector RAID Reference Manual
ccmnand area.
AS soon as yoo tyI::e the fc::::.m: digits, the screen will Ce erased and replaced
wi th a large banner reading •••
RAID
Below the banner will be a list of the RAID ccmnands, similar to the list
fc:und at the l:eginning of this manual. This list is a "help screen" which you
can view during nornal use of RAID by simply inputting a question mark (?) in
the cx:mnarxJ node.- At the l:ottan of the list, ycu will see •••
Simply depress the space bar or arr:/ other key., As soon as yeo do, the RAID
debugging display will appear. If you specified a prcgZ:dm when loading RAID,
this program will be loaded at this' tine. If it does not exist on the disk,
then yeo will see a ? in the cx:mnarxJ area of the display. You may row proceed
to run RAID. At- any tine, if yoo want to load a CP/M file fran disk, yc:u may
use the Load File a:mnands found in Chapter 3.
2-2
Rev. l.l-A
5/30/80
Vector RAID Reference Manual
.2
A RAID session
As mentioned in Perspective, simulation is the heart and purpose of RAID.
After RAID is loaded, yoo nay load a targe t program us ing the Load command,
unless a target program was specified when loading RAID. Then use the Projr:a1ll
Counter camnand (P) to set the value of the PC to the beginning of the target
program. Next, you may use one of the exeCJte camrands to begin simulation.
For example, yoo can simply depress the TAB key in order to simulate execution
of the one instruction pointed to by the PC. More often, ycu will initiate
contiruous sinulation. A canplete list of the ExeOlte camnand cptions is found
in the "Execute operations" section of Chapter 3. For example, the ExeOlte
a:::nUraOOs rontciin a way to caUse the status display to be refreshed only when
the target program passes pre-selected lX>ints during continuCU5 simulation.
The purpose of s:i.rnulation is to be able to view the status of the system
after each instruction or group of instructions is exeOlteci. 'lberefore, the
screen rontains at all ti.Ires a continuously upjated status display. This is
referred to as the "RAID display." The Dump and Stack camrands can te used at
aIr:! tine to control what part(s) of" rrerory are displayed in the dump and stack
areas of the RAID display.
You will usually watch si.nrulation occuring for a while. Yoo can step it at
aIr:! tine, in order to change what part (s) of m=rrory are displayed, or to change
the value of a register or memory location to see the effect,. or to change the
value· of PC in order to restJIIe sirrulation at a different point. You can also
set a "halt location," a point where simulation will step autc:aYatically when
certain conditions are rret, such as a register or memory location having a
certain value, or the PC reaching a certain value, or a specific opcode being
exeOlted.. After entering such a:::nUraOOs, ycu can then resurre s:i.rnulation. When
simulation is not taking place, RAID is waiting for camrands in the camrand
node •.
For those sections· of· pcograms that cannot be s:i.rnulated (see Perspective),
you can execute them "'directly, II· that is, actually execute them· wi thou t
simulation. To stop direct. execution in mid-stream, you can specify
"brea1q:oint" addresses in advance. When the target ptcgtam I s direct execution
reaches one of these addresses, control. returns to the RAID camnand node, which
then waits for another camrand.
To practice and dencnstrate the use of RAID, a -deno target program is loaded
into the CP1M TPA at the same time RAID is loaded, if no other file is
specified. while loading. The deno program starts at address Ol03H. For
example, to watch RAID rapidly simulate this program, first load RAID, then
enter the camnand P 103 <RErrORN> follcwed by XF <RErrORN>.
To exit RAID and return to CP/M, execute the Quit command by ~ing Q
<RETURN> on the camrand line. To return to the Exteooed Systems Moni tor, jus t
depress the ESC key at any tine while RAID is in control.
Rev. l.l-A
5/30/80
2-3
Vector RAID Reference Manual
2.3
The RAID display
A- drawing of the RAID display is famd at the beginning of this manual, for
reference purposes. It occupies the top 18 lines of the screen, which are
referred to as the "reserved" portion.
This display will always l:e on the screen during RAID opera"t:ion, without
change. The only exception is if the target program changes the screen
directly, or roves the cursor into the reserved part of the screen. If the
target program simply displays its ·output line-by-line according to cursor
location, using the normal Extended Systems Monitor video driver, without
changing the cursor location, then this cutput will scroll through the botton
six lines of the screen only. (This is a feature made possible by Vector's
Extended Systems Monitor.) In order to make effective use of RAID, it is not
wise to debug programs which write directly to the reserved part of the
screen.
Whenever there is a change to any part· of the system whose status is
displayed on the screen, that change will appear i.rcnediately on the screen.
For example, if the cperator !.=cps a \-tJOrd off the stack us ing the SP cormnand,
this word will disappear from the stack. display. If the operator enters a
value into RAM rrerory usin;; the EH camrarxi, then this value will appear in the
dump area of the display, assuming that the appropriate part of memory is
represented in the durrt> area. If durirg simulation, the target program changes
the stack, memory, registers, or flags, the changes will irnnediately apt:ear.
This process is called nrefreshinj the display. n·
The only tine the· display is not refreshed, though changes are taking place
in the system, is when the operator specifically requests that it not be
refreshed, usin:J sate' of: the' varioos' Execute caranands (Xl?, XN, or XD}.
The following' sections. will clarify what· the various parts of the RAID
display show. Refer' to the drawing at the beginning of this manual, or to the
screen itself •.
2-4
Rev. l.l-A 5/30/80
Vector RAID Reference Manual
.4
Ccrrmand area
Yoo can type camrancs in the camrand area of the display whenever RAID is in
the canrnand node, arx:] the two small white spots are at the left side of the
conunand area, and there is nothing typed in the area. For rrore information
abcut enterin;J ccmmands, see the beginnirxj of Chapter 3.
Rev. l.l-A 5/30/80
2-5
Vector RAID Reference Manual
2.5
Instruction area
There are seven lines in the instruction area of the screen. Each of these
seven lines stxJw one instruction fran the target prcgram. The first two lines
show the two instructions most recently simulated. They are not necessarily
consecutive in nem:n:y, because'they may be jumps, calls, returns, etc. The
third line, the highlighted one, shows the instruction abalt to be simulated.
The last four lines show the four instructions following the current
instruction in memory. They may or may not be the next instructions to be
simulated.
Each line gives the followin:.; infor:maticn:
(I) 'Ihe instruction am no, one, or two cperands, in hexadecimal notation
with no separaticn be~ insructioo and operands. These are one, ~, three
or four bytes represented by two, four, six or eight hexadecimal digits.
(2) The ASCII representatioo of the instruction am operands. Since there
is one ASCII character p:!r byte, there are ale, ~, or three ASCII characters
shown. If the dlaracter is in reverse video, this nEans the high-order bit is
a one. Control character (those whose 10000r seven bits are between 00 and IF)
are represented differently depending on the system' s character set.· Usually,
they are represented by graphics dlaracters consisting of fran one to six small
white squares in various combinations. A chart showing the correspondence
between graphics characters and' ASCII codes is found at the rear of the
Flashwriter II User's Manual which ~ with every system.
(3) 'Ihe. crldress of the instruction, in hexadecimal notation.
(4) The assenhly language representation of the instruction followed by its
operaOOs. Vector's 808D-superset nnenonics are· used.
2-6
Rev. I.l-A
5/30/80
Vector RAID Reference Manual
•6
CtlInp area:
Six lines are in the dump area -of the display. Each line begins with a
four-digi t hexadecimal nerrory crldress, followed by a colon, which indicates the
t:eginnin; of the manor:y area shown en that line. Each line consists of sixteen
bytes, showinJ the contents of IreItX)ry beginning at. the address given. The
bytes en each line can either be two hexadecimal digits or one ASCII character.
When RAID is first loaded, they are all hexadecimal am begin at address OOOOH.
Each line increases by 10H.
You can chanJe the beginIti.n;J a:1dress of any' one line or any group of lines,
an:l yoo can chan~ the representation to ASCII or back to hexadecimal, by using
the Dump canmands, described in Chaptel: 3.
Rev. l.l-A 5/30/80
2-7
Vector RAID Reference Manual
2. 7
Flags and registers
Next to the instruction area of the display, there are a group of areas
which display the contents of all the Z-80 registers am flags. The Ie f t-hand
side of this area shows the main flags and reg~ters, the next section shews
the alternate flags and registers, arx:1 the third section shows the contents of
the X register, the Y register, the I register, and the interrupt" flag.
The top line sOOws the flags, indicated by "Fft an:] ftF'". On this line, if
,any flag is set, its symbol will ,appear, otherwise the symbol will not be
visible. '!be synt:ols are:
symOOl
flag
s
sign
Z
H
half-carry
P
N
C
zero
parity
add/subtract
carty
The contents of each register are shown as a hexadecimal byte next to the
register- syrrbol. Further, the contents of the A an:] A' registers is shown as
an ASCII equivalent, between double quotes. Last, the contents of the rrerory
addresses p:>inted to by the register pairs BC, DE, HL, BC', DE', and HL' are
given in parenthesis next, to the C,. E, L, C', E', and L' register contents
respectively.
The, contents of the X, Y, and I registers appear in hexadecimal notation
directly beneath the register' symbols. The status of the interrupt" flag
appears below the contents: of the'I register', between parentheses, with (di)
indicatin;; interrupts are disabled, arx:1 (ei) irrlicatin:r they are enabled.,
2-8
Rev. l.l-A 5/30/80
vector RAID Reference Manual
.8
Stack pointer and stack
Along the right side of the display is a colllIlll with the syrrt:cl "SP" at the
top, st.an:ling for "stack J;X'inter". The contents of the stack pointer appear
immediately below, in hexadecimal notation. Belew this is found the contents
of the stack itself, as nuch as will fit in the colunn: 13 hexadecimal words (2
bytes in each. word).
RAID keeps track of a value knc:wn as the "start of the stack". The start of
the stack is the address just al:ove the location of the first word pushed on to
the stack. For example, if the stack pointer is pointing at AOO2H when a
program pushes BBBBH onto the stack as the first word on the stack, then the
start of the stack is at A002H and BBBBH will be stored at AOOOH and AOOlH.
(The processor of ccurse decrenents the stack pointer by 2 before pushing a
word onto the stack, because it always };X)ints to the last word p,IShed onto the
stack. )
How does RAID know where the start of the stack is? When RAID is first
loaded, RAID a.ssuIteS the stac::X is empty. In other words, it assunes the start
of the stack is EqUal to the initial setting of the stack IX>inter.
The hexadecirral word at the top of the stack colunn is always the contents
of the two locations just below the start of the stack. Using the above
example, if the start of the stack is at AOO2H, then the word stored at AO 0 OH
and AOOrn will be the tcp v.m:d in the display. The botton tNOrd in the colLnml
is always the contents of the lOcation r;ointed to by the stack pointer. When
the stack pointer decreases by 2, due to pepping the stack, the botton word
disapt=ears. When the lX>inter increases by 2, due to pushing a word onto the
stack, the new word is added on the bottan. Hence the display really does shew
the stack. As words are p,IShed onto aOO t=OPr:eJ off the stack, the column will
grow longer am shorter respectively.
Note. that there is a Stack conunand' used for changing the setting of the
"start of the stack," which in turn alters what part of rrem::>t:y is displayed in
the· stack column.
.
Stack camnands are cllsOJSSed in Olapter 3.
Rev. l.l-A 5/30/80
2-9
Vector RAID Reference Manual
2.9
Halt area
The halt area of the display is used in conjuction with the Halt ccmnands
80, BP, arxl EM. 'lbese camrands· cause sinulation to halt when a pre-selected
opcode is executed, when a pre-selected PC value OCCJrS, or when the contents
of a pre-selected nenory location take on a given value. After you enter one
of these commands, the entered opcode, PC value, or memory .location and
contents will be displayed next to the 0:, P: I or M:, respectively. This part
of the display simply reminds yOl of the Halt ccmnand (s) yoo had entered.
In the upper right-hand corner of the halt area is a small square area.
When a halt does occur as a result of a Hal t setting, the type of halt is
Wicted in this area. You will see either "BOn, "HPn, or "EM".
'!be 00, EP, and 8M camands are diso.lssed in Chapter 3 •.
2-10
Rev. 1.I-A 5/30/80
Vector RAID Reference Manual
.10
Refresh area
Below the halt area is an -area marked with "Rf: n. This is used in
conjuction with the XN canrtand. XN causes contiruous sinulation, but with the
display refreshing only when the PC counter passes pre selected addresses. Yoo
can pre-select as many as four such addresses. They will then appear in the
refresh area as a reminder. Further, each tine a refresh does occur during
sinulation, the address which caused the refresh will be highlighted within the
refresh ~¢._ the display.
The
xN< canrtand
is diSOlSsed in Chapter 3.
Rev. l.l-A 5/30/80
2-11
Vector RAID Reference Manual
2-12
Rev. 1.1-A 5/30/80
Vector RAID Reference Manual
Ycu can t,yt:e carrnands in the camand area of the display whenever RAID is in
the ccmma.rrl node, and the two small white spots are at the left side of the
c:c:mnan:l area, am there is nothing ~ in the area.
To clear undesired naterial fran the
area, depress the DEL key.o
ConmandS are typed notmally, and edited with the BACl{ SPACE key.
a canmand after typin; it in, depress RE'lURN.
To execute
When a canmand has a pararreter following it, a space before the pararreter is
cptional. If there is nore than one parameter, then there must be space
between each.
When asked to ty};:e an <address> or a <word> as a canmand paraneter, leading
O' s are optional. An address' can have up to four hexadecimal digits. Ycu
cannot ty};:e an "Htl at the eOO.
When yru are asked to ty};:e a. <byte>, tyI;:e b.O hexadecimal digits.
When ycu are asked to ty};:e a <char>, standing for <character>, depress the
key or keys that cause an ASCII character to.be generated. This can t:e a
sirgle key depression, or the simultaneo.lS depression of the CTRL key and/or
the SHIFr key alon; with a character key.
-I
When you are asked to type a <register or register pair>, ycu may either
Sfecify a register or a register pair. To specify a register, ~ one of the
letters A, B, C, D, E, H, or L. To ~ a register pair, type BC, DE, or
HL. To st=eCify an aIternate register,. follow the letter with a single--q'uote
mark, such as in AI. To sp:cify an alternate register pair, follow the pair
wi th a sirgle quote mark, as in CD' •
A ? character appears on the right. side of the area when RAID cannot
understand a camnand.
To halt simulation at any time and return to the command rode, depress
control-shift-brace. In other words, simuiltaneously hold down the CTRL and
SHIFr keys while yoo depress the brace (curley bracket) key.
Rev. l.l-A
5/30/80
3-1
vector RAID Reference
3 .1
Manual
l?tJmp operations
DA. <address> [ <line> [-] ]
IE <address> [<line> [-] ]
There are two dwrp carmmds. They both control what part(s) 'of llellDry are
displayed in the dump area of the display. Dump ASCII (DA) causes the
specified part of the dump area. to appear in ASCII. representation, one
character ~r location. CUmp Hexadecimal (DH) causes the specif ied part to
apt:ear in hex notation, b.U digits per locaticn.
In lxrt:h ccrnrnan:ls, the <line> is a l'lJIIi:)er between 0 arxJ 5. 0 refers to the
top line in the. dtnnp area, 1 to the next line, and so on, with 5 as the last
line.
.
In each ccmnand, if yo.x type 00 line I1lJIIt)er', then the entire ~ area will
be· affected: the a:ntents of the specified address will be displayed in the
upper left-harrl comer, aOO the subsequent 96 locations (16 on each line) will
be displayed •.
If you type a line: number, then only that line will be affected. The 16
locations beginn~ with the specified address will be displayed on that line.
If you type a line number followed by' a, dash, then that line· and all
lines in the dump area will be affected, displaying the locations
beginnl.Ilg with the· specified address.
follow~
3-2
Rev. l.l-A 5/30/80
Vector RAID Reference Manual
.2
Enter operations
<address> <byte> [<address> <byte> ••• ]
Enter Hex
ElI
Enter~I
FA <address> <char> [<address> <char> ••• ]
Enter Register
ER <register or register pair> <byte or word>
These commands. change the specified rrem:::)l:y location or register. The new
register contents will immediately appear on the display. The new memory
contents will inurediately appear if the address is included in the dUIIlp area.
With the Enter Hex and Enter ASCII commands, you may make JOC)re 'than one
entry m the SanE ccmrand line. Simply separate each pararreter with a space as
usual.
With the Enter Register command, you may either specify a register or a
register pair. To specify a register, ~ one of the letters A, B, C, 0, E,
H, or L. To ~cify an alter.nate register, follow the letter-with
sTngTe
quote rrark, such as in ~. '!ben type a 2-digi t byte. To specify a register
pair, ~ Be, DE, or aL. To ~cify an alternate register pair, follow the
pair with asin;le quote maz:k,. as in CD'. Then type a 4-digit word.
a
Execute q?erations:
Rev. l.l-A 5/30/80
See' Secticn 3.ll
3-3
Vector RAID Reference Manual
3.3
Fill
Fill
F <start address> <em address> byte
Fills working menot:y with the byte specified fran the start address to the
end address.
3.4
Go
Go
G· <address>
'!his ccmnand transfers control. oot of RAID and into Sate other program.
CPU will begin exeOltin; autanatically at the address SI,:eCified.
3-4
The
Rev. l.l-A 5/30/80
Vector RAID Reference Manual
.5
Halt operations
Halt
<:Xl
HP <address>
PC
Halt on Opcode
FD <cpccde>
Halt at Register
8R <register or register pair> <byte or word>
Halt at MeIcro:y
EM <address> <byte?
One or more of these conunands can be active at any given tine. Once they
are activated, then sllrulation will automatically halt when the one of the
specif ied conditions occurs. The HP, HO, and 8M ccmnands cause the selected
values to appear en the display in the halt area. Then, when sinulation halts,
the cause of the halt app=ars at the upper right-hand corner of the halt area,
as "BP", "EO" I or "EM".
In Halt on Register, yal may either specify a register or a register pair.
TO st;ecify a register., type one of the letters A, B, C, D, E, H, or L. To
specify an alternate register, follcw the letter with-a single quote mark, such
as in A' • 'Itlen ty];;e a 2-digi t byte. To specify a register pair, type Be, DE,
or HL.~ specify an alternate register pair, follow the pair with asingle
quote nark, as in CD'. '!hen type a 4-digit word.
Rev. l.l-A
5/30/80
3-5
Vector RAID Reference Manual
3.6 Initialize Screen
Initialize Screen
I
This connnand simply clears any extraneaJS ma.terial off the RAID display.
All areas of the display will then reflect the current status ~ t;.he system.
3-6
Rev. l.l-A
5/30/80·
Vector RAID Reference Manual
.7
Load file operations
UJad Hex File
lJ::)ad
Executable File
L <filenaxre>. HEX
L
<filenaxre.file~>
These commands are used to load CP/M cbject files fran a disk. The drive
designater can be included, in standard CP/M forroat, if the desired file is not
in the logged-in drive.
Load ExeOltable File simply loads the file into the TPA at OIOOH. It does
not execute it. This is an alternative to specifying a filenane when loading
RAID.
Load Hex File allows you to simultaneously convert an a.ssetrbled HEX file
into exeOltable for:m aOO then load it at its cwn load address in ItEI1Dry, which
does not have to be OIOOH. '!he load address would have been determined by an
OR; pseudO-op when assaIt>J.in:;, the file.
'!his is an al tema tive to us ing CP /M
utilities before loading RAID in ot:de~ to l~ the file.
Rev. l.l-A 5/30/80
3-7
Vector RAID Reference Manual
3.8
Set Progtam Counter
Set PC
P
<address>
This command simply sets the Progt:am Camter to the desired address.
The
instruction at this a:1dress will inmediately appear on the third line of the
instructicn area of the display. When ya.I begin simulating, the' target ptogram
will be executed beg:innirg at this address.
3-8
Rev. l.l-A 5/30/80
Vector RAID Reference Manual
Quit RAID
This transfers control back to the pCo:Jram which called RAID in the first
place, which is nocmally the CP/M executive.
Rev. l.l-A 5/30/80
3-9
Vector RAID Reference Manual
3.10 Stack operations
Set Start of Stadt
SS <address)
'!he Set Start of Stack ct;:eration resets the start of the stack (explained in
Section 2.8) to a value other than the value set when RAID was loaded. It will
inunediately affect the section of memory displayed in the stack area of the
display. For example, if you increase the start of stack by 2, one addi tional
word will be displayed at the tcp of the colunn. If you decrease it by 2 the
tcp word of the colum will be renoved.
Note, if you decrease the start of stack value, this will leave extraneous
mterial in the stack display. To clear this cut, use the Clear Stack ColuIIU1
carmand, SC.
Clear Stade Column
sc
The Clear Stack Column command only clears extraneous material from the
stack display. It leaves the actual stack displayed.
Pql Stack
SP
Push Stack
SH<~
Pop Stack and Push stack do what they appear to do. When typing the <word>
in the Push Stack cx:rmnarrl, leadin:J 0' s do not have to be typed. The- results of
these carmands will be displayed iImediately in the stack area- of the display.
3-10
Rev. l.l-A 5/30/80
Vector RAID Reference Manual
.11 Execute operations
Exeo.lte Slcwly
XS [<rate>]
This causes simulation to begin at the Program Counter, at the rate of
apptoxinately one instruction every half second. The status display will be
fully refreshed after each instruction.
The cptional <rate> pararceter can' 00 aIr:! hexadecimal 11llJ'li.)er, rut is usually
be'bveen 1 and 10. '!he higher the value, the slC1Ner the rate of simulation.
Exeo.lte Fast; Full. Refresh
XF
[<rate>]
Wi thout the optional <rate> param=ter, this causes simulation to begin at
COlmter, at the maxinum p:::ssible rate, while still refreshing all
parts of the display after each instruction.
the
PrcyLdlll
If ycu include the <rate> paraneter, simulation will take place even faster,
because the display will not. 00 refreshed after each instruction. The higher
the <rate> pararceter, the faster the simulation. You will be able to notice
the difference when the <rate> is in excess of 1000, and even nore so when it
is above 8000. '!he <rate> can be aIr:! hexadecimal 11llJ'li.)er.
ExeOJte· Fast; Partial. Refresh XP [<rate>]
Similar to the XF command, XP causes. an' even faster rate of simulation,
because only the register and stack areas are refreshed when the display is
refreshed.. Again the <rate>· is an cptional hexadecimal 11llJ'li.)er. You will begin
to see a noticably quicker rate· of simulation when <rate> is greater than
80000 •.
Exeo.lte with No Refresh,
XN [<address> <address> ••• ] (up to 4 addr' s)
except as specified
This results in faster simulation than even the XP command, because no
display refresh is done at. all, except at specified addresses. You may
optionally specify from one to four addresses. When the PC of the target
prcgram passes one of these specified addresses, the display will be refreshed.
The chosen refresh addresses will be displayed in the refresh area of the
display (irrlicated by the "Rf:"), and when any refresh takes place during
simulation, the causative address will be highlighted. .
Rev. 1.1-A 5/30/80
3-11
Vector RAID Reference Manual
Execute Directly, with
XD [<address> <address> ••• ] (up to 6 addr' s )
specified breakpoints
This command causes the target program to execute indepeOOently of RAID,
pc. It is not a simulation, but a real
execution, in real time. You may include up to six optional break-point
addresses. When execution of the target program reaches one of these
addresses, execution will stop and control will return to 'RAID. This is
accomplished by replacing the opcodes at the specified addresses with FF
restart codes.
beginning at the set value of the
Execute Directly and return
(LF)
This camrarx1 is exeOlted directly fran the keyboard using the. (LF) key. It
will cause the target pco3t:am to execute directly, in real time, any called
routine. This is particularly useful for disk access or print rc:utines which
cannot l::e simulated in RAID. 'Ibis c:x:mmarxl causes the real time execution of
the called subroutine to halt at the next memory location past the calling
instruction when the subroutine returns. This is of particular value when
debugging a program which calls routines which have already been debugged.
Because, of the limitation of not l::eing able to set break points, this conunand
will not 'Nark for raJtines in PRCM.
Exemte Instructioos
XI' <hex instruction> [<hex instruction> ••• ]
This simply simulates execution of the instructions listed on the carmand
line. Any valid Z-80 cede am cp:rands may t:e listed, with spaces to separate
them., The effects will be· seen in the display.
Execute: Next ' Step
This simulates exeOltion of' the instruction r:ointed to by the PC (the third
instruction in the instruction area of the display). 'llle effects will be seen
in the display.
3-12
Rev. l.l-A 5/30/80
Vector RAID Reference Manual.
t12
Help
screen
Help screen
?
This displays the Help screen at any tine by simply inpltting a question
nm:::k \tIhen the o:mnand IICde. If the tm;get pt:03tdlll has altered the· HELP screen
memory area, the phrase "HELP SCREEN oor AVAIIABLE" will appear in the cc:mnand
area.. To get back .to the Raid screen, hit aI¥ key e·
ReVe
l •.l-A 5/30/80
3-13