NAME

WDB_CONTEXT_CONT - continue a context

SYNOPSIS

INPUT: WDB_CTX
OUTPUT: (

DESCRIPTION

This routine continues a context that has been suspended or has hit a breakpoint. The input parameters are specified in WDB_CTX:

typedef struct wdb_ctx			/* a particular context */
    {
    WDB_CTX_TYPE	contextType;	/* type of context */
    UINT32		contextId;	/* context ID */
    } WDB_CTX;

If contextType is WDB_CTX_SYSTEM, the system context is continued. (This only makes sense if the agent is in system mode.) If contextType is WDB_CTX_TASK, the task whose ID is contextId is continued.

ERRORS

WDB_ERR_AGENT_MODE

Attempting to continue a task from system mode or the system from task mode.

WDB_ERR_INVALID_CONTEXT

The context does not exist.

WDB_ERR_NO_RT_PROC

The agent does not support this service.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_CONTEXT_CREATE

NAME

WDB_CONTEXT_CREATE - create a context on the target

SYNOPSIS

INPUT: WDB_CTX_CREATE_DESC
OUTPUT: UINT32

DESCRIPTION

This routine creates a context on the target as specified in WDB_CTX_CREATE_DESC:

typedef struct wdb_ctx_create_desc	/* how to create a context */
    {
    WDB_CTX_TYPE	contextType;	/* task or system context */

    /* the following are used for task and system contexts */

    TGT_ADDR_T		stackBase;	/* bottom of stack (NULL = malloc) */
    UINT32		stackSize;	/* stack size */
    TGT_ADDR_T 		entry;		/* context entry point */
    TGT_INT_T		args[10];	/* arguments */

    /* the following are only used for task contexts */

    WDB_STRING_T	name;		/* name */
    TGT_INT_T		priority;	/* priority */
    TGT_INT_T		options;	/* options */
    TGT_INT_T		redirIn;	/* redirect input file (or 0) */
    TGT_INT_T		redirOut;	/* redirect output file (or 0) */
    TGT_INT_T		redirErr;	/* redirect error output file (or 0) */
    } WDB_CTX_CREATE_DESC;

where WDB_CTX_TYPE is one of the following:

typedef enum wdb_ctx_type		/* type of context on the target */
    {
    WDB_CTX_SYSTEM	= 0,		/* system mode */
    WDB_CTX_GROUP	= 1,		/* process group (not implemented) */
    WDB_CTX_ANY		= 2,		/* any context (not implemented) */
    WDB_CTX_TASK	= 3,		/* specific task or processes */
    WDB_CTX_ANY_TASK	= 4,		/* any task */
    WDB_CTX_ISR		= 5,		/* specific ISR (not implemented) */
    WDB_CTX_ANY_ISR	= 6		/* any ISR (not implemented) */
    } WDB_CTX_TYPE;

The output value is the task ID of the new task.

ERRORS

WDB_ERR_RT_ERROR

The task creation failed.

WDB_ERR_NO_AGENT_PROC

The agent is in external mode (the version 1.0 external-mode agent does not support context creation).

WDB_ERR_NO_RT_PROC

The agent does not support this service.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_CONTEXT_KILL

NAME

WDB_CONTEXT_KILL - kill a context on the target

SYNOPSIS

INPUT: WDB_CTX
OUTPUT: (

DESCRIPTION

This routine kills the context specified in WDB_CTX:

typedef struct wdb_ctx			/* a particular context */
    {
    WDB_CTX_TYPE	contextType;	/* type of context */
    UINT32		contextId;	/* context ID */
    } WDB_CTX;

If contextType is WDB_CTX_SYSTEM, the "system context" is killed. (This means VxWorks is rebooted.) Otherwise the task whose ID is contextId is killed.

ERRORS

WDB_ERR_AGENT_MODE

Trying to kill a task while in system mode.

WDB_ERR_INVALID_CONTEXT

The context does not exist.

WDB_ERR_NO_RT_PROC

The agent does not support this service.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_CONTEXT_RESUME

NAME

WDB_CONTEXT_RESUME - resume a context on the target

SYNOPSIS

INPUT: WDB_CTX
OUTPUT: (

DESCRIPTION

This routine resumes the target context specified by WDB_CTX:

typedef struct wdb_ctx			/* a particular context */
    {
    WDB_CTX_TYPE	contextType;	/* type of context */
    UINT32		contextId;	/* context ID */
    } WDB_CTX;

If contextType is WDB_CTX_SYSTEM, the "system context" is resumed (in other words, VxWorks is resumed). Otherwise the task whose ID is contextId is resumed.

ERRORS

WDB_ERR_AGENT_MODE

Trying to resume a task while in system mode.

WDB_ERR_INVALID_CONTEXT

The context does not exist.

WDB_ERR_NO_RT_PROC

The agent does not support this service.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_CONTEXT_STATUS_GET

NAME

WDB_CONTEXT_STATUS_GET - get the context of a status on the target

SYNOPSIS

INPUT: )
OUTPUT: INPUT:

DESCRIPTION

This request returns the status of the target context specified by WDB_CTX:

typedef struct wdb_ctx			/* a particular context */
    {
    WDB_CTX_TYPE	contextType;	/* type of context */
    UINT32		contextId;	/* context ID */
    } WDB_CTX;

If contextType is WDB_CTX_SYSTEM, we get the status of the "system context". At present, this request is only implemented for the "system context".

The return value can be :

WDB_CTX_RUNNING

The target context is running.

WTX_CONTEXT_SUSPENDED

The target context is suspended.

ERRORS

WDB_ERR_AGENT_MODE

Trying to get the status of a context other than the system context.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_CONTEXT_STEP

NAME

WDB_CONTEXT_STEP - single step a context

SYNOPSIS

INPUT: WDB_CTX_STEP_DESC
OUTPUT: (

DESCRIPTION

This routine single steps a context. The context is defined by WDB_CTX_STEP_DESC:

typedef struct wdb_ctx_step_desc	/* how to single step a context */
    {
    WDB_CTX		context;	/* context to step */
    TGT_ADDR_T		startAddr;	/* lower bound of step range */
    TGT_ADDR_T 		endAddr;	/* upper bound of step range */
    } WDB_CTX_STEP_DESC;

where WDB_CTX describes the context to step:

typedef struct wdb_ctx			/* a particular context */
    {
    WDB_CTX_TYPE	contextType;	/* type of context */
    UINT32		contextId;	/* context ID */
    } WDB_CTX;

startAddr and endAddr specify the range of instructions to step over. If startAddr and endAddr both equal 0, then one instruction is stepped. Otherwise stepping occurs until the pointer is out of the step range.

NOTE

When the step completes, notification occurs by issuing an asynchronous event of type WDB_EVT_BP. See WDB_EVENT_GET for details.

ERRORS

WDB_ERR_AGENT_MODE

Trying to step a task in system mode or trying to step the system in task mode.

WDB_ERR_INVALID_CONTEXT

Trying to step an invalid context.

WDB_ERR_NO_RT_PROC

The agent does not support this service.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_CONTEXT_SUSPEND

NAME

WDB_CONTEXT_SUSPEND - suspend a context on the target

SYNOPSIS

INPUT: WDB_CTX
OUTPUT: (

DESCRIPTION

This routine suspends the target context specified by WDB_CTX:

typedef struct wdb_ctx			/* a particular context */
    {
    WDB_CTX_TYPE	contextType;	/* type of context */
    UINT32		contextId;	/* context ID */
    } WDB_CTX;

where WDB_CTX_TYPE is one of the following:

typedef enum wdb_ctx_type		/* type of context on the target */
    {
    WDB_CTX_SYSTEM	= 0,		/* system mode */
    WDB_CTX_GROUP	= 1,		/* process group (not implemented) */
    WDB_CTX_ANY		= 2,		/* any context (not implemented) */
    WDB_CTX_TASK	= 3,		/* specific task or processes */
    WDB_CTX_ANY_TASK	= 4,		/* any task */
    WDB_CTX_ISR		= 5,		/* specific ISR (not implemented) */
    WDB_CTX_ANY_ISR	= 6		/* any ISR (not implemented) */
    } WDB_CTX_TYPE;

If contextType is WDB_CTX_SYSTEM, the "system context" is suspended (in other words, VxWorks is suspended). Otherwise the task whose ID is contextId is suspended.

ERRORS

WDB_ERR_AGENT_MODE

Trying to suspend a task while in system mode

WDB_ERR_INVALID_CONTEXT

The context does not exist.

WDB_ERR_NO_RT_PROC

The agent does not support this service.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_DIRECT_CALL

NAME

WDB_DIRECT_CALL - call a function on the target in the agent's context

SYNOPSIS

INPUT: WDB_CTX_CREATE_DESC
OUTPUT: UINT32

DESCRIPTION

This routine calls the specified function in the target agent's context and waits for the function to return. The function is specified by the entry and args[10] members of WDB_CTX_CREATE_DESC. The other members are ignored and are set to NULL.

typedef struct wdb_ctx_create_desc	/* how to create a context */
    {
    WDB_CTX_TYPE	contextType;	/* task or system context */

    /* the following are used for task and system contexts */

    TGT_ADDR_T		stackBase;	/* bottom of stack (NULL = malloc) */
    UINT32		stackSize;	/* stack size */
    TGT_ADDR_T 		entry;		/* context entry point */
    TGT_INT_T		args[10];	/* arguments */

    /* the following are only used for task contexts */

    WDB_STRING_T	name;		/* name */
    TGT_INT_T		priority;	/* priority */
    TGT_INT_T		options;	/* options */
    TGT_INT_T		redirIn;	/* redirect input file (or 0) */
    TGT_INT_T		redirOut;	/* redirect output file (or 0) */
    TGT_INT_T		redirErr;	/* redirect error output file (or 0) */
    } WDB_CTX_CREATE_DESC;

The output contains the result of the function and is a UINT32.

ERRORS

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_EVALUATE_GOPHER

NAME

WDB_EVALUATE_GOPHER - execute a Gopher string

SYNOPSIS

INPUT: WDB_STRING_T
OUTPUT: WDB_MEM_XFER

DESCRIPTION

Gopher is a small, interpreted language that allows the traversal of simple data structures in target memory. This request sends the specified Gopher program to the target for evaluation and returns the result of the evaluation in a Gopher tape. The contents of the target memory specified by the Gopher program are written to the tape. For more information on the Gopher language, see the documentation of WTX_GOPHER_EVAL in the API Reference Manual: WTX Protocol or the discussion in the API User's Guide: The WTX Protocol. The string to be evaluated is passed in WDB_STRING_T.

The result of evaluating the Gopher string is returned in a WDB_MEM_XFER structure:

typedef struct wdb_mem_xfer		/* transfer a block of memory */
    {
    WDB_OPQ_DATA_T	source;		/* data to transfer */
    TGT_ADDR_T		destination;	/* requested destination */
    TGT_INT_T		numBytes;	/* number of bytes transferred */
    } WDB_MEM_XFER;

ERRORS

WDB_ERR_GOPHER_SYNTAX

The Gopher string is malformed.

WDB_ERR_GOPHER_FAULT

A memory fault occurred while executing the string.

WDB_ERR_GOPHER_TRUNCATED

The resulting reply was too large to upload.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB, WTX_GOPHER_EVAL

---

WDB Protocol : Requests

WDB_EVENTPOINT_ADD

NAME

WDB_EVENTPOINT_ADD - add an asynchronous eventpoint

SYNOPSIS

INPUT: WDB_EVTPT_ADD_DESC
OUTPUT: UINT32

DESCRIPTION

This routine adds an asynchronous eventpoint to the target. The type of event to add an eventpoint for is specified by WDB_EVTPT_ADD_DESC:

typedef struct wdb_evtpt_add_desc	/* how to add an eventpt */
    {
    WDB_EVT_TYPE	evtType;	/* type of event to detect */
    TGT_INT_T		numArgs;	/* eventType dependent arguments */
    UINT32  *  		args;		/* arg list */
    WDB_CTX		context;	/* context in which event must occur */
    WDB_ACTION 		action;		/* action to perform */
    } WDB_EVTPT_ADD_DESC;

where args points to an argument list and context is:

typedef struct wdb_ctx			/* a particular context */
    {
    WDB_CTX_TYPE	contextType;	/* type of context */
    UINT32		contextId;	/* context ID */
    } WDB_CTX;

WDB_ACTION is:

typedef struct wdb_action		/* a specific action */
    {
    WDB_ACTION_TYPE	actionType;
    UINT32		actionArg;
    TGT_ADDR_T		callRtn;
    TGT_INT_T		callArg;
    } WDB_ACTION;

and WDB_ACTION_TYPE is:

typedef enum wdb_action_type		/* what to do when an event occurs */
    {
    WDB_ACTION_CALL	= 1,		/* condition the evtpt via a proc */
    WDB_ACTION_NOTIFY	= 2,		/* notify the host */
    WDB_ACTION_STOP	= 4		/* stop the context */
    } WDB_ACTION_TYPE;

Currently, eventpoints can be added for the following event types:

WDB_EVT_BP

breakpoint

WDB_EVT_HW_BP

hardware breakpoint

WDB_EVT_CTX_EXIT

context exit

WDB_EVT_CTX_START

context creation

All possible event types are enumerated by WDB_EVT_TYPE:

typedef enum wdb_evt_type		/* type of event on the target */
    {
    WDB_EVT_NONE	= 0,		/* no event */
    WDB_EVT_CTX_START	= 1,		/* context creation */
    WDB_EVT_CTX_EXIT	= 2,		/* context exit */
    WDB_EVT_BP		= 3,		/* breakpoint */
    WDB_EVT_HW_BP	= 4,		/* hardware breakpoint */
    WDB_EVT_WP		= 5,		/* watchpoint */
    WDB_EVT_EXC		= 6,		/* exception */
    WDB_EVT_VIO_WRITE	= 7,		/* virtual I/O write */
    WDB_EVT_CALL_RET	= 8,		/* function call finished */
    WDB_EVT_TSFS_OP	= 9,		/* VIO II operation */
    WDB_EVT_USER	= 10		/* user event */
    } WDB_EVT_TYPE;

context specifies the context for which the event should be detected. Currently, contextType can be WDB_CTX_SYSTEM (for a system mode breakpoint), WDB_CTX_TASK (for a task-specific eventpoint), or WDB_CTX_ANY_TASK for a tasking breakpoint that applies to any task.

numArgs and args specify arguments to pass to the eventpoint. For WDB_EVT_CTX_EXIT and WDB_EVT_CTX_START eventpoints, numArgs should be zero. For WDB_EVT_BP, numArgs should be one or two, args[0] should be the breakpoint address and args[1] (optional) should be the breakpoint count. For WDB_EVT_HW_BP, numArgs should be three, args[0] should be the breakpoint address, args[1] should be the breakpoint count and args[2] should be the hardware breakpoint access type. For more informations on hardware breakpoint access type, refer to the WTX_EVENTPOINT_ADD_2 documentation.

action is set to the appropriate action to perform when the breakpoint is hit as defined by the structures WDB_ACTION and WDB_ACTION_TYPE in wdb.h.

The return value is an eventpoint ID, which is a handle to the eventpoint.

NOTES

1.

Context-specific eventpoints are automatically deleted when the context exits. Otherwise eventpoints are persistent until WDB_EVENTPOINT_DELETE is called to delete them.

2.

Tasking breakpoints are disabled if the agent switches to external mode (by way of WDB_MODE_SET), but are reenabled if the agent switches back again to tasking mode. Similarly, external-mode breakpoints are disabled if the agent switches to tasking mode and reenabled if the agent switches back again.

3.

When the eventpoint is hit, notification occurs as described in the "ASYNCHRONOUS NOTIFICATION SENT BY THE AGENT" section of the WDB man page. After being notified, the host uploads the event with the WDB_EVENT_GET procedure.

4.

A hardware breakpoints can generate WDB_EVT_BP if it is an instruction hardware breakpoint or WDB_EVT_WP if it is a data access breakpoint.

ERRORS

WDB_ERR_INVALID_EVENT

There is no handler for the specified event type.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_EVENTPOINT_DELETE

NAME

WDB_EVENTPOINT_DELETE - delete an eventpoint

SYNOPSIS

INPUT: WDB_EVTPT_DEL_DESC
OUTPUT: (

DESCRIPTION

This routine deletes the eventpoint specified by WDB_EVTPT_DEL_DESC:

typedef struct wdb_evtpt_del_desc	/* how to delete an eventpoint */
    {
    WDB_EVT_TYPE 	evtType;	/* type of event */
    TGT_ADDR_T	 	evtptId;	/* eventpoint ID */
    } WDB_EVTPT_DEL_DESC;

evtType specifies the type of eventpoint to delete. evtptId specifies the eventpoint to delete. (-1 means delete all eventpoints of the given type.)

NOTE

Context-specific eventpoints are automatically deleted when the context exits. Otherwise eventpoints are persistent until WDB_EVENTPOINT_DELETE is called to delete them.

ERRORS

WDB_ERR_INVALID_EVENTPOINT

The eventpoint specified does not exist.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_EVENT_GET

NAME

WDB_EVENT_GET - upload an event from the target

SYNOPSIS

INPUT: )
OUTPUT: INPUT:

DESCRIPTION

This routine uploads an asynchronous target event to the host. The return value, WDB_EVT_DATA, is:

typedef struct wdb_evt_data		/* reply to a WDB_EVENT_GET */
    {
    WDB_EVT_TYPE 	evtType;	/* event type detected */
    union 				/* eventType specific info */
	{
	WDB_MEM_XFER		vioWriteInfo;	/* vio write event data */
	WDB_CALL_RET_INFO	callRetInfo;	/* call return event data */
	WDB_EVT_INFO		evtInfo;	/* any other event info */
	} eventInfo;
    } WDB_EVT_DATA;

The type of event uploaded can be determined by the value of evtType.

NOTE

It is not necessary to poll for target events. Notification of events is given as described in the "ASYNCHRONOUS NOTIFICATION SENT BY THE AGENT" section of the WDB man page. Call WDB_EVENT_GET to retrieve the event data after being notified that an event has occurred.

ERRORS

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_FUNC_CALL

NAME

WDB_FUNC_CALL - call a function on the target

SYNOPSIS

INPUT: WDB_CTX_CREATE_DESC
OUTPUT: UINT32

DESCRIPTION

This routine calls a function on the target. The call is not made directly by the WDB agent, but rather from a task created for the purpose. The WDB_CTX_CREATE_DESC structure describes how to create the context for invoking the function:

typedef struct wdb_ctx_create_desc	/* how to create a context */
    {
    WDB_CTX_TYPE	contextType;	/* task or system context */

    /* the following are used for task and system contexts */

    TGT_ADDR_T		stackBase;	/* bottom of stack (NULL = malloc) */
    UINT32		stackSize;	/* stack size */
    TGT_ADDR_T 		entry;		/* context entry point */
    TGT_INT_T		args[10];	/* arguments */

    /* the following are only used for task contexts */

    WDB_STRING_T	name;		/* name */
    TGT_INT_T		priority;	/* priority */
    TGT_INT_T		options;	/* options */
    TGT_INT_T		redirIn;	/* redirect input file (or 0) */
    TGT_INT_T		redirOut;	/* redirect output file (or 0) */
    TGT_INT_T		redirErr;	/* redirect error output file (or 0) */
    } WDB_CTX_CREATE_DESC;

The return value is the task ID of the task which executes the function. The actual return value of the function is passed back to the host as an asynchronous event of event type WDB_EVT_CALL_RET. See WDB_EVENT_GET for details.

ERRORS

WDB_ERR_AGENT_MODE

This command cannot be executed in system mode.

WDB_ERR_NO_RT_PROC

The agent does not support this service.

WDB_ERR_RT_ERROR

The runtime callouts failed.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_MEM_CACHE_TEXT_UPDATE

NAME

WDB_MEM_CACHE_TEXT_UPDATE - synchronize cache after writing to the target

SYNOPSIS

INPUT: WDB_MEM_REGION
OUTPUT: (

DESCRIPTION

This routine is used to synchronize the data and instruction caches after writing text to the target. WDB_MEM_REGION defines the input parameters:

typedef struct wdb_mem_region		/* a region of target memory */
    {
    TGT_ADDR_T		baseAddr;	/* memory region base address */
    TGT_INT_T		numBytes;	/* memory region size */
    UINT32		param;		/* proc dependent parameter */
    } WDB_MEM_REGION;

baseAddr and numBytes specify the region of memory to update.

ERRORS

WDB_ERR_MEM_ACCES

The memory region is invalid.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_MEM_CHECKSUM

NAME

WDB_MEM_CHECKSUM - checksum a block of target memory

SYNOPSIS

INPUT: WDB_MEM_REGION
OUTPUT: UINT32

DESCRIPTION

This request performs a standard TCP/IP checksum (it sums 16-bit words using one-compliment arithmetic and returns the one-compliment of the result).

typedef struct wdb_mem_region		/* a region of target memory */
    {
    TGT_ADDR_T		baseAddr;	/* memory region base address */
    TGT_INT_T		numBytes;	/* memory region size */
    UINT32		param;		/* proc dependent parameter */
    } WDB_MEM_REGION;

where baseAddr and numBytes specify the source region. The checksum is returned as a 32-bit integer.

ERRORS

WDB_ERR_MEM_ACCES

The target memory cannot be read.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_MEM_FILL

NAME

WDB_MEM_FILL - fill target memory with a pattern

SYNOPSIS

INPUT: WDB_MEM_REGION
OUTPUT: (

DESCRIPTION

This request fills the specified area of target memory with a pattern. The input parameter is WDB_MEM_REGION:

typedef struct wdb_mem_region		/* a region of target memory */
    {
    TGT_ADDR_T		baseAddr;	/* memory region base address */
    TGT_INT_T		numBytes;	/* memory region size */
    UINT32		param;		/* proc dependent parameter */
    } WDB_MEM_REGION;

baseAddr and numBytes specify the region of target memory to fill. param specifies the 4-byte pattern used to fill the region.

ERRORS

WDB_ERR_MEM_ACCES

The target memory cannot be written.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_MEM_MOVE

NAME

WDB_MEM_MOVE - move memory on the target

SYNOPSIS

INPUT: WDB_MEM_REGION
OUTPUT: (

DESCRIPTION

This routine requests the agent to move the contents of the specified area of memory to another memory location. WDB_MEM_REGION specifies the various parameters:

typedef struct wdb_mem_region		/* a region of target memory */
    {
    TGT_ADDR_T		baseAddr;	/* memory region base address */
    TGT_INT_T		numBytes;	/* memory region size */
    UINT32		param;		/* proc dependent parameter */
    } WDB_MEM_REGION;

where baseAddr and numBytes specify the source region and param specifies where to move the contents to.

ERRORS

WDB_ERR_MEM_ACCES

The target memory cannot be read/written.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_MEM_PROTECT

NAME

WDB_MEM_PROTECT - write enable/disable a region of target memory

SYNOPSIS

INPUT: WDB_MEM_REGION
OUTPUT: (

DESCRIPTION

This request enables or disables write protection for a region of target memory. The input parameters are contained in WDB_MEM_REGION:

typedef struct wdb_mem_region		/* a region of target memory */
    {
    TGT_ADDR_T		baseAddr;	/* memory region base address */
    TGT_INT_T		numBytes;	/* memory region size */
    UINT32		param;		/* proc dependent parameter */
    } WDB_MEM_REGION;

baseAddr and numBytes specify the region of target memory affected. To write-enable the region, set param to 0. To write-protect the region, set param to a non-zero value.

NOTE

This routine will affect an entire MMU page on the target.

ERRORS

WDB_ERR_NO_RT_PROC

The target runtime has no procedure to support write protection.

WDB_ERR_MEM_ACCES

The protection routine failed.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_MEM_READ

NAME

WDB_MEM_READ - read memory from the target

SYNOPSIS

INPUT: WDB_MEM_REGION
OUTPUT: WDB_MEM_XFER

DESCRIPTION

This request reads the contents of a specified target memory region to a host buffer. The region to read is specified by WDB_MEM_REGION:

typedef struct wdb_mem_region		/* a region of target memory */
    {
    TGT_ADDR_T		baseAddr;	/* memory region base address */
    TGT_INT_T		numBytes;	/* memory region size */
    UINT32		param;		/* proc dependent parameter */
    } WDB_MEM_REGION;

where baseAddr is the starting address and numBytes is the number of bytes to read.

The memory is returned in WDB_MEM_XFER:

typedef struct wdb_mem_xfer		/* transfer a block of memory */
    {
    WDB_OPQ_DATA_T	source;		/* data to transfer */
    TGT_ADDR_T		destination;	/* requested destination */
    TGT_INT_T		numBytes;	/* number of bytes transferred */
    } WDB_MEM_XFER;

This structure should be initialized to point to a host buffer (or zero to malloc).

ERRORS

WDB_ERR_MEM_ACCES

The target memory cannot be read.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_MEM_SCAN

NAME

WDB_MEM_SCAN - scan a block of target memory for a pattern

SYNOPSIS

INPUT: WDB_MEM_SCAN_DESC
OUTPUT: TGT_ADDR_T

DESCRIPTION

This routine scans a block of target memory for a pattern. The input parameters are specified in WDB_MEM_SCAN_DESC:

typedef struct wdb_mem_scan_desc
    {
    WDB_MEM_REGION	memRegion;	/* region of memory to scan */
    WDB_MEM_XFER	memXfer;	/* pattern to scan for */
    } WDB_MEM_SCAN_DESC;

where WDB_MEM_REGION is:

typedef struct wdb_mem_region		/* a region of target memory */
    {
    TGT_ADDR_T		baseAddr;	/* memory region base address */
    TGT_INT_T		numBytes;	/* memory region size */
    UINT32		param;		/* proc dependent parameter */
    } WDB_MEM_REGION;

and WDB_MEM_XFER is:

typedef struct wdb_mem_xfer		/* transfer a block of memory */
    {
    WDB_OPQ_DATA_T	source;		/* data to transfer */
    TGT_ADDR_T		destination;	/* requested destination */
    TGT_INT_T		numBytes;	/* number of bytes transferred */
    } WDB_MEM_XFER;

memRegion specifies the region of target memory to search and memXfer specifies the pattern to search for. If numBytes is greater than 0, search forwards. Otherwise a backwards search is performed. If param is equal to 0, the search tries to match the pattern specified by source. Otherwise the search continues until the pattern does not match.

The return value is the address at which the match was found. TGT_ADDR_T is a type defined in host.h.

ERRORS

WDB_ERR_MEM_ACCES

The target memory cannot be read.

WDB_ERR_NOT_FOUND

The pattern cannot be found.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_MEM_WRITE

NAME

WDB_MEM_WRITE - write the contents of host memory to target memory

SYNOPSIS

INPUT: WDB_MEM_XFER
OUTPUT: (

DESCRIPTION

This request writes from host memory to target memory. The source is specified by WDB_MEM_XFER:

typedef struct wdb_mem_xfer		/* transfer a block of memory */
    {
    WDB_OPQ_DATA_T	source;		/* data to transfer */
    TGT_ADDR_T		destination;	/* requested destination */
    TGT_INT_T		numBytes;	/* number of bytes transferred */
    } WDB_MEM_XFER;

source is set to the address of a memory block on the host. numBytes indicates the number of bytes to transfer. destination points to a target address to which the memory contents should be transferred.

ERRORS

WDB_ERR_MEM_ACCES

The target memory cannot be written.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_MODE_GET

NAME

WDB_MODE_GET - get the agent mode

SYNOPSIS

INPUT: )
OUTPUT: INPUT:

DESCRIPTION

This request gets the agent mode. The return value can be either:

WDB_MODE_TASK

the agent runs as a task.

WDB_MODE_EXTERN

the agent runs in external mode.

ERRORS

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_MODE_SET

NAME

WDB_MODE_SET - set the agent mode

SYNOPSIS

INPUT: UINT32
OUTPUT: (

DESCRIPTION

This request sets the agent mode. The input parameter can be either:

WDB_MODE_TASK

the agent runs as a task.

WDB_MODE_EXTERN

the agent runs in external mode.

The agent can only perform external mode debugging if it is communicating using a driver that supports polled mode.

ERRORS

WDB_ERR_AGENT_MODE

The requested mode is not supported by the agent.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_REGS_GET

NAME

WDB_REGS_GET - get the registers of a context on the target

SYNOPSIS

INPUT: WDB_REG_READ_DESC
OUTPUT: WDB_MEM_XFER

DESCRIPTION

This routine gets the registers of the context specified by WDB_REG_READ_DESC:

typedef struct wdb_reg_read_desc	/* register data to read */
    {
    WDB_REG_SET_TYPE regSetType;	/* type of register set to read */
    WDB_CTX	     context;		/* context associated with registers */
    WDB_MEM_REGION   memRegion;		/* subregion of the register block */
    } WDB_REG_READ_DESC;

where WDB_CTX is:

typedef struct wdb_ctx			/* a particular context */
    {
    WDB_CTX_TYPE	contextType;	/* type of context */
    UINT32		contextId;	/* context ID */
    } WDB_CTX;

If contextType is WDB_CTX_SYSTEM the routine gets the VxWorks registers at the time the system-mode agent last stopped the system. (This only makes sense if you are doing external-mode debugging.) Otherwise the routine gets the registers of task contextId. regSetType determines the type of registers to get as specified by:

typedef enum wdb_reg_set_type		/* a type of register set */
    {
    WDB_REG_SET_IU	= 0,            /* integer unit register set */
    WDB_REG_SET_FPU	= 1,            /* floating point unit register set */
    WDB_REG_SET_MMU	= 2,            /* memory management unit reg set */
    WDB_REG_SET_CU	= 3,            /* cache unit register set */
    WDB_REG_SET_TPU	= 4,            /* timer processor unit register set */
    WDB_REG_SET_SYS	= 5		/* system registers */
    } WDB_REG_SET_TYPE;

Currently supported register sets include:

WDB_REG_SET_IU

integer unit register

WDB_REG_SET_FPU

floating point unit register set

The return structure WDB_MEM_XFER is:

typedef struct wdb_mem_xfer		/* transfer a block of memory */
    {
    WDB_OPQ_DATA_T	source;		/* data to transfer */
    TGT_ADDR_T		destination;	/* requested destination */
    TGT_INT_T		numBytes;	/* number of bytes transferred */
    } WDB_MEM_XFER;

source must point to a buffer on the host into which the contents of the register set can be copied. The register set is treated by the agent as an opaque block of memory; the bits are transferred with no swapping or other changes. The actual structure of the block is determined by the VxWorks data structures REG_SET and FPREG_SET. memRegion specifies the region within the block of memory to upload.

ERRORS

WDB_ERR_INVALID_PARAMS

The register-set type is unsupported.

WDB_ERR_NO_RT_PROC

The agent does not support this service.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_REGS_SET

NAME

WDB_REGS_SET - set the registers of a context on the target

SYNOPSIS

INPUT: WDB_REG_WRITE_DESC
OUTPUT: (

DESCRIPTION

This routine sets the registers of the context specified by WDB_REG_READ_DESC:

typedef struct wdb_reg_read_desc	/* register data to read */
    {
    WDB_REG_SET_TYPE regSetType;	/* type of register set to read */
    WDB_CTX	     context;		/* context associated with registers */
    WDB_MEM_REGION   memRegion;		/* subregion of the register block */
    } WDB_REG_READ_DESC;

where WDB_CTX is:

typedef struct wdb_ctx			/* a particular context */
    {
    WDB_CTX_TYPE	contextType;	/* type of context */
    UINT32		contextId;	/* context ID */
    } WDB_CTX;

If contextType is WDB_CTX_SYSTEM the routine sets the VxWorks registers at the time the system-mode agent last stopped the system. (This only makes sense if you are doing external mode debugging.) Otherwise the routine sets the registers of task contextId. regSetType determines the type of registers to set as specified by:

typedef enum wdb_reg_set_type		/* a type of register set */
    {
    WDB_REG_SET_IU	= 0,            /* integer unit register set */
    WDB_REG_SET_FPU	= 1,            /* floating point unit register set */
    WDB_REG_SET_MMU	= 2,            /* memory management unit reg set */
    WDB_REG_SET_CU	= 3,            /* cache unit register set */
    WDB_REG_SET_TPU	= 4,            /* timer processor unit register set */
    WDB_REG_SET_SYS	= 5		/* system registers */
    } WDB_REG_SET_TYPE;

Currently supported register sets include:

WDB_REG_SET_IU

integer unit register

WDB_REG_SET_FPU

floating point unit register set

The return structure WDB_MEM_XFER is:

typedef struct wdb_mem_xfer		/* transfer a block of memory */
    {
    WDB_OPQ_DATA_T	source;		/* data to transfer */
    TGT_ADDR_T		destination;	/* requested destination */
    TGT_INT_T		numBytes;	/* number of bytes transferred */
    } WDB_MEM_XFER;

The actual structure of the block is determined by the VxWorks data structures REG_SET and FPREG_SET. The memXfer field of WDB_REG_WRITE_DESC specifies where in the block to copy the data. The register set is treated by the agent as an opaque block of memory. source specifies a host buffer, which is copied exactly with no swapping or other changes. numBytes specifies the number of bytes of data to transfer. destination specifies the byte offset within the register block to copy to. This mechanism allows one to set all the registers at once or just a few registers at a time.

ERRORS

WDB_ERR_INVALID_PARAMS

The register-set type is unsupported.

WDB_ERR_NO_RT_PROC

The agent does not support this service.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_TARGET_CONNECT

NAME

WDB_TARGET_CONNECT - connect the target server to the target agent

SYNOPSIS

INPUT: )
OUTPUT: INPUT:

DESCRIPTION

This routine connects the target server to the target agent. Any server can connect to the agent, but the agent only accepts requests from the last-connected host. For more details on connecting to the agent, see the section "REQUESTS SENT TO THE AGENT".

ERRORS

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_TARGET_DISCONNECT

NAME

WDB_TARGET_DISCONNECT - disconnect the target server from the target agent

SYNOPSIS

INPUT: (none)
OUTPUT: (

DESCRIPTION

This request disconnects the target server from the target agent.

ERRORS

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_TARGET_PING

NAME

WDB_TARGET_PING - probe the target

SYNOPSIS

INPUT: (none)
OUTPUT: (

DESCRIPTION

This request tests the connection to the target.

ERRORS

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB

---

WDB Protocol : Requests

WDB_VIO_WRITE

NAME

WDB_VIO_WRITE - write data to a virtual I/O channel

SYNOPSIS

INPUT: WDB_MEM_XFER
OUTPUT: UINT32

DESCRIPTION

This routine writes data from the host to a virtual I/O channel on the target. The input parameters are supplied in WDB_MEM_XFER:

typedef struct wdb_mem_xfer		/* transfer a block of memory */
    {
    WDB_OPQ_DATA_T	source;		/* data to transfer */
    TGT_ADDR_T		destination;	/* requested destination */
    TGT_INT_T		numBytes;	/* number of bytes transferred */
    } WDB_MEM_XFER;

source and numBytes specify the block of memory to write to the target. destination is a virtual I/O channel number. The routine returns the number of bytes actually transferred (which could be less than numBytes if the VIO input buffer on the target is full). See the man page for wdbVioDrv for details on how to open a VIO channel on the target.

NOTE

There is no WDB_VIO_READ routine. VIO data transferred from the target to the host is uploaded as an asynchronous event (with WDB_EVENT_GET).

ERRORS

WDB_ERR_INVALID_VIO_CHANNEL

There is no such virtual I/O channel open on the target.

WDB and RPC errors

As described in the "REPLY ERRORS" section of the WDB man page.

SEE ALSO

WDB