Apple IIGS Debugger Debugging Software Reference Manual

Below you will find brief information for the Apple IIGS Debugger. This document details how to control program execution, including single-stepping, tracing, and real-time modes. Learn to set breakpoints to suspend execution, define memory protection ranges, and utilize various display screens for inspecting registers, stack, memory contents, and code disassembly. It also covers using included desk accessories like Loader Dumper and Memory Mangler for advanced debugging tasks.

PDF

Document

Af'?t£

PROG.'lAMMm

.&I>IOOEVEUlPSi"S

JSSW..UlON

29:l s.v

~3td. ~

~"Ct\WA~

2l:6-2:i~

APPLE

IIGS

Debugger

Reference

Version 1.1.1

APDA# K2SBUG

, - - - '

Apple

IIGS

Debugger Reference

APDA Draft

August 20, 1987

Apple Technical Publications

This document does not include:

• final editorial corrections

• final art work

• an index

APPLE COMPUTER , INC.

This manual is copyrighted by Apple or by Apple's suppliers, with all rights reserved. Under the copyright laws, this manual may not be copied, in whole or in part, without the written consent of Apple Computer,

Inc. This exception does not allow copies to be made for others, whether or not sold, but all of the material purchased may be sold, given, or lent to another person. Under the law, copying includes lranslating into another language.

20525 Mariani Avenue

Cupertino, California 95014

(408) 996-1010

Apple, the Apple logo, and Macintosh are registered irademarks of Apple Computer, Inc.

Apple nGSis a trademark of Apple Computer, Inc.

Simultaneously published in the United States and Canada.

Apple

lles

Debugger

1 Chapter

Overview

Getting Started

What You Need

Debugger Restrictions

Loading the Debugger

Loading Your Program

Debugger Display Screens

Selecting Displays

The Master Display

Test-Program Display

Memory Display

Direct Page Display

Help Screen

Running Your Program

Single-Step and Trace Modes

Real-Time Mode

The Command Filter

Memory Protection

14 Breakpoints

15 Printing

15 Using Monitor Routines

17 Chapter 2. Using the Debugger

17

Debugging Segmented Programs

18 Watching a Running .

Disassembly

19 Using Breakpoints

20 Using Memory-Protection Ranges

21 Debugging Multilanguage Programs

23 Chapter 3. Command Reference

23

Debugger Registers

65816 Registers

Altering the Contents of Registers

28 Stack Subdisplay

29 Disassembly Subdisplay

32 RAM

Subdisplay

34 Breakpoint Subdisplay

36 Memory-Protection Subdisplay

39 Command Line

39 Altering the

Contents

of

Memory

Hexadecimal-Decimal Conversion

Configuring the

Master Display

Saving a Display Configuration

Command-Line Commands

47 Chapter 4. Desk Accessories

47

LoaderDurnper

47

Dump Memory Segment Table

APDADrqft

Table o/Contents

8120187

Table ojContellls

Dump Pathname Table

Dump Jump Table

Dump Loader Globals

Dump ProDOS Packets

Dump File Buffer Variables

Dump Load Segment Infonnation

Dump Address

Memory Mangler

LIST

LmeNumoor

Handle

Location

Attributes

UserUD

Lengili

Previous Handle

Next Handle

MON

QUIT

Memory Manager Commands

Appendix: Command Summary

Keystroke Modifier

60 SeJectffig a Display

60 Editing the

Master

Display

Display Configuration

Disassembly Subdisplay

RAM Subdisplay

Breakpomts Subdisp1ay

Memory-Protection Subdisplay

Command-Lme Commands

Command-Editing Commands

Setting Registers and Memory Values

Breakpomts

Hexadecimal-Decimal Conversion

Savmg Display Configurations

Prmting

Loading and Runnmg Your Program

Other Command-Line Commands

66 Trace and Smgle-Step Mode Commands

Apple lIGS Debugger

APDA Draft

ii

8120187

Apple JIGS Debugger

List of Figures

Chapter 1. Overview

1.1. Master Display

1.2. Sample Memory Display

Chapter 2. Using the Debugger

Chapter 3. Command Reference

29 3.1. Disassembly Subdisplay

33 3.2. RAM Subdisplay

Chapter 4. Desk Accessories

48 4.1. Memory Segment Table Output

49 4.2. Pathname Table Output

51 4.3. Jump Table Output

52 4.4. Loader Globals Output

53 4.5. ProOOS Packets Output

54 4.6. File Buffer Variables Output

54 4.7. Load Segment Information Output

55 4.8. Dump Address Output

57 4.9. Memory-Block Attributes

List of Tables

Chapter 1. Overview

1.1. Selecting Debugger Displays

Chapter 2. Using the Debugger

Chapter 3. Command Reference

30 3.1. Disassembly Operand Formats

Chapter 4. Desk Accessories

Table o/Contents

APDADraft

iii

8120187

Table a/Contents

Apple lIes

Debugger

APDA Draft

8120187

Apple /lGS Debugger Chapter

1: Ov

e rview

Chapter 1 Overview

The Apple nGS Debugger is designed to aid you in rmding bugs in your programs by allowing you to control execution of any load file. The debugger includes the following features:

• You can step through your code one instruction at a time (in

single-step m o de ) .

• You can step continuously through your code under control of the debugger (in

trace mode) .

• You can execute your code , or any portion of your code, at full speed when timing is critical (in

real-time mode).

• You can insen breakpoints in your code at which the debugger automatically suspends execution.

• You can set a breakpoint so that execution is suspended only after the breakpoint location has been passed through a given number of times.

• You can enter the Monitor, execute Monitor commands, and then return to the debugger.

• You can display the debugger's Master Display, which shows the contents of

Apple IIGS registers, the breakpoints and memory-protection ranges you have set, portions of the stack and memory, and a disassembly of your program's code .

• You can display 368 contiguous bytes of the direct page.

• You can display any 368 contiguous bytes of RAM in any single memory bank.

• You can display your program's normal screen in any Apple IIGS display mode .

• You can call up on-line help screens for belp with any of the debugger's functions.

This manual describes each of the Apple nGS Debugger's displays and commands. First you are told how to stan the debugger and load your program for testing. Next , the debugger's displays are described briefly, followed by an explanation of how to use the debugger. Finally, a reference section describes each of the debugger ' s displays and commands.

Following the description of the debugger, two desk accessories that are included on your debugger disk are described: Loader Dumper and Memory Mangler . Loader Dumper lets you see where in memory the System Loader has loaded each segment of your program and gives you infonnation about the various tables and variables that the loader uses .

Memory Mangler lets you execute a variety of Apple IIGS Memory Manager routines and provid e s lists of the memory blocks that are in use, purged , and disposed by the Memory

Manager .

Once you are familiar with the operaton of the debugger, you can use the summary of debugger commands in the appendix for quick-reference purposes .

APDADraft

8120 1 87

Chapter

1: Overview

Apple IlGS Debugger

Getting Started

This section tells you how to load the debugger and how to load the program to be tested.

It also describes the restrictions on the use of the debugger.

What You Need

The Apple IIGS Debugger is located on its own program disk. The program to be tested can be located on the same disk (if it's small enough to fit) or on another disk. Since the debugger is memory-resident, once it is loaded you can remove the debugger disk and load your program from another disk.

Debugger Restrictions

The Apple IIGS Debugger requires approximately 17900 ($4600) bytes of memory (not including the memory requirements of the program you are testing). Because the debugger is loaded into memory by the Apple IIGS System Loader and Memory Manager, you have no control over where in memory the debugger is loaded. If your program is relocatable, it will be loaded by the System Loader and Memory Manager so that conflicts between the debugger and your program are extremely unlikely.

If you write absolute code, however, you will not be able to use it with the debugger if any of the following conditions occur:

• The application writes to the area of memory in which the debugger is loaded.

• The application write-protects the area of memory in which the debugger is loaded.

For example, if the debugger is in the language card, the application must not writedisable the language cani

• The application

"banks out" the area of memory in which the debugger is loaded. For example, if the debugger is in the $DOOO space of the language card, the application cannot change language-card banks.

• The application assigns its direct page or stack into the debugger's code space.

• The application uses the same stack space as the debugger.

Important:

In single-step and trace modes, if the application writes or steps to a location between 20 bytes before the beginning of the debugger's stack and 8 bytes after the end of the debugger's stack, the debugger stops executing the program and prints s= on the command line. To continue operation, you must change the value of the S register so that it is outside the debugger's stack range. In real-time mode, a stack conflict can cause the debugger to crash.

Loading the Debugger

To load the debugger from APW, type the full pathoame of the debugger, ending in the debugger's filename,

DEBUG, and press Return. If you are using a hard disk, you can place the debugger in the utility subdirectory of APW, replacing the Exec file named

DEBUG that is present in that directory. Then to load the debugger, you can simply type

DEBUG and press Return.

APDADraft

8120187

Apple

Iles

Debugger

Chapter

1 :

Overview

Loading Your Program

When you load the debugger, the debugger's copyright and version number are displayed on the conunand-input line at the bottom of the screen (the command-input line is shown in

Figure 1.1). Type the following command:

LOAD

pathname

Here

pathname

represents the full or partial pathname of the program you wish to debug.

If any ProDOS 16 errors are generated during program load, the ProDOS 16 error number is written to the conunand line. After a successful load, the following registers are set as indicated:

KJPC The program bank register (K) and program counter (PC) are set to the starting address of the fIrst segment of the program.

X , Y

The accumulator is set to the User ID of the program loaded. The User ID is assigned by the User ID Manager, as described in the

Apple

Iles

Toolbox Reference

manual.

The X and Y index registers are set to

The processor status register is set to

The direct-page register is set to the bottom of the direct-page/stack space of the program.

S The stack register is set to the top of the direct-page/stack space .

In addition, ProOOS 16 prefIx 1 is set to the prefIx of the ftle you loaded.

Note: When you load your program, be sure to make a note of the settings of the

K/PC

register and other registers (in the Register subdisplay at the top of the screen) before you do anything else. After you have used the debugger to run your . program, or have reset any registers with debugger conunands, you must know the starting location of your program in memory and starting register values in order to run your program again .

Debugger Display Screens

When you load and start the Apple llGS

Debugger, a display similar to the one shown in

Figure 1.1 appears on the screen . This display, referred to as the

Master Display,

contains a command-input line, plus several subdisplays that contain the following types of information:

• the contents of the 658l6's registers (the Register subdisplay)

• the contents of the stack (the Stack subdisplay)

• a disassembly of your program's object code (the Disassembly subdisplay)

• the contents of a portion of memory (RAM) that you specify (the RAM subdisplay)

APDADraft

3

81 20187

Chaprer 1: OveIView Apple llGS Debugger

• the breakpoints you have set (the Breakpoint subdisplay)

• the memory ranges you have protected (the Memory-Protection subdisplay)

In addition, you have the option of switching to a display of the contents of the direct page, to a display of the contents of any region of memory you choose, to on-line help, or to any of the display screens normally used by your program.

The commands you can use to select a display are described in the next section. Each of the displays and subdisplays is described briefly in the sections that follow and in detail in the reference section at the end of this chapter .

P zc

30 00110000 e

1000-03-01 12/1000: AO 15 18

LOA 1815

12/1103-00-00 12/1003: 90 50 10 STA 1050,X

00/0000-00-00 12/1006: 9F 20 30 05 STA 053020

00/0000-00-00

A9 77 66

LOA 46677

00/0000-00-00

82 20 10

80 20

BRL 2030 (+1020)

BRA 1032 (+20)

00/0000-00-00

F4 12 34

62 FC FF

PEA 3412

PER 1012 (-0004)

00/0000-00-00

1018: 87 45

12/101A: 62 00 FO

STA [45 )

PER 0010

E1/0000.000F

12/1010: A9 23

LOA 123

01/0900.1FFF

12/101F: A2 45 67

LOX 16745

01/6000.

12/1022: 4F 50 4E 02 EOR 024E50

01/0000.0633

12/1026: OC 89 23

00/0000.0000

12/1029: 1C BE F2

00/0000.0000

12/102C: 73 40

00/0000.0000

1)110'>"-(1

JHL (2389)

JSL (F2BE,X)

AOC (40,S) ,Y

Clo1P (06),Y

00/0000.0000-

12/1030: OA

00 23

ASL

BRK 23

Command Line

Figure 1.1.

Master Display

Memory Protection

Selecting Displays

When you start the Apple IIGS Debugger, the Master Display appears on the screen . Use the commands in Table 1.1 to call other displays.

8120187

APDADraft

"._-

Apple lIeS Debugger

Table 1 .

1. Selecting Debugger Displays

Display

Help screen

Memory

Direct-Page

Application

Chapter I,' Overview

How to Select

From any display, type a question mark

(?) and press Return.

From the Master Display, type the starting address of the memory block you wish to display, followed by a colon ( : ), and press

Return.

From the Master Display, type

D and press Return .

To see the display generated by your application, type OFF on the

Master Display command line and press Return, and then start your application as described in the section "Running Your Program" later in this chapter.

To change the display mode, press one of the following keys

(these keypress commands work while in single step or trace modes

only-see the section "Single Step and Trace Modes" in this chapter for more information on these keypress commands) : text page I text page 2

4O-column screen

SO-column screen text mode full-screen graphics mixed text and graphics low-resolution graphics

Hi-Res graphics

Double Hi-Res graphics black-and-white (for Double-Hi-Res graphics)* color (for Double-Hi-Res graphics)*

Super Hi-Res graphics

Monitor

Master Display

*These commands worIc only on a color RGB monitor.

To call the Monitor, type

MON on the Master Display command line and press Return.

Direct-Page or Memory Display, press Esc.

If your application is being displayed, type ON and press Return.

From the Monitor, press Control-Y and press Return to return to the

Master Display.

Note:

If the command filter is in effect, you must hold down one or more keystroke-modifier keys in oreler to pass commands on to the debugger while your program is running. See the section "The Command Filter" later in this chapter for more information on this function.

The Master Display

The Master Display includes information on many aspects of the debugging process .

. When you start the Apple nGS Debugger, a display similar to the one in Figure 1.1 appears. The exact contents of this display depend on the actual contents of memory and on the way in which you have configured the debugger.

APDADrafr

8 1 20 1 87

Chapter 1: Overview

Apple

IIGS

Debugger

In this section, the use of each subdisplay is briefly described. For explanations of all the commands that can be used with a particular subdisplay, see the section about that subdisplay in Chapter 3, "Command Reference."

The Register su bdisplay shows the contents of several 65816 hardware registers. the M and Q pseudoregisters, and some flags and addresses used by the debugger. If you are uncertain about the significance of any of these registers and flags, consult the appropriate section in Chapter 3.

The Stack subdisplay shows the contents of 19 bytes of your program's stack. The default location for the stack pointer is the bottom line in the Stack subdisplay, but you can set it to any line you choose with the

SET command, as described in the section "Configuring the

Master Display" in Chapter 3.

The Disassembly subdisplay shows a disassembly of the machine code in memory using standard APW Assembler mnemonics and address-mode syntax. Disassembly-operand formats are shown in Table 3.1. When you start the debugger, this subdisplay is blank.

You can assemble a single instruction and display it at the bottom of this subdisplay, or you can disassemble any 19 contiguous lines of code and list them in this field. When you enter trace or single-step modes, a running disassembly of your program is shown in the

Disassembly subdisplay, with the current instruction highlighted. You can use the

SET command to change the line that is used for the current instruction.

The RAM subdisplay shows the contents of any 19 memory locations you select. You can display each section as either a single hexadecimal byte with the equivalent ASCII character

(or MouseText character if the high bit is set), as a 2-byte value, or as a 3-byte value.

The Breakpoints subdisplay shows from 0 to 17 breakpoint locations you have set. A

breakpoint is ·a point in your code at which you want the debugger to suspend execution so you can examine the contents of memory and the registers. Each breakpoint includes a

trigger value--that is, the number of times you want the code at that location to be executed before execution is interrupted, and the number of times the program has actually passed through this breakpoint so far. You can increase or decrease the number of lines in the

Breakpoint subdisplay by simultaneously adjusting the number of lines in the Memory

Protection subdisplay.

The Memory Protection subdisplay shows memory-address ranges that you have set either to be executed in real time

(code-trace ranges, indicated by a

T) or to be the only ranges within which code can be executed at all (code-window ranges, indicated by a w).

You can increase or decrease the number of lines in the Memory Protection subdisplay by simultaneously adjusting the number of lines in the Breakpoint subdisplay.

The command-input line (or

command line)is used for executing most debugger commands. The only commands

not

executed from this line are single-keystroke commands used to control code trace, cursor movement commands used to enter data into the Master Display, and the Esc key, used to return to the Master Display from other displays. See the section "Command-Line Commands" in Chapter 3 for a list of the commands available from the Master Display.

APDADraft

8120187

' -

Apple lles

Debugger Chapter 1: Overview

Test-Program Display

To tum off the debugger's Master Display and show the normal screen display of your program, type OFF on the command line and press Return. Although the Apple nos

Debugger uses only the 8<H:olUlIUl text mode, it remembers the last display mode your program was in and switches to that mode when you turn off the Master Display. To change to a different display mode, turn off the Master Display, enter trace or single-step mode, and use one of the display-mode commands listed in the section "Single-Step and

Trace Modes" later in this chapter. To return to the Master Display, type

ON and press

Return.

Note:

If the command filter is in effect, you must hold down one or more keystroke-modifier keys in order to pass commands on to the debugger. See the section 'The Command Filter" later in this chapter for more information on this function.

Memory Display

You can select a display of the contents of any 368 contiguous bytes of RAM in any single memory bank. To get a Memory Display, type the starting address of the memory block, followed by a colon (:), into the command line in the Master Display and press Return. For example, to obtain a display of the contents of the 368 bytes starting at address 1100 in bank 12, type the following (the slash

(I)

is optional):

12/1100:

A sample Memory display is shown in Figure 1.2. Each line begins with the memory address of the fITSt byte shown on that line, followed by the contents of 16 memory locations. The memory contents are shown first as hexadecimal values and then as their equivalent ASCn characters. The character set is displayed as follows:

ASCII Value

$00-$

$20--$7F

$80-$9F

$AO-$FF

Displayed As

. (period) normal video

• (inverse-video period) inverse video

APDADraft

8120187

Chapter i: Overview Apple iiGS Debugger

12/1100: 01 02 03 04 05 06 07 09 09 OA OB OC 00 OE OF 10 ..

...

. . . . . . . . . . .

12/1110: 11 12 13 14 15 16 17 18 19 1A 1B 1C 10 1E 1F 20 . . . . . . . . . . . . . . .

12/1120: 21 22 23 24 25 26 27 28 29 2A 2B 2C 20 2E 2F 30

!"#$ % &'

()*+,-./O

12/1130: 31 32 33 34 35 36 37 38 39 3A 3B 3C 30 3E 3F 40 123456789:; <=> ?@

12/1140: 41 42 43 44 45 46 47 48 49 4A 4B 4C 40 4E 4F 50 ABCOEFGHIJKLMN O P

12 / 1150: 51 52 53 54 55 56 57 58 59 SA 5B 5C 50 5E SF 60 QRSTUVWXYZ[\] ' _ '

12/1160: 61 62 63 64 65 66 67 68 69 6A 6B 6C 60 6E 6F 70

•

12/1170: 71 72 73 74 75 76 77 78 79 7A 7B 7C 70 7E 7F 80

•

• • •

12 / 1180: 81 82 83 84 85 86 87 88 89 8A 8B 8C 80 8E 8F 90

12/1190: 91 92 93 94 95 96 97 98 99 9A 9B 9C 90 9E 9F AO

12/11AO: A1 A2 A3 A4 AS A6 A7 A8 A9 AA AB AC AD AE AF BO

12/11BO: B1 B2 B3 B4 B5 B6 B7 B8 B9 BA BB BC BO BE BF CO

12/11CO: C1 C2 C3 C4 C5 C6 C7 C8 C9 CA CB CC CD CE CF 00

::::',:;)

12/1100: 01 02 03 04 05 06 07 08 09 OA OB OC 00 OE OF EO

12/11EO: E1 E2 E3 E4 E5 E6 E7 E8 E9 EA EB EC EO EE EF FO

12/11FO: F1 F2 F3 F4 F5 F6 F7 F8 F9 FA FB FC FO FE FF 00

1-.

", op

12/1200: 01 02 03 04 05 06 07 08 09 OA OB OC 00 OE OF 10 . . . . . . . . . . . . . . . .

12/1210: 11 12 13 14 15 16 17 19 19 1A 1B 1C 10 1E 1F 20 .

. . . . . . . . . . . . .

12/1220: 21 22 23 24 25 26 27 28 29 2A 2B 2C 20 2E 2F 30

!"#$ % &'

()*+,-./O

12/1230: 31 32 33 34 35 36 37 38 39 3A 3B 3C 30 3E 3F 40 123456789:;<=>?@

12/1240: 41 42 43 44 45 46 47 48 49 4A 4B 4C 40 4E 4F 50 ABCOEFGHIJKLMNOP

12/1250: 51 52 53 54 55 56 57 58 59 SA 5B 5C 50 5E SF 60 QRSTUVWXYZ[\]' .

12/1260: 61 62 63 64 65 66 67 68 69 6A 6B 6C 60 6E 6F 70 abcde£ghijk1mn o p

:12 / 1270:

Figure 1.2. Sample Memory Display

To change the contents of memory, use the commands described in the section "Altering the Contents of Memory" in Chapter 3. To return to the Master Display, press Esc.

Direct-Page Display

You can select the Apple nGS

Debugger's Direct-Page Display by typing

D on the cOlDIDand line and pressing Return. This display shows 368 bytes of the direct page starting with the address in the D register . The Direct-Page Display is identical in appearance and function to the Memory Display that you would obtain for a block of memory starting at the address in the D register.

Help

Screen

To display a help screen showing the commands available at any time, enter a question mark (7). To return from the help screen to the display from which you called it, press any key

except

Esc. To return to the Master Display, press Esc .

APDADraft

8120187

-_ _

Apple !lGS Debugger Chapter

1,'

Overview

Running Your Program

You can step through your program one instruction at a time or continuously, with the

Apple IIOS Debugger intercepting and interpreting each instruction . Executing your program in this fashion gives you maximum control over the process, allowing you to stop at any point and examine the contents of the registers or your program's display . For timing-critical programs and sections of programs, you can also execute the code at full speed. TIlis section explains how to do the following:

• step through your program one instruction at a time (single-step mode)

• step continuously through your program (trace mode)

• execute your program at full speed (real-time mode)

• set and use breakpoints

• set and use memory-protection ranges

Important:

S register so that it is outside the debugger's stack range. In real-time mode, a stack conflict can cause the debugger to crash.

Single-Step

and

Trace Modes

In single-step mode, you can step through your program one instruction at a time. As each instruction is executed, the instruction is highlighted in the Disassembly subdisplay of the

Master Display. In trace mode, the Apple IIGS Debugger automatically steps through each instruction in succession; other than being free-running, trace mode is identical to singlestep mode. Use the following commands from the command line to initiate single-step and trace modes (the command line is still active if you turn the Master Display off to see your program's display):

---

APDADraft

8120187

Chapter 1: Overview

Apple llGS Debugger

Command

addressS

addressT

Action

Enter single-step mode at the current instruction . The current instruction is the next instruction to be executed as indicated by the

KJPC register. The

KJPC register is updated by the debugger each time an instruction is executed in single-step or trace modes, each time a new program is loaded, and each time you execute a K= , PC=, or

K/PC= command. The current instruction appears at the highlighted line of the Disassembly subdisplay; press the Space bar to execute it, or press Return to enter trace mode.

Enter single-step mode at address

address.

The

KJPC register is set to

address

and the instruction at

address

appears at the highlighted line of the Disassembly subdisplay; press the Space bar to execute it, or press Return to enter trace mode.

Enter trace mode at the current instruction (as indicated by the

K/PC register and the highlighted line of the disassembly subdisplay). The debugger begins executing code immediately, and continues to execute instructions until you press

Esc to stop it or until it reaches a breakpoint or a

BRK instruction.

Enter trace mode at address

address.

The

KlPC register is set to

address

and the debugger begins executing code immediately. The debugger continues to execute instructions until you press Esc to stop it, or until it reaches a breakpoint or a

BRK instruction.

Note: When you load your program, be sure to make a note of the values of all the fields in the Register subdisplay before you do anything else. After you have used the debugger to nut your program, or have reset any registers with a debugger command. you must lrnow the starting location and register settings for your program in order to nut it

Once you are in either single-step or trace mode, you can use any of the following keypress commands. The commands that change display modes are intended for use with your program's display. Do not use them when the debugger's Master Display is on the screen .

APDADraft

8120187

' -

Apple IIGS Debugger

Chapter 1: Overview

Command

Esc

Space bar

Return

Action

Tenninate trace or single-step mode and return to the command-line,

Single-step one instruction,

Start continuous tracing.

Trace until the next

RTS, RTI , or

RTL.

This command allows you to trace through one subroutine at a time.

Begin to execute code in real time at the current instruction .

If the current instruction (the next to be executed) is a

JSL , execute in real time until the matching

RTL or until an

RTI that returns to the following instruction. If the next instruction is not a

JS L , this command is ignored .

Skip the next instruction. You can use this command to skip over a

BRK instruction, for example .

Toggle the sound on or off. If the sound is on, the speaker beeps each time an instruction is executed.

Change the display to text page I . Use this command when in 40column text mode or mixed text and graphics mode .

Change the display to text page 2. Use this command when in 40column text mode or mixed text and graphics mode.

Change the display to a 4O-column screen. Use this command when in text mode .

Change the display to a 8O-column screen. Use this command when in text mode.

Change the display to text mode.

Change the display to full-screen graphics mode .

Change the display to mixed text and graphics mode .

Change the display to low-resolution graphics mode.

Change the display to high-resolution graphics mode.

Change the display to double-high-resolution graphics mode .

Change the display to super-high-resolution graphics mode. This is the normal Apple nos display mode .

Change the display to black-and-white double-high resolution graphics mode .

Change the display to color double-high-resolution graphics mode.

Change to the slow trace rate.

--+

Change to the fast trace rate.

Pause the trace until the Apple key is released.

Display a help screen.

Note:

If the conunand filter is in effect, you must hold down one or more

APDADraji

8120 1 87

Chapter i:

Overview Apple

lIeS

Debugger

keystroke-modifier keys in order to pass commands on to the debugger. See the section "The Command Filter" later in this chapter for more information on this function.

Real-Time Mode

In real-time mode, the debugger passes control of the computer to the code that you specify. The code runs at full speed, just as it would if you were running it without the debugger.

Before you tty running your program in real-time mode, read through the rest of the

"Running Your Program" section. As described in the following sections, you can still exercise considerable control over the execution of your program, even if it is running in real-time mode. You can pass keystrokes on to the debugger rather than to your program by specifying a command filter (see the section 'The Command Filter"); you can specify memory ranges outside of which no code is executed (see the section "Memory

Protection"); and you can cause execution to stop automatically at any breakpoints you specify (see the section "Breakpoints") . You can run your entire program in real-time mode, or you can specify that the code in certain memory ranges is to be run in real-time mode while the rest of the program is run in trace or single-step mode.

Use the following commands from the command line to initiate real-time mode:

Command Action

addressx addressJ

JSL directly to code at address

address.

If you omit

address,

the current

K/PC address is used. (Note that if you omit

address,

you must use an uppercase

X for this command.) This command assumes your routine ends in an

RTL: the code is executed in real-time mode and when the

RTL is executed control returns to the debugger. The debugger automatically turns off the Master Display before executing this command.

JML directly to code at address

address.

If you omit

address,

then the current

K/PC address is used. This command executes an unconditional jump to

address

and the code at that address is executed in real-time mode. Control does not return to the debugger unless you have set a real breakpoint or a nonbreakpoint

BRK is executed (while breakpoints are set to

DBRK).

See the section "Breakpoints" in this chapter for information on the use of breakpoints . The debugger automatically turns off the Master Display before executing this command.

The Command Filter

The Apple IIGS Debugger normally intercepts all keystrokes and passes them to the debugger's command interpreter.

If the keyboard, you can set the debugger to pass all keystokes on to the application unless one or more keystroke-modifier keys are also pressed. To select the key or keys to be used as the keystroke modifier, use the KE

Y command as described in the section "Register

Subdisplay" in Chapter 3.

APDADraft

8120 18 7

-'"

Apple IIGS Debugger

Chapter 1: Overview

Keystroke modifiers prevent debugger commands from interfering with your program .

For example, suppose your program has menu options that are activated by key presses, and that Q causes the program to quit You can set the keystroke modifier so that commands are passed to the debugger only when you hold down the Option key. Then to toggle sound on or off without causing your test program to quit, you would press

Option-Q.

Remember that when you have set a keystroke modifier, you must use that key or key combination in order to send any command to the debugger while in trace or single-step mode . For example, to quit trace mode when Option is set as the keystroke modifier, press

Option-Esc; to single-step one instruction, press Option-Space bar.

Memory Protection

The Apple

DGS

Debugger allows you to specify address ranges within which code is executed at full speed (code-trace ranges) and to specify ranges outside which no code is executed (code-window ranges). Instructions for setting these ranges are given in the section "Memory-Protection Subdisplay" in Chapter 3.

All code outside a code-trace range (indicated by a

T on the Memory-Protection subdisplay) is executed in single-step or trace mode . When your code executes a

JSL to this memoryprotection address range, the code inside this range is executed in real time. When the matching

RTL is encountered, execution returns to single-step or trace mode .

Use code-trace ranges to specify subroutines that must be executed at full speed, such as disk I/O routines. Note that interpreted breakpoints do not function inside code-trace ranges; you must insert real breakpoints to stop execution within a code-trace range. When you start the debugger, a code-trace range is automatically set for the range El/()()()() through El/OOOF so that Apple

DGS tool calls are run at full speed.

If one or more code-window address ranges (indicated by w's on the Memory-Protection subdisplay) are specified, then code is executed only if it is inside one of the code-window ranges. Any time the program counter (K/PC) equals an address not in any of the codewindow address ranges, execution stops.

(If you don't specify any code-window address ranges, code can be executed at any address.)

When one or more code-window address ranges are set, execution is in trace or single-step mode unless a

JSL is made to a code-trace address range that is completely contained in a code-window address range. Once such a

JSL is made, execution is in real time until the matching

RTL is encountered.

You can use code-window ranges to protect code outside the normal code for your program from being executed. Thus, for example, if a bug in your code is causing the system to crash by executing code in the wrong location in memory, you can restrict execution to protect that area of memory by making sure it lies outside any code-window ranges. Then, when your program jumps to that area of memory, execution stops and you can attempt to find the location and nature of the bug.

APDADraft

13

8120187

Chapter

1: Overview

Apple IIGS Debugger

Breakpoints

breakpoint

is an instruction at which execution is suspended. The Apple IIGS Debugger allows you to set up to 17 memory addresses as breakpoints. Breakpoints can be either

real

interpreted.

A real breakpoint is a

BRK instruction that the debugger has insened in the code.

An interpreted breakpoint is a memory address at which the debugger suspends execution in trace mode. When interpreted breakpoints are set, the debugger compares the address of the instruction about to be executed (that is, the program counter) to the breakpoint addresses before executing each instruction .

Instructions for setting breakpoints are given in the section "Breakpoint Subdisplay" in

Chapter 3. In order for breakpoints to work when the debugger is running in real-time mode, you must insert real breakpoints into the code. To set real breakpoints, set the breakpoint addresses as described in the section on the Breakpoint subdisplay, press Esc to return to the command line, and then type

IN and press Return. The letter i is displayed under

BRK in the upper left comer of the Master Display to indicate that real breakpoints are in. To remove real breakpoints, type

OUT on the command line and press Return . The letter

0 is displayed under

BRK in the upper left comer of the Master Display to indicate that real breakpoints are out. Real breakpoints must be removed before you can set, change, or delete breakpoints.

For each breakpoint, you must set a

trigger value.

The trigger value specifies the number of times that the instruction at the breakpoint address must be encountered before the debugger suspends execution. For example, if you set the trigger value for a breakpoint to

2, the debugger executes that instruction the first time it is encountered but suspends execution, rather than executing the instruction, the second time it is arrived at. To disable a breakpoint without removing the breakpoint address, set the trigger value to 0; breakpoints with trigger values of 0 are ignored by the debugger.

In trace mode, execution stops when the trigger value is reached for both real and interpreted breakpoints. In real-time mode, execution stops when the trigger value is reached for real breakpoints only. In single-step mode, the computer beeps when the trigger value is reached.

In trace and single-step modes, execution stops any time a

BRK instruction is encountered that is

1IOt

set as a breakpoint. In real-time mode, you can select whether a nonbreakpoint

BRK causes a return to the debugger or an exit to the Monitor. To have nonbreakpoint

BRK instructions return you to the debugger, type

DBRK on the command line and press Return.

A d appears nextto the i or

0 in the upperleft comer of the Master Display. To have nonbreakpoint

BRK instructions cause an exit to the Monitor, type

UBRK on the command line and press Return. A u appears in the upper left comer of the Master Display. The default mode is

DBRK: you are returned to the debugger when a nonbreakpoint

BRK is encountered during real-time execution.

When a breakpoint is triggered, execution stops and you can check the contents of the registers and memory locations shown in the Master Display or Memory Display. To resume execution in trace mode, type

T on the command line and press Return. When an interpreted breakpoint is triggered in single-step mode, the computer beeps. Continue pressing the Space bar to continue stepping through the code. When a

BRK instruction that you did not set as a breakpoint is encountered in trace or single-step modes, execution stops, the computer beeps, and the Register subdisplay contains information about the state

APDADraft

8120187

' -

Apple IIGS Debugger

Chapter

1 :

Overview

of the machine when the break occwred. Use the

ON command to see the Master Display, if necessary .

To clear all breakpoints (when real breakpoints are out), type

CL R on the command line and press Return .

Printing

You can print any debugger text screen, including help screens and your program ' s display, by typing

P on the command line and pressing Return. You cannot use the

P command to print graphics screens .

To set the slot to which the debugger assumes the printer is connected , use the

SET command as described in the section " Configuring the Master Display" in Chapter 3.

Although the debugger is launched by the Apple

IIGS

Programmer's Workshop, it is not an

APW utility program. Therefore, the printer initialization string and other printer variables you set in APW are not active when you are in the debugger. If you use the Apple

IIGS computer's built-in printer port, you can use the Control Panel to set printer communication options.

Using Monitor Routines

The Apple

IIGS

Monitor consists of a set of ROM-based routines that you can use to perfonn many functions not otherwise available from the debugger. The Monitor provides the following features:

• You can examine the contents of any locations in memory , including ROM routines .

• You can change the contents of any locations in RAM.

• You can copy a block of data from one location in memory into another and verify that the contents of the two blocks of memory are identical.

• You can clear a range of memory .

• You can search for one or more bytes within a I1IIIge of memory addresses.

• You can examine and change the contents of Apple

IIGS regi s ters .

• You can convert hexadecimal numbers to decimal and vice versa.

• You can perfonn hexadecimal addition and subtraction .

• You can run a machine-language program that is in memory.

• You can enter machine-language programs directly from the keyboard, using standard

65816 mnemonics (this Monitor routine is called the Mini-Assembler).

• You can disassemble a I1IIIge of addresses.

• You can start Applesoft BASIC.

• You can change the screen display .

• You can change the cursor symbol.

• You can redirect input and output links.

APDADraft

8120 1 87

Chapter

Overview Apple llGS Debugger

• You can call Apple IIGS tool sets.

• You can set and display the system clock time and date.

To enter the Apple IIGS Monitor, type

MON on the debugger's command line and press

Return. To return from the Monitor to the debugger, press Control-Y and then press

Return. The Apple llGS Monitor is described in detail in the

Apple llGS Firmware

Reference

manual.

APDADraft

8 1 20187

Apple IIeS Debugger

Chapter

Using the Debugger

Chapter 2 Using the Debugger

The Apple

IIGS

Debugger allows you to load your program into memory and to run through it under the debugger's control. As the program executes, you can examine the contents of the 65816's registers, of your program's direct page and stack, and of any locations in memory in which you are interested You can interact with the program as required, returning to the debugger's display at breakpoints that you set or when the program crashes.

The Apple

IIGS

Debugger can display an assembly-language disassembly of your program's machine code. It cannot execute your source code or recreate your source code from machine code. Therefore, the debugger is easiest to use with assembly-language programs. However, even if your program was written in a higher level language and you have no knowledge of assembly language, you can use the debugger to detennine in which load segment the problem lies. You can also gain a better understanding of the operation of your program by examining the contents of the stack, direct page, memory, and registers.

We do not have the space here to examine in detail all of the abilities of the Apple

IIGS

Debugger, but we will give you some hints that should help get you started debugging your program.

Debugging Segmented Programs

In order to use the Apple

IIGS

Debugger to debug a segmented program, you must know wbere in memory each segment has been loaded.

In the case of dynamic segments, you must know not only where the segment has been loaded, but whether it has been loaded.

This infonnation is available through a deslc accessory provided with the Apple

IIGS

Debugger called Loader Dumper.

To load your program using the debugger and to determine where in memory each segment is loaded, use the following procedure:

1. From the APW command line, type

DEBUG and press Return to call the debugger.

The debugger Master Display will appear on the screen.

2. Type

LOAD

pathname, where pathname is the pathname of the program you want to debug, and press Return. Your program is now loaded into memory.

3. Press Apple-Contol-Esc to get the Desk Accessories menu.

4. Select

Loader Dumper from the Desk Accessories menu. The Loader Dumper main menu will appear on the screen.

5. Select

Dump Pathname Table from the Loader Dumper main menu. The pathname table provides a cross-reference of pathnames and User IDs.

APDADraft

8120187

Chapter

2 :

Using the Debugger

Apple

TICS

Debugger

6. Scroll through the pathnarne table (by pressing Return for each pathname) until you find the pathnarne of the program you are testing . Make a note of the User ID ofthe program.

7. Press Esc to get back to the Loader Dumper main menu.

8. Select

Get UserID Information from the main menu.

9. Type in the User ID of your program in response to the prompt that appears on the screen.

10. A listing of all the load segments in your program appears on the screen. Write down the memory locations of all the segments.

11. Press Esc to return to the main menu, press Esc again to quit Loader Dumper , and then select Qu i t from the Desk Accessories menu to return to tlte debugger.

You now have several possible courses of action open to you. If you do not have any idea in which load segment your program is crashing, you can start by running the program until it crashes and then examining the debugger display to determine the location of the problem instruction. If you know in which segment the problem lies, you can go immediately to that segment, or you can set a breakpoint at the beginning of that segment and run the program until it stops automatically at that breakpoint.

Watching a Running Disassembly

If your program does not require any input from the keyboard, you can watch a disassembly on the debugger screen as the program executes to fmd the exact location at which it goes astray . This techniquewill probably be useful only for short programs or programs that crash almost immediately upon execution, because the program will execute very slowly while the debugger display is on the screen .

To run your program under control of the Apple nOS

Debugger, with a running disassembly appearing on the screen, use the following procedure:

1. If you have not already done so, load your program as described above. Write down the information in the Register subdisplay of the debugger so that you can return the IDlIChine to its initial state each time you run your program.

2. Type s and press Return. The debugger is now in single-step mode, starting with the first instruction of your program. Each time you press the Space bar, the instruction highlighted in the Disassembly subdisplay is executed. To return to the debugger's command line, press Esc. WalCh the contents of the registers and the stack as you execute commands. If any specific memory locations are critical to the execution of the program, you can display those locations in the RAM subdisplay of the Master Display.

To execute commands automatically in quick succession (that is, to enter trace mode), press Return. To start trace mode from the debugger's command line , type

T and press Return. Your program will begin executing under debugger control , one instruction at a time in rapid succession. The speaker beeps each time an instruction is executed You can turn off the speaker by pressing Q. You can stop execution at any time by pressing Esc.

3. When your program executes a

BRK instruction, the disassembly stops scrolling.

The last execution executed (the

BRK instruction) is highlighted. The last several

APDADraft

8120187

Apple lIes

Debugger

Chapter

Using the Debugger

instructions executed appear above the current instruction. A BRK instruction is actually a null (a zero byte). Since a

BRK instruction is not a nonnal part of a program, the fact that your program executed one means that some previous instruction (contrary to your intent when you wrote the program) sent the program off to the wrong place in memory. With luck, the instruction that sent your program off into Never Never land will still be on the screen.

If the errant instruction is no longer on the screen, set a code-window range as described in the section "Using Memory-Protection Ranges"later in this chapter and run the program again.

Important: Remember to restore all the fields in the debugger's Register subdisplay to their original values before attempting to rerun the program. If you do not, the program will probably not run correctly through no fault of its own .

Using Breakpoints

If you have to interact with your program in order for it to run, if you have some idea of which segment contains the bug, or if you just want to execute the program more quick:iy, you can set one or more

breakpoints

before running the program . A breakpoint is a location at which the debugger suspends execution of the program, giving you the opportunity to examine the disassembly and the state of the machine at that location.

To set breakpoints and run the program under debugger control, use the following procedure:

I. If you have not already done so, load your program as described above. Write down the information in the Register subdisplay of the debugger so that you can return the machine to its initial state each time you run your program.

2. As described above, use the Loader Dumper routine to determine the starting locations of the load segments of your program .

3. Back in the debugger, type

BP and press Return in order to specify breakpoints.

Following the instructions in the section "Breakpoint Subdisplay" in Chapter 3, set breakpoints at the beginning of each load segment

(if you do not know in which segment the bug lies) or at the beginning of any segment that you want to examine more closely.

If you must interact with the program in order for it to run, set a keystroke modifier that will not interfere with your program (The keystroke modifier is a key that you must press simultaneously with any key that you want the debugger to interpret as a debugger command. For example, if you set the Option key as the keystroke modifier, you must press Option-Esc to terminate trace mode. If you do not press the keystroke-modifier key, the debugger ignores the keypress and your program is free to act on it)

5. Type OFF and press Return. The debugger display will be cleared so you can see the normal display of your program. Trace mode also runs more quick:iy with the debugger's display turned off.

6. Type

T and press Return . Your program will begin executing under debugger control, one instruction at a time in rapid succession. The speaker beeps each time an instruction is executed. You can turn off the speaker by pressing Q (remember also to press the keystroke-modifier key that you have set, if any) . Interact with

APDADraft

19

8120187

Chapter

2: Using the Debugger

Apple IIGS Debugger

your program as you normally do (it will run more slowly than normal). You can stop execution at any time by pressing Esc (remember the keystroke modifier!).

7. When the debugger comes to a breakpoint, the debugger's Master Display appears on the screen. The number shown under

K/PC in the Register subdisplay indicates the location of the instruction at which the program stopped. To see a disassembly of the program starting at the breakpoint location, type the

K/PC address followed by an L (for example, Ol0240L) and press Return.

8. If you are narrowing in on the bug, you might want to use single-step mode with the debugger's Master Display on the screen. To step through the segment one instruction at a time, type s and press Return. Now each time you press the Space bar (remember the keystoke modifier), one instruction is executed You can watch the contents of the stack and the machine's registers as each instruction executes.

You can also display the contents of up to 19 memory locations, which you can watch as the program executes.

9. To return to executing the program automatically, press Esc to exit single-step mode, and then type

OFF and

T as before. Each time the debugger gets to a breakpoint, it will return you to the Master Display.

If at any time during execution of the program a dynamic segment is loaded, you can pause execution of your program and go back to Loader Dumper to find out where in memory it has been placed.

Breakpoints can be used for other purposes than finding a particular segment. Suppose, for example, that your program seems to run alright for awhile, then crashes after having lulled you into a false expectation of success. In this case, it is possible that some routine is failing, not the first time it is run, but only after going through several iterations. To handle such a situation without stopping the program every time the routine is executed, you can include a trigger value for a breakpoint. The debugger counts the number of times it encounters the breakpoint and suspends execution only when the trigger value is reached.

If you must execute a routine a full speed in order for it to work correctly, you can insert

real breakpoints

into the code. When you do so, the debugger actually inserts

BRK instructions into memory at the breakpoint locations. Trigger values work for real breakpoints that you have set; the debugger will still suspend execution any time it encounters a

BRK instruction that you did not set as a breakpoint.

Using Memory-Protection Ranges

It may be that certain portions of your code must be executed at the full speed of the 65816 microprocessor. To cause this to happen automatically every time you trace through the program, you can set any areas of memory you choose as code-trace ranges. When the program executes a jump to a location within a code-trace range, the debugger relinquishes control to your program and the code is executed at full speed.

The portion of memory used to run tool calls is automatically set as a code-trace range when you load the debugger.

You can also set one or more portions of memory (the limits of your code as revealed by

Loader Dumper, perhaps) as code-window ranges. If the program attempts to execute code outside the code-window ranges you have set, execution stops. You might want to set a code-window range, for example, if your program is executing a jump to execution at some

APDADraft

8120187

Apple IIGS Debugger Chapter

Using the Debugger

incorrect memory location and trashing memory before it stops, so that you have to reboot the machine every tittle you try to run the program with the debugger .

If your program loads a dynamic segment during execution and you want to pause as soon as control is transferred to the dynamic segment, you can set code window ranges to include all the static segments at the start of the program . Then when the dynamic segment is loaded and control is transferred to it, the program will be outside any code window range and execution will stop .

Important:

Once you have set any code window range , no code will be executed that is not in a code window range. Therefore, if you set a code window range equal to the memory location of one of your program segments , you must set code window ranges for all other segments that you want to run . Remember also to set the portion of memory used to run tool calls (E I/OOOO-E llOOOF) to a code window range if your program makes any tool calls.

Debugging Multilanguage Programs

One of the advantages of using the APW development environment is that it allows you to link together routines written in different programming languages . This facility can lead to unique problems, however, especially when information is passed between routines written in different languages.

To use the Apple IIGS Debugger to debug parameter-passing problems, use the following procedure:

I. Set breakpoints at the beginning of the calling segment and at the beginning of the called segment.

2. Run the program in trace or real-time mode until the first breakpoint is reached .

Search this segment to find the JSL that calls the other segment.

If you do not need to interact with the program, the easiest way to do this is to run in trace mode with the Master Display on the screen until the second breakpoint is reached . Then both the JSL and the fIrst instruction of the called segment will be on the screen .

If you cannot do that, try listing a disassembly (using the addressL command) until you see the appropriate JSL.

3. Set a breakpoint just before the JSL that calls the second segment. You can remove the other two breakpoints now if you wish.

4 . Run the program until the JSL breakpoint is reached . Parameters are normally passed either on the stack or in the A, X, and Y registers. The actual information passed may be a pointer to the data rather than the data itself. By examining the contents of the registers, the stack, and memory, determine where the parameter is that is being passed and that it has the value you expect.

5 . Execute the JS

The return address should have been added to the stack .

6. Step through the segment in single step-mode . Is the called routine reading the parameter passed to it?

If more than one parameter was passed, are the parameters being read in the correct order? Is an integer being handled as floating point , or is an

ASCII string being handled as a number? Is a number being truncated or rounded inappropriately? By a careful study of the action of the called routine, you should be able to determine the source of the problem.

APDADraft

21

8/20/87

Chapter

2 :

Using the Debugger AppLe lies

Debugger

If all parameters are being passed correctly. perhaps the problem occurs when the results are passed back to the calling routine. To fmd the

RTL. return to the

JSL and start single-step mode. Then press the R key; the debugger will enter trace mode and automatically stop when the next

RTL is reached. You might have to do this several times until you reach the right

R TL.

Study the stack and registers as before to determine whether the results are being passed correctly back to the calling routine.

APDADraft

8/20/87

Apple llGS Debugger

Chapter

Command Reference

Chapter 3 Command Reference

In this chapter, each of the subdisplays of the Master Display is described in detail. This chapter includes commands for customizing the Master Display and for setting memory addresses, memory-protection ranges, and breakpoints. It describes the use of the

Disassembly subdisplay, as well as of all the commands that you can enter on the command-input line.

Register Subdisplay

The Register subdisplay, along the top of the Master Display, shows the contents of the

Apple lIas

Debugger's registers and the 65816's registers.

Debugger Registers

The Apple lIas

Debugger's registers are displayed toward the left end of the Register subdisplay as follows:

Key:

keystroke modifier. This hexadecimal number indicates the key or key combination that you can use as a command filter to prevent debugger commands from interfering with your test program when your program is running in trace or single-step modes. To select the key or keys to be used as the keystroke modifier, use the following command:

KEY=keynum

Each bit of the binary number represented by the hexadecimal number

keynum

specifies one of the keys to be used as a keystroke modifier; set that bit to 1 to make that key part of the keystroke modifier. The bits are assigned as follows:

APDADraft

8120187

Chapter

Command Reference

Apple IIGS Debugger

Bit:

Key: A 0

2 1 0

K R a.

Hex Value :

..:[) 2)

04 02 01

The abbreviations in this diagram refer to the following keys:

Abbreviation Key

C

Shift

Control

Caps Lock

K repeat: hold the key down until it repeats o

A any key on an external keypad (not the keypad on the Apple lIas keyboard)

Option

For example, to set both the Shift and Caps Lock keys as keystroke modifiers, use the following command:

KEY=05

The KEY value in the register subdisplay changes to 05 to indicate the key combination that is set as the keystroke modifier (01 for the Shift key plus 04 for the Caps Lock key).

Now, when you want to send a command to the debugger while in trace or single-step modes, press both the Shift and Caps Lock keys while pressing the key that invokes the command. For example, to switch to the slow trace rate, press the following key combination:

Shift-Caps Lock+-.

BlUt: breakpoint flags. The first flag reads i

(for

in)

if you have used the debugger to set real breakpoints in

the

program.

If you have transparent breakpoints set, this flag reads

(for

out).

The second flag reads d (for

debugger)

if BRK instructions (other than those that you have inserted with

the

debugger) return you to the debugger. If such

BRKS cause an exit to the Monitor, this flag reads u (for

user).

DebugD: debugger's direct page. This value indicates the starting location of the debugger's lK byte direct-page/stack segment in bank $00. For example, if the

Debugger's direct page begins at 0011000, then DebugD reads 1000.

65816 Registers

The 65816's registers are displayed as follows:

K/PC: program bank register (K) and program counter (PC). The program bank register serves as the upper 8 bits of the 24-bit address of the next instruction to be executed; the program counter holds the lower 16 bits of the address of the next instruction. There is no carry from the high bit of the PC into the low bit of the K register when the PC is

APDADroft

8/20/87

---.

Apple IIGS Debugger

Chapter

Command Reference

incremented. When you specify an address in a debugger command and do not specify the bank number. the current value of the K register is used.

B: data-bank register. This value provides the upper 8 bits of the address in addressing modes that generate only the lower 16 bits.

D: direct page register. This value determines the location of the direct page in bank $00.

For example. if the direct page begins at 00/1234. then Dreads

1234. s: stack pointer. This register indicates the next available location on the stack. If the emulation-mode flag e == 1. S must be between $0100 and $OIFF.

A: accumulator: This register stores flrst one operand and then the result for most arithmetic and logical operations. This register is 2 bytes wide if the emulation-mode flag e

0 and the memory/accumlator-mode flag m

== 0; otherwise. it is considered to be 1 byte wide (though the high byte can still be accessed through an

XBA instruction). x:

X register. This register is used to provide index values for address calculations. and it holds operands for some arithmetic and logical operations. This register is 2 bytes wide if e == 0 and the index-register-mode flag

x

== 0; otherwise. it is considered to be 1 byte wide

(the high byte is forced to 0).

Y register. This register is used to provide index values for address calculations. and it holds operands for some arithmetic and logical operations. This register is 2 bytes wide if e

0 and x

== 0; otherwise. it is considered to be 1 byte wide (the high byte is forced to 0).

M: machine-state register. This pseudoregister.located at $C068 (in any of banks $00.

$01. $EO. or $El). can be used to set a variety of Mega II-chip soft switches. The M register is described in detail in the

Apple IIGS Hardware Reference

manual. The bits that comprise this hexadecimal number indicate the status of the following machine states:

Bit

Name o

SlotCxROM

1 ROMBANK

Meaning

If this bit is 1. internal ROM at $CxOO is active; if O. external ROM

(that is. ROM on the circuit board at $CxOO) is active.

This bit is reserved; it must equal O.

Warning: Setting ROMBANK to

1 will almost certainly cause the system to crash .

2 BANK2

If this bit is O. bank I language-card RAM (at $0000 through

$DFFF) is selected; if 1. bank. 2 is selected. Switching banks with this bit does not write-enable language-card RAM. Use the

L flag to both write-enable RAM and switch language-card banks.

3 RDROM

4 RAMWRT

5 RAMRD

6

PAGE2

If this bit is 1. language-card ROM is read-enabled; if

O. languagecard

RAM is read-enabled.

If this bit is O. main-memory RAM is write-enabled; if

1. auxiliarymemory RAM is write-enabled.

If this bit is O. ' main-memory RAM is read-enabled; if 1. auxiliarymemory RAM is read-enabled.

If this bit is O. text page 1 is selected; if 1. text page 2 is selected.

APDADraft

25

8120187

Chapter

3 :

Command Reference Apple IIGS Debugger

7 ALlZP

If this bit is 0, bank-switched memory, stack, and zero page are in main memory; if 1, they are in auxiliary memory.

Q: "quagmire" register . This pseudoregister is composed of the lower 7 bits of the shadow register at $C035, and the high bit of the configuration register at $C036. The bits of this hexadecimal number set the following states: o text page 1 1

= shadowing off

I Hi-Res graphics page 1 I

= shadowing off

2 Hi-Res graphics page 2

3. Super Hi-Res graphics

= shadowing off

4.

auxiliary-memory Hi-Res graphics 1

= shadowing off

5. reserved

6. IOLC (I/O and language card)

7 . high-speed operation must be 0

= shadowing off

= high speed on

Shadowing is described in the

Technical Introduction to the Apple JIGS

manual and the

Apple JIGS Hardware Reference

manual.

L: language-card bank register. This flag emulates the Monitor

value=L

command. Set L

0 to write-enable language-card RAM and select bank I. Set L

1 to write-enable language-card RAM and select bank 2. Changing L automatically changes bit 2 of the M register.

P: processor status register. This register contains status flags and mode-select bits. The individual bits are shown at the right end of the Register subdisplay, as follows:

APDADraft

8120187

Apple

lles

Debugger Chapter

3: CoT1ll7lilllli Reference

i z c e

r1ag Name

n negative-result flag v overflow flag m

1 x b d

Meaning

disabled.

If z

I, the result was zero . carry flag emulation-mode flag

If c

I, a carry occurred.

= I,

6502

emulation mode is selected.

Altering the Contents of Registers

To alter the contents of the registers displayed in the Master Display, type one of tbe following commands on the command line and press Return (note that tbese commands are case sensitive):

APDADraft

8120187

Chapter

CommandRejerence

Apple IIGS Debugger

Command Action

e x rn

Toggle the e flag: if this flag is set to I, change it to 0; if it's set to 0, change it to 1.

Toggle the x flag: if this flag is set to I, change it to 0; if it's set to 0, change it to 1. This command works only if e = O.

Toggle the m flag: if this flag is set to I, change it to 0; if it's set to 0, change it to 1. This command works only if e

register=value

Set the register specified by

register

to the value specified by

value.

The values for all registers are given as hexadecimal numbers, except for the processor status bits, which can be either I or O. Register names are case sensitive.

For example, to set the X index register to

$12EO, use the following command:

X=12EO

Note: The lengths of the X, Y, and A registers depend on the settings of the e, x, and m processor bits, as discussed in the register descriptions in the preceding section, "65816 Registers."

Stack Subdisplay

The Stack subdisplay, along the left side of the Master Display, shows the contents of a portion of the 65816's stack.

This subdisplay shows the addresses and contents of the memory locations just before and just afta" the location pointed to by the stack pointer. The current location of the stack pointer is shown in the Register subdisplay (see the earlier section, "Register Subdisplay'') and is highlighted in the Stack subdisplay. You can change the position of the current stack location within this subdisplay by using the

SET conunand. See the section "Configuring the Master

Display" later in this chapter for a discussion of the

SET command .

See the section "RAM Subdisplay" later in this chapter for a discussion of commands you can use to change values in memory.

APDADraj't

28

8120187

"

Apple IIGS Debugger

Disassembly Subdisplay

Chapter

CommandReference

ITA IOSO,I:

, IF 20 3D OJ .TA

onolo

AI ,., 51 LDA fU11

.1lIo

IUlO (.1OlOI

.D lon IUOI

'1oA J4l1 na lOU '·0004) nil. lUI

Ul 0010

LOa. tal

LOll: U'JU

4r )0 f.I 02 loa OUEIO

, ~

I t 22 ,JIlL (2l1',

JIL (rlll,J:)

&DC

,.O.'I,Y au (On.Y

. n

The Disassembly subdisplay, along the right side of the Master Display, shows a disassembly of your program's object code using standard APW 65816 assembly mnemonics and address-mode syntax. As shown in

Figure 3.1, each line of this subdisplay is composed of three parts: the address, the bytes stored starting at that address, and the disassembled version of those bytes.

12/1000:

15 18

12/1003: 9D 50 10

LDA 1815

STA 1050,X

12/1006: 9F

20 30 05 STA 053020

12/100A: A9 77 66 LDA

16677

12/100D:

82 20 10

12/1010: 80 20

12/1012: F4 12 34

BRL 2030 (+1020 )

BRA 1032 (+20 )

PEA 3412

12/1015: 62 FC FF

12/1018: 87 45

12/101A: 62 00

12/101D: A9 23

PER 1012 (-0004)

STA [ 45]

PER 001D

12/101F: A2 45 67

LDA t23

LDX

16745

12/1022: 4F 50 4E 02 EOR 024E50

12/1026:

89 23

12/1029: 7C BE F2

JML (2389)

JSL (F2BE, X)

12/1031: 00 23

BRK 23

Figure

3.1.

Disassembly Subdisplay

For example, look at the first line of the Disassembly subdisplay in Figure 3.1. The first part of the line, the address, is composed of the high-order byte ($12) that specifies the memory bank, followed by the 2-byte ($1000) location within that bank of the first byte in the instruction. The next 1 to 4 bytes

(AD

15 18 in this example) show the contents of memory starting at that location, corresponding to the instruction that the Apple IIOS

Debugger interpreted to stan at that location. The last part of the line

(LDA

1815) shows the 65816 opcode and operand. Operand address formats, summarized in Table 3.1, are the same as those used by the Apple IIos Monitor

Mini-

Assembler and described in the

Apple IIGS Firmware Reference manual. All numbers are hexadecimal.

APDADraft

8120187

Chapter

Command Reference

Apple lIGS Debugger

Table 3.1. Disassembly Operand Formats

Addressing Mode Example Operand

Absolute

Absolute indexed with

Absolute indexed with Y

Absolute indexed indirect

Absolute indexed long

Absolute indirect

Absolute long

Accumulator

Block move

Direct page

Direct page indexed with

Direct page indexed with Y

Direct page indexed indirect with X

Direct page indirect

Direct page indirect indexed with Y

Direct page indirect indexed long

Direct page indirect long

Immediate

Implied

Program counter relative

Program counter relative long

Stack

Stack: relative

Stack relative indirect indexed with Y

1234

1234,X

1234,Y

(1234,X)

081234,X

(1234 )

081234

5678

12,X

12, Y

(12, X)

(12 )

(12) ,

[12) ,

[ 12)

H2 or 111234

1000 {+l2)

1000 {-1234}

10,S

(10,S),Y

You can change the position of the clUTent instruction within the subdisplay by using the

SET command. See the section "Configuring the

Master Display" later in this chapter for a discussion of the

SET command.

Note: The Apple IIGS Debugger disassembler interprets all bytes in memory as

65816 instructions; it cannot distinguish between code and data. Strings of data therefore appear as nonsense instructions in the Disassembly subdisplay.

When you start the debugger, the Disassembly subdisplay is blank. The debugger enters values into this subdisplay in response to any of the following command-line commands.

Whenever you enter an address, you can include the slash after the bank or not, as you wish. If you do not include a bank number, the current value of the K register is used for the bank.

APDADraft

30

8120187

Apple

lIeS

Debugger

Chapter

Command Reference

Command

addressL

addressT addressS

Action

The contents of memory staning at

address

are disassembled, and the next 19 lines of that disassembly are displayed .

The next 19 lines of the disassembly are displayed, starting at the current

K/PC

address. If you have executed no previous disassembly commands, the disassembly starts at the staning address of the first segment of your program.

Enter trace mode at address

address.

If you omit

address,

the current

K/PC

address is used. As the Apple IIos Debugger traces the code, it disassembles it and lists the results in the

Disassembly subdisplay. The currently executing instruction is highlighted. Trace mode is described in the section "Single-Step and Trace Modes" in Chapter l.

Enter single-step mode at address

address.

If omit

address,

the current

K/PC

address is used. As the Apple steps through the code, lIas

Debugger it disassembles it and lists the results in the Disassembly subdisplay. The currently executing instruction is highlighted. Single-step mode is described in the section

"Running Your

Program"

in this chapter .

ASM

Clear the Disassembly subdisplay to prepare for entering a sequence of instructions using the

address:instruction

command.

address:instruction

This command causes the debugger to assemble the instruction

instruction

and place the opcode and operand in memory at address~

Simultaneously, the instruction is placed on the last line of the Disassembly subdisplay. Use the

ASM command before using this command.

Space bar

instruction

See the section" Altering the Contents of Memory" in this chapter for more information on this command and a discussion of other commands to change values in memory.

Once you have used the

address

instruction

command, pressing the Space bar causes the next available address to be printed on the command line. Type in the next instruction to be assembled and press Return.

The Disassembly subdisplay shows the instructions following the current instruction in memory.

If the current instruction jumps to or calls another routine, however, the address called or jumped to appears as the current instruction after the call or jump is executed. For example, assume the Disassembly subdisplay is as follows:

12 / 10 2 E:C1 06

CMP (06), Y

12/1037:AD 18

LDA (1815)

APDADraft

8120187

Chapter

Command Reference Apple IIGS Debugger

When the

JML instruction is executed, the current instruction becomes the one jumped to, and the display changes accordingly. It might look like this:

12/1030:0A

ASL

77 66 LOA i6677

RAM Subdisplay

The RAM subdisplay, located to the right of the

Stack subdisplay, shows the contents of any 19 memory locations you select As illustrated in Figure 3.2, each location can show either a single hexadecimal byte value and the equivalent ASCII character, a 2-byte value, or a 3-byte value. The 2- and 3-byte values are displayed as addresses; that is, the low byte

(the one corresponding to the address in the left column) is displayed at the right. For example, if you place the value lA in location 01/0100, IB in 0110101, and lC in 01/0102, and display a 3-byte value at 0110100, then the line of the RAM subdisplay looks like this:

01/0100: 1C1B1A

APDADraft

8120187

Apple JIGS Debugger Chapter

3:

Command Reference

00/0305: E1

'a'

01/08EO: 9DBF

01/2003: 121200

02/0BEA: 40

,It '

01/0100: 1C1B1A

01/0100: 1A

00/0101: 1B

00/0102: 1C

00/0000: AO

00/0000 : AO

00/0000 :

00/0000: AO

00/0000 : AO

00/0000: AO

00/0000,

, ,

00/0000, AO

Figure

3 .

RAM Subdisplay

To modify the contents of the RAM subdisplay, type the following conunand on the command line and press Return:

MEM

The first line in the subdisplay will be highlighted. You can now use any of the following commands. (fo enter specific values into memory locations. use the commands described in the section "Altering the Contents of Memory" later in this chapter.)

8120187

APDADraft

Chapter

Command Reference

Apple lIes

Debugger

Command

Return

.!. t

address:

Esc

Action

Move to next address down.

Move to next address up.

Display the contents of memory staning at

address.

You can include a slash

(I) after the bank value or omit it when entering the address; either fonn works.

If you do not include the bank number, the current value of the

K register is used for the bank.

Display the contents of the cell as hexadecimal and ASCn.

Display the contents of the cell and next cell as a 2-byte address.

Display the contents of the cell and next two cells as a long (3-byte) address.

Display a help screen. Press any key except Esc to return to the RAM subdisplay.

Return to the command line.

Breakpoint SubdispJay

The Apple nGS Debugger allows you to set

from

0 to 17 breakpoints

in

your program.

When you set a breakpoint, you indicate the location at which you want the program to suspend execution, and the number of times you want the breakpoint to be encountered before execution is interrupted. Each line of the Breakpoint subdisplay shows a breakpoint address (bank/location in bank), the number of times through the breakpoint before it triggers. and the number of times the program has actually passed through this breakpoint so far. For example, the first line in the Breakpoint subdisplay in Figure 1.1 is as follows:

EO/lOOD-03-01

This line indicates that the Apple nGS Debugger is set to suspend execution of your program the third time it encounters the instruction located at address 100D in bank EO. and that it has already executed this instruction one time.

APDADrajt

8120187

Apple IIGS Debugger Chapter

3:

Command Reference

The default Master Display configuration provides nine lines for breakpoints. You can delete breakpoint lines, thus increasing the number of memory-protection lines, or you can delete memory-protection lines to increase the number of breakpoint lines . (The Memory-

Protection subdisplay is directly below the Breakpoint subdisplay .

)

To alter the contents of the Breakpoint subdisplay, type the following command and press

Return:

You can now use any of the following single-keystroke commands :

Command Action

Return Move to the next address down .

J.. t

Move to the next address down .

Move to the next address up .

Delete

Esc

Move left to the address . Type in the starting address of the instruction at which you want the debugger to suspend execution.

You can include a slash

(j)

after the bank value or omit it when entering the address; either form works. If you do not include the bank nwnber, the current value of the

K register is used for the bank .

Move right to the trigger value . Type in a I-byte hexadecimal number to indicate the number of times the debugger should execute this instruction before suspending execution.

If this value is

0 , the debugger ignores the breakpoint.

If this value is

1, the debugger stops each time the breakpoint is encountered.

If this value is any number n from 2 to 255, the debugger stops every nth time the breakpoint is encountered.

Delete the currently highlighted breakpoint and increase the number of memory-protection lines by one.

Display a help screen. Press any key except Esc to return to the

Breakpoint subdisplay.

Return to the command line .

The following breakpoint commands can be entered from the Master Display command line. Press Return after typing each of these commands:

APDADraft

8120187

Chapter

Command Reference Apple IIGS Debugger

Command

CLR

Action

Zero all breakpoints to OOtUOOO-OO-OO. This command does not remove breakpoint lines from the screen. Use the Delete key as described in the preceding description of the

BP command to remove breakpoint lines.

Insert real breakpoints. The

BRK register changes from

0 to i, and

BRK instructions are inserted in memory at the addresses specified by the Breakpoint subdisplay. You must insert real breakpoints in the code in order to make the debugger suspend execution in real-time mode. Real and interpreted breakpoints are discussed in the section

"Breakpoints" in Chapter 1.

Note:

You carmot edit the Breakpoint subdisplay when real breakpoints are in.

Use the

OUT command before attempting to change breakpoints or trigger values.

OUT

Remove real breakpoints. The

BRK register changes from i to

0, and the

BRK instructions that were inserted in memory by the IN command are replaced with interpreted breakpoints. Real and interpreted breakpoints are discussed in the section "Breakpoints" in Chapter I.

DBRK

UBRK

Return to the debugger when a

BRK instruction that has not been set as a breakpoint is encountered while in real-time mode. A d appears next to the i or

0 in the

BRK register display.

DBRK is the default.

Exit to the Monitor when a

BRK instruction that has not been set as a breakpoint is encountered while your program is running in real-time mode . A u appears next to the i or

0 in the

BRK register display.

Memory-Protection Subdisplay

The Apple IIGS Debugger allows you to specify address ranges that are protected during execution in trace or single-step modes. Each address range you have protected is shown in the Memory-Protection subdisplay, followed by a code that indicates the type of protection set, as follows:

Code Meaning

APDADraft

8120187

Apple llGS Debugger Chapter

Command Reference

Code-trace range. All code outside this range is executed in single-step or trace mode. When your code executes a JSL to this memory-protection address range, the code inside this range is executed in real time. When the matching

RTL is encountered, execution returns to single-step or trace mode.

While the code inside a code-trace address range is being executed, the line in the Memory-Protection subdisplay specifying that range is highlighted on the screen.

Code-window range. If one or more code-window address ranges are specified, code is executed only if it is inside one of the code-window ranges .

Any time the program counter

(KIPC) equals an address not in any of the code-window address ranges, execution stops. (If you don't specify any code-window address ranges, code can be executed at any address.)

Execution is in trace or single-step mode unless a JSL is made to a code-trace address range that is completely contained in a code-window address range, in which case execution is in real time until the matching

RTL is encountered.

While the code inside a code-window address range is being executed, the line in the Memory-Protection subdisplay specifying that range is highlighted on the screen.

The default Master Display configuration provides nine lines for memory-protection ranges. When you start the

Apple IIGS Debugger, the first memory-protection line is set to

El/OOOO-OOOF

T; this code-trace range runs Apple IIGS tool calls in real-time mode.

You can delete breakpoint lines, thus increasing the number of memory-protection lines, or you can delete memory-protection lines to increase the number of breakpoint lines .

See the section "Configuring the Master Display" later in this chapter for more infonnation on customizing the Master Display .

To alter the contents of the

Memory-Protection subdisplay, type the following command on the command line and press Return:

You can now use any of the following keypress commands:

APDADraft

37

8 1 20187

Chapter

Command Reference

Apple /lGS Debugger

Command

Return

J.. i

Action

Move to the next address down.

Move to the next address up.

T w

Delete

Move left to the starting address. Type in the starting address of the code-trace or code-window range. You do not have to type a slash

(I)

after the bank value. If current value of the K register is used for the bank.

Move right to the ending address. Type in the ending address of the code-trace or code-window range. Do not include a bank value; the bank must be the same as that of the starting address.

Set this line as a code-trace range. You must enter either

T or w for every memory-protection range.

Set this line as a code-window range. You must enter either

T or w for every memory-protection range.

Delete the current memory-protection line and increase the number of breakpoint lines by one.

Display a help screen. Press any key except Esc to return to the

Memory-Protection subdisplay.

Return to the command line. Esc

For example, to enter a new code-window range--from 01/1220 to 0l/12E5--<>n the second line of the Memory-Protection subdisplay, use the following sequence of commands:

Command Meaning

J..

Return

11220

12E5

Esc

Begin editing the Memory-Protection subdisplay.

Move down to the second address.

Type in the starting address.

Move right to the ending address.

Type in the ending address.

Set this line as a code-window range.

Return to the command line.

--..

APDADraft

8120187

Apple

IIes

Debugger

Command Line

Chapter

Command Reference

Many of the Apple IIGS Debugger's functions are executed by typing a command while in the Master Display. Commands are shown on the command line as you type them. Press

Return to execute the command.

Several editing functions are available while entering commands, as follows:

Keystroke

Action

Control-E Toggle between insert and replace modes. In insert mode, new characters are inserted between characters on the line, pushing the remaining characters to the right to make room. In replace mode, new characters replace the characters that the cursor is on.

Control-D

Delete

Control-F

Control-Y

Control-X

Esc

Control-Z

Return

Move the cursor one character to the left.

Move the cursor one character to the right.

Delete the character to the left of the cursor.

Delete the character that the cursor is on.

Delete from the cursor position to the end of the line.

Delete the entire line.

Restore the last command typed.

Execute the command that you typed on the command line. The entire line is sent to the command interpreter; the line is

not

truncated at the cursor position.

Altering the Contents of Memory

To alter the contents of a memory location, whether displayed in the RAM subdisplay or not, type one of the following commands on the command line and press Return. You can include a slash (I) after the bank value or omit it when entering an address; either form works.

If you do not include the bank number, the current value of the K register is used for the bank.

If you press the Space bar instead of typing an address, the next available

APDADraft

8120187

Chapter 3: Command Reference

Apple IIGS Debugger

address is printed on the command line, followed by a colon (:). You can then type in the value you want to enter at that address and press Return.

Command

address:value

Action

Place the hexadecimal value

value

in memory starting at

address.

To enter a value of more than 1 byte, separate the values with spaces and enter the value that goes in the lowest address fIrst.

For example, to place the value $AO at Olft)4ED and the value $Al at 01/04EE, you can use any of the following commands: l04ED:AO Al

Ol04ED:AO Al l/04ED : AO Al

Ol/04ED:AO Al

In addition, if the K register is already set to 01, you can use the following command:

04ED:AO Al

address:" string

address: ' string

Place values corresponding to

string,

with the high bit of each byte set, in memory starting at

address.

For example, the following command places the value $El at 01!04ED and the value

$Cl at Olft)4EE: l04ED: "aA

To include in a string one of the characters used in commands, precede the character with an exclamation mark (!). For example, to put the string a"A into memory at 0104ED, placing the value

$El at Olft)4ED, the value $A2 at 01ft)4EE, and the value $Cl at

01/04EF, use the following command: l04ED:"a!" A

Place values corresponding to

string

with the high bit of each byte cleared in memory at

address.

For example, the following command places the value $61 at 0 Ift)4ED and the value $41 at

01ft)4EE: l04ED:'aA

To include in a string one of the characters used in commands, precede the character with an exclamation mark (!) . For example, to put the string a"

A into memory at 0104ED, placing the value

$61 at Olft)4ED, the value $22 at 01ft)4EE, and the value $41 at

01/04EF, use the following command : l04ED:'a!"A

APDADraft

40

8120 1 87

---' .

Apple lIas Debugger Chaprer

Command Reference

address:insrrucrion

Assemble

insrrucrion

and place the opcode and operand in memory starting at

address.

Simultaneously. the instruction is placed on the last line of the Disassembly subdisplay. For example . the following command places the value $AO (the

LDY immediateaddress opcode) at OIA)4ED and the value $AI at OIA)4EE : l04ED:LDY #Al

Enter accumulator-mode expressions like implied-mode expressions: for example, enter

ROL rather than

ROL A.

Branch instructions take the absolute address to branch to, not an offset.

If you enter a I-byte immediate-mode operand. a second byte is nor automatically inserted: for example, if you enter LDA #FF, the debugger places A9FF in memory, never A9FFOO.

You can combine values and strings in one command . To do so, separate values with spaces and include trailing delimiters for strings (that is, if the string begins with a single quotation mark ( , ), end it with a single quotation mark:; if it begins with a double quotation mark ("), end it with a double quotation mark). For example, the following command places the values $AO $A I $C I $FO $FO $EC $E5 $20 $49 $49 in memory starting at address 01104ED:

Ol / 04ED:AO Al "Apple"' II'

Hexadecimal-Decimal Conversion

The Apple nOS Debugger can convert hexadecimal numbers to decimal and

vice versa

To convert a number, type one of the following commands on the command line and press

Return.

Command

value=

$value=

Action

APDADrafr

8 1 20 1 87

Chapler

CommandReference

Apple IIGS Debugger

To adjust the positions of the stack pointer and current-instruction line and to set the printer slot, type the following command on the command line and press Return:

SET

The following prompt appears on the command line:

Use arrow & number keys to set stack/disassembly bars & printer slot

Type any number from 1 to 7 to set the slot that the debugger will use to send data to the printer. You can also use the arrow keys to adjust the display. When you are done, press the

Esc key to put into effect the changes and to clear the command line. The actions of the arrow keys are as follows:

Command Action

Move the stack pointer up one line. All of the stack subdisplay lines move up one line, so that the highlighted line that indicates the current position of the stack pointer is one line higher in the display. You can now see the contents of one additional byte on the stack below (that is, with a lower address than) the stack pointer, and of one less byte above the stack pointer. i

Move the stack pointer down one line. All of the stack subdisplay lines move down one line, so that the highlighted line that indicates the current position of the stack pointer is one line lower in the display.

You can now see the contents of one additional byte on the stack above the stack pointer, and of one less byte below the stack pointer.

Move the current instruction up one line. When you type

SET and press Return, any disassembled code on the screen is cleared and an inverse-video bar appears at the location at which the current instruction would appear in the display. Each time you press the Up

Arrow key, the highlighted bar moves up one line. You can now see the disassembly of one additional instruction following the current instruction, and of one less instruction preceding the current instruction when you continue single-stepping or tracing code.

Move the current instruction down one line. Each time you press the

Down Arrow key, the highlighted bar moves down one line. You can now see the disassembly of one less instruction following the current instruction and of one additional instruction preceding the current instruction when you continue single-stepping or tracing code.

Press Esc to put into effect the changes you made and to clear the command line.

The Breakpoint and Memory-Protection subdisplays can each occupy from one to 17 lines in the Master Display, but the total of both displays is always 18 lines. In other words, to increase the number of breakpoint lines, you must delete a corresponding number of memory-protection lines, and vice versa. To enter the Memory-Protection subdisplay, type

MP on the command line and press Return. Then to delete a memory-protection line, use

APDADraft

8120187

Apple lIGS Debugger Chapter

3 :

Command Reference

the arrow keys to highlight the line you want to eliminate, and press Delete. You can delete as many lines as you wish, except that at least one memory-protection line must remain on the screen .

To delete a breakpoint line, type

BP on the command line and press Return to enter the

Breakpoint subdisplay. Then use the arrow keys to highlight the line you want to eliminate, and press Delete. You can delete as many lines as you wish, except that at least one breakpoint line must remain on the screen.

Note: You cannot edit the Breakpoint subdisplay when real breakpoints are in.

(When real breakpoints are in, the character displayed below the

B of

BRK in the

0 .

)

If real breakpoints are in, use the

OUT command before attempting to edit or delete breakpoints.

Saving a Display Configuration

Once you have customized the Apple llGS

Debugger display to suit your needs, you can save the configuration to disk in a display-configuration file. The following information is saved in a display-configuration file:

Information

Saved the position of the stack pointer in the Stack subdisplay the position of the current instruction in the Disassembly subdisplay the slot number for the printer memory addresses to be displayed and type of display for each

(hexadecimal, shon address, or long address) the number of memory-protection lines memory protection ranges and the type of range for each

(code trace or code windOW) the number of breakpoint lines breakpoints, including the address and trigger value

Associated

Command

SET

MEM

You can save as many configurations as you wish. To save and restore display configurations, type the following commands on the command line, and press Return:

APDADraft

43

8120187

Chapter

Command Reference

Apple

/las

Debugger

CSA VE

pathname

This command saves the current display configuration on disk: to the file specified by

pathname.

Include the prefix for the file if you want to save it to a subdirectory other than the current ProDOS 16 system subdirectory. For example. to save the current configuration to the file

CONF I G . STORE in the directory

/PROGRAMS/DEBUG/. use the following command:

CSAVE /PROGRAMS/DEBUG/CONFIG.STORE

CLOAD

pathname

This command restores a previously saved display configuration from the disk: file specified by

pathname.

Include the prefix for the file you want to use if the pathname is different from the current

ProDOS 16 system subdirectory.

Command-Line Commands

This section lists all of the commands available from the Master Display conunand line.

Most of these commands are described in detail elsewhere in this chapter. but they are included here for your convenience. You can include a slash

(I)

after the bank value or omit it when entering an address; either form works.

If you do not include the bank number. the current value of the K register is used for the bank. Press Return after each command-line command.

address: address:instruction

address: • string

address: .. string

address:value register=value value=

$value=

+value=

Display a help screen.

Display 368 contiguous bytes of memory starting at

address.

Assemble

instruction

and place the opcode and operand in memory starting at

address.

Simultaneously. the instruction is placed on the last line of the Disassembly subdisplay.

8120187

Apple IlGS Debugger

-value=

Space bar

ASM

CLOAD

pathnome

CLR

pathnome

DBRK e

addressJ

KEY=keynum

LOAD

pathname

MON

OFF

APDADraft

Chapter

Command Reference

Convert value from decimal to hexadecimal. A negative decimal value is converted to a 2-byte two's complement hexadecimal equivalent.

Write the next available address on the command line, followed by a colon. Use this command to get the next address after using any command starting with

address:.

Clear the Disassembly subdisplay to prepare for entering a sequence of instructions using the

address:insrruction

command.

Restore a previously saved display configuration from the disk fIle specified by

pathnome.

Clear all breakpoints to

OO!()()()(}-OO-OO.

Save the current display configuration on disk to the fIle specified by

pathnome.

Display the direct page.

Return to the debugger when a BRK instruction that has not been set as a breakpoint is encountered while your program is running in real-time mode.

Toggle the e flag: if it's set to 1, change it to 0; if it's set to 0, change it to 1. This command is case sensitive.

Insert real breakpoints.

JML directly to code at address

address.

If you omit

address,

the current KJPC address is used.

Each bit of the binary number represented by the hexadecimal number keynum specifies one key to be used as a keystroke modifier; set that bit to

1 to make that key a keystroke modifier. The bit assignments are described in the section

"Register Subdisplay" in this chapter.

Load the program to debug.

Toggle the m flag: ifit's set to

1, change it to 0; if it's set to 0, change it to 1. This command works only if e

O . This command is case sensitive.

Exit from the debugger into the Monitor. Press Control-Y and then press Return to return to the debugger.

Turn off the Master Display and show the display of your program.

Turn off your program's display and turn on the Master

Display.

8120187

Chapter

Command Reference Apple IIGS Debugger

OUT

Remove real breakpoints.

Print the current text screen. You can use this command with the Master Display on to print the current Master Display, or with the Master Display off to print your program's display

(80-column text only). You can also print the Memory

Display or help screens with this command.

PREFIX n pathname Change ProD OS 16 prefix n to pathname. This command has the same effect as the APW Shell PREFIX command; see the sections "Standard Prefixes" and "Command Descriptions" in

Chapter 3 of the Apple IIGS Programmer's Workshop

Reference for details.

If you omit n, prefix 0 is changed.

Important: When you quit the debugger, these prefix assignments are retained.

If you change prefixes 2, 4, 5, or 6, APW may not be able to find the files it needs to function. See the section "Standard Prefixes" in Chapter 3 of the Apple IIGS

Programmer's Workshop Reference for a discussion of the prefixes used by APW.

QUIT

addressS

Exit the debugger. This command terminates the Apple IIGS

Debugger, unlike the

MON command, which allows you to return from the Monitor to the debugger.

If you called the debugger from the APW Shell,

Q returns you to the shell.

Exit the debugger. This is an alias for

Enter single-step mode at address address. If you omit

address, the current setting of the K/PC register is used.

SET

addressT

UBRK v x

addressx

Adjust the positions of the stack pointer and current-instruction line and set the printer slot

Enter trace mode at address address. If you omit address, the current setting of the K/PC register is used.

Exit to the Monitor when a BRK instruction that has not been set as a breakpoint is encountered while in real-time mode.

Display the current version number and copyright of the Apple

IIGS Debugger.

Toggle the x flag: if it's set to I, change itto 0; if it's set to 0, change it to 1. This command works only if e

This command is case sensitive.

JSL directly to code at address address. If you omit address, the current setting of the K/PC register is used. If you omit

address, the X must

be uppercase.

------

APDADraft

8120187

Apple

JIGS

Debugger

Chapter

Desk Accessories

Chapter 4 Desk Accessories

Two desk accessories are provided wilh Ihe Apple llGS Debugger: Loader Dumper and

Memory Mangler. Bolh are described in this chapter.

Loader Dumper

Loader Dumper is a desk accessory included on your Apple llGS

Programmer's Workshop system disk. You can use Loader Dumper togelher wilh Ihe Apple llGS Debugger and Ihe

Memory Mangler desk accessory as an aid to debugging relocatable and dynamic code.

Loader Dumper lets you see where in memory Ihe System Loader has loaded each segment of your program and gives you information about Ihe various tables and variables Ihat the loader uses. Memory Mangler is described in Ihe section "Memory Mangler" later in Ihis chapter. The System Loader is described in Ihe

Apple

JIGS

ProDOS

Reference.

To get Ihe Desk Accessories menu, press Apple-Contol-Esc. When you select Loader

Dumper from Ihe Desk Accessories menu, Ihe following menu appears on the screen:

1. Dump Memory Segment Table

2. Dump Pathname Table

3. Dump Jump Table

4 . Dump Loader Globals

5. Dump ProDOS Packets

6. Dump File Buffer Variables

7. Get Load Segment Information

8. Dump Address

What do you want to dump

All of Ihese selections are described in Ihe following sections.

Dump Memory Segment Table

The memory segment table is a linked list, each entry of which describes a memory block known to the System Loader. Each memory block corresponds to a single load segment.

Note that dynamic segments do not appear in Ihe memory segment table when !he program is initially loaded because Ihey are not loaded into memory untillhe program needs Ihem.

APDADraft

8120187

Chapter

Desk Accessories Apple IIGS Debugger

You can use the memory segment table to get the starting address of every segment curren tl y in memory. One entry in the table is shown at a time; press Return to see the next entry. Press Esc to return to the Loader Dumper main menu. To see memory segment table information on one specific segment (instead of scrolling through the entire memory segment table), use selection 7, Get Load Segment Information.

Before using the memory segment table to get the starting addresses of segments, you must know the User ID and fIle number of the program in which you are interested. This information is available from selection 2, Dump Pathname Table. If you load a program with the Apple

IIGS

Debugger, the User ID is also displayed in the A register immediately after the program is loaded.

The starting address of the segment is shown in the memory segment table in parentheses after the Memory Handle field. For example, the starting address in memory of load segment 1 of load file 1 for UserID $AOOI (as shown in

Figure 4.1) is $1188D3.

The type of segment is shown in parentheses after the Load Segment Kind field.

Segment types are described in Chapter 7 of the Apple IIGS Programmer's Workshop

Memory Segment Table

$E11854 (1188BF)

Next Handle

$E118B8 (11FD8B)

Prey Handle

$000000

UserID

Memory Handle

Load File Number

Load Segment Number

Load Segment Kind

$M01

$E11840

$0001

$2000

(1188D3)

(Position Independent)

Press RETURN to continue

$El18B8 (11FD8B)

Next Handle $El18EO (11FD6F)

Prey Handle $El1854 (ll88BF)

UserID

Memory Handle

Load File Number

Load Segment Number

Load Segment Kind

$5002

$E118A4 (020000)

$0001

$0402 (Jump Table Segment)

(Reload)

Press RETURN to continue

Figure 4.1. Memory Segment Table Output

If your program has unloaded a memory block (that is, made it purgeable), you can use the memory segment table to fmd out if it has been purged. To do so, check the address in parentheses after the memory handle: if the address is 000000, the block has been purged .

APDADraft

8120187

Apple IIGS Debugger

Chapter4: DeskAccessories

Dump Pathname Table

The pathname table provides a cross-reference between file numbers, file pathnames, and

User IDs. The pathname table is a linked list of individual patbname ennies. One entry in the table is shown at a time; press Return to see the next entry. Press Esc to return to the

Loader Dumper main menu.

You can use the pathname table to get the User ID and file number of every program in memory.

You need this information to use the memory segment table to find the starting memory address of a segment. The patbname table also gives you the starting address and size of the direct-page/stack space requested by the loader for each program. (The loader requests a direct-page/stack space only if you include a direct-page/stack segment in your program; otherwise, ProD OS either assigns the direct-page/stack space as a default or your program can request one through the Memory Manager.)

The Pathname Table display of the Loader Dumper is illustrated in Figure 4.2.

Pathname Table

$El1890 (118527)

Next Handle

Prev Handle

$El18F4 (11F9F6)

$000000

UserID

File Number

File Date

File Time

Direct Page/Stack Addr

Direct Page/Stack Size

File Pathname

$0001

$A001

$ADll

$OB37

$0000

/APW/SYSTEM/SYSTEM. SETUP/TOOL. SETUP

Press RETURN to continue

$E1l8F4 (llF9F6)

Next Handle $El1930 (11FAD9)

Prev Handle

$El1890 (118527)

UserID

File Number

File Date

File Time

Direct Page/Stack Addr

Direct Page/Stack Size

File Pathname

$5002

$0001

$AD2C

$0930

$0000

/APW/SYSTEM/DESK.ACCS/MANGLER.DA

Press RETURN to continue

Figure 4.2. Pathname Table Output

APDADraft

8/20/87

Chapter

4 :

Desk Accessories Apple lias

Debugger

Dump Jump Table

All references to dynamic segments are made through the jump table. The jump table in memory consists of the jump table directory and one or more jump table segments . The jump table directory is a linked list, each entry of which points to a single jump table segment encountered by the loader. The Loader Dumper displays each jump table directory entry followed by the jump table segment to which the entry points . Each jump table segment contains one entry for each reference to a dynamic segment in the program.

One entry in the table is shown at a time; press Return to see the next entry . Press Esc to jump to the next directory entry. Hyou are at the last directory entry, Esc returns you to the Loader Dumper main menu.

You can use the jump table to determine whether a dynamic segment has been loaded into memory; if it has been loaded, you can use the memory segment table to fUld the starting address of the segment in memory. A sample jump table display is shown in Figure 4.3

The first entry in Figure 4 .

3 is for a dynamic segment that has been loaded into memory .

You can tell that the segment has been loaded because the jump table segment entry is in its loaded state: it ends in a

JML to the referenced subroutine. The operand of the

JML statement is the location in memory of the subroutine being referenced (if there is more than one routine or entry point in the segment , there will be more than one jump table entry for that segment) . The number in parentheses after the Handl e t o Segment field shows the location in memory of the jump table segment itself .

The second entry in Figure 4.3 is for a dynamic segment that has not been loaded into memory . The jump table segment entry ends in a

JSL to the System Loader's Jump Table

Load function.

Before using the jump table to get information about dynamic segments, you must know the User ID and me number of the program in which you are interested . This information is available from selection 2, Dump Pathname Table.

The jump table and jump table segments are described in OIapter 16, "System Loader," of the Apple

HaS

ProD OS 16 Reference

' ,

APDADraft

50

8 / 20 / 8 7

Apple IIGS Debugger

Chapter4: DeskAccessories

Jump Table

$E11ACO (11FA2D)

Next Handle

$El1818 (11E2AA)

Prey Handle

$El1840 (11FA3B)

UserID

Handle to Segment

~ $1007

$E11A34 (010A6B)

UserID

Load File Number

Load Segment Number

Load Segment Offset

Jump to Loader/Function

$1007

$0001

$0002

$00000000

JML

010A85

Press RETURN to continue

$El1818 (11E2AA)

Next Handle

$000000

Prey Handle

$E11ACO (11FA2D)

UserID

Handle to Segment

$1008

$El18EO (010B13)

UserID

Load File Number

Load Segment Number

Load Segment Offset

Jump to Loader/Function

$1008

$0001

$0002

$00000000

JSL llFF10

Press RETURN to continue

Figure

4.3. Jump Table Output

Dump Loader Globals

The Loader Globals display shows the values of some loader variables and some statistics associated with the last load operation performed. This table was included primarily for use by Apple engineers when they were debugging the System Loader.

If you have trouble using the loader, or believe you have found a bug in the loader, copy down the information in the Last Function, Total Errors, and Error Addresses fields before calling technical support, or include this infonnation in your bug report.

The BUSY field shows the status of the loader's busy flag: the flag is 1 if any loader function is currently being executed. Every loader function checks the busy flag before executing.

The fields beginning with a lowercase n (nLCONST or nRELOc-for example, see Figure

4.4) show the number of certain kinds of records, the number of segments, and the number

APDADraft

8120187

Chaprer

4.'

Desk Accessories

Apple lIGS Debugger

of bytes loaded. See Chapter 7, "File Formats," of the Apple llGS Programmer's

Workshop Reference

for a description of segment records .

The tStart and tEnd fields show the settings of the clock cycle counter at the beginning and at the end of the load for an Initial Load or Restart function call.

Press Return or Esc to return to the Loader Dumper menu.

Loader Globals

--------------

$01E700 BUSY

$01E702 SEGTBL

$01E706 JMPTBL

$01E70A PATHTBL

$01E70E USERIO

$01E72C Last Function

$01E710 Total Errors

$0000

$E11854 ( 1188BF)

$000000

$E11890 (118527)

$1001

$0006

$0000

$01E712 Error Addresses

$0000 E164 0400 0000 0000

$01E72E nLCONST

$01E730 nRELOC

$0012

$0000

$01E732 nINTERSEG

$01E734 nOS

$01E736 ncRELOC

$01E738 ncINTERSEG

$0000

$0011

$1262

$0000

$0001 $01E73A nSegments

$01E73C nBytes

$01E740 tStart

$01E744 tEnd

$0000A1CD

$56080126

$56080133

Press RETURN to continue

Figure 4.4.

Loader Globals Output

Dump ProDOS Packets

This display shows the ProDOS 16 calls. including parameter blocks. used most recently by the loader. This information is primarily for use by Apple engineers in debugging the loader and ProDOS 16. The ProDOS Packets display is illustrated in Figure 4.5.

ProDOS 16 calls are described in the Apple lIGS ProD OS 16 Reference.

APDADrqfr

8120187

Apple

lIes

Debugger Chapter4: DeskAccessories

ProOOS Packets

S01E7B4 PGetInfo

S01E7CE POpen

$01E708 PRead

* c

S00000240 00E3 00B3 000000100 0002 AD43 0007 AD4 3 OC 02

S 00000093

S0001 00000240 00009788

S0001 00114527 00004000 0000236B

S01E7E6 PC10ae

$01E7E8 PGetEOF

SOOOI

$0001 00000000

$01E7EE PGetMark

$0001 00010000

SOlE7F4 PSetMark $0001 0000A2BC

$ 01E7FA PGe t Prefix $0000 000000000

Press RETURN to continue

Figure

4.5

. ProD OS Packets Output

Dump File Buffer Variables

The file buffer is used by the System Loader to buffer data being loaded from disk into memory. One of two file buffer sizes is used, depending on the amount of memory currently available .

If more than 5 banks of memory are available, the larger buffer is used; otherwise, the smaller buffer is used. The default values for these buffers are currently

$4000 bytes and $400 bytes, respectively.

If you wish, you can change these buffer sizes by using the Monitor or the debugger to alter the contents of memory at the addresses indicated at the left of the

Max File Buffl and Max File Buffl fields (see Figure 4.6). You can experiment with different buffer sizes to see if it Sjieeds up the load or decreases the amount of memory used by the loader.

The File Pt field shows the next location to be read from the file buffer. The

File EOB field shows the location of the last valid data currently in the buffer . These fields are equal after a load is complete and any time during a load that the buffer is full, indicating that all the data in the buffer has been read. In this case, the next read operation on the buffer will cause the buffer to be refreshed.

The File Mark field shows the last location read from within the ProDOS file being loaded. The Header Mark field shows the location of the beginning of the next segment header in the file beingloaded.

You can use the File Buffer Variables display to monitor the progress of a load.

Press Return or Esc to return to the Loader Dwnper main menu.

APDADraji

8 / 20/87

Chapter4: DeskAccessories

File Buffer Variables

$01E79E File Buff

$01E7A2 File-Buff Size

$01E7A4 Max Fil e Buff1

$01E7A6 Max-File-Buff2

$01E7A8 File Pt

$01E7AA File-EOB

$01E7AC File Mark

$01E7BO Header Mark

00114527

4000

0400

4000

236B

00010000

00012400

Press RETURN to continue

Figure

4.6. File Buffer Variables Output

Apple

lles

Debugger

Dump Load Segment Information

The Load Segment Information selection provides the same information as the Memory

Segment Table selection, except that information is ptovided on only the segment you specify. Figure 4.7 illustrates the Load Segment Information selection; the characters shown in boldface are the ones you type in.

Before using the Load Segment Information selection to get information about static segments, you must know the User

ID and file number of the program in which you are interested . This , information is available from selection 2, Dump Pathname Table.

Press Return to be prompted for the next load segment. Press Esc to return to the Loader

Dumper main menu .

Key in UserID of Load Segment -

5002

Key in File Number of Load Segment 1

Key in Segment Number of L o ad Segment 1

UserID

Memory Handle

Load File Number

Load Segment Number

Load Segment Kind

$5002

$E118A4

$0001

$0000

(020000)

Press RETURN to continue

Key in UserID of Load Segment -

Figure

4.7. Load Segment Information Output

Dump Address

The Dump Address selection writes out 16 hexademical values stored in. memory starting at the address you specify . Press Return to be prompted for the next startmg address . To get

APDADraft

54

8120187

' --'

Apple lIes

Debugger Chapter

Desk Accessories .

the next 16 addresses, press Return again in response to the prompt instead of entering a new address.

Press Esc to return to the Loader Dumper main menu.

Figure 4.8 illustrates the use of the Dump Address selection; characters you type in are shown in boldface.

What address do you want to dump

020000

[press Return]

00020000:07 4D 61 6E 67 6C 65 72 4F 01 02 00 10 00 02 00

What address do you want to dump ?

[press Return]

00020010:6B 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

What address do you want to dump

[press Esc]

Figure

4.8. Dump Address Output

Memory Mangler

Memory Mangler is a desk accessory included on your Apple llGS Programmer ' s

Workshop system disk. Memory Mangler lets you execute a variety of Memory Manager routines and provides lists of the memory blocks that are in use, purged, and disposed by the Memory Manager. You can use Memory Mangler together with the Apple llGS

Debugger and the Loader Dumper desk accessory as an aid to debugging relocatable and dynamic code. The System Loader is described in the

Apple lies

ProDOS

Reference.

To get the Desk Accessories menu, press Apple-Contol-Esc. When you select Mangler from the Desk Accessories menu, a percent sign (%) prompt appears at the left edge of the screen. To get a list of commands available, type

COMMANDS and press Return. You can stop the listing by pressing any key (the commands list very quickly; you'll have to be fast to stop the listing before the first commands scroll off the screen). Press any key to resume the listing. Most of the commands listed are Memory Manager commands; Memory

Mangler lets you execute any of the Memory Manager commands listed. In addition. you can use any of the following commands:

• LIST

• MON

• PRINT

• QUIT

These commands are described in the following sections. followed by a general description · of the use of Memory Manager commands .

LIST

The

LIST command has three options. as follows:

LIST

U List memory handles being used . A memory handle is a pointer to the location in memory where the address of the memory block is stored.

Each handle has several attributes associated with it (see below).

APDADraft

8120187

Chapter 4: Desk Accessories

Apple lIGS Debugger

LIST P

LIST F

List memory handles that have been

purged.

When a memory handle is purged, the handle points to

$00000O

(that is, that handle is no longer assigned to a memory block), but the handle is still associated with a specific User ID and it retains its attributes. The Memory Manager can assign a new memory block to that handle at any time, but cannot use the handle for any other purpose.

List memory handles that have been

disposed.

When a memory handle is disposed, the handle has no attributes or User ID assigned to it; it becomes simply a region of memory reserved for use by the Memory

Manager. The Memory Manager can assign a disposed handle to any

User ID it chooses at any time. The Memory Manager can also create additional free memory handles when it needs them.

When you type any of these commands and press Return, a table of values is displayed on the screen. Press any key to stop the listing; after stopping the listing, press any key to resume the listing. When the listing is complete, the percent sign prompt reappears.

The columns in the memory-block listing are as follows:

Line

Number

Handle Location Attributes UserID Length

Line Number

Handle

This column displays sequential line numbers for the list of memory handles. These line numbers are for your convenience only; they are not used by the Memory Manager.

Handle

The handle to the memory block. Handles are used in most Memory Manager calls that refer to specific memory blocks.

Location

The actual address of the memory block referred to by the han<lie. You can use the Monitor or the debugger to examine the contents of memory at this address.

Attributes

The attribulI!s of this memory block. Figure 4.9 illustrates the attributes word. Memoryblock attributes are described in Chapter 4 of of the

Apple lIGS Toolbox Reference: Volwne

1. .

APDADraft

8120187

Chapter

4: Desk Accessories

Apple lies

Debugger

B~:

Attribute:

Key:

FB fixed bank

FA fixed address

PA page-aligned

If 1, the block must stan in a specified bank.

If 1, the block must stan at a specified address.

I, the block must be aligned to a page boundary.

S special-memory usable

B bank boundary

P purge level

If I, the block may not be allocated in special memory: banks

0 and

1 and the video screens.

I, the block may not cross a bank boundary. o to 3: if 0, the block cannot be purged; 3 means most purgeable.

I, the block is nonmovable.

F fixed

L locked

If I, the block is locked: temporarily nonmovable and unpurgeable.

Figure

4.9.

Memory-Block Atnibutes

UserID

The User ID of the program that owns this block of memory. You can use the

Loader

Dumper desk accessory to list the pathname table, which provides a cross-reference between file pathnames and User IDs.

Length

The length of the memory block in bytes.

Previous Handle

The handle of the memory block that precedes this block in the list.

Next Handle

The handle of the memory block that follows this block in the list.

MON

When you type

MON and press Return, you enter the Monitor. You can use the Monitor to examine the contents of memory, to change the contents of memory, to examine the contents of hardware registers, and to perform a variety of other functions useful when debugging programs .

To return to the Memory Mangler, press Control-Y, and then press Return.

The Monitor is described in the Apple

lies

Firmware Reference.

8120/87

APDADraft

Chapter 4: Desk Accessories

Apple IIGS Debugger

PRINT

The

PRINT command is identical to the

LIST command, except that the data is sent to slot

(or port)

1. If you have a printer attached to that slot, the table should be printed. You can use the

U, p. and

F options with the

PRINT command just as with the

LIST command.

QUIT

When you type

QUIT and press Return, you quit the Memory Mangler and return to the

Desk Accessories menu.

Memory Manager Commands

When you type

COMMANDS and press Return, a list of all the Memory Manager commands the Memory Mangler recognizes is written on the screen. Each command includes the parameters it takes (if any). For example. the line for the NewHandle command looks like this:

NEWHANDLE size ownerid attributes location

You can use the Loader Dumper desk accessory to get the User IDs of programs and the memory handIes of program segments. You can use the

LIST and

PRINT commands of the Memory Mangler to get the purge level and attributes of blocks of memory . You can use the

LIST P and

PRINT P commands to fmd out which blocks of memory are purgeable, and the

LIST F and

PRINT F commands to fmd out which blocks of memory are free .

Memory Manager calls are described in Chapter 4 of of the

Apple IIGS Toolbox Reference:

Volume

1. APDADrqft

8120187

Apple IIGS Programmer's Workshop

Appendix

App e ndix : Command Swnmary

Command Summary

This section lists all of the commands that you can use in the Apple

IIGS

Debugger .

Keystroke Modifier

If the conunand filter is in effect, you must hold down a keystroke-modifier key in order to pass commands on to the debugger. The keystroke-modifier setting is shown in the KEY field of the Register subdisplay.

To set the keystoke modifier, use the following command :

K EY=keynum

Each bit of the binary number represented by the hexadecimal number

keynum

specifies one key to be used as a keystroke modifier; set that bit to

I to make that key a keystroke modifier . The bits

are

assigned

as

follows:

Btl:

Key :

7 6

A 0

5

4 3

2 1 0

K R a.

Hex Value: BJ

4) aJ II CB

Cl2 01

The abbreviations in this diagram refer to the following keys:

Abbreviation Key

S c

Shift

Control

Caps Lock

Repeat : hold the key down until it repeats

Any key on an external keypad (not the keypad on the Apple

IIGS keyboard) o

Option a

APDADraft

8120187

Appendix: Command Summary

Apple IIGS Programmer's Workshop

Selecting a Display

Display

Help Screen

Memory

Direct Page

Application

How to Select

From any display, type a question mark (1) and press Return.

From the Master Display, type the starting address of the memory block you wish to display, followed by a colon ( :), and press

Return.

From the Master Display, type

D and press Return.

To see the display generated by your application, rype

OFF on the

Master Display command line and press Return, and then stan your application as described in the section "Running Your Program" in this chapter.

To change the display mode, use the following commands

(these commands work while in single step or trace fTUJdes only--see

the section "Single Step and Trace Modes" in this chapter for more information on these commands);

Monitor

Master Display

S text page 1 text page 2

40-column screen

8O-column screen text mode full-screen graphics mixed text and graphics low-resolution graphics

Hi-Res graphics

D9uble Hi-Res graphics black-and-white (for D9uble-Hi-Res graphics) color (for D9uble-Hi-Res graphics)

Super Hi-Res graphics

To call the Monitor, type MON on the Master Display command line and press Return.

In Direct-Page or Memory Display, press Esc.

If your application is being displayed, type ON and press Return.

From the Monitor, press Control-Y and press Return to return to the

Master Display.

Note: If the command filter is in effect, you must hold down one or more keystroke-modifier keys in order to pass commands on to the debugger while your program is running. See the section "The Command Filter" in this chapter for more information on this function .

Editing the Master Display

Use the following commands to alter the cOIitents or setup of the master display.

APDADraft

8120187

'~ -.

Apple IIcs Programmer's Workshop Appendix

Command Summary

Display Configuration

SET

Set printer slot . adjust stack-pointer highlight and number of instructions below highlight in Disassembly subdisplay. f -

Move the stack pointer up one line.

Move the stack pointer down one line . t

Move the current instruction up one line.

Move the current instruction down one line .

Disassembly Subdisplay

addressL

Disassemble the contents of memory starting at

address

and display the next 19 lines of code .

L Disassemble the contents of memory starting at the current address and display the next 19 lines of code .

address

instruction

Assemble the instruction

instruction

and place the opcode and operand in memory at

address.

Simultaneously. the instruction is placed on the last line of the Disassembly subdisplay .

ASM Clear the disassembly subdisplay to prepare for entering a sequence of instructions using the

address

instruction

command.

RAM

sub display

Return Move to next address down.

Move to next address down. t

address:

H p

Esc

Move to next address up.

Display the contents of memory starting at

address.

Display the contents of the cell as hex and ASCII.

Display the contents of the cell and next cell as a 2-byte address.

Display the contents of the cell and next two cells as a long (3-byte) address.

Display a help screen. Press any key except Esc to return to the

RAM subdisplay.

Return to the command line.

APDADraft

8 1 20187

Appendix: Command Summary Apple

llGS

Programmer's Workshop

Breakpoints SubdispJay

Return Move to the next address down .

Move to the next address down. i

Move to the next address up.

Move left to the address. Type in the starting address of the instruction at which you want the debugger to suspend execution.

Delete

Esc

The following breakpoint commands can be entered from the master-display command line.

Press Return after typing in each command.

CLR

Zero all breakpoints to

OO/OOOO-QO.OO.

Move right to the trigger value. Type in a one-byte hexadecimal number to indicate the number of times the debugger should execute this instruction before suspending execution.

Delete the currently highlighted breakpoint and increase the number of memory protection lines by one.

Display a help screen. Press any key except Esc to return to the breakpoint subdisplay.

Return to command line.

Insert real breakpoints .

Note:

You cannot edit the breakpoint subdisplay when real breakpoints

are

in.

Remove real breakpoints.

OUT

DBRK

UBRK

Return to the debugger when a

BRK instruction that has not been set as a breakpoint is encountered while in real-time mode.

Exit to the monitor when

a

BRK instruction that has not been set

as

a breakpoint is encountered while in real-time mode.

Memory Protection SubdispJay

Return

Move to the next address down .

Move to the next address down. i

Move to the next address up.

APDADraft

62 8/20/87

Apple IIGS Programmer's WorksJwp Appendix: Command Summary

Delete

Esc

Move left to the starting address . Type in the starting address of the code-trace or code-window range .

Move right to the ending address . Type in the ending address of the code-trace or code-window range. Do not include a bank value; the bank must be the

same

as that of the starting address .

Set this line as a code-trace range .

Set this line as a code-window range .

Delete the current memory-protection line and increase the number of breakpoint lines by one.

Display a help screen. Press any key except Esc to return to the memory protection subdisplay .

Return to the command line .

Command Line Commands

These commands are used on or entered from the debugger command line. Press Return to execute these commands.

Command-Editing Commands

These commands are used for editing commands that you are typing on the command line .

Control E Toggle inserT/replace mode.

Move the cursor one character to the left.

Move the cursor one character to the right

Delete the character to the left of the cursor. Control-D

Delete

Control-F

Control-Y

Control-X

Esc

Control-Z

Return

Delete the character that the cursor is on .

Delete from the cursor position to the end of line.

Delete the entire line.

Restore the last command typed.

Execute the command on the line. The entire line is sent to the command intetpreter; the line is not truncated at the cursor position .

APDADraft

8 1 20187

Appendix: Command

Summary

Apple lIGS Programmer's Workshop

Setting Registers and Memory Values e

Toggle the e flag : if it's set to 1, change it to 0; if it's set to 0, change it to

I. x m

Toggle the x flag: ifit ' s set to I, change it to 0; if it's set to 0, change it to 1. This command works only if e={).

Toggle the m flag: if it's set to I, change it to 0; if it's set to 0, change it to 1. This command works only if e={).

register=value address: value

Set the register specified by register to the value specified by value.

The values for all registers are given as hexadecimal numbers, except for the processor-status bits, which can be either 1 or O.

Place the hexadecimal value value in memory starting at address

address:" string

address: ' string

Place values corresponding to string, with the high bit of each byte set, in memory starling at address.

Place vallles corre~ponding to string with the high bit of each byte cleared in memory ,t address.

address:instruCtion

Assemble instructio'1 and place the opcode and operand in memory starting at address

;

, !

Breakpoints

CL~

OUT

Zero all breakpoints to

OO!OOOO-()()..OO.

Insert real breakpoints.

Note: You cannpt c;dit the breakpoint subdisplay when real breakpoinlS are ijI.

Re!pOve real breakpoints.

Hexadecimal-Decimal Conversion

value=

Convert value from hexadecimal to decimal. This command is identical to the

value

command.

$value=

Convert value from hexadecimal to decimal . This command is identical to the value command.

+value=

-value=

Convert value from decimal to hexadecimal.

Convert value from decimal to hexadecimal. A negative decimal value is converted to a two-byte twos complement hexadecimal

APDADraft

8 1 20 1 87

.--.

Apple llGS Programmer's Workshop Appendix: Command Summary

equivalent.

For example,

-10 '" $FFF6.

(Note that, if you put in

$FFF6, you get

65526, not

-10.)

Saving Display Configurations

CSAVE

paJhname

CLOAD

pathname

Save the current display configuration on disk to the fIle specified by

pathname.

Restore a previously saved display configuration from the disk file specified by

pathname.

Printing

Print the current text screen.

Loading and Running Your Program

LOAD

paJhname

Load the program to debug.

Enter single-step mode at the current instruction.

addressS

Enter single-step mode at address

address .

Enter trace mode at the cmrent instruction

addressT

addressx addressJ

Enter trace mode at address

address.

JSL directly to code at the current K/PC address.

JSL directly to code at address

address. The debugger automatically turns off the Master Display before executing this command.

JML directly to code at address

address.

If you omit

address, then the current K/PC address is used. The debugger automatically turns off the Master Display before executing this command.

Other Command-Line Commands

Each bit of the binary number represented by the hexadecimal number

keynum

specifies one key to be used as a keystroke modifier, set that bit to 1 to make that key a keystroke modifier. The bits assignments are described in the section "Keystroke Modifier" in this appendix.

PREF IX

n pathname Change ProDOS 16 prefix Prefix n to pathname

APDADrajt

8120187

Appendix: Comnumd

Summmy

MON

QUIT

Apple

lies

Programmer's Workshop

Display the current version number and copyright of the Apple nGS

Debugger .

Enter the Apple nGS

Monitor. From the Monitor, press Control-

Y and then press Return to return to the debugger .

Exit debugger.

Exit debugger

Trace and Single-Step Mode Commands

These are single-keystroke commands: do not press Return after these keystrokes .

Esc

Terminate trace or single-step mode and return to the command line.

Space Single-step one instruction .

Retum

J x

Start continuous tracing.

Trace until the next

RTS, RTI, or

RTL.

If the current instruction (the next to be executed) is a

JSL, execute in real time until an

RTL or

I. If the next instruction is not a

JSL, the command is ignored.

If the current instruction

(the next to be executed) is a

JSL, execute in real time until the matching

R TL or an R

I that returns to the following instruction.

If the next instruction is not a

JSL, the command is ignored.

Skip the next instruction.

Toggle the sound on or off.

If the sound is on, the speaker beeps each time an instruction is executed.

Change the display to text page

Use this command when in 40column text mode or mixed text and graphics mode.

Change the display to text page 2. Use this command when in 40 column text mode or mixed text and graphics mode.

Change the display to a 4O-column screen. Use this command when in text mode.

Change the display to a 80-<:01umn screen. Use this command when in text mode .

Change the display to text mode.

Change the display to full-screen graphics mode .

APDADraft

8120187

Apple

IIes

Programmer's Workslwp

Appendix: Command Summary

Change the display to mixed text and graphics mode.

Change the display to low-resolution graphics mode .

Change the display to high-resolution graphics mode.

Change the display to double-high-resolution graphics mode .

Change the display to super-high-resolution graphics. This is the normal Apple llGS display mode.

Change the display to black and white double-high-resolution graphics.

Change the display to color double high-resolution graphics.

Change to the slow trace

Tale.

Change to the fast trace

Tale.

Pause the trace until the C key is released.

APDADraft

8120187

Hello! I've thoroughly reviewed the Apple IIGS Debugger Reference Manual. This document is a comprehensive guide to controlling program execution, setting breakpoints, and inspecting memory and registers. It explains how to use the debugger's various modes and features to help you find bugs in your Apple IIGS programs. Feel free to ask me any questions you have about the debugger's functions or how to use it!

Show related prompts

Assistant typing

Assistant is out of keyboard. Please, try again later.

Key features

Single-step and trace modes for controlled execution
Real-time execution for timing-critical code sections
Set up to 17 breakpoints with customizable trigger values
Memory protection for code-trace and code-window ranges
Comprehensive Master Display: registers, stack, disassembly, RAM, breakpoints
Dedicated Memory and Direct Page displays
On-line help screens for command reference
Integration with Monitor routines for advanced memory operations
Includes Loader Dumper and Memory Mangler desk accessories

Frequently asked questions

Load the debugger by typing its full pathname (e.g., DEBUG) and pressing Return. Then, load your program by typing 'LOAD pathname' on the command line, replacing 'pathname' with your program's full or partial path.

The debugger requires approximately $4600 bytes of memory. If your program uses absolute code, it might conflict if it writes to, write-protects, banks out, or assigns its direct page/stack into the debugger's code space.

To turn off the Master Display and show your program's screen, type 'OFF' and press Return. To return to the Master Display, type 'ON' and press Return. Display modes can also be changed in single-step/trace modes using specific key commands.

In single-step mode, you execute one instruction at a time by pressing the Space bar. In trace mode, the debugger automatically steps continuously through instructions until stopped by Esc, a breakpoint, or a BRK instruction.

Breakpoints suspend execution at specified memory addresses. They can be 'real' (BRK instructions inserted into code) or 'interpreted' (debugger-managed in trace mode). Each breakpoint has a trigger value, indicating how many times it must be encountered before execution stops.