Subject: Re: Nifty List and GSBug
From: [email-masked] (David A Lyons)
Date: 6 Aug 91 15:46:59 GMT
Newsgroups: comp.sys.apple2

In article <[email-masked]> [email-masked] (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:[email-masked]

My opinions are my own, not Apple's.