Professional Documents
Culture Documents
Newton Driver
Development Kits
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
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
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.
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
Hammer Menus
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.
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.
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
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.
Disable/Enable Breakpoints
This command toggles between disabling and enabling breakpoints. When breakpoints
are disabled, they will never trigger.
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.
Stop Spying
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 (#).
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.
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.
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.
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
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.
14 Procedures Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3
Hammer Menus
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.
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
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
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.
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
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.
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.
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.
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.
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
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.
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
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.
26 Windows Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 3
Hammer Menus
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.
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.
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 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.
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
Beep on Stops
This option enables and disables the audible indication of stopping.
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
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
Spy Options...
This command requires specialized hardware and does not work with Armistice cards or
Newtons.
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
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.
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
Enable Stdout
Leave this option off if you only need stdio for the Listener.
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
36 Tests Menu
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 4
Hammer Shortcuts
Hammer Shortcuts
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
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
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:
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.
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
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.
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.
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
Alternatively, you can set the PC to the new return instruction and back out another
level.
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.
MOV R12, SP
STMDB SP!, {R4-R7, R11-R12, LK-PC}
SUB R11, R12, 4
MOV R0, Rx
ADD R0, SP, #xx
BL __ct__6RefVarFCl
MOV Rx, R0
Tests Menu 41
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95
CHAPTER 5
(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]
Writing a short is done a byte at a time (which is why you should avoid shorts).
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
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.
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 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 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 serial on PCMCIA
n IR
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 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
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
46 Limitations
Draft. Preliminary, Confidential. ©3/15/95 Apple Computer, Inc. 3/15/95