hammer user’s guide

ð

ð

Newton Driver Development Kits

Hammer User’s Guide

Preliminary Draft 0.8

March 14, 1995 Jonathan Simonoff© Apple Computer, Inc. 1995

ð Apple Computer, Inc.© 1994, 1995 Apple Computer, Inc.All rights reserved. No part of this publication or the software described in it may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Computer, Inc., except in the normal use of the software or to make a backup copy of the software. The same proprietary and copyright notices must be affixed to any permitted copies as were affixed to the original. This exception does not allow copies to be made for others, whether or not sold, but all of the material purchased (with all backup copies) may be sold, given, or loaned to another person. Under the law, copying includes translating into another language or format. You may use the software on any computer owned by you, but extra copies cannot be made for this purpose. Printed in the United States of America.The Apple logo is a registered trademark of Apple Computer, Inc. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws.No licenses, express or implied, are granted with respect to any of the technology described in this book. Apple retains all intellectual property rights associated with the technology described in this book. This book is intended to assist application developers to develop applications only for licensed Newton platforms.

Apple Computer, Inc.20525 Mariani AvenueCupertino, CA 95014408-996-1010

Apple, the Apple logo, APDA, AppleLink, LaserWriter, Macintosh, MPW, and Newton are trademarks of Apple Computer, Inc., registered in the United States and other countries.The light bulb logo, MessagePad, NewtonScript, and Newton Toolkit are trademarks of Apple Computer, Inc.FrameMaker is a registered trademark of Frame Technology Corporation.ARM is a trademark of Advanced RISC Machines Ltd.Helvetica and Palatino are registered trademarks of Linotype Company.ITC Zapf Dingbats is a registered trademark of International Typeface Corporation.

Simultaneously published in the United States and Canada.

LIMITED WARRANTY ON MEDIA AND REPLACEMENT

If you discover physical defects in the manual or in the media on which a software product is distributed, APDA will replace the media or manual at no charge to you provided you return the item to be replaced with proof of purchase to APDA.

ALL IMPLIED WARRANTIES ON THIS MANUAL, INCLUDING IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE LIMITED IN DURATION TO NINETY (90) DAYS FROM THE DATE OF THE ORIGINAL RETAIL PURCHASE OF THIS PRODUCT.

Even though Apple has reviewed this manual, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS MANUAL, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS MANUAL IS SOLD “AS IS,” AND YOU, THE PURCHASER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY.

IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS MANUAL, even if advised of the possibility of such damages.

THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty.

Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state.

iii

Draft. Preliminary , Confi dential. © 1995 Apple Computer , Inc. 3/15/95

Chapter 1 Introduction 1

Chapter 2 Getting Started 3

Chapter 3 Hammer Menus 5

File Menu 5Open (ð-O) 6Close (ð-W) 6Save As... 6Write Memory... 6

Commands Menu 6Go (ð-G) 7Stop (ð-.) 7Rerun (ð-R) 8Reload & Rerun 8Clear All Breakpoints 8Step (Into) (ð-S), Step (Over) (ð-T) 8Start Spying 8Spy Within Procedure 8Stop Spying 8Get Spy Counts 8Reset Spy Counts 9OS Object... 9Convert... 9Translate... 9

Procedures Menu 10Procedure... (ð-P) 10Define... 11Code Windows 11

Memory Menu 13Memory... 14Frame... 16Find... 18Heap 18MMU 19Inverse MMU 20

Contents

iv

Draft. Preliminary , Confi dential. © 1995 Apple Computer , Inc. 3/15/95

Windows Menu 20Hot Windows 21Display 21Status Window 21The CPU Window 23The FPE Registers Window 24Stack Trace Window 24Stack Trace From... 24Spy Window 24

Options Menu 24Stop on Debug traps 25Beep on Stops 25Register names... 25Spy Options... 26

Config Menu 26Cripple Memory 27Stop on Aborts 27Stop on Throws 27Default Stdio off/on 27Bunwarmer Diagnostics 27Don’t Sleep 27Fake Battery Level 27Enable Stdout 27Enable Package Symbols 27

Tests Menu 28

Chapter 4 Hammer Shortcuts 29

Chapter 5 Hammer Debugging Tips 31

CHAPTER 1

1

Draft. Preliminary , Confi dential. © 3/15/95 Apple Computer , Inc. 3/15/95

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.

CHAPTER 1

Introduction

2


CHAPTER 2

Getting Started

3


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.

CHAPTER 2

Getting Started

4 Viewing Frames that Refer to Packages


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

CHAPTER 3

Hammer Menus

File Menu 5


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

CHAPTER 3

Hammer Menus

6 File Menu


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

CHAPTER 3

Hammer Menus

Commands Menu 7


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.

CHAPTER 3

Hammer Menus

8 Commands Menu


Figure 3-3 Commands Menu

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

CHAPTER 3

Hammer Menus

Commands Menu 9


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 & RerunThe 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 BreakpointsThis menu item clears all breakpoints, both temporary and permanent. (Breakpoints are discussed in “Breakpoints” on page 3-14.)

Clear All Breakpoint HitsYou 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 BreakpointsThis 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

CHAPTER 3

Hammer Menus

10 Commands Menu


“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 SpyingThis menu command requires specialized hardware and does not work with Armistice cards or Newtons.

Spy Within ProcedureThis menu command requires specialized hardware and does not work with Armistice cards or Newtons.

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

Get Spy CountsThis menu command requires specialized hardware and does not work with Armistice cards or Newtons.

Reset Spy CountsThis 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).

CHAPTER 3

Hammer Menus

Commands Menu 11


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

CHAPTER 3

Hammer Menus

12 Commands Menu


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 ProfilingThis command starts profiling.

Stop ProfilingThis 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.


Do Script ProfilingThis 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.


CHAPTER 3

Hammer Menus

Procedures Menu 13


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.

CHAPTER 3

Hammer Menus

14 Procedures Menu


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 WindowsEach 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 ).

CHAPTER 3

Hammer Menus

Procedures Menu 15


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

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

Breakpoints set

Current PC

Breakpoint column

PC indicator column

CHAPTER 3

Hammer Menus

16 Procedures Menu


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).

CHAPTER 3

Hammer Menus

Memory Menu 17


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

CHAPTER 3

Hammer Menus

18 Memory Menu


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.

CHAPTER 3

Hammer Menus

Memory Menu 19


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.

CHAPTER 3

Hammer Menus

20 Memory Menu


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.

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

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.)

Table 3-1 The Frame Command

Selected NumberEffect W ith Shift Key Up

Effect W ith Shift Key Down

The address of a frame or array Opens a window displaying the frame or array

Don’t do this1

A Ref2 of a forwarding object that forwards, eventually, to a 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 displaying the frame or array

The address of a Ref of a frame or array The number is treated as an address, and a memory window is opened at the selected address

The address of an address of a Ref of a frame or array

A Ref of a forwarding object that forwards, eventually, to a frame or array

The address of a Ref of a forwarding object that forwards, eventually, to a frame or array

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

CHAPTER 3

Hammer Menus

Memory Menu 21


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

CHAPTER 3

Hammer Menus

22 Memory Menu


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.

HeapSelecting 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.

CHAPTER 3

Hammer Menus

Memory Menu 23


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

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 HeapThis item displays a window showing the kernel heap.

Script HeapDisplays 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.

Statistics for this heap

CHAPTER 3

Hammer Menus

24 Memory Menu


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

Memory InfoThis item displays a window giving memory information.

MMUThe 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 MMUThe 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.

CHAPTER 3

Hammer Menus

Windows Menu 25


Smash Heap Tags

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

Sort by AddressSorts the items in the selected heap window by address.

Sort by SizeSorts the items in the selected heap window by size.

Sort by TaskSorts the items in the selected heap window by task.

Load Package and other Command Keys for the ListenerThe 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.

CHAPTER 3

Hammer Menus

26 Windows Menu


Figure 3-17 Windows Menu

Hot WindowsWhen 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.

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

Status WindowThe 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.

CHAPTER 3

Hammer Menus

Windows Menu 27


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.

CHAPTER 3

Hammer Menus

28 Windows Menu


The CPU WindowThe 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.

CHAPTER 3

Hammer Menus

Options Menu 29


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 WindowDisplays the contents of the floating-point registers. They cannot be edited.

Stack Trace WindowSelecting 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 WindowThe 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.

CHAPTER 3

Hammer Menus

30 Options Menu


Figure 3-21 Options Menu

Stop on Debug trapsIf this option is not checked, calls to DebugStr and Debugger do not stop, but DebugStr still displays its string.

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

Add Time StampsThis 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 BreaksThis 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:

CHAPTER 3

Hammer Menus

Options Menu 31


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 PathsThis 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 StdioThis 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 ListenerThis 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 PrintsThis 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.

CHAPTER 3

Hammer Menus

32 Config Menu


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.

CHAPTER 3

Hammer Menus

Config Menu 33


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 MemorySet this item to pretend there is only 640K of RAM.

CHAPTER 3

Hammer Menus

34 Config Menu


Enable ListenerThis 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 AbortsUseful for finding bugs. When you use an Armistice card, this happens whether or not this item is checked.

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

Heap CheckingTurn on heap checking.

Stack ThrashingTurn on checking for stack thrashing.

OS ProfilingInclude the Newton OS in profiling.

Default Stdio Off/OnStandard 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 DiagnosticsYou use this item only if you have specialized hardware. Set this item to invoke diagnostics at boot time.

Don’t SleepThis 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.).

CHAPTER 3

Hammer Menus

Tests Menu 35


Fake Battery LevelThe 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 StdoutLeave 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 MemoryThis option tells Hammer to use PC spy memory.

Erase Internal StoreThis 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.

CHAPTER 3

Hammer Menus

36 Tests Menu


Figure 3-24 Tests Menu

CHAPTER 4

Hammer Shortcuts

Tests Menu 37


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

CHAPTER 4

Hammer Shortcuts

38 Tests Menu


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.

CHAPTER 5

Hammer Debugging Tips

Tests Menu 39



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 fi nd 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

CHAPTER 5


40 Tests Menu


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 fi nd 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.

CHAPTER 5


Tests Menu 41


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

CHAPTER 5


42 Tests Menu


(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.

CHAPTER 6

Debugging Using a Newton

What You Need 43



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:

CHAPTER 6


44 Beginning Serial Debugging


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 controln Stop target*n Set breakpoints in ROM, packagesn Set breakpoints with expressions (e.g. R0== 0x00000000)n Step and step over in ROM or packages

CHAPTER 6


Features 45


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

n Exceptions Handlingn Stop on throwsn Stop on abortsn User wants to see unmapped memory

n Memory Relatedn See code (ROM and packages)*n See heaps*n See memory*n Modify memory

n Stdion Stdio windown files

n Listener windown Also supports loadpackage/newloadpackage

n Choose any available serial channelsn built-in serial port*n serial on PCMCIAn IR

n Start debugging after target crashedn 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 Miscellaneousn See/Modify registern Stack trace*n Copy target screen*n Greg’s window (command-I):* n MMU tablen CPU windown FPE registersn Event tracing

CHAPTER 6


46 Limitations


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

hammer user’s guide

Documents