Debugging symbol format

[qwertyface]

I've been wondering if there might be value in coming up with a format for debugging symbols for ROMs and for gt1 files, if one doesn't exist at the moment.

Obviously there's the interface.json files, which define the public interface for a ROM, but there's a lot of points of interest that are defined as labels, or purely as Python variables. I guess the labels can be extracted from the .lst files that usually accompany the .roms. However I think that the names of significant memory addresses are mostly lost upon assembly.

As for vCPU code, I've mostly been exposed to GCL, which doesn't have any support for writing symbols anywhere as far as I know. Do either of the compilers support writing symbols to a file?

When I've needed this sort of information, I've been working in Python, so it hasn't been too hard[1] to use Marcel's modules to process the source files and gain access to the names that way, but it seems like there should be a better and more universal approach.

Any thoughts? Does this seem like it would be useful?

[1] It is actually quite hard.

[at67]

For ROMvX0 and gtBASIC there were a few occasions where I did need access to ROM Symbols and I thus added a slight change to asm.py to produce a Symbol table in gtBASIC module format, i.e.

Code: Select all

const videoZ = &h100
const startVideo = &h103
const vBlankStart = &h104
const vblankExpansion = &h12e
const vPulseInit = &h135
const sound1 = &h158
const vBlankNormal = &h191
const vBlankSample = &h198
const videoA = &h201
const pixels = &h20a
const sound3 = &h2ae
const sound2 = &h2b1
const videoB = &h2ca
const videoC = &h2d3
const videoD = &h2dc
const videoE = &h2e9
const videoF = &h2ec
const nopixels = &h2f6
const ENTER = &h2ff
const NEXTY = &h300
const NEXT = &h301
const EXIT = &h30b
const RESYNC = &h30c
const LDWI = &h311
const DEC = &h314
const MOVQB = &h316
const LSRB = &h318
const LD = &h31a
const ADDBI = &h31c
const CMPHS = &h31f
const LDW = &h321
const POKEI = &h325
const LSLV = &h327
const ADDVB = &h329
const STW = &h32b
const CNVXY = &h32d
const PREFX2 = &h32f
const MOVWA = &h332
const BCC = &h335
const SUBBI = &h338
const DEEKV = &h33b
const ARRVW = &h33d
const LDARRW = &h33f
const ADDVI = &h342
const SUBVI = &h344
const SUBVB = &h348
const DJGE = &h34a
const MOVQW = &h34d
const STWM = &h34f
const STARRW = &h351
const LDARRB = &h353
const STARRB = &h355
const STARRI = &h357
const LDI = &h359
const PEEKV = &h35b
const ST = &h35e
const POP = &h363
const MOVB = &h365
const PEEKA = &h367
const POKEA = &h369
const TEQ = &h36b
const TNE = &h36d
const DEEKA = &h36f
const LDWM = &h372
const PUSH = &h375
const DOKEI = &h377
const ARRW = &h379
const SCRLHR = &h37b
const DOKEA = &h37d
const LUP = &h37f
const ANDI = &h382
const CALLI = &h385
const ORI = &h388
const XORI = &h38c
const DBGE = &h38e
const BRA = &h390
const INC = &h393
const INCWA = &h395
const CMPHU = &h397
const ADDW = &h399
const LDNI = &h39c
const DBNE = &h39e
const DEEKR = &h3a0
const PACKAW = &h3a2
const DJNE = &h3a4
const CMPI = &h3a7
const ADDVW = &h3a9
const SUBVW = &h3ab
const PEEK = &h3ad
const PREFX1 = &h3b1
const SYS = &h3b4
const SUBW = &h3b8
const JEQ = &h3bb
const JNE = &h3bd
const JLT = &h3bf
const JGT = &h3c1
const JLE = &h3c3
const JGE = &h3c5
const PREFX3 = &h3c7
const REENTER = &h3cb
const DEF = &h3cd
const CALL = &h3cf
const TGE = &h3d5
const TLT = &h3d7
const TGT = &h3d9
const TLE = &h3db
const DECWA = &h3dd
const ALLOC = &h3df
const PACKVW = &h3e1
const ADDI = &h3e3
const SUBI = &h3e6
const LSLW = &h3e9
const STLW = &h3ec
const LDLW = &h3ee
const POKE = &h3f0
const DOKE = &h3f3
const DEEK = &h3f6
const ANDW = &h3f8
const ORW = &h3fa
const XORW = &h3fc
const RET = &h3ff
const shiftTable = &h500
const font32up = &h700
const font82up = &h800
const notesTable = &h900
const noteTrampoline = &h9c0
const invTable = &ha00
const STB2 = &h2211
const STW2 = &h2214
const XCHGB = &h2217
const MOVW = &h2219
const ADDWI = &h221b
const SUBWI = &h221d
const ANDWI = &h221f
const ORWI = &h2221
const XORWI = &h2223
const FNT6X8 = &h2225
const FNT4X6 = &h2228
const CONDII = &h222a
const CONDBB = &h222c
const CONDIB = &h222f
const CONDBI = &h2232
const XCHGW = &h2234
const OSCPX = &h2237
const SWAPB = &h2239
const SWAPW = &h223c
const NEEKA = &h223f
const NOKEA = &h2242
const ADDVL = &h2245
const SUBVL = &h2248
const ANDVL = &h224b
const ORVL = &h224e
const XORVL = &h2251
const JEQL = &h2254
const JNEL = &h2257
const JLTL = &h225a
const JGTL = &h225d
const JLEL = &h2260
const JGEL = &h2263
const ANDBI = &h2266
const ORBI = &h2269
const XORBI = &h226c
const ANDBK = &h226f
const ORBK = &h2272
const XORBK = &h2275
const JMPI = &h2278
const SUBIW = &h227b
const VADDBW = &h227d
const VSUBBW = &h2280
const VADDBL = &h2283
const VSUBBL = &h2286
const CMPII = &h2289
const IMIDI = &h228b
const PMIDI = &h228e
const PMIDIV = &h2291
const MERGE4 = &h2294
const MOVL = &h22cd
const MOVF = &h22d0
const NROL = &h22d3
const NROR = &h22d6
const LSLN = &h2311
const SEXT = &h2313
const NOTW = &h2315
const NEGW = &h2317
const ANDBA = &h2319
const ORBA = &h231c
const XORBA = &h231f
const FREQM = &h2322
const FREQA = &h2324
const FREQI = &h2327
const VOLM = &h2329
const VOLA = &h232c
const MODA = &h232f
const MODI = &h2332
const SMPCPY = &h2334
const SCRLH = &h2337
const SPARE = &h233a
const LEEKA = &h233d
const LOKEA = &h233f
const FEEKA = &h2341
const FOKEA = &h2343
const MEEKA = &h2345
const MOKEA = &h2347
const LSRVL = &h2349
const LSLVL = &h234c
const INCL = &h234f
const DECL = &h2352
const STPX = &h2354
const PRN4X6 = &h2357
const VTBL = &h2359
const OSCZ = &h235c
const LSL8 = &h235e
const ADDBA = &h2360
const SUBBA = &h2362
const NOTB = &h2364
const ABSVW = &h2367
const INCW = &h236a
const DECW = &h236c
const WAITVV = &h236e
const LSRV = &h2373
const DEEKRI = &h2375
const NCOPY = &h23cd
const STLU = &h23d0
const STLS = &h23d3
const NOTL = &h23d5
const NEGL = &h23d8
const NOTE = &h2411
const MIDI = &h2414
const XLA = &h2417
const ADDLP = &h241a
const SUBLP = &h241d
const ANDLP = &h2420
const ORLP = &h2423
const XORLP = &h2426
const CMPLPU = &h2429
const CMPLPS = &h242c
const RANDW = &h242f
const LDPX = &h2431
const ABSW = &h2433
const SGNW = &h2436
const MULB3 = &h2439
const MULB5 = &h243b
const MULB6 = &h243d
const MULB7 = &h243f
const MULB8 = &h2441
const MULB9 = &h2443
const MULB10 = &h2445
const WAITVB = &h2447
const MULW3 = &h2449
const MULW5 = &h244b
const MULW6 = &h244d
const MULW7 = &h244f
const MULW8 = &h2451
const MULW9 = &h2453
const MULW10 = &h2455
const prn4x6Return = &h3585
const memSize = &h1
const entropy0 = &h6
const entropy1 = &h7
const videoY = &h9
const frameCount = &he
const serialRaw = &hf
const buttonState = &h11
const xoutMask = &h14
const vPC = &h16
const vAC = &h18
const vACH = &h19
const vLR = &h1a
const vSP = &h1c
const vTmp = &h1d
const romType = &h21
const sysFn = &h22
const sysArgs0 = &h24
const sysArgs1 = &h25
const sysArgs2 = &h26
const sysArgs3 = &h27
const sysArgs4 = &h28
const sysArgs5 = &h29
const sysArgs6 = &h2a
const sysArgs7 = &h2b
const soundTimer = &h2c
const userVars = &h30
const videoTable = &h100
const userCode = &h200
const soundTable = &h700
const screenMemory = &h800
const vReset = &h1f0
const wavA = &hfa
const wavX = &hfb
const keyL = &hfc
const keyH = &hfd
const oscL = &hfe
const oscH = &hff
const maxTicks = &hf
const qqVgaWidth = &ha0
const qqVgaHeight = &h78
const buttonRight = &h1
const buttonLeft = &h2
const buttonDown = &h4
const buttonUp = &h8
const buttonStart = &h10
const buttonSelect = &h20
const buttonB = &h40
const buttonA = &h80
const zippedRacerHorizon = &h503f
const Racer = &h5c89
const Mandelbrot = &h63e3
const Credits = &h68d8
const Snake = &h6b3c
const TinyBASIC = &h7274
const Statements2 = &h500
const Hexnum = &h5ce
const GetLine2 = &h6e8
const Statements5 = &hdeb
const Print = &h13a0
const Statements3 = &h14a0
const Statements4 = &h15a0
const Statements6 = &h16a0
const Save = &h17a0
const Newline = &h18a0
const Line = &h19a0
const Line2 = &h1aa0
const Buffer = &h1ba0
const BasicProgram = &h1bc0
const TicTac = &h7f0e
const returnHere = &hffa0
const TicTacGtb = &h7f31
const WozMon = &h871b
const Apple1 = &h8984
const MSBASIC = &ha71e
const Egg = &hcd3a
const SDCard = &hd228
const Loader = &hdb83
const Boot = &hdbab
const Main = &he723
const Reset = &hf845
const Command = &h81

A standard format, (.json), or whatever would probably better so that it was available for more uses.

[qwertyface]

Thanks. Presumably your debugger also makes use of some non-public symbols (specifically ENTER and NEXT) for single stepping vCPU code.

[lb3361]

GLCC option --syms prints a symbol map. Option --frags tells you where all modules go in memory.

The compiler is based on LCC which has ways to output more detailed debugging information into the .o files (stabs format). This is currently not used because one would also have to write a source code debugger to make full use of this capability.


Example: (compiling https://github.com/lb3361/gigatron-lcc/ ... e/sieve1.c)

Code: Select all

$ glcc -rom=v5a -map=64k,hionly -Dprintf=mincprintf sieve1.c -o sieve1.gt1 --syms --frags
sieve1.c:44: warning: missing return value

Symbol table
	88e8 public    _@_bcopy_                 libc.a(rt_bcopy.s)      
	8c4c public    _@_divu                   libc.a(rt_divu.s)       
	88e2 public    _@_fcopy_                 libc.a(rt_bcopy.s)      
	84ef public    _@_modu                   libc.a(rt_modu.s)       
	83ea public    _@_raise_zdiv             libc.a(raise_zdiv.s)    
	8c44 public    _@_rtrn_00                libc.a(rt_save.s)       
	8c3f public    _@_rtrn_80                libc.a(rt_save.s)       
	8c36 public    _@_rtrn_c0                libc.a(rt_save.s)       
	8c2d public    _@_rtrn_e0                libc.a(rt_save.s)       
	8c24 public    _@_rtrn_f0                libc.a(rt_save.s)       
	8c1b public    _@_rtrn_f8                libc.a(rt_save.s)       
	8c12 public    _@_rtrn_fc                libc.a(rt_save.s)       
	8c09 public    _@_rtrn_fe                libc.a(rt_save.s)       
	8c00 public    _@_rtrn_ff                libc.a(rt_save.s)       
	8bbd public    _@_save_80                libc.a(rt_save.s)       
	8bb3 public    _@_save_c0                libc.a(rt_save.s)       
	8ba9 public    _@_save_e0                libc.a(rt_save.s)       
	8b9f public    _@_save_f0                libc.a(rt_save.s)       
	8b95 public    _@_save_f8                libc.a(rt_save.s)       
	8b8b public    _@_save_fc                libc.a(rt_save.s)       
	8b81 public    _@_save_fe                libc.a(rt_save.s)       
	8b77 public    _@_save_ff                libc.a(rt_save.s)       
	8ae6 public    _@_wcopy_                 libc.a(rt_wcopy.s)      
	8bc4 public    __@divworker              libc.a(rt_divworker.s)  
	83cb public    __@raisem                 libc.a(raise.s)         
	84fe public    __glink_magic_bss         libc.a(_init1.c)        
	83f8 public    __glink_magic_fini        libc.a(_start.s)        
	82fe public    __glink_magic_init        libc.a(_start.s)        
	84fa private   __glink_magic_init        libc.a(cons_output.c)   
	84ac private   _callchain                libc.a(_start.s)        
	8600 public    _console_clear            libc.a(cons_clear.s)    
	8770 public    _console_ctrl             libc.a(cons_ctrl.c)     
	8535 public    _console_printchars       libc.a(cons_printchar.s)
	8629 public    _console_reset            libc.a(cons_geom.c)     
	8b00 public    _console_setup            libc.a(cons_setup.c)    
	8484 public    _exit                     libc.a(_start.s)        
	8488 public    _exitm                    libc.a(_start.s)        
	8491 public    _exitm_msgfunc            libc.a(_start.s)        
	848d private   _exitvsp                  libc.a(_start.s)        
	0200 public    _gt1exec                  _gt1exec.s              
	8b22 public    _init_bss                 libc.a(_init1.c)        
	8408 public    _memchr2                  libc.a(memchr.s)        
	838e private   _memscan0                 libc.a(memchr.s)        
	8594 private   _printonechar             libc.a(cons_printchar.s)
	83ce public    _raise_disposition        libc.a(raise.s)         
	83ba public    _raisem                   libc.a(raise.s)         
	8451 public    _start                    libc.a(_start.s)        
	850d public    _utoa                     libc.a(utoa.s)          
	8869 private   cons_addr                 libc.a(cons_output.c)   
	88b2 public    console_clear_screen      libc.a(cons_output.c)   
	8900 public    console_clear_to_eol      libc.a(cons_output.c)   
	8a98 private   console_exitm_msgfunc     libc.a(cons_setup.c)    
	8cbc public    console_info              libc.a(cons_geom.c)     
	8990 public    console_print             libc.a(cons_output.c)   
	8cde public    console_state             libc.a(cons_output.c)   
	8476 public    exit                      libc.a(_start.s)        
	8d00 public    flags                     sieve1.c                
	84d1 public    itoa                      libc.a(itoa.s)          
	8240 public    main                      sieve1.c                
	8400 public    memchr                    libc.a(memchr.s)        
	8345 public    memset                    libc.a(memset.s)        
	85dd public    mincprintf                libc.a(mincprintf.c)    
	83b6 public    raise                     libc.a(raise.s)         
	8933 private   scroll                    libc.a(cons_output.c)   
	8680 public    strlen                    libc.a(strlen.c)        
	8500 public    utoa                      libc.a(utoa.s)          

Fragment map
	0200-0226 (39 bytes)     CODE  _gt1exec                     _gt1exec.s            
	8240-82fd (190 bytes)    CODE  main (1/2)                   sieve1.c              
	82fe-82ff (2 bytes)      DATA  __glink_magic_init           libc.a(_start.s)      
	8300-8344 (69 bytes)     CODE  main (2/2)                   sieve1.c              
	8345-838d (73 bytes)     CODE  memset                       libc.a(memset.s)      
	838e-83b5 (40 bytes)     CODE  _memscan0                    libc.a(memchr.s)      
	83b6-83e9 (52 bytes)     CODE  raise                        libc.a(raise.s)       
	83ea-83f6 (13 bytes)     CODE  _@_raise_zdiv                libc.a(raise_zdiv.s)  
	83f8-83f9 (2 bytes)      DATA  __glink_magic_fini           libc.a(_start.s)      
	83fa-83ff (6 bytes)      DATA  .27                          libc.a(cons_ctrl.c)   
	8400-8450 (81 bytes)     CODE  memchr                       libc.a(memchr.s)      
	8451-84ab (91 bytes)     CODE  _start                       libc.a(_start.s)      
	84ac-84d0 (37 bytes)     CODE  .callchain                   libc.a(_start.s)      
	84d1-84ee (30 bytes)     CODE  itoa                         libc.a(itoa.s)        
	84ef-84f8 (10 bytes)     CODE  _@_modu                      libc.a(rt_modu.s)     
	84fa-84fd (4 bytes)      DATA  __glink_magic_init           libc.a(cons_output.c) 
	84fe-84ff (2 bytes)      DATA  __glink_magic_bss            libc.a(_init1.c)      
	8500-8534 (53 bytes)     CODE  utoa                         libc.a(utoa.s)        
	8535-8593 (95 bytes)     CODE  _console_printchars          libc.a(cons_printchar.s)
	8594-85dc (73 bytes)     CODE  _printonechar                libc.a(cons_printchar.s)
	85dd-85ff (35 bytes)     CODE  mincprintf (1/3)             libc.a(mincprintf.c)  
	8600-8628 (41 bytes)     CODE  _console_clear               libc.a(cons_clear.s)  
	8629-867f (87 bytes)     CODE  _console_reset               libc.a(cons_geom.c)   
	8680-86b5 (54 bytes)     CODE  strlen                       libc.a(strlen.c)      
	86b6-86fe (73 bytes)     CODE  mincprintf (2/3)             libc.a(mincprintf.c)  
	8700-876f (112 bytes)    CODE  mincprintf (3/3)             libc.a(mincprintf.c)  
	8770-87f8 (137 bytes)    CODE  _console_ctrl (1/2)          libc.a(cons_ctrl.c)   
	8800-8868 (105 bytes)    CODE  _console_ctrl (2/2)          libc.a(cons_ctrl.c)   
	8869-88b1 (73 bytes)     CODE  cons_addr                    libc.a(cons_output.c) 
	88b2-88e1 (48 bytes)     CODE  console_clear_screen         libc.a(cons_output.c) 
	88e2-88fe (29 bytes)     CODE  _@_bcopy_                    libc.a(rt_bcopy.s)    
	8900-8932 (51 bytes)     CODE  console_clear_to_eol         libc.a(cons_output.c) 
	8933-898f (93 bytes)     CODE  scroll                       libc.a(cons_output.c) 
	8990-89fe (111 bytes)    CODE  console_print (1/2)          libc.a(cons_output.c) 
	8a00-8a97 (152 bytes)    CODE  console_print (2/2)          libc.a(cons_output.c) 
	8a98-8ae5 (78 bytes)     CODE  console_exitm_msgfunc        libc.a(cons_setup.c)  
	8ae6-8afc (23 bytes)     CODE  _@_wcopy_                    libc.a(rt_wcopy.s)    
	8b00-8b21 (34 bytes)     CODE  _console_setup               libc.a(cons_setup.c)  
	8b22-8b76 (85 bytes)     CODE  _init_bss                    libc.a(_init1.c)      
	8b77-8bc3 (77 bytes)     CODE  _@_save_ff                   libc.a(rt_save.s)     
	8bc4-8bf3 (48 bytes)     CODE  __@divworker                 libc.a(rt_divworker.s)
	8bf4-8bfe (11 bytes)     DATA  .20                          sieve1.c              
	8c00-8c4b (76 bytes)     CODE  _@_rtrn_ff                   libc.a(rt_save.s)     
	8c4c-8c89 (62 bytes)     CODE  _@_divu                      libc.a(rt_divu.s)     
	8c8a-8c9b (18 bytes)     DATA  .21                          sieve1.c              
	8c9c-8caa (15 bytes)     DATA  .2                           sieve1.c              
	8cab-8cbb (17 bytes)     DATA  .msg                         libc.a(raise_zdiv.s)  
	8cbc-8ccf (20 bytes)     DATA  console_info                 libc.a(cons_geom.c)   
	8cd0-8cdd (14 bytes)     DATA  .32                          libc.a(cons_ctrl.c)   
	8cde-8ce5 (8 bytes)      DATA  console_state                libc.a(cons_output.c) 
	8ce6-8ced (8 bytes)      DATA  .6                           libc.a(cons_setup.c)  
	8d00-acfe (8191 bytes)   BSS   flags                        sieve1.c              

[qwertyface]

That's interesting. I'd not heard of stabs. Source code debugging is the sort of use case I was thinking of building up to. For now, I think just being able to replace addresses with variable names while stepping through instructions would be very useful, but I'm approaching it with a GCL mindset, where variables are all global and statically allocated. That isn't the case for the other vCPU languages.

[lb3361]

In GCL you have two things, variables and symbols.

Variables are in a dict named 'program.vars' that could be printed with an additional option in 'compilegcl.py'.

Symbols seem to be mingled with the native symbols and accessible in a dict named '_symbols' imported from module 'asm.py'. This module also defines the 'loadBindings' function that imports 'interface.json'. But new symbols defined in your gcl are added to that. One could also print them from 'compilegcl.py' I assume...