P2 ROM Monitor/Debugger (rev 1 & rev 2 silicon)

Cluso99 · 2019-10-18 - 23:23:30

P2 Monitor/Debugger
The Monitor/Debugger is loaded into the top 16KB of HUB RAM from the internal serial ROM by the booter software. The Monitor/Debugger code occupies HUB $FCA78-$FD025 inclusive (1454 bytes).
The Monitor/Debugger, along with TAQOZ and the autobaud booter, are all resident in HUB after power-up. Only an external serial terminal connected to Pins 63(in) and 62(out) is necessary to invoke the Monitor/Debugger or TAQOZ.
The Monitor/Debugger can be entered directly from power-up via the two character Serial autobaud sequence “> “ followed by Ctl-D. The Monitor/Debugger uses the serial connection via P63(in) and P62(out). The Monitor/Debugger supports the following commands at the input prompt…

---------------------------------------------------------------------------------------------
LMM DEBUGGER - SUPPORTED COMMANDS (Rev 1 & 2 silicon)
---------------------------------------------------------------------------------------------
xxxxxx : xx xx xx xx ... <cr>  DOWNLOAD:  to   cog/lut/hub {addr1} following {byte(s)}
xxxxxx - [xxxxxx] [L] <cr>     MEM LIST:  from cog/lut/hub {addr1} to < {addr2}  L=longs
xxxxxx G <cr>                  GOTO:      to   cog/lut/hub {addr1}
Q <cr>                         QUIT:      Quit Rom Monitor and return to the User Program
                                             {addr} is on the stack
Lfilename.xxx<cr>              LOAD:      Load file from SD   (8.3 filename)
                                             returns "=" on success, "!" on failure
Rfilename.xxx<cr>              RUN:       Run  file from SD   (8.3 filename)
                                             returns "!" on failure
<esc><cr>                      TAQOZ:     goto TAQOZ
<cr>                                      will repeat last MEM LIST command
---------------------------------------------------------------------------------------------
Note: COG/LUT addresses are 3 digits or less and <$3FF, otherwise hub address is presumed. 
To list a low Hub address below $400, use a leading zero. (When calling from a user program use $1x_xxxx as only the lower 20 address bits are used)

Calling the Monitor/Debugger from User Programs
The Monitor/Debugger is callable from a users’ program.
The Monitor/Debugger Routines are also callable from a users’ program.
COG & HUB RAM Usage by the Debugger/Monitor
The Monitor/Debugger uses COG RAM $1E0-$1EF for variables.
The Receive String routines use HUB RAM $FC000-$FC04F as the input buffer unless lmm_bufad is initialised to point to a different HUB RAM address. Note: This buffer overwrites to booter code!

Below is a list of Routines that may be called by a user’s program…

--------------------------------------------------------------------------------------------
LMM DEBUGGER - Routines callable from users' programs
--------------------------------------------------------------------------------------------
_SerialInit   = $fcab8 'Serial Initialise     (lmm_x & lmm_bufad must be set first)
_HubTxCR      = $fcae4 'Sends <cr><lf>        (overwrites lmm_x)
_HubTxRev     = $fcaec 'Sends lmm_x with bytes reversed
_HubTx        = $fcaf0 'Sends lmm_x           (can be up to 4 bytes)
_HubHexRev    = $fcb24 'Sends lmm_x with bytes reversed as Hex char(s) as defined in lmm_f
_HubHex8      = $fcb28 'Sends lmm_x as Hex char(s) after setting lmm_f as 8 hex chars
_HubHex       = $fcb2c 'Sends lmm_x as Hex char(s) as defined in lmm_f
_HubTxStrVer  = $fcb9c 'Sends hub $0 terminated string at lmm_p address 
                           after setting lmm_p=##_str_vers
_HubTxString  = $fcba4 'Sends hub $0 terminated string at lmm_p address
_HubListA2H   = $fcbc4 'List/Dump line(s) from lmm_p address to lmm_p2 address 
                           after setting lmm_f=#_LIST+_ADDR2 
_HubList      = $fcbc8 'List/Dump line(s) from lmm_p address to lmm_p2 address 
                           according to lmm_f
_HubRx        = $fcb10 'Recv char into lmm_x
_HubRxStrMon  = $fccc4 'Recv string into hub address pointed to by lmm_bufad after setting 
                           prompt=lmm_x=#"*" & params=lmm_f=#_RXSTRING+_ECHO_+_PROMPT
_HubRxString  = $fcccc 'Recv string into hub address pointed to by lmm_p/lmm_bufad 
                           according to params in lmm_f
_HubMonitor   = $fcd78 'Calls the Monitor; uses lmm_bufad as the input buffer address
_RdLongCogHub = $fcf34 'read cog/lut/hub long from lmm_p address into lmm_x, then lmm_p++
_str_vers     = $fd014 'locn of the monitors hub string, $0 terminated
--------------------------------------------------------------------------------------------
  _HUBROM     = $FC000 'ROM $FC000
  _HUBBUF     = $FC000 'use as RxString buffer    (overwrites Booter)
  _HUBBUFSIZE = 80     'default size for _HUBBUF  (can be 128)
--------------------------------------------------------------------------------------------

Below is a list of the COG RAM variables and their usage…

--------------------------------------------------------------------------------------------
LMM DEBUGGER - COG VARIABLES $1E0-$1EF
-------[ LMM parameters, etc ]--------------------------------------------------------------
lmm_x     = $1e0 'parameter passed to/from LMM routine (typically a value)
lmm_f     = $1e1 'parameter passed to      LMM routine (function options; returns unchanged)
lmm_p     = $1e2 'parameter passed to/from LMM routine (typically a hub/cog ptr/addr)
lmm_p2    = $1e3 'parameter passed to/from LMM routine (typically a 2nd hub/cog address)
lmm_c     = $1e4 'parameter passed to/from LMM routine (typically a count)
-------[ LMM additional workareas ]-------------------------------------------
lmm_w     = $1e5 'workarea (never saved - short term use between calls, except _HubTx)
lmm_tx    = $1e6 '_HubTx
lmm_hx    = $1e7 '_HubHex/_HubString
lmm_hx2   = $1e8 '_HubHex
lmm_hc    = $1e9 '  "
lmm_lx    = $1ea '_HubList
lmm_lf    = $1eb '  "
lmm_lp    = $1ec '  "
lmm_lp2   = $1ed '  "
lmm_lc    = $1ee '  "
lmm_bufad = $1ef '_HubRxString
--------------------------------------------------------------------------------------------

The following are values passed in lmm_f for HEX, LIST and RXSTRING calls…

--------------------------------------------------------------------------------------------
LMM DEBUGGER - lmm_f CALL Modes...(b4..b0 are modifier options)
--------------------------------------------------------------------------------------------
_HEX_     = 2 << 5   ' hex...
  _REV_    = 1 << 4  '   - reverse byte order
  _SP      = 1 << 3  '   - space between hex output pairs
 '_DIGITS  = 7..0    ' no. of digits to display where 0 is 8 digits
_LIST     = 3 << 5   ' LIST memory line (1/4 longs) from cog/hub
  _ADDR2   = 1 << 4  '  1= use lmm_p2 as to-address
  _LONG_   = 1 << 1  '  1=display longs xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx
_RXSTRING = 5 << 5   ' RXSTRING...
  _ECHO_   = 1 << 4  '    - echo char
  _PROMPT  = 1 << 3  '    - prompt (lmm_x)
  _ADDR    = 1 << 2  '    - addr of string buffer supplied
  _NOLF    = 1 << 1  '    - strip <lf>
--------------------------------------------------------------------------------------------

Note: The use of the lmm_ prefix is a carry over from when I first wrote the Monitor/Debugger way back in 2013. This was intended for the original P2 design which did not support HUBEXEC. So I used the LMM model as originally defined by Bill Henning. LMM stands for Large Memory Model, where a tiny routine in COG fetches each instruction from HUB and executes it in COG.

Cluso99 · 2019-10-18 - 23:31:43

Monitor/Debugger - COG Variables (for use in your program(s) as res or equ

''============[ COG VARIABLES - MONITOR]========================================
                org     $1E0              ' place the variables in cog $1E0-$1EF
''-------[ LMM parameters, etc ]------------------------------------------------
lmm_x           res     1       ' parameter passed to/from LMM routine (typically a value)
lmm_f           res     1       ' parameter passed to      LMM routine (function options; returns unchanged)
lmm_p           res     1       ' parameter passed to/from LMM routine (typically a hub/cog ptr/addr)
lmm_p2          res     1       ' parameter passed to/from LMM routine (typically a 2nd hub/cog address)
lmm_c           res     1       ' parameter passed to/from LMM routine (typically a count)
''-------[ LMM additional workareas ]-------------------------------------------
lmm_w           res     1       ' workarea (never saved - short term use between calls, except _HubTx)
lmm_tx          res     1       ' _HubTx
lmm_hx          res     1       ' _HubHex/_HubString
lmm_hx2         res     1       ' _HubHex
lmm_hc          res     1       '   "
lmm_lx          res     1       ' _HubList
lmm_lf          res     1       '   "
lmm_lp          res     1       '   "
lmm_lp2         res     1       '   "
lmm_lc          res     1       '   "
lmm_bufad       res     1       ' _HubRxString
                fit     $1F0

-OR-

''============[ COG VARIABLES $1E0-$1EF - MONITOR]=============================
''-------[ LMM parameters, etc ]-----------------------------------------------
  lmm_x         = $1e0          ' parameter passed to/from LMM routine (typically a value)
  lmm_f         = $1e1          ' parameter passed to      LMM routine (function options; returns unchanged)
  lmm_p         = $1e2          ' parameter passed to/from LMM routine (typically a hub/cog ptr/addr)
  lmm_p2        = $1e3          ' parameter passed to/from LMM routine (typically a 2nd hub/cog address)
  lmm_c         = $1e4          ' parameter passed to/from LMM routine (typically a count)
''-------[ LMM additional workareas ]------------------------------------------
  lmm_w         = $1e5          ' workarea (never saved - short term use between calls, except _HubTx)
  lmm_tx        = $1e6          ' _HubTx
  lmm_hx        = $1e7          ' _HubHex/_HubString
  lmm_hx2       = $1e8          ' _HubHex
  lmm_hc        = $1e9          '   "
  lmm_lx        = $1ea          ' _HubList
  lmm_lf        = $1eb          '   "
  lmm_lp        = $1ec          '   "
  lmm_lp2       = $1ed          '   "
  lmm_lc        = $1ee          '   "
  lmm_bufad     = $1ef          ' _HubRxString
'' +--------------------------------------------------------------------------+
'' ASCII equates
'' +--------------------------------------------------------------------------+
  _CLS_         = $0C     
  _BS_          = $08
  _LF_          = $0A
  _CR_          = $0D
  _TAQOZ_       = $1B           ' <esc>   goto TAQOZ
'' +--------------------------------------------------------------------------+

Cluso99 · 2019-10-18 - 23:32:04

Code examples to go here

Cluso99 · 2019-10-21 - 08:40:16

The first post has been updated with a description of the Monitor/Debugger.

evanh · 2019-10-21 - 12:04:06

Thanks Cluso. Add it to your sticky links.

samuell · 2019-10-23 - 23:40:55

I was wondering how to enter the monitor, all this time. So, in short, right at boot:
- [>][ ][Esc] to enter TAQOZ
- [>][ ][Ctrl + D] to enter P2 Monitor

Thanks, Cluso! It worked.

Kind regards, Samuel Lourenço

Equip your Genius

Categories

P2 ROM Monitor/Debugger (rev 1 & rev 2 silicon)

Comments

Equip your Genius

Quick Links

Categories

P2 ROM Monitor/Debugger (rev 1 & rev 2 silicon)

Comments