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
In order to debug your ARM-based code, your application needs to do the following:
Activate the ARM Debugger Nub
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
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
Debugging Constants
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 catchesErrFatalDisplay()
calls. - When the master switch is disabled, the you are limited to calling the
AdnDebugEnableSet()
andAdnDebugEnableGet()
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
AdnDebugBreak Macro
Purpose
Break into Palm OS Debugger from the ARM subroutine.
Declared In
AdnDebugMgr.h
Prototype
#define AdnDebugBreak ()
Parameters
Returns
Comments
This macro is the ARM-based equivalent to the Debug Manager call DbgBreak()
.
AdnDebugEnableGet Macro
Purpose
This macro returns flags indicating which debugging features are enabled.
Declared In
AdnDebugMgr.h
Prototype
#define AdnDebugEnableGet ()
Parameters
Returns
UInt32 representing flags as defined in "Debugging Constants".
Example
UInt32 flags = AdnDebugEnableGet(); flags |= kAdnEnableMasterSwitch | kAdnEnableFullDebugging; AdnDebugEnableSet(flags)See Also
AdnDebugEnableGetSupported Macro
Purpose
This macro returns flags indicating which debugging features are supported.
Declared In
AdnDebugMgr.h
Prototype
#define AdnDebugEnableGetSupported ()
Parameters
Returns
UInt32
made up of kAdnEnable
flags as defined in "Debugging Constants".
AdnDebugEnableSet Macro
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
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
AdnDebugLicenseeSpecific Macro
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
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
Comments
This macro is the ARM-based equivalent to the Debug Manager call DbgMessage()
.
AdnDebugMessageIf Macro
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
See Also
AdnDebugNativeRegister Macro
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
Comments
The flag kAdnEnableFullDebugging
must be set using AdnDebugEnableSet
in order for AdnDebugNativeRegister()
calls to be processed correctly.
See Also
AdnDebugNativeRegisterAddr Macro
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
Comments
The flag kAdnEnableFullDebugging
must be set using AdnDebugEnableSet
in order for AdnDebugNativeRegisterAddr()
calls to be processed correctly.
AdnDebugNativeUnregister Macro
Purpose
This macro unregisters a PACE native object with the debugger.
Declared In
AdnDebugMgr.h
Prototype
#define AdnDebugNativeUnregister ()
Parameters
Returns
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
Purpose
This macro unregisters a PACE native object with the debugger.
Declared In
AdnDebugMgr.h
Prototype
#define AdnDebugNativeUnregisterAddr (
rsrcID
)
Parameters
Returns
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
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 ()