bkenddoc.c

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

*
* This function writes data to target memory. The memory region is described
* by a WDB_MEM_XFER structure pointed to by <pWdbMemXfer>.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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:
* .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: Target Server Back End"
*
*/

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

/*******************************************************************************
*
* bkendModeGet - get the debugging mode
*
* 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:
* .iP WDB_ERR_COMMUNICATION
* The connection to the target has died.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/

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

/*******************************************************************************
*
* bkendModeSet - set the debugging mode
*
* 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:
* .iP WDB_ERR_COMMUNICATION
* The connection to the target has died.
* .iP WDB_ERR_AGENT_MODE
* The requested mode is not supported.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/

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

/*******************************************************************************
*
* bkendRegsGet - get target register value(s)
*
* This function gets CPU register value(s).
* The registers to get are described by a WDB_REG_READ_DESC structure
* pointed to by <pWdbRegRead>.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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>.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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:
* .iP WDB_ERR_COMMUNICATION
* The connection to the target has died.
* .iP WDB_ERR_AGENT_MODE
* An invalid debugging mode was specified for the operation.
* .iP WDB_ERR_INVALID_PARAMS
* Unsupported regSetType.
* .iP WDB_ERR_INVALID_CONTEXT
* Invalid context.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/

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

/********************************************************************************
* bkendRegsSet - set target register value(s)
*
* This function sets CPU register value(s).
* The registers to get are described by a WDB_REG_WRITE_DESC structure
* pointed to by <pWdbRegWrite>.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h WDB_MEM_XFER
*
* 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
* Invalid agent mode for the operation.
* .iP WDB_ERR_INVALID_PARAMS
* Unsupported `regSetType'.
* .iP WDB_ERR_INVALID_CONTEXT
* Invalid context.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/

UINT32 bkendRegsSet
    (
    WDB_REG_WRITE_DESC * pWdbRegWrite		/* register to set */
    )
    {
    ...
    }

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

UINT32 bkendServiceCall
    (
    u_long	procNum,		/* procedure number to perform */
    FUNCPTR	inProc,			/* xdr function to code input args */
    char *	in,			/* input argument pointer */
    FUNCPTR	outProc,		/* xdr function to decode output args */
    char *	out			/* output arguments pointer */
    )
    {
    ...
    }

/*******************************************************************************
*
* bkendTgtConnect - connect to the target
*
* 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.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h WDB_TGT_INFO
*
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h WDB_AGENT_INFO
*
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h WDB_RT_INFO
*
*
* Most of the fields are straightforward to initialize. However, the following
* fields may not be obvious:
* .iP `rtType'
* set to WDB_RT_VXWORKS when connected to a VxWorks target. 
* .iP `cpuType'
* set to the value of the target CPU as
* defined in the header file ${WIND_BASE}/host/include/cputypes.h.
* .iP "`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:
* .iP WDB_ERR_COMMUNICATION
* Unable to connect to the target.
* .iP WDB_ERR_CONNECTION_BUSY
* The target is already connected to a target server.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/

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

/*******************************************************************************
*
* bkendTgtDisconnect - disconnect from the target
*
* 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:
* .iP WDB_ERR_COMMUNICATION
* The connection to the target has died.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/

UINT32 bkendTgtDisconnect (void)
    {
    ...
    }

/*******************************************************************************
*
* bkendTgtPing - ping the target
*
* This function checks the connection to the target.
*
* 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 bkendTgtPing (void)
    {
    ...
    }

/********************************************************************************
* bkendVIOWrite - write data to a target virtual I/O channel
*
* 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>.
*
* EXPAND ../../../../../share/src/agents/wdb/wdb.h 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:
* .iP WDB_ERR_COMMUNICATION
* The connection to the target has died.
* .iP WDB_ERR_NO_AGENT_PROC
* Virtual I/O is not supported by the back end.
* .iP WDB_ERR_NO_RT_PROC
* No virtual I/O driver is present in the target.
* .iP WDB_ERR_INVALID_VIO_CHANNEL 
* Invalid VIO channel.
*
* SEE ALSO
* .I "API Programmer's Guide: Target Server Back End"
*
*/


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