home *** CD-ROM | disk | FTP | other *** search
/ EDUCORP 8 / Educorp2Compilation.sit / educorp2 / Demos / Aztec Source Level Debugger / demo / bc.r < prev    next >
Encoding:
Text File  |  1988-06-22  |  15.2 KB  |  563 lines
  1. p @"This session is under the control of a command file"
  2. p @"that is being read in.  At the appropriate time, you will"
  3. p @"be prompted to <Hit Any Key to Continue>."
  4. p @"The command file may be aborted by entering a Ctrl-C or Cmd-C"
  5. p @"at the prompt."
  6. &
  7. p @n
  8. p @"Welcome to a demonstration walk-through of the Aztec C Source"
  9. p @"Level Debugger. We will take a look at some of the functions"
  10. p @"and features by debugging a sample program."
  11. &
  12. p @n
  13. p @"At this point, the debugger has been started by double clicking"
  14. p @"on the bc.dbg icon.  If you were running under the Aztec or"
  15. p @"MPW Shell, you would enter the command line:"
  16. p @n
  17. p @"    sdb bc"
  18. p @n
  19. p @"Before getting into the debugging itself, let's look at SDB's"
  20. p @"display and how it can be manipulated. The first thing you notice"
  21. p @"is that the window is split into three sub-windows. The top window"
  22. p @"is the source window which is a scrollable window used to examine"
  23. p @"the source of the program being debugged. Notice that one line in"
  24. p @"the window is highlighted to indicate the current location of the"
  25. p @"program counter. That is, this is the line about to be executed."
  26. p @"The source can be scrolled by using the scroll bar to the right"
  27. p @"of the window or by using the SHIFT UP and SHIFT DOWN arrow keys."
  28. p @"Finally notice that the lines are numbered so that they can be"
  29. p @"referenced by the debugger commands."
  30. &
  31. p @n
  32. p @"The second window is a one line window which is the command window."
  33. p @"This window is used to input commands to the debugger. The command"
  34. p @"window supports the standard types of cursor editing and also"
  35. p @"supports a history mechanism using the up and down arrow keys."
  36. p @"There is also a small gadget at the end of the window which can be"
  37. p @"used to move the command line up or down and thereby increasing or"
  38. p @"decreasing the sizes of the source and data windows. The command"
  39. p @"window may also be moved by using the SHIFT-CMD-UP and"
  40. p @"SHIFT-CMD-DOWN arrow keys."
  41. &
  42. p @n
  43. p @"The third and final window is the data window which displays the"
  44. p @"output of the various commands given to the debugger. This window"
  45. p @"is also a scrollable window with approximately 4000 characters"
  46. p @"saved in a circular buffer making it possible to look back at"
  47. p @"previous output. This window may be scrolled from the keyboard"
  48. p @"by using the CMD-UP and CMD-DOWN arrow keys."
  49. &
  50. p @n
  51. p @"There are just two more notes on the display before we get to the"
  52. p @"program itself. First, note that the window size can be changed"
  53. p @"and the number of lines in the source and data areas will be"
  54. p @"adjusted appropriately. Second, when the debugger is active, the"
  55. p @"debugger window can be toggled between the back of all other"
  56. p @"windows and the front by using the <esc> or ` key. For this demo, we"
  57. p @"will do that for you. For example,"
  58. &
  59. &2
  60. p @n
  61. p @"Well, that's it for the display, let's get to some debugging."
  62. &
  63. p @n
  64. p @"The first thing you notice when SDB is started is that it has"
  65. p @"loaded the program to be debugged into memory, set a breakpoint"
  66. p @"on the 'main()' function, started the program and stopped at the"
  67. p @"beginning of main(). The second thing you notice is that SDB has"
  68. p @"automatically found the correct file and line number"
  69. p @"corresponding to the beginning of main(). This is important"
  70. p @"since this particular program consists of several source files"
  71. p @"all located in a subdirectory."
  72. &
  73. p @n
  74. p @"Let's get started by using the 's' command. This command will"
  75. p @"single step the program source line by source line. Doing it once"
  76. p @n
  77. p @"sdb?s"
  78. p @n
  79. p @"moves us past the function entry code to the first statement"
  80. p @"which calls InitGraf()."
  81. s
  82. &
  83. p @n
  84. p @"A second"
  85. p @n
  86. p @"sdb?s"
  87. p @n
  88. p @"actually executes the statement."
  89. s
  90. &
  91. p @n
  92. p @"Let's do two single steps by giving a count"
  93. p @n
  94. oe
  95. 2s
  96. oe
  97. p @n
  98. p @"which brings us to a function call to setupmenus()."
  99. p @n
  100. p @"Since an s would actually step into the function,"
  101. p @"we'll use a t to treat the function as a single instruction."
  102. p @n
  103. &
  104. p @"sdb?t"
  105. p @n
  106. t
  107. p @"We'll now let the rest of the initialization take place and stop"
  108. p @"at line 24 by using the g command with a temporary breakpoint."
  109. p @n
  110. &
  111. oe
  112. g .24
  113. oe
  114. p @n
  115. p @"At this point we are about to open the window for the program"
  116. p @"output, which is a good time to discuss some commands for"
  117. p @"displaying memory. We knew above that the OpenLibrary() calls"
  118. p @"returned non-zero by watching where control went at the 'if'"
  119. p @"statements. Now we want to see the exact value of the myWindow"
  120. p @"variable before assigning a new value to it. One way is to use the"
  121. p @"'dw' command to display words of memory as in:"
  122. p @n
  123. oe
  124. dw myWindow 
  125. oe
  126. &
  127. p @n
  128. p @"Since myWindow is a pointer, it consists of the first two words"
  129. p @"displayed which are zero. We could also have displayed it as bytes"
  130. p @"or long words by using the 'db' or 'dl' commands respectively."
  131. &
  132. p @n
  133. p @"While the 'd' commands are useful for looking at raw memory, there"
  134. p @"is a much more elegant command which can be used to look at"
  135. p @"program variables and data. This is the 'p' command which is"
  136. p @"extremely flexible and powerful, but in its simplest form can be"
  137. p @"used as:"
  138. p @n
  139. oe
  140. p myWindow
  141. oe
  142. &
  143. p @n
  144. p @"Note that the 'p' command not only knows where the myWindow variable"
  145. p @"is in memory, but also knows the type of the variable and displays"
  146. p @"the type as part of it's output. Since it knows the type, it also"
  147. p @"knows exactly how many bytes to use when getting the value of the"
  148. p @"variable."
  149. &
  150. p @n
  151. p @"Now let's open the window by using"
  152. p @n
  153. p @"sdb?s"
  154. p @n
  155. p @"again."
  156. s
  157. &
  158. p @n
  159. p @"When the line was executed, the window was opened and appeared"
  160. p @"momentarily before disappearing. This is because when the"
  161. p @"debugger gets control because of a breakpoint or the end of a"
  162. p @"single step it automatically makes its window the front window"
  163. p @"and activates it."
  164. &
  165. p @n
  166. p @"Let's look again at the value of myWindow."
  167. p @n
  168. oe
  169. p myWindow
  170. oe
  171. &
  172. p @n
  173. p @"We know the NewWindow() succeeded because we saw the window"
  174. p @"appear, and now we have the address of the GrafPort structure"
  175. p @"pointed to by the myWindow variable. Now, when we said 'p myWindow' we"
  176. p @"were printing a pointer to a  GrafPort structure and got a hex value"
  177. p @"for the address. If we want to look at the contents of the"
  178. p @"structure we could try several things."
  179. &
  180. p @n
  181. p @"First, we could use the 'dw' command with the hex value displayed"
  182. p @"above to look at the structure contents. Or more simply, we could"
  183. p @"look at what myWindow points at by using:"
  184. p @n
  185. oe
  186. dw *myWindow
  187. oe
  188. &
  189. p @n
  190. p @"This saves us from having to deal with hex numbers, but is still"
  191. p @"going to be a lot of work to get any useful information. So, as a"
  192. p @"last resort, why not try the 'p' command again, but this time on"
  193. p @"*myWindow instead of just Window."
  194. &
  195. p @n
  196. oe
  197. p *myWindow
  198. oe
  199. p @n
  200. p @"Voila! Since myWindow was a pointer to a structure, *myWindow is an"
  201. p @"instance of a structure and the 'p' command proceeded to dump the"
  202. p @"entire contents of the structure. There are two important things"
  203. p @"to notice here. First, SDB was able to display the type and name"
  204. p @"of each structure element. Second, with both the 'dw' and the 'p'"
  205. p @"command we were able to use a C expression as a parameter of the"
  206. p @"command. In fact, we can use any arbitrary C expression as a"
  207. p @"parameter."
  208. &
  209. p @n
  210. p @"For example, to see just the value of the portRect, we could say:"
  211. p @n
  212. oe
  213. p myWindow->portRect
  214. oe
  215. &
  216. p @n
  217. p @"or to see the visible region:"
  218. p @n
  219. oe
  220. p **myWindow->visRgn
  221. oe
  222. &
  223. p @n
  224. p @"This is extremely powerful and can be summarized by saying that"
  225. p @"you can debug most programs without actually knowing the physical"
  226. p @"hex address of any variable. We'll expand on this a little later."
  227. &
  228. p @n
  229. p @"Let's move on now by looking at the next few lines of source,"
  230. p @"which aren't too threatening looking, and skipping over them by"
  231. p @"going to line 29 using the 'g' command."
  232. &
  233. p @n
  234. oe
  235. g .29
  236. oe
  237. p @n
  238. p @"Unlike the 's' command, the 'g' command let's the processor run"
  239. p @"the program at full speed until a breakpoint is reached. If no"
  240. p @"breakpoints have been set, the program will run until it exits."
  241. p @"In this case, we have set a temporary breakpoint at line 29 by"
  242. p @"following the 'g' command with the '.29'."
  243. &
  244. p @n
  245. p @"In general, source lines are specified by an optional file name"
  246. p @"followed by a '.' and the line number. Thus we could also have said:"
  247. p @n
  248. p @"   g main.c.29"
  249. p @n
  250. p @"to achieve the same effect. If no file name is present, the file"
  251. p @"currently displayed in the source window is assumed."
  252. &
  253. p @n
  254. p @"Let's continue by single stepping the call to the redraw() function."
  255. &
  256. p @n
  257. p @"sdb?s"
  258. s
  259. p @n
  260. p @"Unlike previous function calls, this time single stepping has"
  261. p @"brought us to the beginning of the function being called. This is"
  262. p @"because the previous calls were to functions for which there was"
  263. p @"no source available. In this event, the function is called"
  264. p @"directly without 'stepping into' the function itself. However, if"
  265. p @"the source is present, the function is 'stepped into' at the"
  266. p @"beginning of the function. As we did with setupmenus(), it would"
  267. p @"have been possible to treat the redraw() function as though there"
  268. p @"were no source by using the 't' command which single steps without"
  269. p @"ever 'stepping into' functions."
  270. &
  271. p @n
  272. p @"It is possible to see how we got here by looking at a stack"
  273. p @"backtrace."
  274. p @n
  275. oe
  276. ds
  277. oe
  278. &
  279. p @n
  280. p @"This shows the redraw() function was called from main() which was"
  281. p @"called from _main() with two arguments which was called from ...."
  282. &
  283. p @n
  284. p @"The same backtrace can be shown with local variable values by"
  285. p @"using 'dS' instead of 'ds'."
  286. p @n
  287. p @"Now that we're here, let's look at what redraw() is going to do."
  288. p @"First it draws the axes and then labels them and then draws the"
  289. p @"bars for the chart. Another feature of SDB is that it knows the"
  290. p @"location of the source to every function. Let's use that to look"
  291. p @"at the drawaxes() function."
  292. &
  293. p @n
  294. oe
  295. df drawaxes
  296. oe
  297. p @n
  298. p @"SDB has automatically changed source files and moved to the"
  299. p @"beginning of the drawaxes() function. This function resets the Pen"
  300. p @"values and then draws the axes based on the variables passed into"
  301. p @"the function. Then starting at line 12, it saves the values for"
  302. p @"the axes in the 'xyb' structure. So, lets set a permanent"
  303. p @"breakpoint at line 12."
  304. p @n
  305. oe
  306. bs .12
  307. oe
  308. &
  309. p @n
  310. p @"Lets just check it to make sure it got the right file."
  311. p @n
  312. oe
  313. bd
  314. oe
  315. &
  316. p @n
  317. p @"Okay, now let's just recheck where the program counter is by using"
  318. p @"the context command."
  319. &
  320. p @n
  321. oe
  322. c
  323. oe
  324. p @n
  325. p @"Good enough, now we want to run till we hit that breakpoint."
  326. &
  327. p @n
  328. oe
  329. g
  330. oe
  331. p @n
  332. p @"Let's flip the window to the back for a couple of seconds to"
  333. p @"examine the axes we've drawn."
  334. &
  335. &2
  336. p @n
  337. p @"Now we can examine some more of SDB's commands. First, although"
  338. p @"SDB is a source level debugger, it still retains many assembly"
  339. p @"level abilities. For example, to look at the assembly language"
  340. p @"that corresponds to the next few statements, we use the unassemble"
  341. p @"command."
  342. &
  343. p @n
  344. oe
  345. u pc,2
  346. oe
  347. &
  348. p @n
  349. p @"Note that the source and assembly language are intermixed. Using"
  350. p @"the 'z' command we can switch from source to assembly mode and"
  351. p @"back. When in assembly mode, single stepping is done by assembly"
  352. p @"language statement."
  353. &
  354. p @n
  355. p @"The values of the local variables in a function can be displayed:"
  356. p @n
  357. oe
  358. da
  359. oe
  360. &
  361. p @n
  362. p @"The complement to the 'da' command is the 'dg' command which"
  363. p @"displays the values of all global variables."
  364. p @n
  365. p @"Note that the structure Myxyb is pointed to by the pointer xyb as"
  366. p @"passed in to the current function. Let's look at the contents."
  367. p @n
  368. oe
  369. p *xyb
  370. oe
  371. &
  372. p @n
  373. p @"All zero to start. Let's execute a line."
  374. &
  375. p @n
  376. p @"sdb?s"
  377. s
  378. p @n
  379. p @"And check the contents now."
  380. p @n
  381. oe
  382. p *xyb
  383. oe
  384. &
  385. p @n
  386. p @"This brings us to another VERY powerful feature of SDB. Suppose"
  387. p @"that at this point we realize that we really meant to place the"
  388. p @"value of 'xaxis+1' into the xyb structure. Again we have several"
  389. p @"ways to do this. The assembly language debugger approach is to"
  390. p @"find the address of the structure."
  391. p @n
  392. oe
  393. p xyb
  394. oe
  395. &
  396. p @n
  397. p @"Then we could look at the value stored there."
  398. p @n
  399. oe
  400. dw *xyb
  401. oe
  402. &
  403. p @n
  404. p @"Finally we could modify it using an instruction like"
  405. p @n
  406. p @"   mw *xyb = 36"
  407. &
  408. p @n
  409. p @"On the other hand, the SDB approach is to use the evaluate"
  410. p @"command. This command evaluates an arbitrary C expression. For"
  411. p @"this case we could use:"
  412. p @n
  413. oe
  414. e ++xyb->xaxis
  415. oe
  416. &
  417. p @n
  418. p @"which would increment the value. We could also say"
  419. p @n
  420. oe
  421. e xyb->xaxis = xaxis + 1
  422. oe
  423. &
  424. p @n
  425. p @"With this capability, it is also possible to modify local"
  426. p @"variables on the stack without knowing their exact address."
  427. &
  428. p @n
  429. p @"The 'e' command is even more powerful since when we say an"
  430. p @"arbitrary C expression we pretty much mean it. For example, let's"
  431. p @"try:"
  432. p @n
  433. oe
  434. e DrawString("hello world!")
  435. oe
  436. p @n
  437. p @"Now we'll flip the windows to look at the output."
  438. &
  439. &2
  440. p @n
  441. p @"Since DrawString() was linked with the program it can be called as"
  442. p @"part of the expression evaluation."
  443. &
  444. p @n
  445. p @"Okay, let's show one more feature and then we'll give you a chance"
  446. p @"to play. First, let's go back to the function that called this one"
  447. p @"by using the convenient shorthand symbol '@'."
  448. &
  449. p @n
  450. oe
  451. g @
  452. oe
  453. p @n
  454. p @"Now, lets label the axes by calling single stepping the next two"
  455. p @"lines using the 't' command."
  456. &
  457. p @n
  458. p @"sdb?t"
  459. t
  460. &
  461. p @n
  462. p @"sdb?t"
  463. t
  464. p @n
  465. p @"Let's flip the window to the back for a couple of seconds to"
  466. p @"look at the result."
  467. &
  468. &2
  469. p @n
  470. p @"Next, the program will draw the actual bars for the chart and then"
  471. p @"will return. So let's set a breakpoint at the return of the"
  472. p @"current function."
  473. p @n
  474. oe
  475. bs @
  476. oe
  477. &
  478. p @n
  479. p @"Let's check the breakpoint table."
  480. p @n
  481. oe
  482. bd
  483. oe
  484. &
  485. p @n
  486. p @"Hmmm, we might as well get rid of the old one."
  487. p @n
  488. oe
  489. bc drawaxes.c.12
  490. oe
  491. &
  492. p @n
  493. p @"And now we turn on single step trace mode."
  494. p @n
  495. oe
  496. bT
  497. oe
  498. &
  499. p @n
  500. p @"This will force single stepping until a breakpoint is reached. Now"
  501. p @"we type 'g' and watch the program run."
  502. &
  503. p @n
  504. oe
  505. g
  506. oe
  507. p @n
  508. p @"Back at the main() function, we disable line tracing."
  509. p @n
  510. oe
  511. bT
  512. oe
  513. &
  514. p @n
  515. p @"And now we let the program run to completion. You will have to"
  516. p @"click in the close box to get the program to quit."
  517. &
  518. p @n
  519. oe
  520. g
  521. oe
  522. p @n
  523. p @"At this point, the program has exited and is gone so most commands"
  524. p @"won't work anymore. For example:"
  525. &
  526. p @n
  527. oe
  528. 2s
  529. oe
  530. p @n
  531. p @"To reload the program, the 'lp' command is used."
  532. &
  533. p @n
  534. oe
  535. lp
  536. oe
  537. p @n
  538. p @"And we're ready to go again."
  539. &
  540. p @n
  541. p @"In summary, SDB through its support of arbitrary C expressions and"
  542. p @"in particular the 'e' and 'p' commands allows the programmer to"
  543. p @"debug his program without ever having to:"
  544. p @n
  545. p @"    LOOK AT ANY ASSEMBLY LANGUAGE!"
  546. p @n
  547. p @"    LOOK AT ANY HEX ADDRESSES!"
  548. p @n
  549. p @"    CALCUALATE THE OFFSET OF A STRUCTURE ELEMENT!"
  550. &
  551. p @n
  552. p @"Instead, the programmer tests and debugs with the same syntax used"
  553. p @"to write the program in the first place."
  554. &
  555. p @n
  556. p @"When you've finished working with the program, you can exit sdb by"
  557. p @"using the q for quit command.  The only other command that you'll need"
  558. p @"to remember is the ? for help.  With that you should be able to figure"
  559. p @"the rest out by yourself."
  560. &
  561. p @n
  562. p @n"The command file has now terminated, and you're in control."
  563.