Part II: System Management

25 ARM Debug Nub

ARM Debug Nub Structures and Types

AdnDbgPostLoadParamsType

AdnDbgPostUnloadParamsType

ARM Debug Nub Constants

Debugging Feature Flags

Semihosting SWI Opcodes

Miscellaneous ARM Debug Nub Constants

ARM Debug Nub Functions and Macros

AdnDebugBreak

AdnDebugEnableGet

AdnDebugEnableGetSupported

AdnDebugEnableSet

AdnDebugLicenseeSpecific

AdnDebugMessage

AdnDebugMessageIf

AdnDebugNativeRegister

AdnDebugNativeRegisterAddr

AdnDebugNativeUnregister

AdnDebugNativeUnregisterAddr

AdnDebugUpdateLoadedModules

AdnGetNativeCodeBaseAddr

SetR10ToDataPointer

This chapter provides documentation for the ARM-based debugger nub. It is divided into the following sections:

ARM Debug Nub Structures and Types

ARM Debug Nub Constants

ARM Debug Nub Functions and Macros

The header file AdnDebugMgr.h declares the API that this chapter describes. These functions can be used within ARM subroutines, also called PACE native objects ("PNOs").

For more information on using the APIs described in this reference chapter, see "Using the ARM Debug Nub" of Chapter 15, "Debugging Strategies."

ARM Debug Nub Structures and Types ^TOP^

AdnDbgPostLoadParamsType Struct ^TOP^

Purpose

Parameter block that accompanies the _SemihostPostLoad() function. This structure is not normally used by third-party developers.

Declared In

AdnDebugMgr.h

Prototype

typedef struct _AdnDbgPostLoadParamsType {
   int32_t processID;
   uint32_t moduleID;
   void *codeAddr;
   void *dataAddr;
   uint32_t libType;
   uint32_t libCreator;
   uint32_t rsrcType;
   uint16_t rsrcID;
   uint16_t reserved;
} AdnDbgPostLoadParamsType

AdnDbgPostUnloadParamsType Struct ^TOP^

Purpose

Parameter block that accompanies the _SemihostPostUnload() function. This structure is not normally used by third-party developers.

Declared In

AdnDebugMgr.h

Prototype

typedef struct _AdnDbgPostUnloadParamsType {
   uint32_t processID;
   uint32_t moduleID;
} AdnDbgPostUnloadParamsType

ARM Debug Nub Constants ^TOP^

Debugging Feature Flags ^TOP^

Purpose

Flags supplied to AdnDebugEnableSet() and returned by AdnDebugEnableGet() and AdnDebugEnableGetSupported() that specify which debugging features are enabled.

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.

Semihosting SWI Opcodes ^TOP^

Purpose

Opcodes used to invoke various functions. Applications do not need to make use of these opcodes directly; the various macros described under "ARM Debug Nub Functions and Macros" use them to access the needed operating system functions.

Declared In

AdnDebugMgr.h

Constants

#define kAdnSemihostArmReportException 0x0018

#define kAdnSemihostArmWrite0 0x0004

#define kAdnSemihostDebugEnableGet 0x0153

#define kAdnSemihostDebugEnableGetSupported 0x0155

#define kAdnSemihostDebugEnableSet 0x0152

#define kAdnSemihostLicenseeSpecific 0x0154

#define kAdnSemihostNativeRegister 0x0150

#define kAdnSemihostNativeUnregister 0x0151

#define kAdnSemihostPUDConnect 0x0101

#define kAdnSemihostPUDDebugBreak 0x0132

#define kAdnSemihostPUDDownloadEvent 0x0140

#define kAdnSemihostPUDFaultNotification 0x0133

#define kAdnSemihostPUDModulePostLoad 0x0130

#define kAdnSemihostPUDModulePostUnload 0x0131

#define kAdnSemihostPUDModuleTableUpdate 0x0134

#define kAdnSemihostPUDProcessCreate 0x0110

#define kAdnSemihostPUDProcessDestroy 0x0111

#define kAdnSemihostPUDProfilerEvent 0x0141

#define kAdnSemihostPUDThreadCreate 0x0120

#define kAdnSemihostPUDThreadDestroy 0x0121

Miscellaneous ARM Debug Nub Constants ^TOP^

Purpose

Additional constants declared by the ARM debug nub header file AdnDebugMgr.h.

Declared In

AdnDebugMgr.h

Constants

#define adnFtrCreator 'adbg'

Creator ID of the ARM debug nub feature; if this feature is present, the value returned from a call to FtrGet() is the version of the ARM debug nub feature present on the device. See "ARM Debug Nub Feature Set" for an example of how to use this constant.

#define adnFtrNumVersion 0

Feature number that retrieves the version of the ARM debug nub feature. See "ARM Debug Nub Feature Set" for an example of how to use this constant.

#define kAdnErrUnsupportedCall 0xFFFFFFFF

Value returned by AdnDebugLicenseeSpecific() if the requested function is not supported by the device.

ARM Debug Nub 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().

Compatibility

Implemented only on devices running Palm OS Garnet or Palm OS Cobalt where the ARM Debug Nub Feature Set is present.

AdnDebugEnableGet Macro ^TOP^

Purpose

Determines which debugging features are enabled.

Declared In

AdnDebugMgr.h

Prototype

#define AdnDebugEnableGet ()

Parameters

None.

Returns

A UInt32 representing flags as defined under "Debugging Feature Flags".

Example

The following code obtains the current debugger settings and then updates them by setting addtional flags.

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

See Also

AdnDebugEnableGet(), AdnDebugEnableSet

Compatibility

Implemented only on devices running Palm OS Garnet or Palm OS Cobalt where the ARM Debug Nub Feature Set is present.

AdnDebugEnableGetSupported Macro ^TOP^

Purpose

Determines which debugging features are supported.

Declared In

AdnDebugMgr.h

Prototype

#define AdnDebugEnableGetSupported ()

Parameters

None.

Returns

A UInt32 representing flags as defined under "Debugging Feature Flags".

See Also

AdnDebugEnableGet()

Compatibility

Implemented only on devices running Palm OS Garnet or Palm OS Cobalt where the ARM Debug Nub Feature Set is present.

AdnDebugEnableSet Macro ^TOP^

Purpose

Enables the specified debugging features.

Declared In

AdnDebugMgr.h

Prototype

#define AdnDebugEnableSet (
   flags
)

Parameters

→ flags

kAdnEnable... flags as defined under "Debugging Feature Flags"

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 this macro.

See Also

AdnDebugEnableGet

Compatibility

Implemented only on devices running Palm OS Garnet or Palm OS Cobalt where the ARM Debug Nub Feature Set is present.

AdnDebugLicenseeSpecific Macro ^TOP^

Purpose

Makes a licensee-specific call to the ARM debug nub.

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 kAdnErrUnsupportedCall if the licensee-specific function in not supported.

Compatibility

Implemented only on devices running Palm OS Garnet or Palm OS Cobalt where the ARM Debug Nub Feature Set is present.

AdnDebugMessage Macro ^TOP^

Purpose

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

Compatibility

Implemented only on devices running Palm OS Garnet or Palm OS Cobalt where the ARM Debug Nub Feature Set is present.

AdnDebugMessageIf Macro ^TOP^

Purpose

Displays a debug message in the debugger if a specified condition 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

Compatibility

Implemented only on devices running Palm OS Garnet or Palm OS Cobalt where the ARM Debug Nub Feature Set is present.

AdnDebugNativeRegister Macro ^TOP^

Purpose

Registers a PACE native object (PNO) 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 PNO's resource type (for example, 'ARMC').

→ _rsrcID

The PNO's resource ID.

Returns

Nothing.

Comments

PNO registration should be done after locking the code. Any previously unresolved breakpoints will be activated.

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

See Also

AdnDebugNativeRegisterAddr(), AdnDebugNativeUnregister()

Compatibility

Implemented only on devices running Palm OS Garnet or Palm OS Cobalt where the ARM Debug Nub Feature Set is present.

AdnDebugNativeRegisterAddr Macro ^TOP^

Purpose

Registers a PACE native object (PNO) with the debugger. This version can be used for code that is in a chunk separate from the application. Most PNOs 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 PNO's resource type (for example, 'ARMC').

→ _rsrcID

The PNO's resource ID.

→ _codeAddr

The PNO's code base address.

Returns

Nothing.

Comments

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

See Also

AdnDebugNativeRegister(), AdnDebugNativeUnregisterAddr()

Compatibility

Implemented only on devices running Palm OS Garnet or Palm OS Cobalt where the ARM Debug Nub Feature Set is present.

AdnDebugNativeUnregister Macro ^TOP^

Purpose

Ask the debugger to unregister the PACE native object (PNO) invoking this macro.

Declared In

AdnDebugMgr.h

Prototype

#define AdnDebugNativeUnregister ()

Parameters

None.

Returns

Nothing.

Comments

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

To unregister a PNO other than the one invoking this macro, use AdnDebugNativeUnregisterAddr(). AdnDebugNativeUnregister() invokes AdnGetNativeCodeBaseAddr() in order to determine the base address of the PNO to be unregistered.

See Also

AdnDebugNativeRegister(), AdnDebugNativeUnregisterAddr()

Compatibility

Implemented only on devices running Palm OS Garnet or Palm OS Cobalt where the ARM Debug Nub Feature Set is present.

AdnDebugNativeUnregisterAddr Macro ^TOP^

Purpose

Ask the debugger to unregister a PACE native object (PNO) identified by its code base address.

Declared In

AdnDebugMgr.h

Prototype

#define AdnDebugNativeUnregisterAddr (
   _codeAddr
)

Parameters

→ _codeAddr

PNO code base address.

Returns

Nothing.

Comments

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

Generally, PNOs which are unregistering themselves should use the simpler form, AdnDebugNativeUnregister(). AdnDebugNativeUnregisterAddr() is useful in the case where the code making this call needs to unregister native code that lives elsewhere (for example, in a different chunk), and thus AdnGetNativeCodeBaseAddr() won't retrieve the correct code base address.

See Also

AdnDebugNativeRegisterAddr()

Compatibility

Implemented only on devices running Palm OS Garnet or Palm OS Cobalt where the ARM Debug Nub Feature Set is present.

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

Declared In

AdnDebugMgr.h

Prototype

#define AdnDebugUpdateLoadedModules ()

Parameters

None.

Returns

Nothing.

Compatibility

Implemented only on devices running Palm OS Garnet or Palm OS Cobalt where the ARM Debug Nub Feature Set is present.

AdnGetNativeCodeBaseAddr Macro ^TOP^

Purpose

Obtain the code base address for a PACE native object (PNO).

Declared In

AdnDebugMgr.h

Prototype

#define AdnGetNativeCodeBaseAddr ()

Parameters

None.

Returns

The invoking PNO's code base address.

Comments

This macro is used by AdnDebugNativeRegister() and AdnDebugNativeUnregister() to obtain the PNO's code base address.

Compatibility

Implemented only on devices running Palm OS Garnet or Palm OS Cobalt where the ARM Debug Nub Feature Set is present.

SetR10ToDataPointer Macro ^TOP^

Purpose

Helper routine that sets register r10 to point to your data section (the GOT from gcc).

Declared In

AdnDebugMgr.h

Prototype

#define SetR10ToDataPointer (
   ptr
)

Parameters

→ ptr

Pointer to your data section; r10 is set to this value.

Returns

Nothing.

Comments

This macro is only useful if you have compiled your code to be r10-relative.

Compatibility

Implemented only on devices running Palm OS Garnet or Palm OS Cobalt where the ARM Debug Nub Feature Set is present.