Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

6    AdnDebug Manager

Palm OS® Debugger Guide

Palm OS® Developer Suite

This chapter provides documentation for the ARM-based debugger nub manager, called AdnDebug Manager, and is divided into the following sections:

AdnDebug Manager Concepts
AdnDebug Manager Constants
AdnDebug Manager Functions and Macros

The AdnDebug Manager API is declared in the header file AdnDebugMgr.h. These functions can be used within ARM subroutines, also called PACE native objects.

AdnDebug Manager Concepts ^TOP^

In order to debug your ARM-based code, your application needs to do the following:

Activate the ARM Debugger Nub ^TOP^

The ARM debugger nub is not active on an ARM-based device until an application activates it. Your ARM subroutine must first enable the ARM debugger nub by calling the AdnDebugEnableSet() macro.


	// Tell the debugger we want to enable full debugging 
	UInt32 flags = AdnDebugEnableGet(); 
	flags |= kAdnEnableMasterSwitch | kAdnEnableFullDebugging; 
	AdnDebugEnableSet(flags); 

Register with Palm OS Debugger ^TOP^

Palm OS Debugger needs to be able to resolve where each ARM subroutine is located in memory. Your ARM subroutine must register with Palm OS Debugger by calling the AdnDebugNativeRegister() macro. You need to call the AdnDebugNativeRegister() macro once after the code resource has been locked, typically on the first call into the ARM subroutine.

However, your code should also unregister (prior to the being unlocked) by calling the AdnDebugNativeUnregister() macro.

These calls do not act as breakpoints and they do not halt device operation. But they may cause breakpoints to become resolved or unresolved.


	// Tell the debugger where our code lives in memory: 
	AdnDebugNativeRegister( 
				sysFileTApplication, appFileCreator, 
				NativeResourceType, NativeResourceID);  

The ARM subroutine needs to define appFileCreator, NativeResourceType, and NativeResourceID in order for Palm OS Debugger to locate the corresponding debug symbol file.

For example, if you have an ARMC resource with ID 0001, the debug symbol file is typically of the form ARMC0001.bin.elf. The ELF file must be in the same directory as the PRC file that contains the ARM subroutine you are debugging.

AdnDebug Manager Constants ^TOP^

Debugging Constants ^TOP^

Purpose

These constants define debugging features that you can enable and disable.

Declared In

AdnDebugMgr.h

Constants

#define kAdnEnableDebugIndicator 0x00000002
The debug indicator enables a visual indicator that shows when the debugger nub is performing or waiting for serial communication. For example, on the Tungsten T device, the green LED blinks to indicate that the debugger nub is active.
#define kAdnEnableFullDebugging 0x00000004
The full debugging feature must be enabled in order for application calls to AdnDebugNativeRegister() to be processed correctly. If this feature is disabled, then other native debugging calls (such as ModulePostLoad and ModulePostUnload) are also disabled.
#define kAdnEnableMasterSwitch 0x00000001
When the master switch is enabled, the debug nub catches fatal ARM exceptions, enters the debugger if AdnDebugBreak() is called, and catches ErrFatalDisplay() calls.
When the master switch is disabled, the you are limited to calling the AdnDebugEnableSet() and AdnDebugEnableGet() macros.
#define kAdnEnableShowSafeFatalAlerts 0x00000008
When show safe fatal alerts is enabled, the debugger nub does not catch calls to ErrFatalDisplay() if the Reset, Debug, and Continue options are displayed.

AdnDebug Manager Functions and Macros ^TOP^

AdnDebugBreak Macro ^TOP^

Purpose

Break into Palm OS Debugger from the ARM subroutine.

Declared In

AdnDebugMgr.h

Prototype

#define AdnDebugBreak ()

Parameters

None.

Returns

Nothing.

Comments

This macro is the ARM-based equivalent to the Debug Manager call DbgBreak().

AdnDebugEnableGet Macro ^TOP^

Purpose

This macro returns flags indicating which debugging features are enabled.

Declared In

AdnDebugMgr.h

Prototype

#define AdnDebugEnableGet ()

Parameters

None.

Returns

UInt32 representing flags as defined in "Debugging Constants".

Example

UInt32 flags = AdnDebugEnableGet(); flags |= kAdnEnableMasterSwitch | kAdnEnableFullDebugging; AdnDebugEnableSet(flags)

See Also

AdnDebugEnableSet

AdnDebugEnableGetSupported Macro ^TOP^

Purpose

This macro returns flags indicating which debugging features are supported.

Declared In

AdnDebugMgr.h

Prototype

#define AdnDebugEnableGetSupported ()

Parameters

None.

Returns

UInt32 made up of kAdnEnable flags as defined in "Debugging Constants".

AdnDebugEnableSet Macro ^TOP^

Purpose

This macro enables the debugging features indicated by the parameter flags.

Declared In

AdnDebugMgr.h

Prototype

#define AdnDebugEnableSet (
   UInt32 flags
)

Parameters

flags
kAdnEnable flags as defined in "Debugging Constants"

Returns

Nothing.

Comments

The ARM debugger nub is not active on an ARM-based device until an application activates it. The ARM subroutine must first enable the ARM debugger nub by calling the macro AdnDebugEnableSet().

See Also

AdnDebugEnableGet

AdnDebugLicenseeSpecific Macro ^TOP^

Purpose

This macro makes a licensee-specific call to AdnDebug Manager.

Declared In

AdnDebugMgr.h

Prototype

#define AdnDebugLicenseeSpecific (
   oemID,
    selector,
    param
)

Parameters

oemID
PalmSource-registered OEM ID (creator ID)
selector
Licensee-specific function selector.
param
Function-specific parameter.

Returns

Returns -1 if the licensee-specific function in not supported.

AdnDebugMessage Macro ^TOP^

Purpose

This macro displays a debug message in the debugger.

Declared In

AdnDebugMgr.h

Prototype

#define AdnDebugMessage (
   messageP
)

Parameters

messageP
A pointer to a sequence of ASCII characters terminated by a null character (the string that is displayed in the debugger).

Returns

Nothing.

Comments

This macro is the ARM-based equivalent to the Debug Manager call DbgMessage().

AdnDebugMessageIf Macro ^TOP^

Purpose

This macro displays a debug message in the debugger if the condition specified by the condition parameter is true.

Declared In

AdnDebugMgr.h

Prototype

#define AdnDebugMessageIf (
   condition,
    messageP
)

Parameters

condition
A boolean value.
messageP
A pointer to a sequence of ASCII characters terminated by a null character (the string that is displayed in the debugger).

Returns

Nothing.

See Also

AdnDebugMessage

AdnDebugNativeRegister Macro ^TOP^

Purpose

This macro registers a PACE native object with the debugger.

Declared In

AdnDebugMgr.h

Prototype

#define AdnDebugNativeRegister (
   dbType,
    dbCreator,
    rsrcType,
    rsrcID
) 

Parameters

dbType
The application database type (for example, 'appl').
dbCreator
The application database's creator code.
rsrcType
The PACE native object's resource type (for example, 'ARMC').
rsrcID
The PACE native object's resource ID.

Returns

Nothing.

Comments

The flag kAdnEnableFullDebugging must be set using AdnDebugEnableSet in order for AdnDebugNativeRegister() calls to be processed correctly.

See Also

AdnDebugEnableSet

AdnDebugNativeRegisterAddr Macro ^TOP^

Purpose

This macro registers a PACE native object with the debugger. This version can be used for code that is in a chunk separate from the application. Most PACE native objects can use the simpler form, AdnDebugNativeRegister.

Declared In

AdnDebugMgr.h

Prototype

#define AdnDebugNativeRegisterAddr (
   dbType,
    dbCreator,
    rsrcType,
    rsrcID,
    codeAddr
)

Parameters

dbType
The application database type (for example, 'appl').
dbCreator
The application database's creator code.
rsrcType
The PACE native's object resource type (for example, 'ARMC').
rsrcID
The PACE native's object resource ID.
codeAddr
The PACE native object's code base address.

Returns

Nothing.

Comments

The flag kAdnEnableFullDebugging must be set using AdnDebugEnableSet in order for AdnDebugNativeRegisterAddr() calls to be processed correctly.

AdnDebugNativeUnregister Macro ^TOP^

Purpose

This macro unregisters a PACE native object with the debugger.

Declared In

AdnDebugMgr.h

Prototype

#define AdnDebugNativeUnregister ()

Parameters

None.

Returns

Nothing.

Comments

You should call this macro prior to unlocking the PACE native object code resource so that the debugger breakpoints can be removed.

See Also

AdnDebugNativeRegister, AdnDebugNativeRegisterAddr

AdnDebugNativeUnregisterAddr Macro ^TOP^

Purpose

This macro unregisters a PACE native object with the debugger.

Declared In

AdnDebugMgr.h

Prototype

#define AdnDebugNativeUnregisterAddr (
   rsrcID
)

Parameters

rsrcID
A pointer to the DbgPostUnloadParamsType structure.

Returns

Nothing.

Comments

You should call this macro prior to unlocking the PACE native object code resource so that the debugger breakpoints can be removed.

See Also

AdnDebugNativeRegister, AdnDebugNativeRegisterAddr

AdnDebugUpdateLoadedModules Macro ^TOP^

Purpose

Notify Palm OS Debugger of any recently loaded or unloaded native modules. This call is not used for debugging PACE native objects.

Declared In

AdnDebugMgr.h

Prototype

#define AdnDebugUpdateLoadedModules ()

Parameters

None.

Returns

Nothing.