sdcc/debugger/README

   1 sdcc/debugger
   2
   3 SDCDB debugger - Development notes.
   4 ======================
   5
   6
   7 ddd - Notes from Martin Helmling, May   23, 2003
   8 ========================
   9
  10 Additionally following new commands work:
  11
  12 ignore <breakpointnumber> <ignorecount> - ignore the breakpoint n times
  13 condition <breakpointnumber> <variable> <|>|<=|>=|==|!= <constant> - break condition
  14 commands - see gdb description -
  15
  16 ddd - Notes from Martin Helmling, April 28, 2003
  17 ========================
  18
  19 To fullfill the requirements of 'ddd' ( Data Display Debugger ) to use it at
  20 graphical frontend to 'sdcdb' some new commands must be implemented.
  21
  22 Now you can run the ddd with the commandline
  23
  24 ddd -debugger 'sdcdb -cpu 8032 <file>'
  25
  26 Following commands are additional implemented:
  27
  28 1. execution:
  29
  30 stepi - Step one instruction exactly using simulator 'step' command.
  31 nexti - Step one instruction, but proceed through subroutine calls using simulator 'next' command.
  32 break *<addr> - Set breakpoint at program address
  33
  34 log examples:
  35 -> "stepi\n"
  36 <- "Simulator stopped at Address 0x0051\n"
  37    "\032\032x.c:31:1:beg:0x00000051\n"
  38    "(sdcdb) "
  39 -> "nexti\n"
  40 <- "Simulator stopped at Address 0x0055\n"
  41    "\032\032x.c:33:1:beg:0x00000055\n"
  42    "(sdcdb) "
  43
  44 2. show machine code window:
  45
  46 x /i  - disassemble one asm command
  47 x disassemble asm commands
  48
  49 log examples:
  50 -> "x /i 0x00000055\n"
  51 <- "0x00000055 <main+6>:\t\tmov\tr0,#_l\n"
  52    "(sdcdb) "
  53 -> "disassemble 0x00000055\n"
  54 <- "Dump of assembler code for function main:\n"
  55    "0x0000004f <main>:\t\tmov\tr0,#_ttt\n"
  56    "0x00000051 <main+2>:\t\tmov\t@r0,#0x01\n"
  57 <- "0x00000053 <main+4>:\t\tmov\tr2,#0x09\n"
  58    "0x00000055 <main+6>:\t\tmov\tr0,#_l\n"
  59 ...
  60    "0x000000c1 <main+114>:\t\tret\n"
  61    "End of assembler dump.\n"
  62    "(sdcdb) "
  63 -> "disassemble 0x40 0x45\n"
  64 <- "Dump of assembler code from 0x00000040 to 0x00000045:\n"
  65    "0x00000040 <subfunc1+8>:\t\tinc\tr0\n"
  66    "0x00000041 <subfunc1+9>:\t\tmov\t@r0,ar3\n"
  67    "0x00000043 <subfunc1+11>:\t\tmov\ta,r3\n"
  68    "0x00000044 <subfunc1+12>:\t\trlc\ta\n"
  69    "0x00000045 <subfunc1+13>:\t\tsubb\ta,acc\n"
  70    "End of assembler dump.\n"
  71    "(sdcdb) "
  72 -> "break x.c:23\n"
  73 <- "Breakpoint 1 at 0x4b: file x.c, line 23.\n"
  74    "(sdcdb) "
  75 -> "info breakpoints\n"
  76 <- "Num Type           Disp Enb Address    What\n"
  77    "1   breakpoint     keep y   0x0000004b at x.c:23\n"
  78    "(sdcdb) "
  79 ->
  80
  81 3. show registers and stack
  82
  83 frame - print information about the current Stack
  84 where - print stack
  85 up    - Select and print stack frame that called this one
  86 down  - Select and print stack frame that called this one
  87 info registers - show registers
  88 info all-registers - show also special these function registers,
  89                      which are symbolical defined.
  90 help <cmd> show short help for ddd tooltip info
  91 log examples:
  92
  93 -> "where\n"
  94 <- "#0  0x0000004b in subfunc1 () at x.c:23\n"
  95    "#1  0x0000004f in main () at x.c:31\n"
  96    "(sdcdb) "
  97 -> "frame\n"
  98 <- "#0  0x0000004b in subfunc1 () at x.c:23\n"
  99    "\032\032x.c:23:1:beg:0x0000004b\n"
 100    "(sdcdb) "
 101 -> "up\n"
 102 <- "#1  0x0000004f in main () at x.c:31\n"
 103    "\032\032x.c:31:1:beg:0x0000004f\n"
 104    "(sdcdb) "
 105 -> "frame\n"
 106 <- "#1  0x0000004f in main () at x.c:31\n"
 107    "\032\032x.c:31:1:beg:0x0000004f\n"
 108    "(sdcdb) "
 109 -> "down\n"
 110 <- "#0  0x0000004b in subfunc1 () at x.c:23\n"
 111    "\032\032x.c:23:1:beg:0x0000004b\n"
 112    "(sdcdb) "
 113 -> "frame\n"
 114 <- "#0  0x0000004b in subfunc1 () at x.c:23\n"
 115    "\032\032x.c:23:1:beg:0x0000004b\n"
 116    "(sdcdb) "
 117 -> "info registers\n"
 118 <- "R0  : 0x87 135 .\n"
 119    "R1  : 0x00 0 .\n"
 120    "R2  : 0x05 5 .\n"
 121    "R3  : 0x00 0 .\n"
 122    "R4  : 0x00 0 .\n"
 123    "R5  : 0x08 8 .\n"
 124    "R6  : 0x00 0 .\n"
 125    "ACC : 0x00 0 .\n"
 126    "B   : 0x00 0 .\n"
 127    "DPTR: 0x0005 5\n"
 128    "@DPTR: 0x00 0 .\n"
 129    "PSW  : 0x00 | CY : 0 | AC : 0 | OV : 0 | P : 0\n"
 130    "(sdcdb) "
 131 #  Showing all registers.
 132 -> "info all-registers\n"
 133 <- "R0  : 0x87 135 .\n"
 134    "R1  : 0x00 0 .\n"
 135    "R2  : 0x05 5 .\n"
 136    "R3  : 0x00 0 .\n"
 137    "R4  : 0x00 0 .\n"
 138    "R5  : 0x08 8 .\n"
 139    "R6  : 0x00 0 .\n"
 140    "ACC : 0x00 0 .\n"
 141    "B   : 0x00 0 .\n"
 142    "DPTR: 0x0005 5\n"
 143    "@DPTR: 0x00 0 .\n"
 144    "PSW  : 0x00 | CY : 0 | AC : 0 | OV : 0 | P : 0\n"
 145    "Special Function Registers:\n"
 146 <- "P0=0xff P0_0=1 P0_1=1 P0_2=1 P0_3=1\n"
 147    "SP=0x13\n"
 148    "(sdcdb) "
 149 -> "help step\n"
 150 <- "Step program until it reaches a different source line.\n"
 151    "(sdcdb) "
 152 -> "help stepi\n"
 153 <- "Step one instruction exactly.\n"
 154    "(sdcdb) "
 155
 156 4. show and set variables:
 157 output  [/<fmt>] <expr1> print value of <expr1> without newline for tooltip of ddd
 158 print   [/<fmt>] <expr1> print value of <expr1> with newline
 159 display [/<fmt>] <expr1> print value of <expr1> every time the program is stopped
 160                           or 'display' command without args is used.
 161
 162 set variable <expr1> = <value>
 163
 164
 165 <fmt> is the format for the basic type which is print out.
 166 If no format is set the default format is used.
 167 format is set by ddd  'x' as hex 'o' as octal, 'd' as dezimal and 't' as binary.
 168
 169 <expr1> can by a variable , a array element , a structure element ( [] and . is parsed ).
 170 indices of arrays may be constants or variables.
 171 ( dereference of pointers and casting today not implemented !! )
 172
 173 log examples:
 174 code:
 175
 176 typedef unsigned char uchar;
 177 idata long  l;
 178 typedef struct _txstate
 179 {
 180     uchar dstatus[4];
 181     uchar avalue [8 ];
 182 } txstate_t;
 183
 184 xdata txstate_t txstates[8];
 185
 186 -> "output l\n"
 187 <- "5(sdcdb) "
 188 -> "display l\n"
 189 <- "(sdcdb) "
 190 -> "display /x l\n"
 191 <- "(sdcdb) "
 192 -> "display\n"
 193 <- "2: /x l = 0x00000005\n"
 194    "1: l = 5\n"
 195    "(sdcdb) "
 196 -> "display /o l\n"
 197 <- "(sdcdb) "
 198 -> "display\n"
 199 <- "3: /o l = 00000000005\n"
 200    "2: /x l = 0x00000005\n"
 201    "1: l = 5\n"
 202    "(sdcdb) "
 203 -> "display /d l\n"
 204 <- "(sdcdb) "
 205 -> "display\n"
 206 <- "4: /d l = 5\n"
 207    "3: /o l = 00000000005\n"
 208    "2: /x l = 0x00000005\n"
 209    "1: l = 5\n"
 210    "(sdcdb) "
 211 -> "display /t l\n"
 212 <- "(sdcdb) "
 213 -> "display\n"
 214 <- "5: /t l = 00000000000000000000000000000101\n"
 215    "4: /d l = 5\n"
 216    "3: /o l = 00000000005\n"
 217    "2: /x l = 0x00000005\n"
 218    "1: l = 5\n"
 219    "(sdcdb) "
 220 -> "output l\n"
 221 <- "5(sdcdb) "
 222 -> "print txstates\n"
 223 <- "$2 = { { dstatus = {\'\\1\',\'\\0\',\'\\0\',\'\\0\'},
 224  avalue = {\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\'}},
 225  { dstatus = {\'\\0\',\'\\2\',\'\\0\',\'\\0\'},
 226  avalue = {\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\'}},
 227  { dstatus = {\'\\0\',\'\\0\',\'\\375\',\'\\0\'},
 228  avalue = {\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\'}},
 229  { dstatus = {\'\\0\',\'\\0\',\'\\0\',\'\\0\'},
 230  avalue = {\'\\0\',\'\\0\',\'\\0\',\'\\4\',\'\\0\',\'\\0\',\'\\0\',\
 231 '\\0\'}}, { dstatus = {\'\\0\',\'\\0\',\'\\0\',\'\\0\'},
 232  avalue = {\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\'}},
 233  { dstatus = {\'\\0\',\'\\0\',\'\\0\',\'\\0\'},
 234  avalue = {\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\'}},
 235  { dstatus = {\'\\0\',\'\\0\',\'\\0\',\'\\0\'},
 236  avalue = {\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\'}},
 237  { dstatus = {\'\\0\',\'\\0\',\'\\0\',\'\\0\'},
 238  avalue = {\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\0\',\'\\
 239 0\'}}}\n"
 240    "(sdcdb) "
 241 -> "print txstates[1].dstatus[1]\n"
 242 <- "$5 = \'\\2\'\n"
 243    "(sdcdb) "
 244 -> "print /x txstates[1].dstatus[1]\n"
 245 <- "$7 = 0x02\n"
 246 -> "output txstates[1].dstatus[1]\n"
 247 <- "\'\\2\'(sdcdb) "
 248 -> "set variable txstates[1].dstatus[1] = 0x10\n"
 249 <- "(sdcdb) "
 250 -> "print /t txstates[1].dstatus[1]\n"
 251 <- "$9 = 00010000\n"
 252 -> "print /x txstates[1].dstatus[1]\n"
 253 <- "$10 = 0x10\n"
 254
 255 -> "output l\n"
 256 <- "5(sdcdb) "
 257 -> "set variable l = 2\n"
 258 <- "(sdcdb) "
 259 -> "print l\n"
 260 <- "$15 = 2\n"
 261 -> "print /x txstates[l].dstatus[2]\n"
 262 <- "$16 = 0xfd\n"
 263
 264
 265 ---------------------------------------------------
 266
 267 Implementation Notes:
 268
 269 IMEM and XMEM are cached to optimize the printaut of structures and arrays
 270
 271
 272
 273 Notes April 23, 2003
 274 ========================
 275 Martin Helmling added support for ddd GUI debugger.
 276 Code added to display assembly, set variables, and other commands
 277 to interface to ddd.
 278
 279 From Martins email:
 280
 281 in the attachment is my actual patch.
 282
 283 The 'up' and 'down' stack commands are not implemented.
 284 But the features for 'ddd' to see bopth the c source and the assembler
 285 works,
 286 also the display of variables.
 287 Set variables are only implemented for basic types.
 288 Register variables can also displayed, but here I think a problem in the
 289 *.cdb file exists.
 290 Sometimes the register name not exists:
 291
 292 S:LcacheTxAnalogValue$offset$1$1({1}SC:U),E,0,0
 293 S:LcacheTxAnalogValue$i$1$1({1}SC:S),R,0,0,[]
 294 S:LcacheTxAnalogValue$val$1$1({4}ST__00020000:S),E,0,0
 295 S:LcacheTxAnalogValue$value$1$1({1}SC:U),R,0,0,[]
 296 S:LcacheTxAnalogValue$sloc0$1$0({4}SL:U),E,0,0
 297 S:LsetRelays$addr$1$1({1}SC:U),R,0,0,[r2]
 298 S:LsetRelays$state$1$1({1}SC:U),R,0,0,[r3]
 299 S:LsetRelays$value$1$1({1}SC:U),R,0,0,[r5]
 300 S:L_main$i$1$1({1}SC:U),R,0,0,[]
 301 S:L_main$j$1$1({1}SC:U),R,0,0,[r3]
 302 S:L_main$ok$1$1({1}SC:U),R,0,0,[r3]
 303
 304 the empty [] I mean !!
 305
 306 Is this a known bug  in sdcc ?
 307
 308 Also sometimes not the correct breakpoints for stepping found  in sdcdb.
 309 I try to fix this tomorrow.
 310
 311 Additional patches and notes from Martin(4-24-03):
 312 in the attachment you found three patches:
 313 debugpatch: Only for debugging, you can switch on and off the 4 different
 314              debug and you can grep the debug by the prefix.
 315 signalpatch:Now the simulator stops if the user sends an interrupt
 316              ( or 'ddd' ) and also the simulator does not die by another
 317              user signal.
 318
 319 sympatch:   This is not a feature, THIS is the fix of a BUG !!!
 320              In some circumstances in the *.cdb file the Symbol record
 321              comes before the function record. So the symbol was
 322              generated TWO TIMES in the symbol list. The L:G and L:XG
 323
 324              records then insert entry and exit address to the wrong
 325              symbol. So before a new symbol is generated for the
 326              function, a lookup in the symboltable is done.
 327
 328 Example of a *.cdb:
 329
 330 S:G$ZpuInitialize$0$0({2}DF,SV:S),C,0,0
 331 S:G$ZpuInitialize$0$0({2}DF,SV:S),C,0,0
 332 F:G$ZpuInitialize$0$0({2}DF,SV:S),Z,0,0,0,0,0
 333 S:LZpuInitialize$i$1$1({2}SI:S),R,0,0,[]
 334 L:G$ZpuInitialize$0$0:ADF
 335 L:XG$ZpuInitialize$0$0:BBB
 336
 337
 338 Notes Feb 10, 2002 - Karl Bongers
 339 ========================
 340
 341 SDCDB is a debugger for SDCC compiler.  It works as a front
 342 end to the ucSim simulator/disassembler program.
 343
 344 WARNING: SDCDB is EXPERIMENTAL and NOT A FULLY FUNCTIONING TOOL.
 345
 346 SDCDB does hold out promise for a nice debugger tool that
 347 could integrate well with ucSim and other SDCC tools.  It has
 348 some nice functionality that could augment ucSim nicely.
 349 It reads in a lot of symbolic information from the .CDB
 350 debug files as well as the source code and assembly
 351 listings referred to in these CDB files.
 352 This can be used to display your program data, list
 353 c or asm source code and set breakpoints.
 354
 355 Unfortunately, SDCDB is not quite finished and does not
 356 function well enough yet to recommend for general use.
 357
 358
 359 Usage Notes
 360 ======================
 361 Compile with --debug option:
 362 sdcc --debug hi.c
 363 This should generate .cdb symbolic debug files.
 364
 365 Load sdcdb, like this:
 366 sdcdb hi.ihx
 367
 368 Then you need to do an initial "run" command.  It should hopefully
 369 stop somewhere at the main() entrypoint.
 370
 371 Now you should be able to list code, and set breakpoints.  Type
 372 "c" to continue running to a breakpoint, or type "s" to single
 373 step or "n" to skip function calls.  Tpye "help" for a summary
 374 of commands.
 375
 376 Use a preceeding bang("!") to do s51 simulator commands.  So for
 377 example:
 378 !pc
 379 will send the "pc" command to ucSim and
 380 give you the program counter and list the current line of assembly.
 381 !help
 382 will give you the brief command line help listing of ucSim.  But
 383 this help will scroll of the screen.  So to get a list, I redirect
 384 stdout to a text file to examine like this:
 385 sdcdb hi.ihx 2>&1 | tee sdcdb.log
 386
 387 Type '.' to toggle to a full time ucSim prompt.
 388
 389
 390 SDCDB problem areas.
 391 ======================
 392
 393 Ok, so what are some of its problems?  Lets try to itemize
 394 them so we can fix them:
 395
 396 * It hangs sometimes when trying to do step or next.
 397
 398    This probably has something to do with the context
 399    sdcdb tries to build dynamically.  Sdcdb tries to
 400    trace program operation by placing hidden breakpoints
 401    and stepping threw the simulation between these.
 402
 403 * Does not print variables properly.  Seems to use the
 404   wrong address for the variable. (fixed)
 405
 406 * ASM listing not implemented.
 407   This should be easy enough to add.  This feature
 408   really needs to be implemented before this is a useful
 409   tool.  That or addresses of code functions need to be
 410   readily available for raw ucSim commands.
 411
 412 * No way to browse symbols, files names.
 413   Preferably, it is easy to learn the addresses of variables
 414   and functions too.
 415   (working on this... see new ls,lm,lf commands)
 416
 417 * Does not allow listing, setting breakpoints or viewing variables
 418   before starting the simulation.
 419   (I am fixing now, partly fixed)
 420
 421 * p codestr - print on code char * broken, could be CDB info invalid.
 422
 423
 424 Changes Made
 425 ======================
 426
 427 Added a -z option.  Any options after -z on sdcdb invocation line
 428  are passed directly to ucSim.
 429
 430 Fixed print basic variable command(was not parsing or expecting
 431   "0x" in data coming from ucSim).  Dump bit command changed from
 432   "db" to "dump".
 433
 434 Add support for the following alternative ucSim binaries:
 435  -mz80 - use "uz80" simulator.
 436  -mavr - use "uavr" simulator.
 437  -mxa - use "uxa" simulator.
 438
 439   Note that Z80(and probably avr/xa) does not produce enough
 440   CDB debugging information to
 441   make SDCDB useful.  Hopefully CDB support will be
 442   added to these other linkers and code generators.
 443
 444 Added lf,lm,ls commands(list functions, list modules, list symbols).
 445  This allows browsing some the CDB information SDCDB pulls in
 446  to do the wonderful things it does.
 447
 448 Added '.' prefix/command, used alone switches back and forth
 449  from ucSim/SDCDB command mode).  Also when at the (ucsim) prompt,
 450  if a command is prefixed with '.' it will route the command to
 451  the SDCDB command processor.  (This could obsolete the '!' prefix).
 452
 453
 454 ======================
 455
 456 Fix any remaining shortcomings above and make sdcdb integrate better with
 457 ucSim.
 458
 459 Concerning the hanging on next/step instructions:  This is critical
 460 to fix.  I beleive the problem is related to SDCDB's attempt to
 461 dynamically track context.  To do this, it sets many temporary break
 462 points and uses these to progress step by step through the source code.
 463 It does not seem reliable.  It might be an idea to offer a simplified
 464 mode of stepping and breakpoints.  Need to study this more.
 465
 466 Make SDCDB integrate better with ucSim.
 467 I think if sdcdb can act more transparently in regard to ucSim
 468 it would be used more.  So stress adding value and enhancing
 469 ucSim operation, and not block or hide the functionality of ucSim.
 470
 471 * combine print "p" & "pt" together.  We have room on the screen,
 472 might as well print its type, address and value in one command.
 473
 474 * "fr" command prints the current position in the C code.
 475 Should also print the raw code address for dumping ucSim code.
 476
 477
 478
 479 Developer Notes:
 480 ======================
 481 To debug, it might be helpful to turn on verbose debug dumps
 482 by uncommenting #define SDCDB_DEBUG in sdcdb.h.
 483
 484 Some basic layout:
 485 sdcdb.c - main shell of the program.
 486 cmd.c - process user commands typed in.
 487 simi.c - handle talking to the simulator via a socket connection.
 488 symtab.c - Misc. functions to translate and process linked list
 489   structures(modules, functions, symbols, etc) and CDB file
 490   parsing.
 491 break.c - track and implement break points.
 492
 493 Understanding the structures and access mechanisms of SDCDB
 494 is a bit of work.  The structures include generic linked list
 495 and function access.  These lists are accessed in part by the
 496 functions from ../../src/SDCCset.c and SDCChash.c.  See the
 497 cmd.c:infoSymbols() routine to gain some insight into these
 498 main program structures.  Or type "info symbols" to dump
 499 out some of these.  The new ls,lm,lf commands are also based
 500 on showing information about these lists of structures.
 501
 502 Generic functions are used to act on these linked lists of
 503 structures.  For example, in cmd.c, DEFSETFUNC(funcWithName)
 504 function will find a function structure with a given name.
 505 So the linked list of function structures(with the head
 506 "functions") is traversed and when one is found with a matching
 507 name, a pointer to the function structure is returned.
 508
 509 The src/SDCCset.c,SDCCset.h contain much of the core helper
 510 routines to allowed to implement these linked list access
 511 functions.
 512
 513 The dynamic context tracking is difficult to understand.
 514 It has some concept of stack use, as in
 515 cmd.c:printSymValue(), where it can print variables relative
 516 to the stack pointer.
 517
 518