Diffstat (limited to 'devel/debug/1/src/trace.dok')
1 files changed, 387 insertions, 0 deletions
diff --git a/devel/debug/1/src/trace.dok b/devel/debug/1/src/trace.dok
new file mode 100644
@@ -0,0 +1,387 @@
+#type ("trium8")##limit (13.0)#
+#type ("trium8")##limit (13.0)#
+#center#- % -
+#center#E U M E L - D E B U G
+#center#Task-local Debugging Tools for EUMEL:
+#center##type("trium12.bc")#info, disasm, #type("trium12.b")#and #type("trium12.bc")#trace
+#it("info:")# display and modification of a dataspace on the users terminal in the conventional dump
+ format; search for a bytestring;
+#it("disasm:")# disassembly of EUMEL-0-code out of the standard dataspace using symbolic opcodes
+ and procedure heads;
+#it("trace:")# tracing of user programs, protocolling of executed instructions and their actual operands,
+ trap at a given code address, single-step-mode, multiple-step-mode (interruptable at
+ any time)
+The procedures have no effect outside the task. Especially no other task will be halted by using the
+The debugging tools need a suitable system kernel ("Urlader"). They can be used with kernels for
+processors Z80, 8086 and 80286 with versions 190 \#14, 181 \#347 \#1347, 180 \#347 \#1347 and higher,
+and with 68000-kernel version \#3600 and higher.
+The archive diskette "trace" contains all necessary files. The commands
+ archive ("trace");
+ fetchall (archive);
+ run ("gen.trace")
+insert all source files and generate a dataspace "procheads" containing procedure heads of all
+inserted procedures (including the standard ones). Then the current task becomes a local mana
+ger. Now a son task may be created, in which the debugging tools are available.
+The first time when (in a son task) #it("disasm")# or #it("trace")# protocols a CALL-instruction the dataspace
+'procheads' will be fetched from the father task for subsequent usage. If for any reason (e.g. after
+inserting new packets, see below) the user will change or re-install 'procheads' he has to inform
+the debugging procedures by issuing the command
+#inb# set procheads ("procheads") #ine#
+Access to the dataspace "procheads" may be suppressed by
+#inb# set procheads ("") #ine#
+Procedures inserted at a later time by the user should be added to the dataspace "procheads" (in the
+current task!) by typing the commands
+ bulletin m ("<packetname>");
+ run ("gen.procheads")
+#b("3. Description of the debugging procedures")#
+#b1("3.1 PROC info ")#
+The standard output is a hexadecimal dump of a dataspace in the following format:
+---------------------------- dsid=xx --------------------
+xxxxx: -xx-xx xx xx xx xx xx xx xx xx xx xx xx xx xx xx yyyyyyy.........
+xxxxx: xx xx xx ... .....
+xxxxx: xx xx ... ...
+xxxxx: xx xx xx xx xx xx xx xx xx xx xx xx xx xx xx xx .........yyyyyyy
+#re("INFO: more, address, dsid, lines, find, or quit")#
+The first line displays the dataspace identifier (4 <= dsid <= ff, dsid=4 identifies the standard
+The dump lines begin with the hexadecimal word (!) address of the first word on this line. The order
+of bytes is the same as on EUMEL-'Hintergrund': low byte, high byte. Following the hexadecimal
+display of 16 bytes they will be shown as ascii-characters, too. Non-ascii characters will be
+displayed as '.'.
+The last line shows (as with #it("disasm")# and #it("trace")#, too) possible commands which will be recognized by
+their first letter. If a parameter is needed, it has to be typed as a hexadecimal number followed by a
+<CR>. The <RUBOUT> key may be used to delete the last input character(s).
+Possible commands and their effect:
+m (more): continues displaying at the next higher address
+a (address): specifies a new address
+d (dsid): specifies a new dataspace identifier
+l (lines): specifies a new line count (=window height); this value may be larger than the
+ number of lines of the terminal screen.
+f (find): (tries to) find a hexadecimal or character bytestring. The prompting message
+ find: hex, char, or last param? (h/H/c/C/<CR>)
+ may be answered in several ways. Examples:
+ #inb#h41<CR>#ine# looks for a byte 41h, beginning at the actual position, marked by -xx-.
+ #inb#Hcafe<CR>#ine# searches the bytestring 0cafeh, beginning at the actual word address.
+ Only strings at word addresses will be concerned for a comparison.
+ #inb#challo<CR>#ine# searches the character string "hallo", beginning at the actual position.
+ #inb#Ca<CR>#ine# searches the letter "a", which has to be located at a word address.
+ #inb#H41<CR> #ine#has the same effect.
+ #inb#<CR>#ine# searches the last bytestring explicitly specified in a search command,
+ beginning #bo("behind")# the marked position. The last parameter will be shown
+ during the search.
+ The search can be interrupted at any time by pressing a key. It may then be conti
+ nued by a new 'find' command and <CR>.
+q (quit): leaves #it("info")# .
+Instead of a command the dataspace can be modified within the displayed area by the key-
+ <UP> positions the cursor to the first displayed byte;
+ <Cursorkey>... moves the cursor within the hexadecimal display;
+ <2 hexadecimal digits>... overwrite the byte under the cursor;
+ <CR> leaves the window.
+Note: in the standard dataspace changes within the address range 20000...2ffff are only allowed in
+ conjunction with a 68000-kernel (see also 3.3, note a.).
+#b1("3.2 PROC disasm ")#
+EUMEL-0-code in the address range 20000...3ffff of the standard dataspace will be disassem
+bled. The code will be listed one instruction per line, using symbolic opcodes and (in case of a CALL
+instruction) procedure heads as found in the dataspace "procheads".
+The following example shows the disassembled code of the standard procedure
+REAL OP MOD (REAL CONST left, right):
+ REAL VAR result := left - floor (left/right) * right;
+ IF result < 0.0
+ THEN result + abs (right)
+ ELSE result
+23edd: LN 2000
+23ede: PENTER 15fe
+23edf: FDIV 09c4 0d80 2880
+23ee2: FLOOR 637f 2880 2880
+23ee5: FMUL 28c0 0d80 2880
+23ee8: FSUB 09bc 2880 1880
+23eeb: FLSEQ 6049 1880
+23eed: BT f700
+23eee: PP 0dec
+23eef: PP 28ec
+23ef0: CALL 5d79 abs (REAL C) --> REAL
+23ef1: FADD 18b8 2880 2880
+23ef4: REF 28dc 2080
+23ef6: B f970
+23ef7: REF 18dc 2080
+23ef9: FMOV 21b4 1180
+23efb: RTN 007f
+#re("DISASM: step, more, address, lines, info, or quit")#
+s (step): shows the next instruction on the terminal. The command line will be rewritten.
+m (more): shows the next instructions. The output will stop after 'lines' (standard=12) lines. It
+ can be interrupted at any time by pressing any key. The output list terminates, when
+ an invalid opcode has been detected or when the instruction count exceeds 3ffff.
+a (address): specifies a new code address. Disassembly continues at this address.
+l (lines): specifies a new line count; this value may be larger than the number of lines of the
+ terminal screen.
+i (info): calls #it("info")#. The first line of dump contains the first word of the next instruction not yet
+ disassembled. This word will be marked. (After leaving #it("info")# disassembly would
+ continue with this instruction.)
+q (quit): leaves #it("disasm")#.
+#b1("3.3 PROC trace ")#
+#it("trace")# allowes controlled execution of subsequent EUMEL-0-code. The effect of the trace-mode
+can be demonstrated by showing the protocol produced by
+ #inb#trace; putline ("hallo")<CR>
+ #ine##outb##re("TRACE: step, more, trap, regs, lines, info, disasm, or quit")#
+ 34afb: PP 006d >00009000
+ 34afc: CALL f37a putline (TEXT C)
+ 28d63: PENTER 38fe
+ 28d64: TEST c828 >0
+ 28d65: BF 6b70
+ 28d66: OUT 3c7f 0980 >"hallo" hallo
+ 28d68: OUT 3c7f 6c01 >""13""10""
+ 28d6a: B 6e70
+ 28d6e: RTN 007f --> STOPEN NOERR ARITS
+ 34afd: RTN 007f --> STOPEN NOERR ARITS
+ 20944: RTN 007f --> STPDIS NOERR ARITU
+ trace ended by returning to nontraceable caller
+Comments on this output:
+- the indentation of the protocol lines shows the call depth.
+- in order to get 1 line per instruction as often as possible, some abbreviations are used in the
+ procedure heads: 'C' for 'CONST', 'V' for 'VAR', 'DS' for 'DATASPACE'.
+- the first occurrence of the string 'hallo' is part of the protocol. The second one is a result of the
+ execution of the (first) OUT-instruction. The blank line is produced by the second OUT-instruc
+- the flags given with a RTN-instruction reflect the flag settings #bo("after")# execution of the RTN:
+ STOPEN = stop enabled STPDIS = stop disabled
+ NOERR = no error ERROR = error occurred
+ ARITS = signed arith mode ARITU = unsigned arith mode
+s (step): executes and protocols one instruction (=single-step-mode). For reasons of the
+ implementation, consecutive PP-instructions will be executed as one single step. The
+ same holds for instructions followed by a conditional branch (e.g. EQU+BT).
+ The protocol contains also actual operand values. Example:
+ trace;INT VAR a:= 2 + 11
+ 34afb: ADD 001d 0101 5400 >2 >11(000b) 13(000d)>
+ '>' in front of a value indicates input-operand;
+ '>' behind a value indicates output-operand. (For the instructions MOV, FMOV and
+ TMOV only 1 (output-)operand will be shown.)
+ INT-objects are shown decimal and (in parentheses) hexadecimal (4 digits). The
+ numbers 0 to 9 will be shown only decimal.
+ REAL-objects will be shown in the internal representation (e.g. 11.5 as
+ TEXT-objects will be shown as text denoters. Non-ascii characters will be converted
+ (see example). For long texts only the first 14 characters will be shown, followed by
+ the (correct) number of characters.
+ All other objects (TASKs, DATASPACEs and effective virtual addresses) will be shown
+ hexadecimal (4 or 8 digits).
+m (more): executes and protocols up to 'line count' (standard=12) instructions. Execution can be
+ interrupted at any time by any key, and resumed by commands 's' or 'm'.
+t (trap): sets a trap on a code address. As soon as the instruction count reaches the specified
+ value, the message
+ trap at address .....
+ will be displayed and the execution stopped. (The instruction at the trap address is the
+ next one to be executed!) At the same time the trap is deleted.
+r (regs): shows the relevant EUMEL-0-registers 'icount' (address of the instruction to be
+ executed next), 'pbase' (=packet base, base address for packet data), 'lbase' (=local
+ base, base address for local data on stack) as well as flag registers
+ (STOPEN/STPDIS, NOERR/ERROR, ARITS/ARITU).
+l (lines): specifies a new line count; this value may be larger than the number of lines of the
+ terminal screen.
+i (info): calls #it("info")#, s. 3.1. The instruction word pointed to by the instruction count is the actual
+ position, marked on the first line.
+d (disasm): calls #it("disasm")#, s. 3.2. Disassembly begins at the next instruction not yet executed.
+q (quit): leaves the trace-mode. However, a trap (see above) may still be in effect! Tracing
+ will be #bo("implicitly")# finished as soon as a RTN-instruction returns to a procedure
+ running in the 'unsigned arithmetic'-mode. (Regularly this is the ELAN-Compiler.)
+#bo("Important Notes ")#
+Erroneous use of #it("info")# and #it("trace")# may destruct your task. Therefore read carefully and observe follow
+a. In order to gain control at proper points of the code area, #it("trace")# temporarily modifies the user code
+ by inserting instructions (CALLs to itself) into it. On EUMEL-hardware based on Z80, 8086, or
+ 80286, #it("trace")# does not allow modification of address range 20000...2ffff for reasons of storage
+ management strategy. Therefore calls to procedures occupying this address range will be marked
+ in the protocol by "(*n.t.*)" (for 'nontraceable') and executed normally, i.e. not protocolled.
+ WARNING: execution of a nontraceable procedure cannot be interrupted by <SV> and 'halt'. So
+ be careful!
+b. Traps may only be set on the first word of an instruction. In a sequence of consecutive PP-
+ instructions only the first one may be trapped. In the same manner, a conditional branch (BT / BF)
+ following another instruction (e.g. EQU) may not be trapped.
+c. On inserting #it("trace")# it may get a module number > 2047. In that case the CALL to #it("trace")# occupies
+ 2 words. The user will be informed of this fact at the time just after inserting #it("trace")#:
+ WARNING: call to trace needs 2 words!
+ In this situation special care has to be taken to set a trap, e.g.:
+ LSEQ xxxx xxxx
+ BT xxxx (*branch on true to address a*)
+ a-1: B xxxx
+ a: ...
+ In this example the branch instruction at address 'a-1' may not be trapped because the following
+ instruction (at 'a') would be destroyed by a 2-word-CALL to #it("trace")#. A jump to 'a' would have an
+ undefined effect. So be careful! First inspect the code environment by using #it("disasm")# and then set
+ a trap at a suitable address!
+d. In the current version of #it("trace")# a trap will be implicitly deleted as soon as it has become active. If
+ the user wants (e.g. in a loop) to trap a given address again and again, he has to choose a
+ second suitable address, too, and alternately set a trap at these addresses. (A trap may be
+ #bo("explicitly")# deleted by specifying 0 as trap address.)
+e. One may be tempted to trace the ELAN-compiler by writing
+ trace; do ("..........")
+ which seems to work indeed for dozens of lines but at some point it begins to deliver wrong
+ results even with such trivial instructions as an integer ADD. This trouble arises from a storage
+ assignment policy during compilation of the ELAN compiler: temporary storage (e.g. for calculating
+ the value of an expression) will be assigned above the stack top of a procedure if it does not call
+ any other one. An #bo("implicit")# CALL to #it("trace")# causes a further stack frame to be established thus
+ possibly overwriting some temporary values of a compiler procedure. (Of course, the compiler
+ cannot know anything about CALLs inserted by #it("trace")# into the code area!)
+f. Errors (e.g. overflow) in user programs will be detected by #it("trace")# at the point of their occurrence
+ and reported in the protocol. However, #it("trace")# has no influence on the error handling, i.e. it does
+ not turn off the error flag by itself, nor causes it an error stop on the users level. (#it("trace")# may be
+ seen as an extension of the virtual EUMEL-0-machine offering some additional features but still
+ fully controlled by the users program.)
+g. Each time when the user has control within #it("trace")#, the users code area contains no other patches
+ than a possible CALL at the trap address if specified.
+h. The procedures #it("trace, disasm, info")#, and some others used by them are nontraceable. The body of
+ these procedures will not be protocolled. CALLs to them will be marked as nontraceable. Explicit
+ CALLs to #it("trace")# (i.e. in addition to the first call to switch on the trace mode) will be ignored.
+i. In trace-mode the EUMEL-0-instruction KE has the same effect as an explicit call to #it("info")#.
+j. Protocolling the execution produces output in addition to output programmed by the user. This
+ may lead to unexpected results when the user program specifies cursor positioning. The cursor
+ will always be moved to the position (10,13) instead of the position specified by the user. This is
+ due to the fact that cursor positioning takes place in two steps. One OUT instruction sends the
+ escape character for 'cursor positioning' (=""6""), and a second one sends two bytes containing
+ the coordinate values. The protocol line containing the first OUT will be followed by a lf-cr-
+ sequence (""10""13"") before the next protocol line can be written.