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

31    Debug Manager

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

The Debug Manager provides a set of debugger functions that go above and beyond what is provided in ROM.

Debug Manager Structures and Types
Debug Manager Constants
Debug Manager Functions and Macros
Application-Defined Functions

The header file DebugMgr.h declares the API that this chapter describes.

Debug Manager Structures and Types ^TOP^

DbgCtlEnumInfoType Struct ^TOP^

Purpose

Declared In

DebugMgr.h

Prototype

typedef struct DbgCtlEnumInfoType {
DbgCtlEnumCallbackFunc *enumFuncP;
void *callbackDataP;
} DbgCtlEnumInfoType

Fields

enumFuncP
callbackDataP

Comments

DbgCtlHandlerInfoType Struct ^TOP^

Purpose

Declared In

DebugMgr.h

Prototype

typedef struct DbgCtlHandlerInfoType {
DbgControlFuncType *handlerFuncP;
UInt32 version;
Boolean enabled;
Char name[dbgCtlHandlerNameLen+1];
Char ver[dbgCtlHandlerVerLen+1];
UInt8 reserved1;
UInt32 dwReserved;
} DbgCtlHandlerInfoType

Fields

handlerFuncP
Pointer to the handler's DbgControl() function. This function's prototype must match that declared by DbgControlFuncType().
version
Numeric version number (handler-defined).
enabled
true if the handler is enabled; false if it isn't.
name
Null-terminated handler name. This name should not exceed dbgCtlHandlerNameLen characters in length (not counting the null terminator).
ver
Null-terminated handler version string. This string should not exceed dbgCtlHandlerVerLen characters in length (not counting the null terminator).
reserved1
Reserved for future use.
dwReserved
Reserved field. The caller must initialize this field to zero.

Debug Manager Constants ^TOP^

DbgControl() Constants ^TOP^

Purpose

Constants used in conjunction with DbgControl().

Declared In

DebugMgr.h

Constants

extern DbgControlFuncType DbgControl
#define dbgCtlAllHandlersID 0
Value that can be supplied to DbgControlFuncType() to indicate that the operation is to be handled by all handlers.
#define dbgCtlFirstCustomOp 0x8000
Debug handler operations are numbered beginning with this value. The system reserves all operation number values less than this one.
#define dbgCtlHandled true
Value returned by DbgControlFuncType() to indicate that the debug control operation was handled.
#define dbgCtlHandlerNameLen 31
Maximum handler name length, not including the terminating null character.
#define dbgCtlHandlerVerLen 15
Maximum handler version string length, not including the terminating null character.
#define dbgCtlNotHandled false
Value returned by DbgControlFuncType() to indicate that the debug control operation was not handled.

System-Defined Debug Control Operations Enum ^TOP^

Purpose

Opcodes for system-defined debug control operations. These values are passed in the op parameter of the DbgControlFuncType() function.

Declared In

DebugMgr.h

Constants

dbgCtlOpEnumHandlers = 1
Enumerate all handlers. The handlerID parameter must be set to dbgCtlAllHandlersID.
dbgCtlOpGetHandlerInfo
Get information about a specific handler.
dbgCtlOpEnableHandler
Enable the specified handler. dbgCtlAllHandlersID can be supplied for the handlerID parameter to enable all handlers. The paramP and dwParamP parameters are ignored.
dbgCtlOpDisableHandler
Disable the specified handler. dbgCtlAllHandlersID can be supplied for the handlerID parameter to disable all handlers. The paramP and dwParamP parameters are ignored.
dbgCtlOpGetEnabledStatus
Determine whether a specific handler is enabled. When making this call, dwParamP should point to a UInt32 that will be set to a non-zero value if the handler is enabled, or to zero if it is disabled. The paramP parameter is ignored.
dbgCtlOpGetVersion
Obtain the version number for a specific handler. When making this call, dwParamP should point to a UInt32 that will receive the handler's version number. The paramP parameter is ignored.
dbgCtlOpLAST
Not a valid operation code, this value represents the next unused operation code value.

Debug Manager Functions and Macros ^TOP^

DbgBreak Function ^TOP^

Purpose

Connects to the assembly-level debugger and halts execution.

Declared In

DebugMgr.h

Prototype

voidDbgBreak (
   void
)

Parameters

None.

Returns

Nothing.

See Also

DbgSrcBreak()

DbgCommSettings Function ^TOP^

Purpose

Retrieve or change the communications settings used by the debugger.

Declared In

DebugMgr.h

Prototype

ErrDbgCommSettings (
   UInt32*baudP,
   UInt32*flagsP
)

Parameters

baudP
To retrieve the current settings, set *baudP to zero. Upon return, *baudP will contain the current baud rate. To change the current settings, set *baudP to the new baud rate.
flagsP
If *baudP is set to zero, the communications settings flags are retrieved along with the baud rate and stored in *flagsP. If *baudP is nonzero, *flagsP should contain the desired communications settings flags; see "Serial Settings Constants" for the set of flags that can be combined to make up *flagsP.

Returns

errNone if the operation completed successfully, or serErrNotOpen if the debugger communications library is not open.

DbgGetMessage Function ^TOP^

Purpose

Wait for, and then retrieve, a message packet from the host.

Declared In

DebugMgr.h

Prototype

Char*DbgGetMessage (
   UInt8*bufferP,
   Int32timeout
)

Parameters

bufferP
Pointer to a pre-allocated buffer into which the message is to be written. When allocating memory for this buffer , note that it must be at least sysPktMaxBodySize bytes in length.
timeout
Maximum number of system ticks to wait for the beginning of the packet. A timeout value of -1 means that the function should wait forever.

Returns

A pointer to the start of the text in the received packet, or zero if an error occurred. Note that the returned pointer will not be the same as the supplied buffer pointer.

Comments

Use this function to obtain text input from the serial port.

See Also

DbgMessage()

DbgInit Function ^TOP^

Purpose

Initialize the debugger and the debugger's serial port.

Declared In

DebugMgr.h

Prototype

Int32DbgInit (
   MemPtrspaceP,
   MemPtrdispatchTableP[],
   BooleanopenComm
)

Parameters

spaceP
Pointer to a pre-allocated block of memory to be used for debugger globals. This block of memory should be at least 64 bytes in length.
dispatchTableP
Pointer to system dispatch table, where debugger traps get installed.
openComm
Pass true to open communications and display a welcome message, or false to skip this step.

Returns

The number of bytes used for globals.

Comments

This function is called for you at boot time. Applications do not need to call this function.

DbgMessage Function ^TOP^

Purpose

Sends a null-terminated string to the current debug device.

Declared In

DebugMgr.h

Prototype

voidDbgMessage (
   constChar*aStr
)

Parameters

aStr
The null-terminated string to be sent to the current debug device.

Returns

Nothing.

See Also

DbgGetMessage(), DbgSrcMessage()

DbgSrcBreak Function ^TOP^

Purpose

Connects to the source-level debugger and halts execution.

Declared In

DebugMgr.h

Prototype

voidDbgSrcBreak (
   void
)

Parameters

None.

Returns

Nothing.

See Also

DbgBreak()

DbgSrcMessage Function ^TOP^

Purpose

Displays a message to the source-level debugger.

Declared In

DebugMgr.h

Prototype

voidDbgSrcMessage (
   constChar*debugStr
)

Parameters

debugStr
A null-terminated string.

Returns

Nothing.

See Also

DbgMessage()

Application-Defined Functions ^TOP^

DbgControlFuncType Function ^TOP^

Purpose

Debug control function for implementing debug tracing and other such functions via debug handlers. The system's default implementation of this function (named DbgControl()) does nothing, simply returning dbgCtlNotHandled.

Declared In

DebugMgr.h

Prototype

BooleanDbgControlFuncType (
   UInt32handlerID,
   UInt16op,
   void*paramP,
   UInt32*dwParamP
)

Parameters

handlerID
ID of the debug handler that is to handle this call. A value of dbgCtlAllHandlersID indicates that each handler is to execute the specified operation and then pass the call down the chain for the next handler to execute.
op
Operation ID specific to the handler specified by handlerID. See "System-Defined Debug Control Operations" for a number of operation IDs defined by the system.
paramP
pointer to data specific to the reqested operation.
dwParamP
Pointer to a UInt32 value specific to the requested operation.

Returns

dbgCtlHandled if the specified handler handled the requested operation, or dbgCtlNotHandled if it didn't.

Comments

The default implementation does nothing, leaving the real work up to "debug handlers." Debug handlers will be implemented as system extensions. As they are loaded, extensions will override the DbgControl() function call and chain to those handlers loaded before them.

When a debug control call is made by the client, a handler ID of the handler that implements the functionality is passed in as the first parameter. The handler ID is the unique creator ID of the handler. When a handler is called, it will first examine the handler ID: if it matches its own, the handler will execute the command and return; if the handler ID does not match, the handler must pass the call down the chain and return the value from that call.

The operation to be performed is indicated by the parameter op. Operation codes are specific to each handler, meaning that that the same operation code values may be used by different handlers. Operation code values defined by handlers must begin at dbgCtlFirstCustomOp. The special handler ID of dbgCtlAllHandlersID applies to all handlers. When this handler ID is passed, each handler is responsible for executing the requested action and then passing the call down the chain.

The last two parameters are defined by each handler for its own operations.

DbgCtlEnumCallbackFunc Function ^TOP^

Purpose

Declared In

DebugMgr.h

Prototype

voidDbgCtlEnumCallbackFunc (
   void*callbackDataP,
   UInt32handlerID,
   DbgControlFuncType*handlerFuncP
)

Parameters

callbackDataP
handlerID
handlerFuncP

Returns

Nothing.