You are on page 1of 50

Newton Driver
Development Kits

Hammer User’s Guide


Preliminary Draft 0.8
March 14, 1995 Jonathan Simonoff
© Apple Computer, Inc. 1995
 Apple Computer, Inc. Apple Computer, Inc. ALL IMPLIED WARRANTIES ON
© 1994, 1995 Apple Computer, Inc. 20525 Mariani Avenue THIS MANUAL, INCLUDING
All rights reserved. Cupertino, CA 95014 IMPLIED WARRANTIES OF
408-996-1010 MERCHANTABILITY AND FITNESS
No part of this publication or the
FOR A PARTICULAR PURPOSE, ARE
software described in it may be Apple, the Apple logo, APDA,
LIMITED IN DURATION TO NINETY
reproduced, stored in a retrieval AppleLink, LaserWriter,
(90) DAYS FROM THE DATE OF THE
system, or transmitted, in any form Macintosh, MPW, and Newton are
ORIGINAL RETAIL PURCHASE OF
or by any means, mechanical, trademarks of Apple Computer,
THIS PRODUCT.
electronic, photocopying, Inc., registered in the United States
recording, or otherwise, without and other countries. Even though Apple has reviewed this
prior written permission of Apple The light bulb logo, MessagePad, manual, APPLE MAKES NO
Computer, Inc., except in the normal NewtonScript, and Newton Toolkit WARRANTY OR REPRESENTATION,
use of the software or to make a are trademarks of Apple Computer, EITHER EXPRESS OR IMPLIED,
backup copy of the software. The Inc. WITH RESPECT TO THIS MANUAL,
same proprietary and copyright ITS QUALITY, ACCURACY,
FrameMaker is a registered
notices must be affixed to any MERCHANTABILITY, OR FITNESS
trademark of Frame Technology
permitted copies as were affixed to FOR A PARTICULAR PURPOSE. AS A
Corporation.
the original. This exception does not RESULT, THIS MANUAL IS SOLD
allow copies to be made for others, ARM is a trademark of Advanced “AS IS,” AND YOU, THE
whether or not sold, but all of the RISC Machines Ltd. PURCHASER, ARE ASSUMING THE
material purchased (with all Helvetica and Palatino are ENTIRE RISK AS TO ITS QUALITY
backup copies) may be sold, given, registered trademarks of Linotype AND ACCURACY.
or loaned to another person. Under Company.
IN NO EVENT WILL APPLE BE
the law, copying includes ITC Zapf Dingbats is a registered LIABLE FOR DIRECT, INDIRECT,
translating into another language or trademark of International SPECIAL, INCIDENTAL, OR
format. You may use the software on Typeface Corporation. CONSEQUENTIAL DAMAGES
any computer owned by you, but
Simultaneously published in the RESULTING FROM ANY DEFECT OR
extra copies cannot be made for this
United States and Canada. INACCURACY IN THIS MANUAL,
purpose. even if advised of the possibility of
Printed in the United States of such damages.
America.
THE WARRANTY AND REMEDIES
The Apple logo is a registered SET FORTH ABOVE ARE EXCLUSIVE
trademark of Apple Computer, Inc. AND IN LIEU OF ALL OTHERS,
Use of the “keyboard” Apple logo ORAL OR WRITTEN, EXPRESS OR
(Option-Shift-K) for commercial IMPLIED. No Apple dealer, agent, or
purposes without the prior written LIMITED WARRANTY ON MEDIA employee is authorized to make any
consent of Apple may constitute AND REPLACEMENT modification, extension, or addition to
trademark infringement and unfair this warranty.
competition in violation of federal If you discover physical defects in the
and state laws. manual or in the media on which a Some states do not allow the exclusion
No licenses, express or implied, are software product is distributed, APDA or limitation of implied warranties or
granted with respect to any of the will replace the media or manual at no liability for incidental or consequential
technology described in this book. charge to you provided you return the damages, so the above limitation or
Apple retains all intellectual item to be replaced with proof of exclusion may not apply to you. This
property rights associated with the purchase to APDA. warranty gives you specific legal rights,
technology described in this book. and you may also have other rights
This book is intended to assist which vary from state to state.
application developers to develop
applications only for licensed
Newton platforms.
Contents

Chapter 1 Introduction 1

Chapter 2 Getting Started 3

Chapter 3 Hammer Menus 5

File Menu 5
Open (-O) 6
Close (-W) 6
Save As... 6
Write Memory... 6
Commands Menu 6
Go (-G) 7
Stop (-.) 7
Rerun (-R) 8
Reload & Rerun 8
Clear All Breakpoints 8
Step (Into) (-S), Step (Over) (-T) 8
Start Spying 8
Spy Within Procedure 8
Stop Spying 8
Get Spy Counts 8
Reset Spy Counts 9
OS Object... 9
Convert... 9
Translate... 9
Procedures Menu 10
Procedure... (-P) 10
Define... 11
Code Windows 11
Memory Menu 13
Memory... 14
Frame... 16
Find... 18
Heap 18
MMU 19
Inverse MMU 20

iii
Draft. Preliminary, Confidential. ©1995 Apple Computer, Inc. 3/15/95
Windows Menu 20
Hot Windows 21
Display 21
Status Window 21
The CPU Window 23
The FPE Registers Window 24
Stack Trace Window 24
Stack Trace From... 24
Spy Window 24
Options Menu 24
Stop on Debug traps 25
Beep on Stops 25
Register names... 25
Spy Options... 26
Config Menu 26
Cripple Memory 27
Stop on Aborts 27
Stop on Throws 27
Default Stdio off/on 27
Bunwarmer Diagnostics 27
Don’t Sleep 27
Fake Battery Level 27
Enable Stdout 27
Enable Package Symbols 27
Tests Menu 28

Chapter 4 Hammer Shortcuts 29

Chapter 5 Hammer Debugging Tips 31

iv
Draft. Preliminary, Confidential. ©1995 Apple Computer, Inc. 3/15/95
CHAPTER 1

Introduction

Hammer is the low-level debugger for Newton development that runs on a Macintosh.
You need to use Hammer if you want to debug C, C++, or ARM Assembler code that
runs on a Newton.
Since Hammer is a low-level debugger, it works on compiled code, and does not display
higher-level language symbols. It does, however, display Assembler symbols. Familiarity
with Arm Assembler is very helpful in using Hammer. You may want, at least, to obtain
the Assembler documentation.
You can use Hammer with two kinds of hardware:
n With a ROM emulator such as an Armistice NuBus card. Hammer loads a ROM image
into the Armistice card, and provides a window on the Macintosh that shows what
would appear on a Newton display. This allows you to test different versions of the
Newton ROM.
n With a Newton. This is discussed in Chapter 6, “Debugging Using a Newton.” Some
functions are not available when you do this; they are listed in Chapter 6, and
Hammer indicates to you (by graying menu commands and by beeping) when you
try to use an unavailable function.
This manual is organized around the Hammer menus. For information on Hammer’s
windows, see the section on the Windows menu on page 20.

1
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 1

Introduction

2
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 2

Getting Started

Getting Started

The book “An Introduction to the Newton DDKs” has general instructions for beginning
use of Hammer. You may want to see that section before reading this chapter.
Hammer can debug using a Newton or an Armistice card. The piece of equipment you
debug on is called the debugging target.
Hammer needs an image file to run.
To launch Hammer, you can:
n Drag an image file onto the Hammer6 icon. If you want to choose the debugging
target, hold down the option and command keys while you do this.
n Double-click on an image file. If you want to choose the debugging target, hold down
the option and command keys while you do this.
n Double-click on the Hammer6 icon. In this case, you are prompted to choose an image
file. If you want to choose the debugging target, hold down the option and command
keys while you choose the image file.

Note
You need to have sufficient memory available to Hammer to hold the
image file. If you have trouble launching Hammer, you may need to quit
other applications and try again. If Hammer still has trouble launching,
and you have enough memory, check “Config Menu” on page 3-30 for
information on those settings. u
Hammer remembers the target used the last time it was run, so, unless you change the
target, you only need to use option/command the first time you run Hammer.
If you are using an Armistice card, Hammer loads the image’s code and initialized data
into RAM on the ROM emulator logic board and starts the image executing from address
0. Hammer also opens its Status window when the image is loaded.
If the image has no Debugger traps installed and it does not crash, it just executes as if it
were the application that was launched. If an exception occurs, Hammer displays an
explanation of the reason in its Status window, and then opens its CPU window showing
the register values and a code window showing the offending instruction.

3
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 2

Getting Started

You can change what Hammer does when it launches the image these ways:
n From C, you use the routines Debugger or DebugStr as a debugger trap. From
assembler you use the Debugger or DebugStr macros. Unlike with Macsbug, the
DebugStr parameter is a C string, not a Pascal string.
n If you depress the Caps Lock key while launching Hammer, the image is executed
until the InitFinished routine is completed (the MMU has been enabled) and then
stops.
n If you hold down the Option key while launching an image, Hammer resets and loads
the image but does not run. You must use the Go button in Hammer’s Status window
to cause execution to proceed to the InitFinished routine. (Note that Stepping will
not work until after the InitFinished routine is completed and the MMU has been
enabled.)
Hammer includes a NewtonScript Listener which you can use in the same ways you use
the NTK Inspector. To display the Listener, check the Default Stdio On item in the Config
menu.

Viewing Frames that Refer to Packages


Two of Hammer’s menu commands, the Frame Functions command in the Commands
menu and the Frames command in the Memory menu print information about
NewtonScript frames. Those frames may contain references to packages. If so, you can
make the package information available to Hammer this way:
1. Make aliases for the packages you are interested in and place them in the Hammer
folder.
2. Turn on Enable Package Symbols in the Options menu.
3. If you have trouble, here are two steps you can take:
n When you open your application package, check the Stdio window for information
about what alias name is expected.
n Check if Hammer complains that the file content doesn’t match.

Note
You probably should not run Newton Connection, NTK, or Package
Installer when you have Enable Package Symbols set, because it can lead
to timeouts. u

4 Viewing Frames that Refer to Packages


Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Hammer Menus

The sections that follow describe the Hammer menus.

File Menu
The File menu lets you open image files, close windows, save the contents of certain
Hammer windows, and store and re-load memory.

Figure 3-1 The File Menu

File Menu 5
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Note
The menu items Load pseudo PCMCIA and Save pseudo PCMCIA as
are no longer used. u

Open (-O)
The Open menu item lets you open, load, and run a new image file.

Close (-W)
The Close menu item closes the active window.

Save As...
The Save As menu item lets you save, as text files, the contents of the stdio windows
such as the Listener, stdin/stdout/stderr, heap windows, and Spy windows.

Load Memory...
The Load Memory command lets you fill a piece of memory with a file that has been
saved with the Save Memory command.

Save Memory...
The Save Memory command lets you save the specified memory, as raw binary data, to a
file.

Figure 3-2 The Save Memory Command

6 File Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

The limit field is the address up to which, but not including, you wish to write. In the
above illustration, memory from 0447C9A9 through 0447C9B9 will be written.

Commands Menu
The Commands menu lets you initiate, suspend, and control execution of your program.
It also provides two general purpose utility commands: Convert and Translate.

Commands Menu 7
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Figure 3-3 Commands Menu

Go (-G)
The Go command causes a suspended (Stopped) program to resume execution.

8 Commands Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Stop (-.)
The Stop command suspends execution of the image currently being executed.
The image might not stop if:
n Interrupts are disabled (Hammer uses an IRQ interrupt to stop and start the image).
Interrupts can be blocked in the ARM CPU or by the control ASIC
n The image is too lost to respond to the interrupt because of, for example, bad MMU
tables
n There are hardware problems such as loose or bad cables, a bad Universal card, or you
are connected to the wrong serial port

Rerun (-R)
Rerun causes the image to be re-executed while preserving RAM and any code edits you
have made during this session. Windows are not closed and breakpoints are retained,
unless the image file changes.

Reload & Rerun


The Reload & Rerun command wipes out the contents of RAM. It discards any code
edits you have made, reloads the image, and executes. Breakpoints, except temporary
breakpoints, are retained.

Clear All Breakpoints


This menu item clears all breakpoints, both temporary and permanent. (Breakpoints are
discussed in “Breakpoints” on page 3-14.)

Clear All Breakpoint Hits


You can set breakpoints so that they trigger after a certain number of hits. This menu
item clears all breakpoint hits. See “Breakpoints” on page 3-14 for more information on
breakpoint hits.

Disable/Enable Breakpoints
This command toggles between disabling and enabling breakpoints. When breakpoints
are disabled, they will never trigger.

Step Into (-S), Step Over (-T)


These commands are used to advance program execution one instruction, or step, at a
time. The Step Into and Step Over commands operate in the same way as the Step/Step
and Step Into/Step Over buttons provided in Hammer’s Status window (described in

Commands Menu 9
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

“Go and Step Buttons” on page 3-21). They simply cause the next instruction to be
executed or, if the instruction is a subroutine call, let you either step into the subroutine
or step over the calling instruction.
If the instruction at the current PC is not a BL instruction, the menu items show as Step
(Into) and Step (Over).

Start Spying
This menu command requires specialized hardware and does not work with Armistice
cards or Newtons.

Spy Within Procedure


This menu command requires specialized hardware and does not work with Armistice
cards or Newtons.

Stop Spying
This menu command requires specialized hardware and does not work with Armistice
cards or Newtons.

Get Spy Counts


This menu command requires specialized hardware and does not work with Armistice
cards or Newtons.

Reset Spy Counts


This menu command requires specialized hardware and does not work with Armistice
cards or Newtons.

OS Object...(-J)
This menu item is used for OS development.

Convert... (-N)
The Convert command displays a single calculator. Given a number in hex, binary,
ASCII, signed or unsigned decimal, all other formats are displayed. If an 8-digit hex
value is selected before Convert is chosen from the menu, this value is displayed in all
possible formats. You change the value in any format.
You can also enter and evaluate expressions. The regular C operators with precedence
are supported, as are the ARM registers (note that the LK register is referred to as LR).

10 Commands Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Numbers are hex by default (as they are throughout Hammer); to specify decimal, use
the pound sign (#).

Figure 3-4 Convert Dialog

Translate...
This command translates virtual addresses to physical addresses as defined by the
current state of the MMU. Just like Convert, it can be primed with an 8-digit hex value
that you have selected.

Figure 3-5 Translate Dialog

Commands Menu 11
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Frame Functions...
This command dumps all frame functions (CFunctions and codeBlocks) that are under a
given object. You give the command a reference to the object you are interested in. You
can also specify an object by selecting it before you choose this command. If you enter a
1, the command dumps all frame functions.
The result is dumped to a file in the same folder as the image.
For example:
1. Bring up a memory window for gVarFrame
2. Select the first word in the window
3. Execute the Frame Functions command
4. Hammer creates a file named something like “FFunctions 04407b99” and puts the
information in it.

Start Profiling
This command starts profiling.

Stop Profiling
This command stops profiling.
For this command and the other profiling commands to be enabled, the image must
contain ROM code that supports profiling. If the image you loaded does not support
profiling, this command is grayed out.

Save Profiling Data...


This command prompts you for a file name and saves the profiling data into that file.
For this command and the other profiling commands to be enabled, the image must
contain ROM code that supports profiling. If the image you loaded does not support
profiling, this command is grayed out.

Do Script Profiling
This command sets up profiling. All functions accessible from scripting, including all
NewtonScript functions and top-level C functions, are profiled.
You can also profile other C functions by compiling their C files using profiling compiler
options.
For this command and the other profiling commands to be enabled, the image must
contain ROM code that supports profiling. If the image you loaded does not support
profiling, this command is grayed out.

12 Commands Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Procedures Menu
This menu is used to find or define procedures so that you can quickly access them via
code windows.

Figure 3-6 Procedures Menu

Procedure... (-P)
This item opens a symbol browser. You can type a class prefix in the class box and a
member prefix in the member box. All matching procedures are listed. When you click
“OK,” a window showing the procedure is opened.
Hammer’s search for a symbol is not case sensitive and a prefix of a symbol can be used
(for example, “asyncc” to find AsyncCallback).
For convenience, global names are accepted in the class box.

Define...
With this menu item, you can temporarily define a procedure name to reference a
particular range. These definitions are remembered for the duration of the current
debugging session but not from session to session.

Procedures Menu 13
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Figure 3-7 Define Procedures Dialog

The Procedures menu also includes a list of all open code windows. To display a code
window, select it from the menu. In the menu, window names are displayed in the order
in which the windows were opened (with the last one opened at the bottom) rather than
in any calling or layer order.

Code Windows
Each procedure in your program, as defined by the image file, can be displayed as a
separate code window. These windows are typically opened automatically for you. For
instance, when an exception or breakpoint is encountered, the code window containing
the PC is opened and brought to the front. As another example, if you step into a
procedure call, the called procedure’s code window is opened. Currently Hammer only
knows about procedures with external linkage (that is, it doesn’t know about static
procedures). Static procedures get appended to the previous external procedure.

Opening Code Windows

You can manually open code windows in one of three ways:


n Click on a procedure name that is the operand of a Branch instruction.
n Select the procedures name from the Procedures menu. This menu is a list of all open
code windows.
n Select Procedure from the Procedures menu and type in the name or address (in hex).
Searching for a symbol name is not case sensitive and a prefix of a symbol (name) can
be used (for example, asyncc to find AsyncCallback).

14 Procedures Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Code Window Contents


Code windows display assembly language. Clicking in the PC arrow column beside an
assembly language statement toggles the display of that line between disassembled text
and the hex value of the instruction.

Figure 3-8 Code Window Example

Breakpoint column

Breakpoints set

PC indicator column

Current PC

Command-clicking in the PC arrow area sets the PC to the location where you click.
Code windows allow read-only selection of immediates and the address of PC-relative
LDR/STRs.
The hex value is shown as a DCD directive, with ASCII in comments. The hex part of the
directive is editable. Hex numbers are indicated with “&”. Branch targets in the same
procedure are shown as “Lnn” indicating the line number in the procedure that is the
target of the branch.
Changing the high nibble of a hex opcode to F will cause the instruction to never execute
(such opcodes are actually reserved for other uses on future ARM processors).
Unreachable instructions in C code are automatically shown in hex.

Breakpoints
The simplest way to set a breakpoint is to click on an opcode in a code window. This acts
as a Go Until command. A temporary breakpoint is set at the specified instruction and a
Go command is issued. When the temporary breakpoint is hit, it is automatically cleared.
A permanent breakpoint is set by clicking in the diamond to the left of an opcode.
Clicking on the diamond a second time clears the breakpoint. Command-clicking on the

Procedures Menu 15
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

breakpoint diamond opens the breakpoint dialog where conditional breakpoints can be
set. Expressions are the same as in the Convert window.
You can see the breakpoint dialog by command-clicking a breakpoint. It contains:
n A way to determine what is defined as a “hit” in the case of a conditional statement
such as BEQ. You can define a hit as Always, which means that the statement is hit
whenever it is reached, even if the condition is not satisfied and the statement does
not execute. Alternatively, you can have a hit occur only when the statement would
execute. This is implemented in a much faster way than conditional expressions. The
default when clicking the breakpoint diamond of a conditional instruction is to have a
conditional breakpoint.
n A Stop After check box and a place to enter a value. This can be used to stop only after
the breakpoint has been hit the number of times indicated by the value. Alternatively,
it can be turned off so that the breakpoint doesn't stop and just counts the number of
times it’s been hit.
The breakpoint diamond shows the difference between an unconditional breakpoint
(solid diamond) and a conditional/temporary breakpoint (less solid diamond).

16 Procedures Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Memory Menu
The Memory menu lets you view and change the memory state and contents and also
contains shortcuts for the Listener.

Figure 3-9 Memory Menu

Memory Menu 17
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Memory...
Memory windows let you display the contents of RAM or ROM. Selecting this menu
item while a value is selected in a Hammer window opens a memory window at the
selected address. If no value is currently selected, Hammer brings up a dialog requesting
an address to display. You can enter:
n An address in hex
n A symbol such as a global variable name
n An expression

Figure 3-10 Memory Dialog

Once an address is entered, a Memory window is opened. The three columns displayed
are address, hex value and ASCII value. This window can be scrolled ±4K.

18 Memory Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Figure 3-11 Memory Window

If you hold down shift when opening a memory window while an address is selected,
Hammer treats the address as a handle instead of a pointer.
The hex values displayed in the window can be edited. Currently the ASCII value cannot
be edited.

Frame...
This menu item lets you display the specified variable or selection as a NewtonScript
object.

Memory Menu 19
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

If you have a number selected when you choose this command, what happens depends
on what the number is and whether or not you have the Shift key down. Table 3-1 shows
the various possible results.

Table 3-1 The Frame Command

Effect With Effect With


Selected Number Shift Key Up Shift Key Down
The address of a frame or array Opens a Don’t do this1
window
A Ref 2 of a forwarding object that forwards, eventually, to a displaying the
frame or array frame or array
The address of a forwarding object that forwards, eventually, to
a frame or array
A magic pointer Ref referring to a frame or array
A Ref of a frame or array Opens a
window
The address of a Ref of a frame or array The number is displaying the
treated as an frame or array
The address of an address of a Ref of a frame or array address, and a
A Ref of a forwarding object that forwards, eventually, to a memory
frame or array window is
opened at the
The address of a Ref of a forwarding object that forwards, selected
eventually, to a frame or array address
The address of an address of a Ref of a forwarding object that
forwards, eventually, to a frame or array
A magic pointer Ref referring to a frame or array
The address of a magic pointer Ref referring to a frame or array
The address of an address of a magic pointer Ref referring to a
frame or array
Any other number The number is treated as an
address, and a memory window is
opened at the selected address

1 With the shift key, down the selected number cannot be the address of an object—something will happen but not
what you want. Holding down shift is useful if the number selected is the address or contents of a RefVar,
RefStruct or RefHandle.
2 A Ref is the NewtonScript implementation’s reference to a NewtonScript object (a NewtonScript pointer, if you
will.)

If nothing is selected when you choose this command, Hammer displays the dialog box
shown in Figure 3-12.

20 Memory Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Figure 3-12 Frame Dialog

If you enter a number the behavior is as if the number had been selected, although the
Shift key is ignored. If you enter a symbol or the prefix of a symbol, then the behavior is
as if the symbol’s address had been selected and the shift key was down.
Figure 3-13 shows a frame window for gVarFrame.

Figure 3-13 Frame Window

Memory Menu 21
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

The area of the Frame window below the header includes the address of the object
header, the number of slots, the class and the Dirty, Writeable and Locked flags as icons.
You can select the address of the object header.
You can get additional information by clicking on parts of the frame window.
n Clicking on the Ref in the middle column selects it like any other Hammer number.
n Clicking on a tag in the left column or the value in the right columns is the same as
selecting the Ref and invoking the Frame command with the shift key up; that is, it
opens a Frame or memory window on the object in that slot.

Find...
Find searches for the specified data, as a word or a byte, in the range specified. The limit
value is the address up to which, but not including, you wish to search.

Figure 3-14 Find Dialog

You can click the Find button successively to continue searching. To start the search over,
you need to close and re-open the window, or change start, limit, or data.

Heap
Selecting the Heap item displays four windows showing four different heaps. The
topmost window displays the contents of the pointer heap, indicating the memory
blocks returned by malloc and NewPtr calls. The handle heap shows block returned by
NewHandle. The master pointer heap (mps) shows the master pointers used for the
handles, and the wired heap is used by the operating system.

22 Memory Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

If an 8-digit hex number is selected, Heap opens a single heap window using the
selection as the address of the heap header.

Figure 3-15 Heap Window

Statistics for this heap

Heap windows can be sorted by address, logical block size and task ID, by choosing the
Sort by Address, Sort by Size, and Sort by Task menu items respectively.

Kernel Heap
This item displays a window showing the kernel heap.

Script Heap
Displays a window showing the script heap. You can see paths for the entries in this
heap by choosing Enable Frame Object Paths from the Options menu. Hammer will
rebuild the path names if you execute a Go or Step Over command.
You should execute GC() in the Listener window before using this command.

Memory Menu 23
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

You may want to save the contents of this window using the Save As command and
view them with a spreadsheet.

Memory Info
This item displays a window giving memory information.

MMU
The MMU window displays the segment table information. Clicking on a Paged entry
opens the corresponding Page Table window as shown in the following figure.

Figure 3-16 MMU Window

Inverse MMU
The Inverse MMU item shows the MMU mappings in reverse. The boxes in the topmost
row indicate physical addresses and the boxes below show virtual address mappings.
The permissions (R and W) are also given. Clicking in a virtual address box opens a
memory window.

24 Memory Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Smash Heap Tags


Smash Heap Tags sets all tags of the active heap to 0x7fffffff. It cannot be undone.

Sort by Address
Sorts the items in the selected heap window by address.

Sort by Size
Sorts the items in the selected heap window by size.

Sort by Task
Sorts the items in the selected heap window by task.

Load Package and other Command Keys for the Listener


The last group of commands in the Memory menu are command keys for the Listener
window.
Hammer will type the characters in the command you select in the current line in the
Listener window. If the last character in the string is not a back slash (\), Hammer
deletes any text that might be on the current line, enters the command, and adds a return
character.
You can customize all of these command keys except for Command-2, which always
gives loadpackage(nil) or newloadpackage(nil,nil), whichever is appropriate
for the current image.
To customize, create a text file named Listener Commands in Hammer’s folder. Each
line of the file becomes a command in the Memory menu.

Windows Menu
The commands in this menu let you display the various windows that Hammer provides.

Windows Menu 25
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Figure 3-17 Windows Menu

Hot Windows
When Hot Windows are enabled via this menu choice, the contents of all windows being
displayed by Hammer are updated dynamically. If Hot Windows are disabled, the
windows are updated only when the program is stopped.
This menu item is not supported with ROM emulators.

Display
When you use an Armistice card, the Display menu item brings the Newton Message
Pad window to the front.

Status Window
The bottom of the Hammer Status window shows one, two, or three buttons depending
on the state of your program. When the Status window is first opened (when the image
is launched) the window displays just the Stop button at the bottom of the window.

Go and Step Buttons


When you enter the debugger (because a breakpoint or error was encountered or
because you pressed the Stop Button), three buttons labeled Go, Step, and Step are
displayed as shown below.

26 Windows Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Figure 3-18 Status Window

The Step buttons are just like the Step Into and Step Over menu items. They both cause
the next instruction to be executed. If the next instruction is a subroutine call, the buttons
change to Step Over and Step Into, allowing you to either step over the calling
instruction or step into the subroutine.

Figure 3-19 Status Window Showing Step Over

NOTE
Breakpoints are not installed during Step or Step (Into) operations.
Breakpoints are installed when you Go or Step (Over) or Go Until. u

Rerunning
When your program completes, the buttons are labelled Quit and Rerun. Note that the
buttons have Command key equivalents as indicated on the Commands menu. (The
command key equivalents are the same as their MacsBug counterparts.)
Reload and rerunning a program is the same as quitting the debugger and then
re-launching the image file (except that breakpoints are preserved.) All of the RAM on
the Armistice card or J1 main logic board is zeroed before the program is reloaded. The
ARM processor chip is then reset and execution begins at address 0.

Handy Hex Converter

In addition to indicating the execution state of the program (Running...) or the cause of
program suspension, the Status window displays the value that you have most recently
selected in one of Hammer’s windows. This area of the Status window also functions as
a hex converter: the hex last selected value field can be edited and the equivalent decimal
and ASCII values will be displayed. The hex value can also be selected and copied.

Windows Menu 27
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

The CPU Window


The CPU window has panes for the PC and PSR, the 4 banks of ARM General registers,
the Timer register and the MMU registers. Clicking on a pane label (MMU for example)
toggles the state of the pane, opening it if it is closed and vice versa. The PC/PSR and
General panes are always visible.

Figure 3-20 CPU Windows

The PC/PSR pane shows the current value of the PC and a symbolic interpretation of the
current PSR bits. You can change the PC. Clicking on the PC label is a quick way to find
the PC. If you have opened several windows or scrolled the window containing the PC,
clicking here will ensure that the PC arrow is visible.
The line under the PC is the current processor status register (CPSR). Clicking on the
mode will cycle through the processor modes usr, fiq, irq, svc, abt, and und.
Command-clicking on the mode will toggle between the corresponding 32-bit and 26-bit
modes (such as usr and u26; abt and und have no 26-bit equivalent.). The und mod
registers are not shown because they are used by Hammer.

28 Windows Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

The status register at the bottom of the Supervisor, FIQ, IRQ, and ABT panes is the saved
processor status register (SPSR) for that mode. It is where the CPSR is saved by the
processor when that mode is entered. SPSRs can be changed in the same way the CPSR
can be.
Clicking on a PSR flag toggles its value; upper case indicates the flag is set, lowercase
indicates clear. The I (IRQ) and F (FIQ) flags operate in the reverse: I or F indicates that
the interrupt is disabled, i or f indicates that the interrupt is allowed.
Clicking on the value of a register highlights that value for editing. The 8-digit hex
number temporarily becomes a TextEdit field, complete with Cut, Copy, Paste and Undo.
When you are finished editing the value, typing return replaces the original value with
the new value.
The register bank labels (R8, LK, etc.) are displayed in black for the active bank and gray
for inactive banks.

The FPE Registers Window


Displays the contents of the floating-point registers. They cannot be edited.

Stack Trace Window


Selecting the Stack Trace item from the Windows menu displays the call chain of
procedures to this point. The call chain is defined using R11 as the frame pointer. A nil
value (zero) terminates the chain.
Clicking on a procedure name in this window opens the corresponding code window.
Pressing Option while clicking on a procedure name displays the stack frame of the
procedure called by the selected procedure.
Pressing Command while clicking on a procedure name does a “go until.”

Stack Trace From...


This menu item lets you specify the point at which the stack trace should begin.

Spy Window
The Spy menu item opens and/or brings to the front the window containing the spy
counts.

Options Menu
This menu lets you enable and disable various Hammer options.

Options Menu 29
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Figure 3-21 Options Menu

Stop on Debug traps


If this option is not checked, calls to DebugStr and Debugger do not stop, but
DebugStr still displays its string.

Beep on Stops
This option enables and disables the audible indication of stopping.

Add Time Stamps


This option adds a time stamp to each line in the stdin/stdout window and to log files,
using the Macintosh to determine the time. The times when the image is stopped are not
included.
The times given are not exact because there is a delay between when the image sends a
string to the window and when Hammer gets it, and the delay cannot be calculated
because it depends on other applications that may be running on the Macintosh.

Log Breaks
This option tells Hammer to display a log line if a break point is hit with an expression
condition met. It doesn't matter whether the “Break after” condition is met.
Hammer will display a line similar to this:

30 Options Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

2/10 break at PC= 100530 TTracer::TTracer(char*) + 12


This may be useful to trace the program flow, especially if you turn on Add Time Stamp
option, as well.

Enable Frame Object Paths


This option tells Hammer to include paths for objects in the script heap window (see
“Script Heap” on page 3-22). Hammer will rebuild the path names if you execute a Go or
Step Over command.

Log Stdio
This option tells Hammer to save everything in the stdin/stdout/stderr window to a log
file. The log file is placed in the Hammer folder and is named “HLog stdio”. If a log file
already exists when Hammer tries to open or create one, it is overwritten, so rename the
file if you want to keep it. The log file is closed when you quit Hammer, but not when
you rerun or reload and rerun.

Log Listener
This option tells Hammer to save everything in the NewtonScript Listener window to a
log file. The log file is placed in the Hammer folder and is named “HLog listener”. If a
log file already exists when Hammer tries to open or create one, it is overwritten, so
rename the file if you want to keep it. The log file is closed when you quit Hammer, but
not when you rerun or reload and rerun.

Async Prints
This option tells Hammer to buffer printing to the stdin/stdout/stderr window as
quickly as it can. Display of information in this window is typically delayed, especially
when the image prints a lot. When you check this command, printing to the window is
quicker, but may not show what is going on in the image at that moment.

Register names...
Selecting this option displays the following pane which you can use to change the names
associated with the ARM registers.

Options Menu 31
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Figure 3-22 Register Names Dialog

Spy Options...
This command requires specialized hardware and does not work with Armistice cards or
Newtons.

Serial Debugger Options...


This command brings up a dialog that lets you set how many 4K pages to allocate for
breakpoints when using a Newton for debugging. See Chapter 6, “Debugging Using a
Newton,” for more information.

Config Menu
The Config menu lets you use Hammer to configure images in various ways.

Note
The menu items labeled only by bit number— bit 2, bit 3, and so on—are
not supported on current images. u
Changing these options may have no effect until you Rerun. Note that using the
configuration options carelessly may make it impossible to debug your image. Use these
options with caution.

32 Config Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

IMPORTANT
Hammer may have trouble running with certain Config menu settings.
In particular:
n Stop on Aborts and Stop on Throws should be off
n Default Stdio On, Don’t Sleep, and Fake Battery Level should be on

In general, you should not change these settings unless you have a
particular reason to do so. s

Figure 3-23 Config Menu

Cripple Memory
Set this item to pretend there is only 640K of RAM.

Config Menu 33
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Enable Listener
This item only applies to nodebug images used with a Newton rather than an Armistice
card (see Chapter 6, “Debugging Using a Newton”). When you check it, the Listener is
enabled. For debug images, the Listener is always enabled.

Stop on Aborts
Useful for finding bugs. When you use an Armistice card, this happens whether or not
this item is checked.

Stop on Throws
Useful for finding bugs. When you use an Armistice card, this happens whether or not
this item is checked.

Heap Checking
Turn on heap checking.

Stack Thrashing
Turn on checking for stack thrashing.

OS Profiling
Include the Newton OS in profiling.

Default Stdio Off/On


Standard I/O interferes with interrupts; set this option to prevent standard I/O.
When this item is checked and you are running a debug image, a NewtonScript Listener
window opens. This is similar to the Listener you can use with NTK.

Bunwarmer Diagnostics
You use this item only if you have specialized hardware. Set this item to invoke
diagnostics at boot time.

Don’t Sleep
This item should always be set. It stops the hardware from sleeping. (This is different
from Newton’s sleep setting—this setting deals with the Armistice chip’s sleep feature.).

34 Config Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Fake Battery Level


The Armistice card does not have batteries; set this item to keep the Armistice card from
deciding that the batteries are dead and going to sleep.

Enable Stdout
Leave this option off if you only need stdio for the Listener.

Enable Package Symbols


Set this option if you want to see your symbols loaded from a package. You should not
use this option off if you’re running Hammer and NTK, Newton Connection, or Package
Installer, because it can cause timeouts.

Use PC Spy Memory


This option tells Hammer to use PC spy memory.

Erase Internal Store


This item tells Hammer to erase internal store on rerun and reset.

Tests Menu
The Tests menu is used in OS development to run tests on various sub-systems.

Tests Menu 35
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3

Hammer Menus

Figure 3-24 Tests Menu

36 Tests Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 4

Hammer Shortcuts

Hammer Shortcuts

You may find the following shortcuts useful. In general:


n Clicking on hex numbers selects them. You can copy such selections and edit some of
them (such as data in Memory windows). The value of the current selection is shown
in the Status window. Some menu commands that require numbers operate on the
selection if there is one.
n Command-L selects the Listener window.
In the CPU window:
n Clicking on the PC label (“PC”) opens a code window or scrolls one to reveal the
instruction at the PC.
n Clicking on the mode labels opens and closes that pane of the window.
n Clicking on the status flags toggles them.
n Clicking on the mode cycles through the mode.
n Command-clicking on the mode toggles 26/32 bit.
In Procedure windows:
n Clicking on the target of a “B” or “BL” instruction opens a new code window or
scrolls to show the target.
n Command-clicking on the breakpoint diamond opens the breakpoint dialog where
conditional breakpoints can be set.
n Command-clicking in the PC column sets the PC to that instruction.
In the Listener window:
n Command-2 types “loadpackage(nil)” or “newloadpackage(nil, nil)” for
you.
n Command-3 through Command-9 type strings you can define (see “Command Keys
for the Listener” on page 3-23)
n Up-arrow cycles through the last ten last executed command, and re-submits them
n Control-u erases the contents of the current command line

Tests Menu 37
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 4

Hammer Shortcuts

Note
The following two shortcuts may be removed from Hammer at some
point. u
n Clicking the opcode of an instruction sets a one-time breakpoint at the instruction and
goes. The one-time breakpoint lasts until it is reached or you rerun.
n Clicking in the PC column toggles the display of an instruction between “normal” and
“DCD”. In the “DCD” form you can change the hex value of the instruction. If you
change the value, the change persists until you choose “Reload and Rerun.”
In the Stack Trace window:
n Clicking on a routine reveals the instruction at the return address in that routine.
n Command-clicking on a routine sets a one-time breakpoint at the return address and
goes.
n Option-clicking on a routine opens a memory window on the stack frame.
Holding down the option key while rerunning (or reload and rerun or at Hammer
launch time) prevents the reset image from being run (at therefore prevents memory
from being wiped. It also prevents the image from being started. In this unstarted (“Not
yet initialized”) state you can “Go” but many things won't work: stepping, setting
registers, and so on.
If the caps lock key is down. Hammer will stop the image when the image executes an
InitFinished instruction. This is the first time at which all the features should work.

38 Tests Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 5

Hammer Debugging Tips

Hammer Debugging Tips

Here are some examples of using Hammer.

My code is loaded as a package, and I want to be able to see and use my symbols

1. In your ARM6Link options (provided in the example makefile), change the option
-bin to -aif -bin -dsuppress. For example

ARM6Link -aif -bin -dsuppress -base 0 -o MyProtocol.part


:Objects:MyProtocol.c.o :Objects:MyProtocol.impl.h.o

2. Make a Finder alias of the linker output file, here MyProtocol.part, and put it in
the same folder containing the Hammer6 debugger.
3. If your part is a -protocol part, rename the alias to be the same as the Protocol
name.
4. If your part is a -frames part, rename the alias to be the same as the part info string.
5. Add the -aif option between the partType and partDataFile options on the Packer
command line. For example:

Packer -o MyPackage.pkg MyPackage ∂


-packageid ' no ' -version 1 -copyright ∂
"© 1994 Melon Computer, Inc." ∂
-protocol -aif MyProtocol.part

6. In Hammer, select the Config menu, and make sure that the “Enable Package
Symbols” item is checked. If it isn’t, check it and select “Restart” from the Commands
menu. You’ll only need to do this once; Hammer saves its settings in a preferences file.

I want to find out what caused the “unhandled exception”

1) Set the Stop on Throw item in the Config menu. This will cause Throw to call
DebugStr with a string describing the exception about to be thrown. You can look at the

Tests Menu 39
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 5

Hammer Debugging Tips

stack trace to see who called Throw. The message “evt.ex.abt.bus” is a data or prefetch
abort caused by trying to do a load/store from/to unmapped (non-existent) memory.
The string “evt.ex.msg” is a generic “message” exception; in that case, the second
parameter to Throw (which was passed in R1) contains a pointer to a human-readable
message describing the exception.
To track down a user mode data abort check the Stop on Aborts Config menu item.
When the image aborts in user mode and Stop on Aborts is checked the image stops at
the instruction causing the abort and say “Data Abort” instead of the normal behavior,
which is to throw a “evt.ex.abt.bus” exception and not stop. When you Step or Go, the
aborting instruction is retried. There is no easy way to get the normal throw behavior
when using Stop on Aborts. Stop on Aborts and Stop on Throws are difficult to use with
an Armistice card because there is a constant stream of “normal” data aborts accessing
the memory shared with the Macintosh. It may be possible to stop the image in a state
where the problem abort will happen soon, check the Stop on Aborts item and then wind
up stopped on the correct abort.

I want to convert between hex and ASCII

1) Select the constant and then choose the Convert menu item or just select the value and
look in the Status window where it always displays the most recently selected hex value
in both decimal and ASCII.

I want to check the parameters to a routine

The first four parameters are passed in R0, R1, R2, R3 and the result is returned in R0.
Additional parameters are passed on the stack. Select the value in SP and press
Command-M.
C++ non-static member function have this as an implied first parameter. The first
parameter is passed in R0 unless the routine returns a struct larger than 4 bytes; in which
case, a pointer to the return area is passed in R0. See also section 5 of the ARM Technical
Specification manual.
Actually (for non-static function members) “this” will be in R0 unless the function
returns a struct (or union of class). In that case R0 will be a pointer to the return struct
and R1 will be “this.”

I crashed in a routine and want to find out what parameters caused the problem.

1) Look at the beginning of a routine to see if the parameters (R0-R3) were saved in
permanent registers.
2) If that doesn't help, set the PC to the return instruction (LDM) and step to get back to
the previous routine. At this point, you can often rerun the call by changing the PC.

40 Tests Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 5

Hammer Debugging Tips

Alternatively, you can set the PC to the new return instruction and back out another
level.

I want to look at a local in the stack frame.

1) Look for a place which assigns or reads the local for a procedure call and then use the
procedure call to tell you what offset/register the local is at.
2) Look for a place at the beginning of the function where the local is initialized with a
constant or a parameter.
3) Add a dummy procedure call to your function which takes the local as a parameter.

I want to learn common idioms of the compiler so I can ignore them

Standard Entry saves registers used and sets up a stack frame.

MOV R12, SP
STMDB SP!, {R4-R7, R11-R12, LK-PC}
SUB R11, R12, 4

Standard Exit restores registers, fixes up the stack, and returns.

LDMDB R11, {R4-R7, R11, SP, PC}


Standard Exit is sometimes optimized into a tail call.

LDMDB R11, {R4-R7, R11, SP}


B LastProcedureCallInMethod
Small structures are copied using load multiple.

LDMIA R0, {R3, R12}


STMIA R2, {R3, R12}

Anytime you use a RefVar, a constructor will be inserted.

MOV R0, Rx
ADD R0, SP, #xx
BL __ct__6RefVarFCl
MOV Rx, R0

And a destructor will be inserted at the end of the block.

ADD R0, SP, #xx


MOV R1, #2
BL __dt__6RefVarFv

Tests Menu 41
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 5

Hammer Debugging Tips

(Note that passing a Ref to a function taking a RefArg will implicitly construct/destruct
a temporary RefVar.)
Virtual method calls jump through an array of method pointers.

MOV LK, PC
LDR PC, [Rx, #xx]

Reading a short is done by reading a shifted long.

LDR R0, [SP, #xx]


MOV R0, R0, ASR 16

Writing a short is done a byte at a time (which is why you should avoid shorts).

STRB R0, [SP, #xx+1]


MOV R0, R0 ASR 8
STRB R0, [SP, #xx]

I want to change an instruction to a no-op

1. Click in the PC Indicator Column; this converts the disassembled instruction to its hex
opcode.
2. Change the left-most digit (usually “E”) to “F”. This sets the conditional field to
“never.”
You can also use this technique to fix “off by one” problems, especially in loops. Page 16
of the ARM CPU manual describes all 16 conditional codes. It’s very easy to change a
BLT to a BLE, for example.

42 Tests Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 6

Debugging Using a Newton

Debugging Using a Newton

You can use Hammer with either an emulator such as an Armistice card or with a
Newton. When you debug using a Newton, Hammer communicates with the Newton
using a serial connection, so it is called serial debugging.
Serial debugging is primarily intended for licensees who develop their software on top
of Newton system software. Such developers may, ultimately, either combine their code
with Newton system software and build a ROM or leave their code as loadable
packages, or do both.
You can use serial debugging for C code and for Newton Script code.
You can’t run the NTK inspector in serial debugging. You must use the listener built in to
Hammer.

What You Need


You need the following for serial debugging:
n A Newton using a 2.0 system, or which has a stable flash ROM that includes the ROM
code needed for serial debugging
n A matching image file. You can use a debug or nodebug image; all features are
available with a nodebug image except starting debugging after the target crashed.
n A Macintosh running Hammer
n The serial debugger setup application, TMChooser, loaded on the Newton
n Serial cable
You may want to use a serial PCMCIA card, which leaves the Newton serial port free for
other uses. We have tested the Socket Communications serial I/O card, and this works
fine with the Newton; we recommend that developers use this. Other cards may work
as well, but we haven’t tested any others yet.
For debugging packages containing C code you also need:

What You Need 43


Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 6

Debugging Using a Newton

n the package you want to debug loaded on the Newton


n the package file and symbol files or their aliases in Hammer’s folder

Beginning Serial Debugging


You need to choose tell Hammer which serial port you want to connect the Newton to.
See page 3 for how to do that.
You first need to set the baud rate in Hammer:
1. Run Hammer.
2. When selecting the image, hold down both the command and the option key.
Hammer shows a dialog for target selection.
3. Choose modem port and click on OK.
4. Choose Serial Debugger Options from the Options menu.
5. Choose the baud rate you want. All of the available baud rates work well.
6. If you have changed baud rate setting, quit Hammer.
To begin serial debugging:
1. If you quit Hammer after changing the baud rate, run Hammer again and select an
image. This time you don’t need to choose the target because Hammer remembers
that as the debugging target.
2. On the Newton, open the TMChooser application.
3. Select the same baud rate you chose in Hammer.
4. Select Serial Debugger.
5. Tap on Connect.
You should see a Listener window on the Macintosh. You can see progress information
in the stdin/stdout/stderr window.

Features
This section lists all the features supported in serial debugging. Features marked with an
asterisk (*) are available with 1.x Newtons.
n Execution control
n Stop target*

n Set breakpoints in ROM, packages

n Set breakpoints with expressions (e.g. R0== 0x00000000)

n Step and step over in ROM or packages

44 Beginning Serial Debugging


Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 6

Debugging Using a Newton

n Can set breakpoint while target is running (that is, you don’t need to stop the
image)
n Exceptions Handling
n Stop on throws

n Stop on aborts

n User wants to see unmapped memory

n Memory Related
n See code (ROM and packages)*

n See heaps*

n See memory*

n Modify memory

n Stdio
n Stdio window

n files

n Listener window
n Also supports loadpackage/newloadpackage

n Choose any available serial channels


n built-in serial port*

n serial on PCMCIA

n IR

n Start debugging after target crashed


n This feature is not supported for nodebug images.

n If configured to, a target in exception mode will wait on a serial port for connecting
to Hammer.
n This allows you to examine the state of a crashed machine.

n Miscellaneous
n See/Modify register

n Stack trace*

n Copy target screen*

n Greg’s window (command-I):*

n MMU table

n CPU window

n FPE registers

n Event tracing

Features 45
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 6

Debugging Using a Newton

Limitations
This section lists the limitations of serial debugging; that is, things you can do when you
use an emulator that you can’t do when serial debugging.
n You can’t do “Cause Abort”, that is, stop when accessing x address with y value.
This can’t be done because of a limitation of the Newton hardware.
n The number of breakpoints in ROM are limited though they are not limited in
packages.
You need to set aside some RAM for ROM breakpoints when starting serial
debugging. More memory allows more breakpoints. 8K is required by the system to
support stepping in ROM. Each additional 4K will give at least one breakpoint. More
breakpoints in the same 4K range don't use any additional memory. For example, 20K
(8K for system and 12K for breakpoints) memory will allow a user to set breakpoints
in three different 4K pages. You can set the amount of memory available by using the
Serial Debugging Options command in the Options menu.
n You cannot change ROM code (for example, to NOP an instruction)
n “Rerun” requires you to press the reset button if the target crashed.
n Scrolling of memory window, code window, heap window, frame window may be
slow.
n The Newton doesn’t sleep while it is stopped
Don't use the Newton’s battery while debugging, use an power adapter.
n You can’t use pc spy/profiling

User Interface Description


In serial debugging, Hammer has a new preferences setting for setting aside how much
memory from target for ROM breakpoints.
If a function is not available for serial debugging, Hammer indicates it to the you in the
following ways:
n if the function is a menu command, then the menu item will be dimmed
n if the function is accessed through a window (say change ROM code), you will hear a
beep when trying to access the unavailable feature
On the Newton, you run an application that lets you setup a serial debugging session.
You can make selection of
n which serial channel to use
n what baud rate to use

46 Limitations
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95