Path: ns-mx!uunet!zaphod.mps.ohio-state.edu!usc!apple!dlyons From: dlyons@Apple.COM (David A Lyons) Newsgroups: comp.sys.apple2 Subject: Re: Nifty List and GSBug Message-ID: <55856@apple.Apple.COM> Date: 6 Aug 91 15:46:59 GMT References: Organization: Apple Computer Inc., Cupertino, CA Lines: 194 In article zane@infopls.chi.il.us (Sameer Parekh) writes: >After seeing Dave Lyons talk about Nifty List ans GSBug, he has >me wondering: What Are They? GSBug is a machine-level debugging utility from Apple, which mainly lets you step through code one instruction at a time. (I'm currently maintaining GSBug.) Nifty List is a Shareware CDA I distribute myself; started in 1987 way before I worked for Apple, and it keeps growing and growing.... It's multipurpose. Quick Reference for the toolbox, browse through lots of system data structures, show toolbox parameters in disassembly listings, make toolbox calls interactively fromm the command line, write your own commands. Here's a handout I used at GS College in Kansas: Exploring the Toolbox Interactively with GSBug and Nifty List by Dave Lyons, 15-Jul-91 An excellent way to get comfortable with the GS Toolbox is exploring it interactively. For example, when you have a question about how a particular toolbox call behaves or when it is getting called, you can usually do a quick experiment to find out. Techniques * Use GSBug and Nifty List together. GSBug is great for taking control of the system when it executes particular toolbox calls or GS/OS calls, and Nifty List is great for examining the state of the system and making any toolbox calls you want "on the fly". * Explore the online help: type "?" at the GSBug command line and at all the sub-screens. Type "?" in Nifty List, and get help for individual commands ("?_" for making toolbox calls, "?\" for a list of all the "backslash" commands, "?\files", etc) * Use Nifty List as a toolbox quick-reference for tool sets, functions within tool sets, and the parameters needed for each function. * Experiment with making toolbox calls from the Nifty List command line; watch the results on the Super Hires screen. * Intercept tool calls being made by applications or other parts of the system. Examine their results. Modify the parameters before making the call, or create an "error" condition after the call. Exercises These exercises demonstrate a moderate variety of GSBug and Nifty List features. Feel free to experiment...these are just ideas to get you started. (Some of the exercisers assume your GS is running the Finder.) Entering and exiting Nifty List Apple-Ctrl-Esc gets you to the CDA menu; move to Nifty List and hit Return. When you want to leave Nifty List, Esc takes you back to the CDA menu. Entering and exiting GSBug Apple-Option-Ctrl-Esc gets you to GSBug. "r Return" (for Resume) puts you back where you were. While in GSBug, you can usually use Apple-Ctrl-Esc to get to CDAs, including Nifty List. (In up-to-date GSBugs, the shortcut "n Return" also takes you to Nifty List.) Step through code From GSBug, type "s Return" and hit Space a few times. Each time you hit Space, GSBug executes a single instruction, or a single toolbox call or GS/OS call. You can watch the register contents change at the top of the screen. -- Hit Esc to return to the command line, then "r Return" to leave GSBug. Set a "Tool Break" or "OS Break" From GSBug, type "SetTBrk _NewWindow" and "TBRkIn" (to enable your toolbreak). Resume and open a new window from the Finder. You'll drop into GSBug when the Finder calls NewWindow (it hasn't executed yet). Type "s Return". Type "s" to see the SuperHires screen. Hit Space to execute the NewWindow (the empty window appears). Type "t" to return to the Text screen. "Esc r Return" will let the Finder continue full-speed. OSBreaks work similarly. Try "SetOSBrk _OpenGS" and "OSBrkIn", for example. (When you don't want your breaks any more, you'll want TBrkOut and OSBrkOut.) You may want to try tool-breaking on TaskMaster. The Finder calls TaskMaster in its main loop. Lots of stuff can happen inside a TaskMaster call (windows are drawn, moved, resized; menus are tracked). -- You may find it helpful after breaking on TaskMaster to press and hold the mouse somewhere (like on the menu bar), hit Space to execute TaskMaster, and do something with the mouse. TaskMaster returns control to GSBug only when, say, you finally choose a menu item (or release the button without choosing one). (After you're done, hit T to see the text screen.) What Tool Sets are being used? What functions do they contain? Enter Nifty List and type "v Return". All loaded tool sets are listed (tool number, version, name, and other information). To see all the functions in a particular tool set, type the tool set number followed by "T". For example, "2t" for all the Memory Manager functions. -- Most tool sets have more functions than fit on one screen, so use Space to freeze the screen and to advance by one line. Use Return to resume scrolling, and Esc or Apple-period to return to the command line. You can also get information on a single tool call, if you know its function number or part of its name. For example, "902t" shows just information on NewHandle. So does "NewH (type the quote this time!). Try "Paint to see all the toolbox functions containing "Paint" (most are in QuickDraw, but one is in Text Edit). -- What is the difference between the "Paint" calls and the similar "Fill" calls? (You may need to refer to Toolbox Reference, Volume 2; but with Nifty List you can quickly confirm the apparent pattern.) Make Some Toolbox Calls Still in Nifty List, type _TotalMem. Nifty List makes the the call for you and displays the result. (For a more verbose display of the result, put a ` in front of it: `_TotalMem.) More easy ones: _SysBeep _GrafOn, _GrafOff, _QDStatus, _QDVersion, _Random. How about a call that needs some input parameter? Integer Math? Type "integer to find that it's tool set number B. Type "bt" to see what calls are there. -- Multiply probably scrolled off...type "90bt" to see its parameters. It needs two inputs, so type _multiply(3,3) to get 9. Int2Dec converts an integer into a decimal string. It needs a place to put the result, and the memory from $00/0300 to $00/03BF is a good place to play with (good for people, not for programs). -- Try "int2dec to see the parameters, then (say) _Int2Dec(100,300,10,0). Then type 300.30f;h to see what it put in memory at location 300. (If you want other scratch space, you can always call NewHandle manually, or you can use the \getdp or \getmem commands.) _GetNewID(1000) allocates a new memory ID in the $10xx range and gives you the result. What if you try something the toolbox considers "illegal", like asking for a memory ID in the "toolbox" range? Try it: _GetNewID(4000) Sometimes it's handy to use the result of one toolbox call as a parameter to another one. No problem! What handles are allocated in memory, and who owns them? Type 0i to get a long(!) list of handles, addresses, sizes, owners, and owner names. The zero means "everybody"--you can cut down the list by typing a more limiting "user ID". Try ?i for help with the i command. If you just want to see what memory IDs are who, try \ids. Try a000i to see all handles owned by "init" files in your system; 5000i to see Desk Accessory handles ("?i" for a list of the memory ID ranges). Disassemble some assembly code Try FF1800L to see a disassembly with a few toolbox calls in it. How about E1/0L to see a lot of system Jump vectors and where they jump to? Follow one and see what it does, or who it's jumping into (the "w" command is helpful). There's more than just one screenful of these vectors (type L again). Who is using the Resource Manager? Type \res to find out the IDs of all the things that have started the Resource Manager (and the addresses of their Resource Converters, if any). You'll probably find 401E (the Resource Manager itself), 1001 or 1002 (the Finder), and possibly more, especially if you have an NDA like the Control Panel open. Keep exploring.... See if you know how to use all the features listed on the Quick Reference pages. See if you can use all the "backslash" commands listed by ?\ See if you can use all the toolbox calls! -- David A. Lyons, Apple Computer, Inc. | DAL Systems Apple II System Software Engineer | P.O. Box 875 America Online: Dave Lyons | Cupertino, CA 95015-0875 GEnie:DAVE.LYONS CompuServe:72177,3233 Internet:dlyons@apple.com My opinions are my own, not Apple's.