Tornado API Reference : Target Server Back End Interface

bkendDoc

NAME

bkendDoc - target server back-end documentation

ROUTINES

bkendCacheTextUpdate( ) - update the instruction cache
bkendContextCont( ) - continue a context
bkendContextCreate( ) - create a context
bkendContextKill( ) - destroy a context
bkendContextStep( ) - single step a context
bkendContextSuspend( ) - suspend a context
bkendContextResume( ) - resume a context
bkendContextStatusGet( ) - get a context status
bkendDirectCall( ) - call a target function synchronously
bkendEventpointAdd( ) - add an event point
bkendEventpointDelete( ) - delete an event point
bkendEventGet( ) - get an event from the target
bkendEvtPending( ) - check if an event is pending
bkendFlagsGet( ) - Get the supported flags for this backend
bkendFreeResultArgs( ) - free the memory used by the returned structure
bkendFuncCall( ) - call a target function asynchronously
bkendGopherEval( ) - evaluate a Gopher string
bkendInitialize( ) - initialize the back end
bkendMemChecksum( ) - perform a checksum on target memory
bkendMemProtect( ) - write protect (or write enable) target memory
bkendMemFill( ) - fill target memory with a pattern
bkendMemMove( ) - move a block of target memory
bkendMemRead( ) - read target memory
bkendMemScan( ) - scan target memory for a pattern
bkendMemWrite( ) - write target memory
bkendModeGet( ) - get the debugging mode
bkendModeSet( ) - set the debugging mode
bkendRegsGet( ) - get target register value(s)
bkendRegsSet( ) - set target register value(s)
bkendTgtConnect( ) - connect to the target
bkendTgtDisconnect( ) - disconnect from the target
bkendTgtPing( ) - ping the target
bkendVIOWrite( ) - write data to a target virtual I/O channel

DESCRIPTION

This documentation is a supplement to the section on the target server provided in the API Programmer's Guide . The interface between the target server and the back end is a TGT_OPS data structure. The back-end initialization routine, which is described in the API Programmer's Guide: Target Server Back End , fills this structure with pointers to the back-end functions. This document describes these functions in detail. The names below are only examples; if you are writing a "foo" back end, you should change the names below from bkendXXX( ) to fooXXX( ). All data types and error codes described here are defined in the header file $WIND_BASE/share/agents/wdb/wdb.h. Most routines take two parameters, the first a pointer to an input structure, the second a pointer to a results structure which the procedure fills in. Some routines take fewer parameters if either input or result structures are not needed. Most routines return an error status, which is either OK if the routine succeeds or one of the error codes defined in wdb.h if the routine fails.

bkendCacheTextUpdate( )

NAME

bkendCacheTextUpdate( ) - update the instruction cache

SYNOPSIS

UINT32 bkendCacheTextUpdate
    (
    WDB_MEM_REGION * pWdbMemRegion /* cache region to update */
    )

DESCRIPTION

This routine is used to synchronize the data and instruction caches on the target. It is called by the host loader after writing code to target memory. If the target has separate instruction and data caches, this routine flushes the data cache to memory and invalidates the corresponding portion of the instruction cache. If no synchronization is needed (for example, because the target has no cache), this routine is a no-op. The region of memory affected is described by a WDB_MEM_REGION structure pointed to by pWdbMemRegion.
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;
The region of target memory to checksum is described by the baseAddr and numBytes fields. The param field is unused.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_MEM_ACCES
Invalid memory region.

bkendContextCont( )

NAME

bkendContextCont( ) - continue a context

SYNOPSIS

UINT32 bkendContextCont
    (
    WDB_CTX * pWdbContext /* context to continue */
    )

DESCRIPTION

This function resumes a context. It is similar to bkendContextResume( ), except that it also handles the logic of stepping away from a breakpoint. The context to continue is specified by a WDB_CTX structure pointed to by pWdbContext.
typedef struct wdb_ctx			/* a particular context */
    {
    WDB_CTX_TYPE	contextType;	/* type of context */
    UINT32		contextId;	/* context ID */
    } WDB_CTX;
If the contextType field is equal to WDB_CTX_SYSTEM, then the system context is resumed. If contextType is WDB_CTX_TASK, then the contextId field specifies the VxWorks task ID to resume.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_AGENT_MODE
The system mode agent can't continue tasks.

WDB_ERR_INVALID_CONTEXT
Invalid context.

WDB_ERR_RT_ERROR
Task continuation was attempted and failed.

WDB_ERR_NO_RT_PROC
Task continue is not supported on target.

bkendContextCreate( )

NAME

bkendContextCreate( ) - create a context

SYNOPSIS

UINT32 bkendContextCreate
    (
    WDB_CTX_CREATE_DESC * pWdbContextDesc, /* context description */
    UINT32 *              pCid             /* context id */
    )

DESCRIPTION

This function creates a new task on the target. The task is described by a WDB_CTX_CREATE_DESC structure pointed to by pWdbContextDesc.
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 fields of this structure are similar to the parameters to the VxWorks routine taskSpawn( ); see the VxWorks reference entry for details. If stackBase is set to NULL, stack space is dynamically allocated for the task. If stackSize is zero, a default stack size is used. The redirIn, redirOut, and redirErr parameters, if non-zero, are redirection file descriptors for the task's standard input, output, and error output respectively. The task ID of the newly created task is returned at the location pointed to by pCid.
This routine is generally not supported by external mode agents.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_AGENT_MODE
The system mode agent can't create tasks.

WDB_ERR_NO_RT_PROC
Dynamic task creation is not supported on the target.

WDB_ERR_RT_ERROR
Task creation was attempted and failed.

bkendContextKill( )

NAME

bkendContextKill( ) - destroy a context

SYNOPSIS

UINT32 bkendContextKill
    (
    WDB_CTX * pWdbContext /* context to kill */
    )

DESCRIPTION

This function kills the context described by a WDB_CTX structure pointed to by pWdbContext.
typedef struct wdb_ctx			/* a particular context */
    {
    WDB_CTX_TYPE	contextType;	/* type of context */
    UINT32		contextId;	/* context ID */
    } WDB_CTX;
If the contextType field is equal to WDB_CTX_SYSTEM, then the system context is killed (in other words, the target must be rebooted). If contextType is WDB_CTX_TASK, then the contextId field specifies the VxWorks task ID to kill. Task deletion is generally not supported by external mode agents.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_AGENT_MODE
The system mode agent can't delete tasks.

WDB_ERR_NO_RT_PROC
Task deletion is not supported on the target.

WDB_ERR_INVALID_CONTEXT
Invalid context.

WDB_ERR_RT_ERROR
Task deletion was attempted and failed.

bkendContextStep( )

NAME

bkendContextStep( ) - single step a context

SYNOPSIS

UINT32 bkendContextStep
    (
    WDB_CTX_STEP_DESC * pWdbContextStep /* context to step */
    )

DESCRIPTION

This function single steps a context according to a WDB_CTX_STEP_DESC structure pointed to by pWdbContextStep.
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;
The startAddr and endAddr specify a range of instructions to step. Single stepping continues until the program counter (PC) is outside the range:
      startAddr <= PC < endAddr
Note the boundary condition: if (PC == endAddr) then stop stepping. At that point, a breakpoint event must be generated and the context being stepped must be stopped. By convention, if startAddr and endAddr are both zero then one machine instruction is stepped. The context field specifies the context to step.
typedef struct wdb_ctx			/* a particular context */
    {
    WDB_CTX_TYPE	contextType;	/* type of context */
    UINT32		contextId;	/* context ID */
    } WDB_CTX;
If context.contextType is equal to WDB_CTX_SYSTEM, then the system context is stepped. If context.contextType is WDB_CTX_TASK, then the contextId field specifies the VxWorks task ID to step.
Stepping must be performed with interrupts locked.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_AGENT_MODE
The system mode agent can't step tasks. system context.

WDB_ERR_INVALID_CONTEXT
Invalid context.

WDB_ERR_RT_ERROR
Task step was attempted and failed.

WDB_ERR_NO_RT_PROC
Task step is not supported on target.

bkendContextSuspend( )

NAME

bkendContextSuspend( ) - suspend a context

SYNOPSIS

UINT32 bkendContextSuspend
    (
    WDB_CTX * pWdbContext /* context to suspend */
    )

DESCRIPTION

This function suspends the context described by a WDB_CTX structure pointed to by pWdbContext.
typedef struct wdb_ctx			/* a particular context */
    {
    WDB_CTX_TYPE	contextType;	/* type of context */
    UINT32		contextId;	/* context ID */
    } WDB_CTX;
If the contextType field is equal to WDB_CTX_SYSTEM, then the system context is suspended. If contextType is WDB_CTX_TASK, then the contextId field specifies the VxWorks task ID to suspend. Task suspension is generally not supported by external mode agents.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_AGENT_MODE
The system mode agent can't suspend tasks.

WDB_ERR_NO_RT_PROC
Task suspension is not supported on target.

WDB_ERR_INVALID_CONTEXT
Invalid context.

WDB_ERR_RT_ERROR
Task suspension was attempted and failed.

bkendContextResume( )

NAME

bkendContextResume( ) - resume a context

SYNOPSIS

UINT32 bkendContextResume
    (
    WDB_CTX * pWdbContext /* context to resume */
    )

DESCRIPTION

This function resumes the context described by a WDB_CTX structure pointed to by pWdbContext.
typedef struct wdb_ctx			/* a particular context */
    {
    WDB_CTX_TYPE	contextType;	/* type of context */
    UINT32		contextId;	/* context ID */
    } WDB_CTX;
If the contextType field is equal to WDB_CTX_SYSTEM, then the system context is resumed. If contextType is WDB_CTX_TASK, then the contextId field specifies the VxWorks task ID to resume. Task resumption is generally not supported by external mode agents.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_AGENT_MODE
The system mode agent can't resume tasks.

WDB_ERR_NO_RT_PROC
Task resumption is not supported on target.

WDB_ERR_INVALID_CONTEXT
Invalid context.

WDB_ERR_RT_ERROR
Task resumption was attempted and failed.

bkendContextStatusGet( )

NAME

bkendContextStatusGet( ) - get a context status

SYNOPSIS

UINT32 bkendContextStatusGet
    (
    WDB_CTX * pWdbContext, /* context to get status of */
    UINT32 *  pCtxStatus   /* context status */
    )

DESCRIPTION

This function returns the status of a context on the target board. The context to test is specified by a WDB_CTX structure pointed to by the pWdbContext.
typedef struct wdb_ctx			/* a particular context */
    {
    WDB_CTX_TYPE	contextType;	/* type of context */
    UINT32		contextId;	/* context ID */
    } WDB_CTX;
If the contextType field is equal to WDB_CTX_SYSTEM, then the system context status is returned. At present, this request is not supported for task mode contexts.
The context status is returned at the memory pointed to by pCtxStatus.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_AGENT_MODE
The system mode agent can't get tasks status or task mode agent is running.

bkendDirectCall( )

NAME

bkendDirectCall( ) - call a target function synchronously

SYNOPSIS

UINT32 bkendDirectCall
    (
    WDB_CTX_CREATE_DESC * pWdbContext, /* function call parameters */
    UINT32 *              pStatus      /* function return value */
    )

DESCRIPTION

This routine calls a target function immediately according to a WDB_CTX_CREATE_DESC structure pointed to by pWdbContext.
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;
Only the entry and args fields are used and the result is a 32-bit integer returned at the host address pointed to by pStatus.
If this request is serviced by a task-mode agent on the target, the function must be invoked in the agent's context. If this request is serviced by an external mode debugger, the function must still be called on the target (either by calling directly in the case of a ROM monitor or by pushing a new call frame on the target execution stack in the case of an ICE back end). When the function is called by an external back end, it must guarantee that the following conditions are true:

the global variable kernelState is TRUE

the global variable intCnt is greater than zero

the existing value of errno is stored

the interrupts are masked via the processor's status register

After the function completes, these resources must be returned to their original state.

RETURNS

OK on success or the following error code:

WDB_ERR_COMMUNICATION
The connection to the target has died.

bkendEventpointAdd( )

NAME

bkendEventpointAdd( ) - add an event point

SYNOPSIS

UINT32 bkendEventpointAdd
    (
    WDB_EVTPT_ADD_DESC * pWdbEventPoint, /* event point to add */
    UINT32 *             pEvtptNum       /* event point number */
    )

DESCRIPTION

This function asks the back end to look for and handle some asynchronous event on the target (for example, a breakpoint or a context exit). The event point is described by a WDB_EVTPT_ADD_DESC pointed to by pWdbEventPoint. The returned event-point ID is saved in the memory location pointed to by pEvtptNum.
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;
The evtType field specifies the type of event (for example, WDB_EVT_BP for a breakpoint, WDB_EVT_CTX_EXIT for context exit, WDB_EVT_CTX_START for context start and WDB_EVT_HW_BP for hardware breakpoints). The numArgs and args fields are specific to each evtType. For example, WDB_EVT_BP has numArgs equal to one or two, args[0] equal to the desired address and args[1] (optional) equal to the breakpoint count. WDB_EVT_HW_BP has numArgs equal to three, args[0] equal to the desired address, args[1] equal to the breakpoint count and args[2] equal to the breakpoint access type. Most other event types have numArgs equal to zero. Not all event types must be handled. However, to support source debugging with CrossWind and a WDB agent, one must support at least the WDB_EVT_BP and WDB_EVT_CTX_EXIT event types.
The context field specifies the context to which the event point applies. This allows, for example, the setting of task-specific breakpoints.
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;
For context start eventpoints (WDB_EVT_CTX_START), the contextId field and contextType fields are not used. This eventpoint always applies to all task mode contexts created.
The action field is a WDB_ACTION structure describing what to do when the event occurs.
typedef struct wdb_action		/* a specific action */
    {
    WDB_ACTION_TYPE	actionType;
    UINT32		actionArg;
    TGT_ADDR_T		callRtn;
    TGT_INT_T		callArg;
    } WDB_ACTION;
The actionType gives a list of actions to perform when the event point is triggered. These actions are bitwise or'ed together:

WDB_ACTION_STOP
stop the context that triggered the event point

WDB_ACTION_NOTIFY
notify the target server of the event

WDB_ACTION_CALL
call the action.callRtn routine with parameter action.callArg

For classical breakpoints, actionType is WDB_ACTION_STOP | WDB_ACTION_NOTIFY. However this syntax provides much more flexibility for handling events.
Context-specific event points should be automatically deleted when the context exits. Otherwise event points are persistent until bkendEventpointDelete( ) is called to delete them. Tasking breakpoints (and hardware breakpoints) must be disabled if the debug mode is changed to external mode using bkendModeSet( ) and reenabled if the mode is switched back again. External mode breakpoints (and hardware breakpoints) are handled similarly when switching to task mode.
When the event occurs and the WDB_ACTION_NOTIFY bit is set, target server notification occurs as described in the API Programmer's Guide: Target Server Back End . After notification, the target server calls bkendEventGet( ) to get the event. All exception events are reported by the back end, even if an event point has not been set for exception events.

CAVEATS

For breakpoint events (WDB_EVT_BP) and hardware breakpoint events (WDB_EVT_HW_BP), if actionType is WDB_ACTION_STOP or 0, interpret it to mean WDB_ACTION_STOP | WDB_ACTION_NOTIFY. For context exit events (WDB_EVT_CTX_EXIT), if actionType is 0, interpret it to mean WDB_ACTION_NOTIFY.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_INVALID_EVENT
Unsupported evtType.

WDB_ERR_EVENTPOINT_TABLE_FULL
The event point table is full.

WDB_ERR_HW_REGS_EXHAUSTED
The CPU hardware breakpoint registers are exhausted (WDB_EVT_HW_BP `evtType`).

WDB_ERR_INVALID_HW_BP
Invalide hardware breakpoint type.

WDB_ERR_INVALID_CONTEXT
Invalid context

bkendEventpointDelete( )

NAME

bkendEventpointDelete( ) - delete an event point

SYNOPSIS

UINT32 bkendEventpointDelete
    (
    WDB_EVTPT_DEL_DESC * pWdbEventpoint /* event point to delete */
    )

DESCRIPTION

This function deletes an event point on the target. The event point to delete is specified by a WDB_EVTPT_DEL_DESC structure pointed to by pWdbEventpoint.
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;
The evtType field specifies the type of event point to delete. It is the same as the value passed to bkendEventpointAdd( ). The evtptId field is the event point ID returned by bkendEventpointAdd( ).

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_INVALID_EVENT
Unsupported evtType.

WDB_ERR_INVALID_EVENTPOINT
Invalid evtptId.

bkendEventGet( )

NAME

bkendEventGet( ) - get an event from the target

SYNOPSIS

UINT32 bkendEventGet
    (
    WDB_EVT_DATA * pWdbEvtData /* event description */
    )

DESCRIPTION

This function is called by the target server to get an event from the target. It is called only after the back end has notified the target server that events are pending on the target. (See the API Programmer's Guide: Target Server Back End for details on the event notification mechanism.) This routine fills in a WDB_EVT_DATA structure pointed to by pWdbEvtData.
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 evtType field depends on the event. If no new events have occurred on the target, this field must be set to WDB_EVT_NONE. The rest of this structure contains an event information structure which depends on the evtType:

Event Type Event Data

WDB_EVT_CTX_EXIT WDB_CTX_EXIT_INFO

WDB_EVT_CTX_START WDB_CTX_START_INFO

WDB_EVT_BP WDB_BP_INFO

WDB_EVT_WP WDB_BP_INFO

WDB_EVT_EXC WDB_EXC_INFO

WDB_EVT_VIO_WRITE WDB_MEM_XFER

WDB_EVT_CALL_RET WDB_CALL_RET_INFO

Event Type	Event Data

WDB_EVT_CTX_EXIT	WDB_CTX_EXIT_INFO
WDB_EVT_CTX_START	WDB_CTX_START_INFO
WDB_EVT_BP	WDB_BP_INFO
WDB_EVT_WP	WDB_BP_INFO
WDB_EVT_EXC	WDB_EXC_INFO
WDB_EVT_VIO_WRITE	WDB_MEM_XFER
WDB_EVT_CALL_RET	WDB_CALL_RET_INFO

RETURNS

OK on success or the following error code:

WDB_ERR_COMMUNICATION
The connection to the target has died.

bkendEvtPending( )

NAME

bkendEvtPending( ) - check if an event is pending

SYNOPSIS


BOOL bkendEvtPending (void)

DESCRIPTION

This function is called by the target server to detect if a target event is pending.

RETURNS

TRUE if a target event is pending, otherwise FALSE.

bkendFlagsGet( )

NAME

bkendFlagsGet( ) - Get the supported flags for this backend

SYNOPSIS


FLAG_DESC *  bkendFlagsGet (void)

DESCRIPTION

This function is called by the target server when it wants to get the flags supported by the currently attached backend. The backend should give a list (NULL terminated) of FLAG_DESC structure.
typedef struct flag_desc
    {
    char *		flagName;	/* verbose flag name */
    char *		flagTerseName;	/* abbreviated name of flag (or NULL) */
    PARSE_RTN		parseRoutine;	/* flag processing routine */
    void *  		outputPtr;	/* where to store the output result */
    char * 		flagHelp;	/* flag help string */
    } FLAG_DESC;
each element represents an option supported by the backend. For each element, you must precise :

flagName
the flag itself (e.g. -foo)

flagTerseName
for an abbreviated version of this flag (NULL if none).

parseRoutine
the routine which will be called by the target server if this flag is set.

outputPtr
an argument which will be given to the routine (a value we want to be set if the flag is found on the command line). For example, an integer address for the flagInt routine. If the flag is found on the command line, this integer will be set with the argument given to the flag (e.g. -foo 10)

flagHelp
a string which will be displayed on help demand.

A detailed description of back-end argument handling can be found in the API Programmer's Guide: Target Server Back End .

RETURNS

a pointer on a FLAG_DESC array (last element is NULL) or NULL if no argument are supported by this backend.

bkendFreeResultArgs( )

NAME

bkendFreeResultArgs( ) - free the memory used by the returned structure

SYNOPSIS


BOOL bkendFreeResultArgs (void)

DESCRIPTION

This function frees any memory allocated by the last back-end function that was called. Ideally, none of the back-end functions allocate memory, in which case this routine becomes a no-op.

RETURNS

TRUE on success, FALSE if an error occurred.

bkendFuncCall( )

NAME

bkendFuncCall( ) - call a target function asynchronously

SYNOPSIS

UINT32 bkendFuncCall
    (
    WDB_CTX_CREATE_DESC * pWdbContext, /* function call parameters */
    UINT32 *              pCid         /* context ID */
    )

DESCRIPTION

This routine calls a target function and returns its result asynchronously. This is done by spawning a new task on the target according to a WDB_CTX_CREATE_DESC structure pointed to by pWdbContext.
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 spawned task is a wrapper which invokes the function and returns its results asynchronously via an event of type WDB_EVT_CALL_RET. The event contains a result of type double, if the WDB_FP_RETURN option bit is set in the options field; otherwise, the result type is int. This procedure returns the ID of the newly spawned task in the address pointed to by pCid.

NOTE

If stackSize is 0, the application should set an appropriate default, preferably WDB_SPAWN_STACK_SIZE, which is defined in configAll.h.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_AGENT_MODE
The system mode agent can't spawn a task.

WDB_ERR_RT_ERROR
Task creation failed on target.

WDB_ERR_NO_RT_PROC
Task creation is not supported on target.

bkendGopherEval( )

NAME

bkendGopherEval( ) - evaluate a Gopher string

SYNOPSIS

UINT32 bkendGopherEval
    (
    WDB_STRING_T * pWdbString, /* gopher string to evaluate */
    WDB_MEM_XFER * pWdbMemXfer /* gopher result */
    )

DESCRIPTION

This function executes a Gopher string pointed to by pWdbString. More information about the Gopher language can be found in the API Programmer's Guide: WTX Protocol . The result of the execution is returned via a WDB_MEM_XFER structure pointed to by pWdbMemXfer.
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;
When the procedure returns, the host buffer pointed to by destination is filled with the Gopher result. If destination is originally NULL, this routine must allocate memory to hold the result and set destination to this location.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_GOPHER_SYNTAX
This is a malformed Gopher string.

WDB_ERR_GOPHER_FAULT
A memory fault occurred while executing the string.

WDB_ERR_GOPHER_TRUNCATED
The Gopher result is too large.

WDB_ERR_MEM_ACCES
Invalid memory region.

bkendInitialize( )

NAME

bkendInitialize( ) - initialize the back end

SYNOPSIS

STATUS bkendInitialize
    (
    char *       tgtName, /* target name to connect to */
    TGT_OPS *    pTgtOps, /* back end functions */
    BKEND_INFO * pBkInfo  /* Backend related informations */
    )

DESCRIPTION

This function is called by the target server to attach this back end. This function is the first back-end function called by the target server and the only one that is called directly. Other back-end functions are called via a TGT_OPS structure pointed to by pTgtOps and filled by this function. The BKEND_INFO structure is also set up by this routine. The target server will handle the asynchronous events according to the value set in this structure pointed to by pBkinfo. A detailed description of back-end initialization routines can be found in the API Programmer's Guide: Target Server Back End .

RETURNS

OK or ERROR if an error is detected in the back-end initialization.

bkendMemChecksum( )

NAME

bkendMemChecksum( ) - perform a checksum on target memory

SYNOPSIS

UINT32 bkendMemChecksum
    (
    WDB_MEM_REGION * pWdbMemRegion, /* memory block to checksum */
    UINT32 *         pChecksumValue /* checksum value */
    )

DESCRIPTION

This function checksums a block of target memory. The block is described by the WDB_MEM_REGION structure pointed to by pWdbMemRegion. The checksum value is returned at the memory pointed to by pChecksumValue.

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;

The region of target memory to checksum is described by the baseAddr and numBytes fields. The param field is not used.

The checksum can be computed using the following code stub:

 UINT32 cksum
     (
     uint16_t *  pAddr,                  /* start of buffer */
     int         len                     /* size of buffer in bytes */
     )
     {
     UINT32      sum = 0;
     BOOL        swap = FALSE;
 
     /* take care of unaligned buffer address */
 
     if ((UINT32)pAddr & 0x1)
         {
         sum += *((unsigned char *) pAddr) ++;
         len--;
         swap = TRUE;
         }
 
     /* evaluate checksum */
 
     while (len > 1)
         {
         sum += *(uint16_t *) pAddr ++;
         len -= 2;
         }
 
     /* take care of last byte */
 
     if (len > 0)
         sum = sum + ((*(unsigned char *) pAddr) << 8);
 
     /* fold to 16 bits */
 
     sum = (sum & 0xffff) + (sum >> 16);
     sum = (sum & 0xffff) + (sum >> 16);
 
     /* swap if we started on unaligned address */
 
     if (swap)
         sum = ((sum & 0x00ff) << 8) | ((sum & 0xff00) >> 8);
 
     return (~sum);
     }

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_MEM_ACCES
Invalid memory region.

bkendMemProtect( )

NAME

bkendMemProtect( ) - write protect (or write enable) target memory

SYNOPSIS

UINT32 bkendMemProtect
    (
    WDB_MEM_REGION * pWdbMemRegion /* memory region to protect */
    )

DESCRIPTION

This function turns on or off write protection of a target memory region. The memory region is described by a WDB_MEM_REGION structure pointed to by pWdbMemRegion.
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;
The region of target memory to protect is described by the baseAddr numBytes fields. If the param field is equal to zero the memory region is write enabled. Otherwise the region is write protected.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_MEM_ACCES
Invalid memory region.

WDB_ERR_NO_RT_PROC
There is no runtime support for this operation.

bkendMemFill( )

NAME

bkendMemFill( ) - fill target memory with a pattern

SYNOPSIS

UINT32 bkendMemFill
    (
    WDB_MEM_REGION * pWdbMemRegion /* memory region to fill */
    )

DESCRIPTION

This function fills a target memory region with a pattern. The memory region to fill is described by a WDB_MEM_REGION structure pointed to by pWdbMemRegion.
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;
The region of target memory to fill is described by the baseAddr and numBytes fields. The four-byte fill pattern is contained in the param field.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_MEM_ACCES
Invalid memory region.

bkendMemMove( )

NAME

bkendMemMove( ) - move a block of target memory

SYNOPSIS

UINT32 bkendMemMove
    (
    WDB_MEM_REGION * pWdbMemRegion /* memory region to copy */
    )

DESCRIPTION

This function moves a block of target memory from one location to another. It handles the case where source and destination blocks overlap. The memory move is described by a WDB_MEM_REGION structure pointed to by pWdbMemRegion.
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;
The region of target memory to move is described by the baseAddr and numBytes fields. The destination address is given in the param field.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_MEM_ACCES
Invalid memory region.

bkendMemRead( )

NAME

bkendMemRead( ) - read target memory

SYNOPSIS

UINT32 bkendMemRead
    (
    WDB_MEM_REGION * pWdbMemRegion, /* memory to read description */
    WDB_MEM_XFER *   pWdbMemXfer    /* area to save the data read */
    )

DESCRIPTION

This function reads the target memory region described by a WDB_MEM_XFER structure pointed to by pWdbMemRegion.
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;
The target start address and the number of bytes to read are in the baseAddr and numBytes fields. The data will be copied to the host memory address pointed to by param.
When this routine returns, it fills in the WDB_MEM_XFER structure pointed to by pWdbMemXfer with information about the memory transfer.
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;
It sets source equal to baseAddr, numBytes for WDB_MEM_XFER equal to numBytes for WDB_MEM_REGION, and destination equal to param.
If the data transfer is too large to be done at once (in other words, larger than the MTU of the target connection), the back end must break up the transfer into a series of smaller transfers.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_MEM_ACCES
Invalid memory region.

bkendMemScan( )

NAME

bkendMemScan( ) - scan target memory for a pattern

SYNOPSIS

UINT32 bkendMemScan
    (
    WDB_MEM_SCAN_DESC * pWdbMemScan, /* scan descriptor */
    TGT_ADDR_T *        pAdrs        /* addr found or -1 */
    )

DESCRIPTION

This function scans target memory for a specified pattern. The target memory region and the pattern are described by a WDB_MEM_SCAN_DESC structure pointed to by pWdbMemScan. If the pattern is found in the target memory region, the pattern start address is pointed to by pAdrs. Otherwise pAdrs is set to -1.
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;
The memRegion field describes the memory region to search.
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;
The baseAddr field describes where to start the search. If numBytes is positive, a forward search is performed; otherwise a backward search is performed. If param is NULL, the search tries to match the pattern. Otherwise, the search stops at the first location where the pattern doesn't match.
The memXfer field describes the pattern to look for.
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 source and numBytes fields point to a host buffer containing the pattern. The destination field is unused.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_MEM_ACCES
Invalid memory region.

WDB_ERR_NOT_FOUND
No match was detected.

bkendMemWrite( )

NAME

bkendMemWrite( ) - write target memory

SYNOPSIS

UINT32 bkendMemWrite
    (
    WDB_MEM_XFER * pWdbMemXfer /* memory to write description */
    )

DESCRIPTION

This function writes data to target memory. The memory region is described by a WDB_MEM_XFER structure pointed to by pWdbMemXfer.
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 source field contains the address of a buffer on the host which is to be transferred to the target. The numBytes field specifies the number of bytes to write. The destination field specifies the target address which will receive the data.
If the data transfer is too large to be done at once (in other words, larger than the MTU of the target connection), the back end must break up the transfer into a series of smaller transfers.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_MEM_ACCES
Invalid memory region.

bkendModeGet( )

NAME

bkendModeGet( ) - get the debugging mode

SYNOPSIS

UINT32 bkendModeGet
    (
    u_int * pMode /* where to return debugging mode */
    )

DESCRIPTION

This function return the current debugging mode of the agent in the location pointed to by pMode.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

bkendModeSet( )

NAME

bkendModeSet( ) - set the debugging mode

SYNOPSIS

UINT32 bkendModeSet
    (
    u_int * pMode /* debugging mode to set */
    )

DESCRIPTION

This function sets the debugging mode to either WDB_MODE_TASK or WDB_MODE_EXTERN. Hardware back ends generally only support the WDB_MODE_EXTERN mode, as they are unable to perform tasking services such as spawning tasks and creating task-specific breakpoints.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_AGENT_MODE
The requested mode is not supported.

bkendRegsGet( )

NAME

bkendRegsGet( ) - get target register value(s)

SYNOPSIS

UINT32 bkendRegsGet
    (
    WDB_REG_READ_DESC * pWdbRegRead, /* register to get */
    WDB_MEM_XFER *      pWdbMemXfer  /* area to save reg values */
    )

DESCRIPTION

This function gets CPU register value(s). The registers to get are described by a WDB_REG_READ_DESC structure pointed to by pWdbRegRead.
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;
The regSetType field specifies the type of registers to read. The back end must support reading integer unit registers (WDB_REG_SET_IU) and must also support floating point registers (WDB_REG_SET_FPU) if the CPU has floating-point support. Additional register-set types are optional. The context field specifies the context whose registers are to be read. If context.contextType is WDB_CTX_SYSTEM, the register values the last time the system was stopped are read (this only makes sense when doing system-mode debugging). If context.contextType is WDB_CTX_TASK, then registers are read from the task whose ID is context.contextID.
A register set is treated as an opaque block of memory by the back end. For floating-point registers, this block is described by the VxWorks data structure FPREG_SET. For integer unit registers, it is described by the VxWorks data structure REG_SET.
To avoid the delay of uploading an entire register block when only some of the registers are actually needed, this routine allows reading of a sub-block of the register structure. This sub-block is specified by the memRegion fields memRegion.baseAddr and memRegion.numBytes.
The resulting register block is transferred up to the host via a WDB_MEM_XFER structure pointed to by pWdbMemXfer.
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;
When this routine returns, the source field in WDB_MEM_XFER points to a block of host memory containing a copy of the register block, and numBytes is set to the number of bytes in the memRegion field in WDB_REG_READ_DESC.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_AGENT_MODE
An invalid debugging mode was specified for the operation.

WDB_ERR_INVALID_PARAMS
Unsupported regSetType.

WDB_ERR_INVALID_CONTEXT
Invalid context.

bkendRegsSet( )

NAME

bkendRegsSet( ) - set target register value(s)

SYNOPSIS

UINT32 bkendRegsSet
    (
    WDB_REG_WRITE_DESC * pWdbRegWrite /* register to set */
    )

DESCRIPTION

This function sets CPU register value(s). The registers to get are described by a WDB_REG_WRITE_DESC structure pointed to by pWdbRegWrite.
typedef struct wdb_reg_write_desc	/* register data to write */
    {
    WDB_REG_SET_TYPE regSetType;	/* type of register set to write */
    WDB_CTX	     context;		/* context associated with registers */
    WDB_MEM_XFER     memXfer;		/* new value of the register set */
    } WDB_REG_WRITE_DESC;
The regSetType field specifies the type of registers to set. The back end must support setting integer-unit registers (WDB_REG_SET_IU), and must also support floating-point registers (WDB_REG_SET_FPU) if the CPU has floating-point support. Additional register-set types are optional. The context field specifies the context whose registers are to be set. If context.contextType is WDB_CTX_SYSTEM, the register values the next time the system is resumed are set (this only makes sense when doing system mode debugging). If context.contextType is WDB_CTX_TASK, then registers are set for the task whose ID is context.contextID.
A register set is treated as an opaque block of memory by the back end. For floating point registers, this block is described by the VxWorks data structure FPREG_SET. For integer unit registers, it is described by the VxWorks data structure REG_SET.
To avoid the delay of setting an entire register block when only some of the registers need changing, this routine allows setting of a sub-block of the register structure. This sub-block is specified by the memXfer fields destination and numBytes. memXfer.source points to a host buffer containing the values of the sub-block of registers which are to be set.
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;

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_AGENT_MODE
Invalid agent mode for the operation.

WDB_ERR_INVALID_PARAMS
Unsupported regSetType.

WDB_ERR_INVALID_CONTEXT
Invalid context.

bkendTgtConnect( )

NAME

bkendTgtConnect( ) - connect to the target

SYNOPSIS

UINT32 bkendTgtConnect
    (
    WDB_TGT_INFO * pWdbTgtInfo /* target and run-time info */
    )

DESCRIPTION

This function is the first back-end function called by the target server when the back end attachment succeeds. It connects to the target and fills pWdbTgtInfo with information about the target and the connection.
typedef struct wdb_tgt_info		/* info on the target */
    {
    WDB_AGENT_INFO  	agentInfo;	/* info on the agent */
    WDB_RT_INFO	    	rtInfo;		/* info on the run time system */
    } WDB_TGT_INFO;
typedef struct wdb_agent_info		/* info on the debug agent */
    {
    WDB_STRING_T	agentVersion;	/* version of the WDB agent */
    TGT_INT_T		mtu;		/* maximum transfer size in bytes */
    TGT_INT_T		mode;		/* available agent modes */
    } WDB_AGENT_INFO;
typedef struct wdb_rt_info		/* info on the run-time system */
    {
    WDB_RT_TYPE		rtType;		/* runtime type */
    WDB_STRING_T	rtVersion;	/* run time version */
    TGT_INT_T		cpuType;	/* target processor type */
    BOOL		hasFpp;		/* target has a floating point unit */
    BOOL		hasWriteProtect; /* target can write protect memory */
    TGT_INT_T		pageSize;	/* size of a page */
    TGT_INT_T		endian;		/* endianness (0x4321 or 0x1234) */
    WDB_STRING_T	bspName;	/* board support package name */
    WDB_STRING_T	bootline;	/* boot file path or NULL if embedded */
    TGT_ADDR_T		memBase;	/* target main memory base address */
    UINT32		memSize;	/* target main memory size */
    TGT_INT_T		numRegions;	/* number of memory regions */
    WDB_MEM_REGION *	memRegion;	/* memory region descriptor(s) */
    TGT_ADDR_T		hostPoolBase;	/* host-controlled tgt memory pool */
    UINT32		hostPoolSize;	/* host-controlled memory pool size */
    } WDB_RT_INFO;
Most of the fields are straightforward to initialize. However, the following fields may not be obvious:

rtType
set to WDB_RT_VXWORKS when connected to a VxWorks target.

cpuType
set to the value of the target CPU as defined in the header file ${WIND_BASE}/host/include/cputypes.h.

hostPoolBase and hostPoolSize
describe a memory region on the target which can be used by the target server to load files. This region must not be part of the VxWorks memory pool or else both the target server and VxWorks will think they control it. The way to reserve memory from VxWorks is to modify the BSP's sysMemTop( ) routine to return less than the real top of memory.

RETURNS

* OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
Unable to connect to the target.

WDB_ERR_CONNECTION_BUSY
The target is already connected to a target server.

bkendTgtDisconnect( )

NAME

bkendTgtDisconnect( ) - disconnect from the target

SYNOPSIS


UINT32 bkendTgtDisconnect (void)

DESCRIPTION

This function detaches from the target. It frees all resources allocated by the back end (in other words, closes any open files and devices).

RETURNS

OK on success or the following error code:

WDB_ERR_COMMUNICATION
The connection to the target has died.

bkendTgtPing( )

NAME

bkendTgtPing( ) - ping the target

SYNOPSIS


UINT32 bkendTgtPing (void)

DESCRIPTION

This function checks the connection to the target.

RETURNS

OK on success or the following error code:

WDB_ERR_COMMUNICATION
The connection to the target has died.

bkendVIOWrite( )

NAME

bkendVIOWrite( ) - write data to a target virtual I/O channel

SYNOPSIS

UINT32 bkendVIOWrite
    (
    WDB_MEM_XFER * pWdbMemXfer, /* virtual I/O to write to */
    UINT32 *       pNumBytes    /* number of bytes written */
    )

DESCRIPTION

This function writes data to a virtual I/O channel on the target. The data to write and the VIO channel are described by a WDB_MEM_XFER structure pointed to by the pWdbMemXfer. The number of bytes written into the I/O channel is saved in the memory location pointed to by pNumBytes.
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 source and numBytes fields specify a buffer on the host containing the VIO data to be written to the target. The virtual I/O channel number is specified by the destination field.
Note: There is no bkendVIORead( ) routine. Virtual I/O data from the target is uploaded to the host via an event; see bkendEventGet( ).
The back end must supply a virtual I/O driver for VxWorks to support this mechanism. The back end must provide a mechanism to pass the data to the driver to support bkendVIOWrite( ). Likewise, the driver must have a mechanism to pass a VIO event to the back end when data is written to the VIO driver from the target. In this way, the driver is specific to the back end.

RETURNS

OK on success or one of the following error codes:

WDB_ERR_COMMUNICATION
The connection to the target has died.

WDB_ERR_NO_AGENT_PROC
Virtual I/O is not supported by the back end.

WDB_ERR_NO_RT_PROC
No virtual I/O driver is present in the target.

WDB_ERR_INVALID_VIO_CHANNEL
Invalid VIO channel.

bkendDoc

NAME

ROUTINES

DESCRIPTION

SEE ALSO

bkendCacheTextUpdate( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

bkendContextCont( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

bkendContextCreate( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

bkendContextKill( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

bkendContextStep( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

bkendContextSuspend( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

bkendContextResume( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

bkendContextStatusGet( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

bkendDirectCall( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

bkendEventpointAdd( )

NAME

SYNOPSIS

DESCRIPTION

CAVEATS

RETURNS

SEE ALSO

bkendEventpointDelete( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

bkendEventGet( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

bkendEvtPending( )

NAME