Part II: System Management

31 Debug Manager

Debug Manager Structures and Types

DbgCtlEnumInfoType

DbgCtlHandlerInfoType

Debug Manager Constants

DbgControl() Constants

System-Defined Debug Control Operations

Debug Manager Functions and Macros

DbgBreak

DbgCommSettings

DbgGetMessage

DbgInit

DbgMessage

DbgSrcBreak

DbgSrcMessage

Application-Defined Functions

DbgControlFuncType

DbgCtlEnumCallbackFunc

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

void DbgBreak (
   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

Err DbgCommSettings (
   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,
   Int32 timeout
)

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

Int32 DbgInit (
   MemPtr spaceP,
   MemPtr dispatchTableP[],
   Boolean openComm
)

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

void DbgMessage (
   const Char *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

void DbgSrcBreak (
   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

void DbgSrcMessage (
   const Char *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

Boolean DbgControlFuncType (
   UInt32 handlerID,
   UInt16 op,
   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

void DbgCtlEnumCallbackFunc (
   void *callbackDataP,
   UInt32 handlerID,
   DbgControlFuncType *handlerFuncP
)

Parameters

callbackDataP

→ handlerID

handlerFuncP

Returns

Nothing.