'see' and 'debug'

[PabloC]

Hello
I have long wanted to start studying and testing FlashForth.
I prepared a board with a PIC18F26K22 and flash it with a FF-5 to it, but it stayed pending, and finally at the end of last March I finally started his study.
First of all, my thanks and acknowledgment to Mikael Nordman for such a great job.
Once I studied how it works, I thought about implementing an application written in flash-forth.
I missed a high level and low level disassembler, to check how the code looks, as well as a forth debugger to detect problems of programnig.
I have started to implement them.
This work has been developed for PIC18.
I would like to provide the code.
I'm looking at how to make a new wiki topic.

[TMN]

Hi Pablo.
There should be a create page button on the left side of the wiki.
You need to be logged into sourceforge to see it.

[Mikael Nordman]

Did you notice that the word see already exists in flashforth ?
Maybe you want a better or different one than this one ?
https://sourceforge.net/p/flashforth/code/ci/master/tree/pic18/forth/see.txt

[PabloC]

The 'see' of forth is complex of programing since this forth is direct-threading or rather subroutine-threaded code, with in-line expansion. In this way a call to a forth word can be compiled as a 'call', a 'goto', or correspond to a serie of inline cpu instructions.
As for the low-level disassembler, I found it important to give the option to interpret the ram bank in use, and present the symbolic name of the SFR, as well as the name of the routine (forth-word) called for each call or each goto.
The names of some SFRs are in a table of constants, to be used by the disassembler and also the assembler.
The names of the cpu instructions are in a table of the disassembler, which in the future could be grouped with the assembler, to take up less space on the flashrom.
Disassembly is done with forth words to be called for each instruction to see (which will use the debug) or by blocks of instrucctions to see from the 'forth' console.
see ( - | word ) see word code on a line
seel ( - | word ) see word code by lines
seea ( - | word ) see word on assembler
(.uasm) ( addr – addr' ) print instruction, returns address to next
                      disassembly variables are updated
(.fw) ( addr – addr' ) print a word, returns address to next word
                      disassembly variables are updated

As an example (copied from the window of a serial terminal ):

**see within

within over - >r - r> u< ;
ok<#,ram>
seel within
UnDec: within
$10b2: over
$10b4: -
$10b6: >r
$10b8: -
$10ba: r>
$10bc: u< ;
ok<#,ram>
seea within
UnDec: within
$10b2: df35 over rcall,
$10b4: df88 - rcall,
$10b6: df44 >r rcall,
$10b8: df86 - rcall,
$10ba: df4f r> rcall,
$10bc: ef8b.f008 u< goto,
ok<#,ram>**

For a branched word:

**: ss $12 0= if dup else $3456 then begin dup until drop ; ok<#,ram>

see ss

ss $0012 (0=?bra>$5fce) dup (bra>$5fd6) $3456 (dup?bra<$5fd6) drop ;
ok<#,ram>
seel ss
UnDec: ss
$5fbc: (lit:$0012)
$5fc2: (0=?bra>$5fce)
$5fc8: dup
$5fcc: (bra>$5fd6)
$5fce: (lit:$3456)
$5fd6: (dup?bra<$5fd6)
$5fdc: drop
$5fe0: ;
ok<#,ram>
seea ss
UnDec: ss
$5fbc: 0e12 $12 movlw,
$5fbe: 6eec PREINC0 a, movwf,
$5fc0: 6aec PREINC0 a, clrf,
$5fc2: 50ed POSTDEC0 w, a, movf,
$5fc4: 10ed POSTDEC0 w, a, iorwf,
$5fc6: e103 $5fce bnz,
$5fc8: ecc4.f007 dup call,
$5fcc: d004 $5fd6 bra,
$5fce: 0e56 $56 movlw,
$5fd0: 6eec PREINC0 a, movwf,
$5fd2: 0e34 $34 movlw,
$5fd4: 6eec PREINC0 a, movwf,
$5fd6: 50ed POSTDEC0 w, a, movf,
$5fd8: 10ee POSTINC0 w, a, iorwf,
$5fda: e0fd $5fd6 bz,
$5fdc: 6eed POSTDEC0 a, movwf,
$5fde: 6eed POSTDEC0 a, movwf,
$5fe0: 0012 return,
ok<#,ram>**

[PabloC]

To implement the debugger, the approach has been to start from the original FF, without modifying anything of the source, in such a way that compiling the forth code from forth it can be operative.
This does not take advantage of the debugging capabilities of the cpu.
In a later version it would be interesting to use the debugging capabilities, but this would imply including code for this purpose in the source file of the forth.
This implementation is made for 18FxxK22 and obviously has dependencies.
I have proposed a debug that executes forth words step by step and that also allows go to assembler, executing instruction to instruction.
The debugger is activated on a forth-word, like "debug -word-". Once in step-by-step execution, it supports instructions by means of a key, which are:
'a'sm 'b'ack 'c'ontinue 'd'ec 'f'orth 'n'est 'h'eaders 'q'uit he'x'
With 'a' it goes to assembler mode, following cpu instructions, and with 'f' it goes on forth words mode.
The forth mode presents the data-stack after executing the instruction.
The assembly mode presents after executing the instruction, the STATUS flags, the bank and the W register, and then the return-stack.
With 'x' and 'd' the presentation of the data-stack is changed to hexadecimal or decimal.
The step-by-step execution in forth is always inside the word that is being traced, to enter a level in the execution we can use the command 'n'est, and go back in the debug nesting using the 'b'ack command.
With the space the current instruction under debubbing is executed, and with 'c' the execution continues until a key is pressed.
In assembler, instruction by instruction is always executed, following the thread of execution.

**  ok<#,ram>
: tsta  $ff dup 2drop ;  ok<#,ram>
: tstb  $5678 count tsta 2drop ;  ok<#,ram>
: tstf 1 4 for cr ." text" tstb next drop ;  ok<#,ram>
  ok<#,ram>
: tstg  4 0 do cr ." loop " i . tstb loop ;  ok<#,ram>
  ok<#,ram>
see tstg
: tstg 4 0 (do>$613a) cr (s"loop " type i . tstb (loop<$6114) (unloop) ; IMMED
 ok<#,ram>
see tstb
: tstb $5678 count tsta 2drop ; IMMED
 ok<#,ram>
see tsta
: tsta $ff dup 2drop ; IMMED
 ok<#,ram>
debug tstb tstg
Debug: 'a'sm  'b'ack  'd'ec  'f'orth  'n'est  'h'eaders  'q'uit  he'x'
loop 0                          d($00)
$5f8c: (lit:$5678)          >   d($01) $5678
$5f94: count                >   d($02) $5679 $0003
$5f98: tsta                 >   d($02) $5679 $0003
$5f9a: 2drop ;              >
loop 1                          d($00)
$5f8c: (lit:$5678)          >   d($01) $5678
$5f94: count                >   d($02) $5679 $0003
$5f98: tsta                 >n  d($02) $5679 $0003
$5f78:   $ff                >   d($03) $5679 $0003 $00ff
$5f7c:   dup                >   d($04) $5679 $0003 $00ff $00ff
$5f80:   2drop ;            >n  d($04) $5679 $0003 $00ff $00ff
$0d72:                      >   d($03) $5679 $0003 $00ff
$0d74:    ;                 >   d($02) $5679 $0003
$5f9a: 2drop ;              >
loop 2                          d($00)
$5f8c: (lit:$5678)          >   d($01) $5678
$5f94: count                >   d($02) $5679 $0003
$5f98: tsta                 >   d($02) $5679 $0003
$5f9a: 2drop ;              >
loop 3                          d($00)
$5f8c: (lit:$5678)          >a
$5f8c: 0e78      $78 movlw,               >   00000 f 78 r($06)<$613a $7fff $7ffc $6130
$5f8e: 6eec      PREINC0 a, movwf,        >   00000 f 78 r($06)<$613a $7fff $7ffc $6130
$5f90: 0e56      $56 movlw,               >   00000 f 56 r($06)<$613a $7fff $7ffc $6130
$5f92: 6eec      PREINC0 a, movwf,        >   00000 f 56 r($06)<$613a $7fff $7ffc $6130
$5f94: ec99.f011 count call,              >   00000 f 56 r($07)<$7fff $7ffc $6130 $5f98
$2332: ef87.f00a c@+ goto,                >   00000 f 56 r($07)<$7fff $7ffc $6130 $5f98
$150e: dd3c      dup rcall,               >   00000 f 56 r($08)<$7ffc $6130 $5f98 $1510
$0f88: 0eff      $ff movlw,               >   00000 f ff r($08)<$7ffc $6130 $5f98 $1510
$0f8a: cfeb.ffec PLUSW0 PREINC0 movff,    >   00000 f ff r($08)<$7ffc $6130 $5f98 $1510
$0f8e: cfeb.ffec PLUSW0 PREINC0 movff,    >   00000 f ff r($08)<$7ffc $6130 $5f98 $1510
$0f92: 0012      return,                  >   00000 f ff r($07)<$7fff $7ffc $6130 $5f98
$1510: ded6      c@ rcall,                >   00000 f ff r($08)<$7ffc $6130 $5f98 $1512
$12be: d4a8      c@ bra,                  >   00000 f ff r($08)<$7ffc $6130 $5f98 $1512
$0c10: 0ef0      $f0 movlw,               >   00000 f f0 r($08)<$7ffc $6130 $5f98 $1512
$0c12: 60ef      INDF0 a, cpfslt,         >   00000 f f0 r($08)<$7ffc $6130 $5f98 $1512
$0c16: 0eec      $ec movlw,               >   00000 f ec r($08)<$7ffc $6130 $5f98 $1512
$0c18: 60ef      INDF0 a, cpfslt,         >   00000 f ec r($08)<$7ffc $6130 $5f98 $1512
$0c1c: d465      $04e8 bra,               >   00000 f ec r($08)<$7ffc $6130 $5f98 $1512
$04e8: dfed      >tblp rcall,             >   00000 f ec r($09)<$6130 $5f98 $1512 $04ea
$04c4: 50ed      POSTDEC0 w, a, movf,     >   00000 f 56 r($09)<$6130 $5f98 $1512 $04ea
$04c6: 6ef7      TBLPTRH a, movwf,        >   00000 f 56 r($09)<$6130 $5f98 $1512 $04ea
$04c8: cfed.fff6 POSTDEC0 TBLPTRL movff,  >   00000 f 56 r($09)<$6130 $5f98 $1512 $04ea
$04cc: 0012      return,                  >   00000 f 56 r($08)<$7ffc $6130 $5f98 $1512
$04ea: 50f7      TBLPTRH w, a, movf,      >   00000 f 56 r($08)<$7ffc $6130 $5f98 $1512
$04ec: 6243      $0043 a, cpfseq,         >   00000 f 56 r($08)<$7ffc $6130 $5f98 $1512
$04ee: d7c8      $0480 bra,               >   00000 f 56 r($08)<$7ffc $6130 $5f98 $1512
$0480: 0009      tblrd*+,                 >   00000 f 56 r($08)<$7ffc $6130 $5f98 $1512
$0482: 50f5      TABLAT w, a, movf,       >   00000 f 03 r($08)<$7ffc $6130 $5f98 $1512
$0484: 6eec      PREINC0 a, movwf,        >   00000 f 03 r($08)<$7ffc $6130 $5f98 $1512
$0486: 6aec      PREINC0 a, clrf,         >   00100 f 03 r($08)<$7ffc $6130 $5f98 $1512
$0488: 0012      return,                  >   00100 f 03 r($07)<$7fff $7ffc $6130 $5f98
$1512: 0efd      $fd movlw,               >   00100 f fd r($07)<$7fff $7ffc $6130 $5f98
$1514: 2aeb      PLUSW0 f, a, incf,       >   00000 f fd r($07)<$7fff $7ffc $6130 $5f98
$1516: e302      $151c bnc,               >   00000 f fd r($07)<$7fff $7ffc $6130 $5f98
$151c: 0012      return,                  >   00000 f fd r($06)<$613a $7fff $7ffc $6130
$5f98: dfef      tsta rcall,              >   00000 f fd r($07)<$7fff $7ffc $6130 $5f9a
$5f78: ec9a.f012 $ff call,                >   00000 f fd r($08)<$7ffc $6130 $5f9a $5f7c
$2534: 68ec      PREINC0 a, setf,         >   00000 f fd r($08)<$7ffc $6130 $5f9a $5f7c
$2536: 6aec      PREINC0 a, clrf,         >   00100 f fd r($08)<$7ffc $6130 $5f9a $5f7c
$2538: 0012      return,                  >   00100 f fd r($07)<$7fff $7ffc $6130 $5f9a
$5f7c: ecc4.f007 dup call,                >f
$5f7c: dup                  >   d($04) $5679 $0003 $00ff $00ff
$5f80: 2drop ;              >q
  ok<#,ram>22137 3 255 255**

[PabloC]

The debug is based on the trigger of the Timer5 that interrupts the execution, and is installed through the method provided by "[i ... i] ;i" to start executing forth from the interrupt. The interrupt code 'dbgirq' changes the return address of the interrupt to the forth-word 'dbgstep' which processes the 'menu' and debug screen outputs, to finally push on the return-stack the original return address, and after resetting the timer emulate the return of the interrupt. For speed reasons, the word 'dbgirq' compares the breakpoints in use, or if we are debugging in assembler mode, and leaves it in a variable-flag, to avoid entering the debug forth menu again if it will be exited immediately.
The debug is executed on the forth itself, using the same data-stack as the forth that is being traced ('operator' task).
At first, it appears that the 'tick' timer could interact with the trace timer5 interrupt, so, pending analysis at another time, it is canceled during the debug.
There also appears to be a 'pause' related system corruption problem. Since 'pause' is called from rx1 ?, rx1, and tx1, and cannot be overridden, finally I choose to put some routines of 'rx1?', 'rx1.', and 'tx1.', which do not call pause, and point them in their corresponding key?, key, and emit. I have to study the implementation and operation of multi-tasking and 'pause'.
It is necessary to access the records saved in the interruption, to save and restore them before returning. Since the same data-stack is used, it is also necessary to save the byte above the pointer, since there are times when the forth primitives use the POSTDEC0-POSTINC0 instructions followed.
The words that process the interrupt and the entry in the debug process, seen from the disassembler itself, are as follows:

seea dbgirq
UnDec: dbgirq
$5cd8: cff3.f0bb PRODL $00bb movff,
$5cdc: cff4.f0bc PRODH $00bc movff,
$5ce0: cff6.f0b7 TBLPTRL $00b7 movff,
$5ce4: cff7.f0b8 TBLPTRH $00b8 movff,
$5ce8: cff5.f0b4 TABLAT $00b4 movff,
$5cec: cfe9.f0b9 FSR0L $00b9 movff,
$5cf0: cfea.f0ba FSR0H $00ba movff,
$5cf4: ee00.f05f $005f 0 lfsr,
$5cf8: ec64.f02a tm5irq? call,
$5cfc: 50ed      POSTDEC0 w, a, movf,
$5cfe: 10ed      POSTDEC0 w, a, iorwf,
$5d00: e042      $5d86 bz,
$5d02: ec43.f02a rstT5 call,
$5d06: 0101      $01 movlb,
$5d08: 51f8      (b)$f8 w, b, movf,
$5d0a: e002      $5d10 bz,
$5d0c: 0e05      $05 movlw,
$5d0e: d001      $5d12 bra,
$5d10: 0eff      $ff movlw,
$5d12: 6ff6      (b)$f6 b, movwf,
$5d14: e00b      $5d2c bz,
$5d16: ee01.f0eb $01eb 0 lfsr,
$5d1a: 38ee      POSTINC0 w, a, swapf,
$5d1c: 4ff6      (b)$f6 f, b, dcfsnz,
$5d1e: d021      $5d62 bra,
$5d20: 50fd      TOSL w, a, movf,
$5d22: 62ee      POSTINC0 a, cpfseq,
$5d24: d7fa      $5d1a bra,
$5d26: 50fe      TOSH w, a, movf,
$5d28: 62ee      POSTINC0 a, cpfseq,
$5d2a: d7f8      $5d1c bra,
$5d2c: c0b3.f1d1 $00b3 $01d1 movff,
$5d30: c0b5.f1d2 $00b5 $01d2 movff,
$5d34: c0b6.f1d3 $00b6 $01d3 movff,
$5d38: c0bb.f1d4 $00bb $01d4 movff,
$5d3c: c0bc.f1d5 $00bc $01d5 movff,
$5d40: c0b7.f1d6 $00b7 $01d6 movff,
$5d44: c0b8.f1d7 $00b8 $01d7 movff,
$5d48: c0b4.f1d8 $00b4 $01d8 movff,
$5d4c: c0b9.f1d9 $00b9 $01d9 movff,
$5d50: c0ba.f1da $00ba $01da movff,
$5d54: c1d9.ffe9 $01d9 FSR0L movff,
$5d58: c1da.ffea $01da FSR0H movff,
$5d5c: 0e01      $01 movlw,
$5d5e: cfeb.f1db PLUSW0 $01db movff,
$5d62: ecad.f02a $00555a call,
$5d66: cfd8.f1ce STATUS $01ce movff,
$5d6a: cfe0.f1cf BSR $01cf movff,
$5d6e: cfe8.f1d0 WREG $01d0 movff,
$5d72: edb8.f02a $005570 calls,
$5d76: cffd.f1f4 TOSL $01f4 movff,
$5d7a: cffe.f1f5 TOSH $01f5 movff,
$5d7e: 0e58      $58 movlw,
$5d80: 6efd      TOSL a, movwf,
$5d82: 0e5c      $5c movlw,
$5d84: 6efe      TOSH a, movwf,
$5d86: c0ba.ffea $00ba FSR0H movff,
$5d8a: c0b9.ffe9 $00b9 FSR0L movff,
$5d8e: c0b4.fff5 $00b4 TABLAT movff,
$5d92: c0b7.fff6 $00b7 TBLPTRL movff,
$5d96: c0b8.fff7 $00b8 TBLPTRH movff,
$5d9a: c0bb.fff3 $00bb PRODL movff,
$5d9e: c0bc.fff4 $00bc PRODH movff,
$5da2: ef2e.f000 $00005c goto,
 ok<#,ram>
seea dbgstep
UnDec: dbgstep
$5c58: 0101      $01 movlb,
$5c5a: 6df6      (b)$f6 b, negf,
$5c5c: e01c      $5c96 bz,
$5c5e: 50fc      STKPTR w, a, movf,
$5c60: 0101      $01 movlb,
$5c62: 6fe2      (b)$e2 b, movwf,
$5c64: dc3c      (gstk) rcall,
$5c66: def7      dbgmenu rcall,
$5c68: c1d1.fffa $01d1 PCLATH movff,
$5c6c: c1d2.ffe1 $01d2 FSR1L movff,
$5c70: c1d3.ffe2 $01d3 FSR1H movff,
$5c74: c1d4.fff3 $01d4 PRODL movff,
$5c78: c1d5.fff4 $01d5 PRODH movff,
$5c7c: c1d6.fff6 $01d6 TBLPTRL movff,
$5c80: c1d7.fff7 $01d7 TBLPTRH movff,
$5c84: c1d8.fff5 $01d8 TABLAT movff,
$5c88: c1d9.ffe9 $01d9 FSR0L movff,
$5c8c: c1da.ffea $01da FSR0H movff,
$5c90: 0e01      $01 movlw,
$5c92: c1db.ffeb $01db PLUSW0 movff,
$5c96: 0004      clrwdt,
$5c98: 0005      push,
$5c9a: c1f5.fffe $01f5 TOSH movff,
$5c9e: c1f4.fffd $01f4 TOSL movff,
$5ca2: 010f      $0f movlb,
$5ca4: 0e42      $42 movlw,
$5ca6: 6f4e      (b)$4e b, movwf,
$5ca8: 6b4d      (b)$4d b, clrf,
$5caa: 0eff      $ff movlw,
$5cac: 6f50      (b)$50 b, movwf,
$5cae: 0efa      $fa movlw,
$5cb0: 6f4f      (b)$4f b, movwf,
$5cb2: 9ef2      INTCON 7 a, bcf,
$5cb4: c1ce.ffd8 $01ce STATUS movff,
$5cb8: c1cf.ffe0 $01cf BSR movff,
$5cbc: c1d0.ffe8 $01d0 WREG movff,
$5cc0: edb8.f02a $005570 calls,
$5cc4: 010f      $0f movlb,
$5cc6: 927e      PIR5 1 a, bcf,
$5cc8: 814e      (b)$4e 0 b, bsf,
$5cca: 0010      retfie,
$5ccc: 0012      return,
 ok<#,ram>

[PabloC]

I repeat the second of the 'post', to give the text of the terminal a monospace format.

---

The 'see' of forth is complex of programing since this forth is direct-threading or rather subroutine-threaded code, with in-line expansion. In this way a call to a forth word can be compiled as a 'call', a 'goto', or correspond to a serie of inline cpu instructions.
As for the low-level disassembler, I found it important to give the option to interpret the ram bank in use, and present the symbolic name of the SFR, as well as the name of the routine (forth-word) called for each call or each goto.
The names of some SFRs are in a table of constants, to be used by the disassembler and also the assembler.
The names of the cpu instructions are in a table of the disassembler, which in the future could be grouped with the assembler, to take up less space on the flashrom.
Disassembly is done with forth words to be called for each instruction to see (which will use the debug) or by blocks of instrucctions to see from the 'forth' console.
see ( - | word ) see word code on a line
seel ( - | word ) see word code by lines
seea ( - | word ) see word on assembler
(.uasm) ( addr – addr' ) print instruction, returns address to next
                      disassembly variables are updated
(.fw) ( addr – addr' ) print a word, returns address to next word
                      disassembly variables are updated
As an example (copied from the window of a serial terminal ):

see within
: within over - >r - r> u< ; 
 ok<#,ram>
seel within
UnDec: within
$10b2: over
$10b4: -
$10b6: >r
$10b8: -
$10ba: r>
$10bc: u< ;
 ok<#,ram>
seea within
UnDec: within
$10b2: df35      over rcall,
$10b4: df88      - rcall,
$10b6: df44      >r rcall,
$10b8: df86      - rcall,
$10ba: df4f      r> rcall,
$10bc: ef8b.f008 u< goto,
 ok<#,ram>

For a branched word:

: ss $12 0= if dup else $3456 then begin dup until drop ;  ok<#,ram>
see ss
: ss $0012 (0=?bra>$5fce) dup (bra>$5fd6) $3456 (dup?bra<$5fd6) drop ;
 ok<#,ram>
seel ss
UnDec: ss
$5fbc: (lit:$0012)
$5fc2: (0=?bra>$5fce)
$5fc8: dup
$5fcc: (bra>$5fd6)
$5fce: (lit:$3456)
$5fd6: (dup?bra<$5fd6)
$5fdc: drop
$5fe0: ;
 ok<#,ram>
seea ss
UnDec: ss
$5fbc: 0e12      $12 movlw,
$5fbe: 6eec      PREINC0 a, movwf,
$5fc0: 6aec      PREINC0 a, clrf,
$5fc2: 50ed      POSTDEC0 w, a, movf,
$5fc4: 10ed      POSTDEC0 w, a, iorwf,
$5fc6: e103      $5fce bnz,
$5fc8: ecc4.f007 dup call,
$5fcc: d004      $5fd6 bra,
$5fce: 0e56      $56 movlw,
$5fd0: 6eec      PREINC0 a, movwf,
$5fd2: 0e34      $34 movlw,
$5fd4: 6eec      PREINC0 a, movwf,
$5fd6: 50ed      POSTDEC0 w, a, movf,
$5fd8: 10ee      POSTINC0 w, a, iorwf,
$5fda: e0fd      $5fd6 bz,
$5fdc: 6eed      POSTDEC0 a, movwf,
$5fde: 6eed      POSTDEC0 a, movwf,
$5fe0: 0012      return,
 ok<#,ram>