Trailing-Edge
-
PDP-10 Archives
-
bb-d868e-bm_tops20_v41_2020_dist_1of2
-
4-1-documentation/ddtman.txt
There are 4 other files named ddtman.txt in the archive. Click here to see a list.
DDT REFERENCE MANUAL
This document describes many of DDT's commands in great detail. Since
this is intended as a quick reference guide until the real DDT reference
manual and card are available, the presentation is very short and
'meaty'. You should be fairly familiar with DDT to use this guide
effectively. DDT42.MEM describes the rest of DDT's commands
(particulary $U).
1.0 Conventions
The following terms are used throughout this guide:
$ An escape (altmode).
<BS> A backspace.
<DINK> A bell.
<CR> A carriage-return.
<LF> A line-feed.
<SP> A space.
<TAB> A tab.
RH(value) The right half of value.
LH(value) The left half of value.
IFIW(value) The effective address when value is treated as an
indirect format indirect word.
GFIW(value) The effective address when value is treated as a
global format indirect word.
Sample DDT commands are enclosed in single quotes whenever their meaning
is not obvious from the context, or where periods at the end of
sentences would be confusing.
2.0 DDT Command Format
All DDT commands have the general format:
expr1<expr2>expr3$$expr4cx
where each exprn can be any DDT expression, c is the DDT command
character, and x is a text argument. All fields except c are optional,
depending on the particular command.
Page 2
Expressions may then be built using any of the following operators:
+ Addition.
- Subtraction.
* Multiplication.
' (apostrophe) Division (NOT '/'!).
<SP> Adds first operand to right half of second operand.
This is used most commonly after opcodes.
,, (comma-comma) Places right half of first operand in the left half
of the result, and the right half of the second
operand in the right half of the result.
, (comma) Delimits the accumulator field in an instruction
and truncate the following expression to 18 bits.
(n) Swap the value of n. Normally used for index
registers in instructions.
3.0 Type-out Modes
Each of the following commands can be typed with one or two $s. The
effect is determined from the following table:
$ Set the specified type-out mode temporarily. Clear
it with the next <CR> command.
$$ Set the specified type-out mode permanently. The
mode can be changed only by setting a new permanent
type-out mode.
The type-out modes (shown in temporary mode) are:
$C Type in numeric format, in the current radix ($nR).
$H Type as two halfwords.
$F Type as a floating-point number, unless
unnormalized, then as a decimal number.
$2F Type as double-precision floating point number
(TOPS20 only) using DFOUT monitor call.
$S Type in instruction (symbolic) format, if possible,
otherwise in numeric format.
$nR Type numbers in radix n (n itself is always
decimal).
$R Try to type numbers in relative format
(symbol+offset) where appropriate (opposite of $A).
Page 3
$A Always type as absolute numbers rather than symbols
(opposite of $R).
$nO Type as left-justified n-bit bytes.
$O Type as bytes, as previously specified by 'bits$3M'.
$5T Type in radix-50 format.
For each of the following, if the left most character of the word being
typed is not 0, then type a words-worth of left-justified characters.
If the left most character is 0, then type the single right-most
character.
$6T SIXBIT text format.
$7T or $T ASCII text format. If all 5 characters are typed
and B35=1, type @ as the sixth character.
$8T ASCII 8-bit text format.
$9T ASCII 9-bit text format.
DDT's defaults are $$S, $$R, and $$8R.
4.0 Retyping Values In Another Format
Each of the following commands retypes the value immediately preceeding
it in the indicated modes. If no value is explicitly typed in, the last
value typed by DDT is used.
; Retype the last value in current type-out mode.
= Retype the last value as a number in current radix
($C).
_ (underbar) Retype the last value as an instruction ($S).
$D Perform $K on the last symbol typed, the retype the
last value in the current type-out mode.
5.0 Type-in Modes
All constructs below may be used in subsequent DDT expressions. Current
type-out modes never affect the type-in modes; thus '10.' is always
decimal ten, even with $$8R.
op ac1,@addr(ac2) Instruction (symbolic) format.
Page 4
symbol# Declares a symbol to be defined later. The symbol
is added to the undefined symbol table, and
references to it are fixed when it is defined. This
cannot generally be used in full expressions.
n1,,n2 Halfword format.
n Octal format (no ending period).
n. Decimal format (ending period).
n.nE+n Floating point format (digits after period).
symbol$5" Radix-50 format.
$"/xxx/ SIXBIT left-justified format, using as many words as
necessary (/ can be any delimiter).
$"x$ SIXBIT right-justified single character format.
"/xxx/ ASCII left-justified format, using as many words as
necessary (/ can be any delimiter).
"x$ ASCII right-justified single character format.
6.0 Type-in Values
Each of the following are internal DDT values, also useful in
expressions.
@ The value 1B13 (the indirect bit in an instruction
or IFIW).
. The current address.
$Q The last value typed by DDT.
$$Q The last value typed by DDT, with the halves
swapped.
$nM The addresses of various DDT flags and masks. See
the description of each command for the full meaning
of these words:
$0M or $M/ The search mask for $W and $N.
$1M/ Terminal control mask.
$2M/ Offset range.
$3M/ Byte mask.
$I The address of flags and other state information in
EDDT. The block at the $I address has the format:
Page 5
$I-1/ APR CONI word.
$I/ PI CONI word.
$I+1/ Mask of PI channels turned off by DDT.
$I+2 Exec virtual address of the EPT.
$I+3/ Exec virtual address of the UPT.
$I+4/ Exec virtual address of the CST.
$I+5/ Exec virtual address of the SPT.
$I+6/ Original AC block word (DATAI PAG,) if abc$4U was
specified.
$nB The address of the block describing breakpoint n.
The block at each of the $nB addresses has the
format:
$nB/ If not 0, the address of breakpoint n. This should
only be set by 'addr$nB'.
$nB+1/ The conditional break instruction. If 0, it acts as
if it were a no-op. The instruction can return +1,
+2, or +3. For each case, this means:
Return +1 Decrement and test the proceed count.
Return +2 Unconditionally break without
affecting the proceed count.
Return +3 Unconditionally proceed without
affecting the proceed count.
$nB+2/ The proceed count (break on transition to 0).
Usually set by $$mP where m becomes the new proceed
count.
$nB+3/ If >= 0, the address to be typed out on a break.
$. The address of the next instruction to be $Xed.
$$. The last value of '$.'. Useful as $$.-1<$$X if you
use $X on a subroutine call on which you meant to use $$X instead.
7.0 Depositing And Examining The Contents Of Addresses
Each of the following 6 commands opens a new address based on the value
typed with the command. If no value is typed, the last value typed out
by DDT is used as a default. A good way to remember this is that the
new address is a function of the last value typed, either by DDT or by
you. The new address is derived from the value based on the number of
$s immediately preceeding the command letter, according to the following
table:
None If the value was defaulted by DDT or the left half
is 0 and no comma was typed, the new address
is RH(value) in the current section (section of ".").
If a value was typed in with
the left half 0 and no comma, then the
new address is 'value' (a fullword address).
Page 6
$ New address is IFIW(value).
$$ New address is GFIW(value).
If a value is typed in, then . is also changed to be the new address.
Otherwise, the new address is only available temporarily, and '.' is not
changed.
/ Open the new address and type its contents in the
current type-out mode.
[ Open the new address and type its contents as a
number in the current radix (sets $C).
] Open the new address and type its contents as an
instruction (sets $S).
! Open the new address but do not type its contents.
Each of the following commands deposits the value specified with the
command, if a value was typed in and the old address was open. Then the
new address to open and type out is then derived from that value as
described above.
\ The new address is opened and typed out, but . is
never changed.
<TAB> The new address is opened and typed out, and . is
always changed to be the new address.
Each of the following commands deposits the value specified with the
command, if a value was specified and the old address was open.
Then the new address is determined from a base address depending on the
number of $s immediately preceeding the command letter, according to the
following table:
None Value of '.'.
$ Last address saved on the address stack (the address
is then removed from the stack).
^ or <BS> Open base address - 1 and type its contents in the
current type-out mode.
<CR> The new address is the base address. Open and type
it out in the current type-out mode only for $<CR>,
not <CR>. If <CR>, then also clear all temporary
type-out modes.
<LF> Open and type out base address + 1 and type its
contents in the current type-out mode.
Page 7
Each of the following commands is useful for storing a single value in a
large area of memory. The deposits are under control of the $nW and
$$nW commands. While the commands are in progress, the ? command will
type the current address and contents.
addr1<addr2>n$Z Deposit n in addresses addr1 through addr2
inclusive. If n is not specified, then 0 is used.
Note that both addr1 and addr2 are required.
addr1<addr2$$Z Equivalent to $Z unless addr1 and addr2 are not
specified. In that case, zero all of memory except
for 20 through 137, DDT, and the symbol table. $Z
is preferred.
The following command is useful for watching an address that is shared
with some independently running process. This can result from pages
mapped between processes, writable sharable high segments, direct memory
access devices, dual CPUs, etc.
addr$V Display addr in the current type-out mode, and
continuously thereafter whenever it changes. The ?
command during the watching displays the current
state of the address. Any other character
terminates the waiting. In exec mode DDTs, the
check is continuous. In user DDTs, the check is
once a clock tick. If addr is not specified, then
the last opened address is used.
8.0 Program Control
addr$G Start the program at addr. If addr is not
specified, start at the program's start address.
The section may be defaulted as for register commands.
The commands below control the breakpoint facility. The decisions on
whether to break and whether to print the breaking instruction are then
handled by the breakpoint's data block (see the $nB value in the Type-in
Values section).
addr1<addr2$nB Set breakpoint n (optional) at addr2, and type
contents of addr1 when break occurs. If addr1 is
not specified, no additional address is typed out.
If n is not specified, the next free breakpoint
number is assigned.
addr1<addr2$$nB Same, but continue from breaks automatically.
n$P Continue from breakpoint, skipping the next n
breaks.
n$$P Continue from breakpoint, skipping the next n
breaks, then continue automatically thereafter.
Page 8
0$nB Remove breakpoint n.
$B Remove all breakpoints.
There are several breakpoint restrictions. Breakpoints may not be
1. modified by the program
2. read as data by the program
3. accumulator 0
4. placed in a section that does not have DDT mapped into it
5. put in a read-only or non-existent page
Each of the commands below execute specific instructions, or the next
sequential instructions in a breakpoint.
instr$X (Instr > 2^27) Execute the single instruction instr.
n$X (n < 2^27) Execute the next n instructions in
sequence (must be in a breakpoint).
addr1<addr2>n$$X Perform $X until the PC becomes addr1 through addr2
inclusive, n times. The default addr1 is .+1, the
default addr2 is addr1+2, and the default for n is
1. During the $$X sequence, the ? command types
the current PC and instruction. Any other character
terminates the $$X.
9.0 Symbols
module$: Open module's symbol table, closing the currently
open one. If module is not explicitly typed, do not
open a new symbol table.
value<symbol: Define symbol with the value value. If value< is
not explicitly typed, the default is RH of '.'.
symbol$K Suppress symbol from DDT type-out, but still allow
input.
symbol$$K Completely delete the first occurrance of symbol
from the symbol table.
? Type all undefined symbols (either from symbol# or
from loading errors).
symbol? Type all modules in which symbol is defined.
Modules in which symbol is global are followed by a
G.
Page 9
10.0 Searching
Whenever a word search ($W or $N) is done, each word is first ANDed with
the search mask (set with mask$M) and then tested. This allows just a
portion of a word to be tested.
During a search, each matching value and its address are typed. The ?
command types the current address and value in it. Any other character
terminates the search.
Following a search, . is set to the last address searched, and the most
recent match addresses are on the PC stack.
addr1<addr2>value$W Search for value from addr1 thru addr2, inclusive.
addr1<addr2>value$N Search for anything but value from addr1 thru addr2,
inclusive.
addr1<addr2>addr3$E Search for words whose effective addresses (always
computed assuming they are IFIWs resolved to
fullword addresses) are addr3, from addr1 thru addr2
inclusive.
11.0 Patch Facility
The patch commands allow the installation of patches using basically the
same conventions as MAKLIB's .INSERT command, with all of the same
restrictions. Code can be added logically before or after an
instruction. This is effected by copying the instruction to the patch
area along with the patch, following the patch with two JUMPAs back to
the main code, and then replacing the original instruction with a JUMPA
to the patch area. The JUMPA to the patch area is installed last so
that running monitors can be patched. The two JUMPAs added to the end
of the patch allow a skipping instruction at the end of the patch.
The instruction to be patched is always at location '.'. The patch area
is selected by an expression or a symbol, an expression, or
neither, as described below. The patch is put in the same section as '.'.
Neither Select the first existing symbol from the list
below, and act as if that symbol had been specified.
PAT (TOPS-10 EDDT only)
FFF (TOPS-20 EDDT, KDDT, and MDDT only)
PAT..
PATCH
PAT (All but TOPS-10 EDDT)
If none of the above symbols exist, act as if the
right half of .JBFF (location 121) had been
specified as an expression, and update the right
half of .JBFF and the left half of .JBSA (location
120) following successful patch insertion.
Page 10
symbol The patch area begins at the address corresponding
to the value of the symbol. Following successful
patch insertion, the symbol is updated to reflect
the size of the patch.
expr The patch area begins at the address corresponding
to the value of the expression.
The following commands control the patch insertion:
value$< Logically insert the patch before the instruction at
location '.'. The patched instruction is copied to
the end of the patch area when the patch is closed.
Value specifies the address of the patch area, as
described above.
value$$< Like value$< but logically insert the patch after
the instruction at location '.'. The patched
instruction is copied immediately to the patch area.
$> Complete the patch insertion by installing all three
JUMPA instructions. The command should be given
while . is the address of the last instruction of
the patch.
The patch may be aborted at any time before typing the $> simply by
typing $0< or restarting DDT.
12.0 Memory Control
Each of the following commands controls the result of an attempted
depositing command when the page containg the address is either
non-existent or write-locked.
$0W or $W Attempt to write-enable a write-locked page before
performing the deposit. On TOPS-10, this is done
with a SETUWP UUO. On TOPS-20, the page is
temporarily made copy-on-write, causing the deposit
to create a private page. Following the deposit,
the page is write-locked again.
$$0W or $$W Do not attempt to write-enable a write-locked page
before a deposit. Such deposit attempts result in
an error message.
$$1W Do not attempt to create a non-existent page before
performing the deposit. Such deposit attempts
result in an error message.
$1W Attempt to create a private page before performing
the deposit.
Page 11
On TOPS-10, the defaults are $0W and $$0W. On TOPS-20, the defaults are
$1W and $$1W.
13.0 Command Files
14.0 Messages
DDT has very few messages. These are:
U You referenced an undefined symbol.
M You referenced a multiply-defined symbol. Type
symbol? to see what modules define it, then open the
symbol table for the module having the definition
you want.
?<DINK><TAB> DDT encountered some error somewhere. The <TAB>
indicates that an address is currently open. Some
of the more obscure error possible are:
. On $>, the patched instruction, the symbol
table, or .JBFF or .JBSA is write-locked.
. You attempted to use $X or $P when not in a
breakpoint.
. You attempted to define or change a symbol when
there is no symbol table or when it is
write-locked.
. You have assigned all of the available
breakpoints.
. $X is about to execute an illegal instruction
(for example, a 0).
?<DINK><CRLF> Same as above, but the <CRLF> indicates that no
location is currently open.
? (without the <DINK>) The address you are attempting to examine does
not exist (for instance, it is in a non-existent
page).
# Following symbol type-out, this indicates that the
symbol is defined in a different module than the one
currently open. Following symbol type-in, this
indicates that you referenced a symbol declared by
symbol# that has not yet been defined.
$nB> A program break occurred because the conditional
break instruction returned +2.
Page 12
$nB>> A program break occurred because the proceed counter
reached 0.
15.0 Misc Commands
$? Makes DDT types out the full message for the latest
error. At present, all memory errors have explanatory
text, but most other errors do not. Hence, if
you get a "?" when attempting to open a register
or deposit, you can give this command to get
an explanation such as "Page does not exist."
exp$$? (TOPS20 only) Takes 'exp' as a TOPS20 monitor
call error code and prints the string corresponding
to it. If 'exp' is not supplied, print the
string for the most recent error in the fork.