bkenddoc.c

vxworks源码源码解读是学习vxworks的最佳途径

*/

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

/*******************************************************************************
*
* bkendDirectCall - call a target function synchronously
*
* This routine calls a target function immediately according to a
* WDB_CTX_CREATE_DESC structure pointed to by <pWdbContext>.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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:
*
* .iP
* the global variable `kernelState' is TRUE
* .iP
* the global variable `intCnt' is greater than zero
* .iP
* the existing value of errno is stored
* .iP
* the interrupts are masked via the processor's status register
* .LP
*
* After the function completes, these resources must be returned
* to their original state.
*
* RETURNS
* OK on success or the following error code:
* .iP WDB_ERR_COMMUNICATION
* The connection to the target has died.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/

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

/*******************************************************************************
*
* bkendEventpointAdd - add an event point
*
* 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>.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h WDB_ACTION
*
* The `actionType' gives a list of actions to perform when the event point
* is triggered. These actions are bitwise or'ed together:
* .iP WDB_ACTION_STOP
* stop the context that triggered the event point
* .iP WDB_ACTION_NOTIFY
* notify the target server of the event
* .iP WDB_ACTION_CALL
* call the `action.callRtn' routine with parameter `action.callArg'
* .LP
* 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 
* .I "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:
* .iP WDB_ERR_COMMUNICATION
* The connection to the target has died.
* .iP WDB_ERR_INVALID_EVENT
* Unsupported `evtType'.
* .iP WDB_ERR_EVENTPOINT_TABLE_FULL
* The event point table is full.
* .iP WDB_ERR_HW_REGS_EXHAUSTED
* The CPU hardware breakpoint registers are exhausted (WDB_EVT_HW_BP `evtType`).
* .iP WDB_ERR_INVALID_HW_BP
* Invalide hardware breakpoint type.
* .iP WDB_ERR_INVALID_CONTEXT
* Invalid context
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/

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

/*******************************************************************************
*
* bkendEventpointDelete - delete an event point
*
* 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>.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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:
* .iP WDB_ERR_COMMUNICATION
* The connection to the target has died.
* .iP WDB_ERR_INVALID_EVENT
* Unsupported `evtType'.
* .iP WDB_ERR_INVALID_EVENTPOINT 
* Invalid `evtptId'.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/

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

/*******************************************************************************
* 
* bkendEventGet - get an event from the target
*
* 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 
* .I "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>.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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':
*
* .TS
* tab(|);
* lf3 lf3
* l l .
* 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
* .TE
*
* RETURNS
* OK on success or the following error code:
* .iP WDB_ERR_COMMUNICATION
* The connection to the target has died.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/

UINT32 bkendEventGet
    (
    WDB_EVT_DATA *	pWdbEvtData		/* event description */	
    )
    {
    ...
    }

/*******************************************************************************
*
* bkendEvtPending - check if an event is pending
*
* 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.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/

BOOL bkendEvtPending (void)
    {
    ...
    }

/*******************************************************************************
*
* bkendEvtPendingClear - obsolete routine
*
* This function is not used. It will be eliminated from the next version
* of the back end API.
*
* RETURNS: N/A 
*
* NOMANUAL
*/

void bkendEvtPendingClear (void)
    {
    ...
    }

/*******************************************************************************
*
* bkendFlagsGet - Get the supported flags for this backend
*
* 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.
* EXPAND ../../../../include/flagutil.h FLAG_DESC
*
* each element represents an option supported by the backend. For each element,
* you must precise :
* .iP `flagName'
* the flag itself (e.g. -foo)
* .iP `flagTerseName'
* for an abbreviated version of this flag (NULL if none).
* .iP `parseRoutine'
* the routine which will be called by the target server if this flag is set.
* .iP `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)
* .iP `flagHelp'
* a string which will be displayed on help demand.
* .LP
* A detailed description of back-end argument handling can be found in the
* .I "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.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/

FLAG_DESC *  bkendFlagsGet (void)
    {
    ...
    }

/*******************************************************************************
*
* bkendFreeResultArgs - free the memory used by the returned structure
*
* 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.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/

BOOL bkendFreeResultArgs (void)
    {
    ...
    }

/*******************************************************************************
*
* bkendFuncCall - call a target function asynchronously
*
* 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>.
* 
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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:
* .iP WDB_ERR_COMMUNICATION
* The connection to the target has died.
* .iP WDB_ERR_AGENT_MODE
* The system mode agent can't spawn a task.
* .iP WDB_ERR_RT_ERROR
* Task creation failed on target.