bkenddoc.c

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

/* bkendDoc.c - target server back-end documentation */

/* Copyright 1995-1998 Wind River Systems, Inc. */
#include "copyright_wrs.h"

/*
modification history
--------------------
01o,10jul98,dbt  doc update
01n,03jul98,c_c  Added new backend Initialization interface.
01m,12jun98,rhp  doc: fix minor format error in bkendContextCont() docn"
01l,08jul97,dgp  doc: update bkendDirectCall (SPR 7724), bkendEventpointAdd 
                      (SPR 7226), bkendFuncCall (SPR 7988), & bkendMemRead 
                      (SPR 7727) to agree with hard-copy API Guide.
01k,06dec96,dgp  doc: correct spelling and "the the"
01j,21nov96,dgp  doc: change Target-Server, correct italic and bold formatting
01i,19nov96,dgp  doc: correct spelling/grammar errors
01h,19sep96,dgp  doc: correct WDB_RT_INFO.cpuType reference in bkendTgtConnect
                 for API Guide - fix SPR #7151
01g,11sep96,dgp  doc: API Guide changes, primarily cross-references
01f,05jul96,p_m  added bkendModeGet() (SPR# 6200).
01e,01jul96,dgp  doc: API Guide formatting changes, all functions
01d,21mar96,ms   added lots of details. removed references to the target agent.
01c,01mar96,elp  updated back end initialization routine header.
01b,03aug95,p_m	 doc tweaks.
01a,28jun95,tpr	 derived from rpccore.c version 01b.
*/

/*
DESCRIPTION
This documentation is a supplement to the section on the target server
provided in the 
.I "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 
.I "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.  

SEE ALSO:
.I "API Programmer's Guide: Target Server Back End"
and 
.I "Object Module Loader"
*/

/*******************************************************************************
*
* bkendCacheTextUpdate - update the instruction cache
*
* 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>.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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:
* .iP WDB_ERR_COMMUNICATION
* The connection to the target has died.
* .iP WDB_ERR_MEM_ACCES
* Invalid memory region.
*
* SEE ALSO
* .I "API Programmer's Guide: Object Module Loader"
*
*/

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

/*******************************************************************************
*
* bkendContextCont - continue a context
*
* 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>.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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:
* .iP WDB_ERR_COMMUNICATION
* The connection to the target has died.
* .iP WDB_ERR_AGENT_MODE	
* The system mode agent can't continue tasks.
* .iP WDB_ERR_INVALID_CONTEXT
* Invalid context.
* .iP WDB_ERR_RT_ERROR
* Task continuation was attempted and failed.
* .iP WDB_ERR_NO_RT_PROC
* Task continue is not supported on target.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/

UINT32 bkendContextCont
    (
    WDB_CTX *	pWdbContext			/* context to continue */
    )
    {
    ...
    }

/*******************************************************************************
*
* bkendContextCreate - create a context
*
* This function creates a new task on the target.
* The task is described by a WDB_CTX_CREATE_DESC structure pointed to by
* <pWdbContextDesc>.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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:
* .iP WDB_ERR_COMMUNICATION
* The connection to the target has died.
* .iP WDB_ERR_AGENT_MODE
* The system mode agent can't create tasks.
* .iP WDB_ERR_NO_RT_PROC
* Dynamic task creation is not supported on the target.
* .iP WDB_ERR_RT_ERROR
* Task creation was attempted and failed.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/

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

/*******************************************************************************
*
* bkendContextKill - destroy a context
*
* This function kills the context described by a WDB_CTX structure
* pointed to by <pWdbContext>.
* 
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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:
* .iP WDB_ERR_COMMUNICATION
* The connection to the target has died.
* .iP WDB_ERR_AGENT_MODE
* The system mode agent can't delete tasks.
* .iP WDB_ERR_NO_RT_PROC
* Task deletion is not supported on the target.
* .iP WDB_ERR_INVALID_CONTEXT
* Invalid context.
* .iP WDB_ERR_RT_ERROR
* Task deletion was attempted and failed.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/

UINT32 bkendContextKill
    (
    WDB_CTX *	pWdbContext			/* context to kill */
    )
    {
    ...
    }

/*******************************************************************************
*
* bkendContextStep - single step a context
*
* This function single steps a context according to a WDB_CTX_STEP_DESC
* structure pointed to by <pWdbContextStep>.
* 
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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:
* .CS
*	startAddr <= PC < endAddr
* .CE
* 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.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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:
* .iP WDB_ERR_COMMUNICATION
* The connection to the target has died.
* .iP WDB_ERR_AGENT_MODE
* The system mode agent can't step tasks.
* system context.
* .iP WDB_ERR_INVALID_CONTEXT
* Invalid context.
* .iP WDB_ERR_RT_ERROR
* Task step was attempted and failed.
* .iP WDB_ERR_NO_RT_PROC
* Task step is not supported on target.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/

UINT32 bkendContextStep
    (
    WDB_CTX_STEP_DESC *	pWdbContextStep		/* context to step */
    )
    {
    ...
    }

/*******************************************************************************
*
* bkendContextSuspend - suspend a context
*
* This function suspends the context described by a WDB_CTX structure
* pointed to by <pWdbContext>.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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:
* .iP WDB_ERR_COMMUNICATION
* The connection to the target has died.
* .iP WDB_ERR_AGENT_MODE
* The system mode agent can't suspend tasks.
* .iP WDB_ERR_NO_RT_PROC
* Task suspension is not supported on target.
* .iP WDB_ERR_INVALID_CONTEXT
* Invalid context.
* .iP WDB_ERR_RT_ERROR
* Task suspension was attempted and failed.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/

UINT32 bkendContextSuspend
    (
    WDB_CTX *	pWdbContext			/* context to suspend */
    )
    {
    ...
    }

/*******************************************************************************
*
* bkendContextResume - resume a context
*
* This function resumes the context described by a WDB_CTX structure
* pointed to by <pWdbContext>.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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:
* .iP WDB_ERR_COMMUNICATION
* The connection to the target has died.
* .iP WDB_ERR_AGENT_MODE
* The system mode agent can't resume tasks.
* .iP WDB_ERR_NO_RT_PROC
* Task resumption is not supported on target.
* .iP WDB_ERR_INVALID_CONTEXT
* Invalid context.
* .iP WDB_ERR_RT_ERROR
* Task resumption was attempted and failed.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/

UINT32 bkendContextResume
    (
    WDB_CTX * 	pWdbContext			/* context to resume */
    )
    {
    ...
    }

/*******************************************************************************
*
* bkendContextStatusGet - get a context status
*
* 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>.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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:
* .iP WDB_ERR_COMMUNICATION
* The connection to the target has died.
* .iP WDB_ERR_AGENT_MODE	
* The system mode agent can't get tasks status or task mode agent is running.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*