📄 wdb.html
字号:
<html><head><!-- /vobs/wpwr/docs/tornado-api/wdbpcl/wdb.html - generated by refgen from wdb.pcl --> <title> WDB </title></head><body bgcolor="#FFFFFF"> <hr><a name="top"></a><p align=right><a href="libIndex.html"><i>Tornado API Reference : WDB Protocol</i></a></p></blockquote><h1>WDB</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>WDB</strong> - WDB Protocol Requests </p></blockquote><h4>REQUESTS</h4><blockquote><p><p><b><a href="./wdb.html#WDB_CONTEXT_CONT">WDB_CONTEXT_CONT</a></b> - continue a context<br><b><a href="./wdb.html#WDB_CONTEXT_CREATE">WDB_CONTEXT_CREATE</a></b> - create a context on the target<br><b><a href="./wdb.html#WDB_CONTEXT_KILL">WDB_CONTEXT_KILL</a></b> - kill a context on the target<br><b><a href="./wdb.html#WDB_CONTEXT_RESUME">WDB_CONTEXT_RESUME</a></b> - resume a context on the target<br><b><a href="./wdb.html#WDB_CONTEXT_STATUS_GET">WDB_CONTEXT_STATUS_GET</a></b> - get the context of a status on the target<br><b><a href="./wdb.html#WDB_CONTEXT_STEP">WDB_CONTEXT_STEP</a></b> - single step a context<br><b><a href="./wdb.html#WDB_CONTEXT_SUSPEND">WDB_CONTEXT_SUSPEND</a></b> - suspend a context on the target<br><b><a href="./wdb.html#WDB_DIRECT_CALL">WDB_DIRECT_CALL</a></b> - call a function on the target in the agent's context<br><b><a href="./wdb.html#WDB_EVALUATE_GOPHER">WDB_EVALUATE_GOPHER</a></b> - execute a Gopher string<br><b><a href="./wdb.html#WDB_EVENTPOINT_ADD">WDB_EVENTPOINT_ADD</a></b> - add an asynchronous eventpoint<br><b><a href="./wdb.html#WDB_EVENTPOINT_DELETE">WDB_EVENTPOINT_DELETE</a></b> - delete an eventpoint<br><b><a href="./wdb.html#WDB_EVENT_GET">WDB_EVENT_GET</a></b> - upload an event from the target<br><b><a href="./wdb.html#WDB_FUNC_CALL">WDB_FUNC_CALL</a></b> - call a function on the target<br><b><a href="./wdb.html#WDB_MEM_CACHE_TEXT_UPDATE">WDB_MEM_CACHE_TEXT_UPDATE</a></b> - synchronize cache after writing to the target<br><b><a href="./wdb.html#WDB_MEM_CHECKSUM">WDB_MEM_CHECKSUM</a></b> - checksum a block of target memory<br><b><a href="./wdb.html#WDB_MEM_FILL">WDB_MEM_FILL</a></b> - fill target memory with a pattern<br><b><a href="./wdb.html#WDB_MEM_MOVE">WDB_MEM_MOVE</a></b> - move memory on the target<br><b><a href="./wdb.html#WDB_MEM_PROTECT">WDB_MEM_PROTECT</a></b> - write enable/disable a region of target memory<br><b><a href="./wdb.html#WDB_MEM_READ">WDB_MEM_READ</a></b> - read memory from the target<br><b><a href="./wdb.html#WDB_MEM_SCAN">WDB_MEM_SCAN</a></b> - scan a block of target memory for a pattern<br><b><a href="./wdb.html#WDB_MEM_WRITE">WDB_MEM_WRITE</a></b> - write the contents of host memory to target memory<br><b><a href="./wdb.html#WDB_MODE_GET">WDB_MODE_GET</a></b> - get the agent mode<br><b><a href="./wdb.html#WDB_MODE_SET">WDB_MODE_SET</a></b> - set the agent mode<br><b><a href="./wdb.html#WDB_REGS_GET">WDB_REGS_GET</a></b> - get the registers of a context on the target<br><b><a href="./wdb.html#WDB_REGS_SET">WDB_REGS_SET</a></b> - set the registers of a context on the target<br><b><a href="./wdb.html#WDB_TARGET_CONNECT">WDB_TARGET_CONNECT</a></b> - connect the target server to the target agent<br><b><a href="./wdb.html#WDB_TARGET_DISCONNECT">WDB_TARGET_DISCONNECT</a></b> - disconnect the target server from the target agent<br><b><a href="./wdb.html#WDB_TARGET_PING">WDB_TARGET_PING</a></b> - probe the target<br><b><a href="./wdb.html#WDB_VIO_WRITE">WDB_VIO_WRITE</a></b> - write data to a virtual I/O channel<br><p></blockquote><h4>DESCRIPTION </h4><blockquote><p><p> This document describes the Wind River Debug (WDB) version 2.0 protocol.It is the protocol used by the Tornado target server back endsthat communicate with the target agent (WDB RPC, WDB Serial, WDB NetROMand WDB Pipe).<p>The diagram below gives an overview of the Tornado environment.<p><pre> +---------+ +---------+ +---------+ +---------+ | | | | | | | | | Shell | | Debugger| | Browser | | Other | | | | | | | | Tools | +----+----+ +----+----+ +----+----+ +----+----+ | | | | +--------------------+ | +-----------+ | | | | +-----------------------+ WTX | | | | Protocol | | | | +--+--+--+--+---+ | | | Target Server | | | +-+--+--+--+--+-+ | | | | | | | | | +--------------------------+ | | | +-----------------+ | +----+ | +--------+ | | | | | | | Target Server +---+---+ +---+----+ +---+----+ +---+----+ +---+----+ Back Ends | WDB | | WDB | | WDB | | WDB | |Non-WDB | | RPC | | Netrom | | Serial | | Pipe | |Back End| +---+---+ +---+----+ +----+---+ +---+----+ +---+----+ | | | | | Host | | | | | - - - - - - - -- - - -|- - - - - |- - - - - - |- - - - - |- - - - - -|- - Target (or simulator)| | | | | | | | | | +---+---+ +---+----+ +----+---+ +---+----+ | |Network| | Netrom | | Serial | | Pipe | | WDB Target Agent |Comm if| |Comm if | |Comm if | |Comm if | | Communication +---+---+ +---+----+ +----+---+ +---+----+ | Interfaces | | | | | +--------+ | +----------+ | | | | | +-------------------+ | | | | | | +--+-+-+-+--+ +----+----+ |WDB Target | | Non-WDB | Agents | Agent | | Agent | +-----+-----+ +----+----+ | | +----+----+ | | | | | vxWorks +-----------------------------+ | | +---------+</pre></blockquote><h4>NOTE</h4><blockquote><p>If you want to create a new back end for Tornado, knowledge ofthe WDB protocol is not needed. Creating a back end that communicateswith the WDB agent requires installing a new communication pathbetween the host and target. Once the communication path is established,the target agent performs all the services needed.Creating a back end that communicates with a non-WDB agent (for example, anICE) requires implementing all the target services required.For details, refer to the <i>API Programmer's Guide: Target Server Back End. </i><p>The next few sections describe the format of messages sent betweenthe host and target. The rest of this chapter describes the actualset of services provided by the agent.<p></blockquote><h4>PROTOCOL OVERVIEW</h4><blockquote><p>The WDB protocol is an RPC-based protocol which uses UDP. The WDB agent acts as a server for requests sent by the target server. For more information, seeone of the many generally available references on UDP and Sun RPC.<p>Some key definitions can be found in <b>share/src/agents/wdb/wdb.h</b>:<ul><li>The UDP port that the agent accepts request from, WDBPORT, is 0x4321.</li><li>The agent's RPC program number, WDBPROG, is 0x55555555.</li><li>The agent's RPC version number, WDBVERS, is 1. </ul><p><p></blockquote><h4>REQUESTS SENT TO THE AGENT</h4><blockquote><p>A WDB request packet sent to the agent contains, in order:<ul><li>A 20-byte IP header.</li><li>An 8-byte UDP header. It consists of four 16-bit words. WDBPORT is word 2.</li><li>A 40-byte RPC request header. It consists of ten 32-bit words. WDBPROG isword 3. WDBVERS is word 4. The RPC procedure number is word 5.</li><li>An XDR stream. The first 12 bytes of this stream is WDB-parameter-wrapper information. (See <b>${<b>WIND_BASE</b>}/share/src/agents/wdb</b> for moreinformation on the <b>WDB_XDR</b> functions.) </ul><p><p>The diagram below shows the layout of the WDB request packet. The main WDB information is contained in the XDR stream. This is where the input parametersfor the WDB functions are transferred to the target agent.<p><pre> +-----+ IP HEADER | | 20 bytes | | | | | | | | +-----+ UDP HEADER | | WDBPORT 8 bytes | | +-----+ RPC REQUEST HEADER | | 40 bytes | | WDBPROG (10 32-bit words) | | WDBVERS | | RPC procedure # | | | | | | | | XDR Stream +-----+ WDB PARAMETER WRAPPER | | Checksum 12 bytes | | Packet Size | | Sequence # | - - | XDR encoded PARAMETERS | | (function input parameters) | | | | | |</pre>The WDB parameter wrapper contains three 4-byte words. The first wordis a checksum over the whole RPC packet (RPC header + XDR stream).The second word is the packet size. These two words enable the agentto determine if a corrupted packet has arrived. The third word isa sequence number. The low order two bytes of the sequence numberare used to allow the agent to ignore old or duplicated requests (whichcan occur with UDP transport). The high order two bytes are the<b>host ID</b>. When a host issues a <b><a href="./wdb.html#WDB_TARGET_CONNECT">WDB_TARGET_CONNECT</a></b> request,the host ID portion of the sequence number is recorded. If a requestarrives from a non-connected host, the RPC fails with the RPCerror status <b>PROG_UNAVAIL</b> or <b>SYSTEM_ERR</b>, depending on whether theagent is already connected to another target server or not.The <b><a href="./wdb.html#WDB_TARGET_CONNECT">WDB_TARGET_CONNECT</a></b> request always establishes a new connection,if necessary by dropping the old one. If the host wants to test whether ornot the agent is already connected before trying to establish a connection,it should first issue a <b><a href="./wdb.html#WDB_TARGET_PING">WDB_TARGET_PING</a></b> request and see if the RPC failswith error status <b>PROG_UNAVAIL</b>. If so the connection is busy.<p>The routine <b>xdr_WDB_PARAM_WRAPPER</b> is used to encode or decode the entire XDRstream (the procedure parameters plus the 12-byte parameter wrapper). The following example is a code stub from the host routine <b><i>rpcCoreClntCall</i>( )</b>:<p><pre> seqNumber++ ; ... wdbParamWrapper.xdr = inProc; /* xdr func for proc params */ wdbParamWrapper.pParams = in; /* pointer to proc params */ wdbParamWrapper.seqNum = processId | seqNumber; /* seq nb */ ... clntStatus = clnt_call (pWdbClnt, procNum, xdr_WDB_PARAM_WRAPPER, &wdbParamWrapper, ...);</pre></blockquote><h4>REPLIES SENT BY THE AGENT</h4><blockquote><p>A WDB reply packet sent by the agent contains, in order:<ul><li>A 20-byte IP header.</li><li>An 8-byte UDP header.</li><li>A 24-byte RPC reply header.</li><li>An XDR stream. The first 12 bytes of this stream is WDB replywrapper info (see below). The rest of the stream is the XDR-encoded reply from the procedure. </ul><p><p>The diagram below shows the layout of the WDB reply packet. As with the WDBrequest packet, the main WDB information is contained in the XDR stream. Theresult of the WDB function is returned to the host in this stream.<p><pre> +-----+ IP HEADER | | 20 bytes | | | | | | | | +-----+ UDP HEADER | | 8 bytes | | +-----+ RPC REPLY HEADER | | 24 BYTES | | WDBPROG (6 32-bit words) | | WDBVERS | | RPC procedure # | | | | | | | | XDR Stream +-----+ WDB REPLY WRAPPER | | Checksum 12 bytes | | Packet Size | | WDB Error Status | - - | XDR encoded REPLY | | (function output) | | | | | |</pre>Like the WDB parameter wrapper, the WDB reply wrapper contains three 4-byte words. The first word is a checksum over the whole RPC packet (RPC header plus XDR stream). The second word is the packet size. These two words enable the host to determine if a corrupted reply was returned (and, if so, to reissue the request). The third word is the WDB error status. The high order bit is set if there are events pending on the target, in which case thehost can issue a <b><a href="./wdb.html#WDB_EVENT_GET">WDB_EVENT_GET</a></b> request to upload the event. The rest of the word is the actual error status.牋<p><p><p></blockquote><h4>REPLY ERRORS</h4><blockquote><p>After a remote procedure is called, the program should perform error checking.Error status can be communicated in one of two ways: in the RPC header or inthe reply wrapper. If the failure is reported in the RPC header, then the host's<b>clnt_call</b> will return an RPC error status. These have conventional meanings according to the RPC specification. In addition, the WDB agent uses thefollowing special codes:<p><dl><dt><b>RPC_PROCUNAVAIL</b><dd>The RPC procedure requested is not configured into the agent. The agent is scalable, so this usually means the agent was built without that service.<p><dt><b>RPC_PROGUNAVAIL</b><dd>The agent refused to execute the procedure because it is connected to another host.<p><dt><b>RPC_SYSTEMERROR</b><dd>The agent refused to execute the procedure because it is not connected to any host. If you were previously connected, the target has rebooted. </dl><p>Even if the RPC call succeeds (meaning that the agent tries to execute your command), the command may still fail. The <b>errCode</b> field in the reply wrappercan be checked; if the lower 30 bits are zero, the command succeeded. (Rememberthat the high-order bit is set if there are events pending on the target.) If the value is non-zero, then the procedure failed and the word contains the error code. Error codes have the format <b>WDB_ERR_XXX</b> and are defined in ${<b>WIND_BASE</b>}<b>/share/src/agents/wdb/wdb.h</b>.<p>The routine <b>xdr_WDB_REPLY_WRAPPER</b> is used to encode or decode the entire XDR stream (the reply data plus the 12-byte reply wrapper). The followingpseudo code shows how it works:<p><pre> wdbReplyWrapper.xdr = outProc; /* reply xdr function */ wdbReplyWrapper.pReply = out; /* where to decode reply */ wdbReplyWrapper.errCode = OK; /* just to clear this field */ ... clntStatus = clnt_call (pWdbClnt, procNum, xdr_WDB_PARAM_WRAPPER, &wdbParamWrapper, xdr_WDB_REPLY_WRAPPER, &wdbReplyWrapper, timeout); check (clntStatus) { if (RPC_TIMEDOUT or RPC_CANTDECODERES or RPC_CANTDECODEARGS) try again if (RPC_SYSTEMERROR) if we were previously connected, then target must have rebooted so resync and reconnect. if (RPC_PROCUNAVAIL) procedure not configured into agent. Try to rebuild the agent with that facility included (e.g., virtual I/O is an optional agent facility). if (RPC_SUCCESS) agent tried to execute the routine. check high order bit of wdbReplyWrapper.errCode to see if events are pending on the target. If so, execute a WDB_EVENT_GET request after finishing processing this reply. mask off the high order bit of wdbReplyWrapper.errCode. if (wdbReplyWrapper.errCode == 0) success! In this case wdbReplyWrapper.xdr decoded the reply and put it in wdbReplyWrapper.pReply. else wdbReplyWrapper.errCode contains the reason for procedure failure. The error coded are defined in wdb.h. }</pre>As the above pseudo code indicates, if you do not receive an RPC error or<b>RPC_SUCCESS</b>, <b>wdbReplyWrapper.errCode</b> contains the reason for the procedurefailure. The possible error codes are as follows:<p><pre>WDB_OK OK /* success */WDB_ERR_INVALID_PARAMS 0x501 /* params invalid */WDB_ERR_MEM_ACCES 0x502 /* memory fault */WDB_ERR_AGENT_MODE 0x503 /* wrong agent mode */WDB_ERR_RT_ERROR 0x504 /* run-time callout failed */WDB_ERR_INVALID_CONTEXT 0x505 /* bad task ID */WDB_ERR_INVALID_VIO_CHANNEL 0x506 /* bad virtual I/O channel */WDB_ERR_INVALID_EVENT 0x507 /* no such event type */WDB_ERR_INVALID_EVENTPOINT 0x508 /* no such eventpoint */WDB_ERR_GOPHER_FAULT 0x509 /* gopher fault */WDB_ERR_GOPHER_TRUNCATED 0x50a /* gopher tape too large */WDB_ERR_EVENTPOINT_TABLE_FULL 0x50b /* out of room */WDB_ERR_NO_AGENT_PROC 0x50c /* agent proc not installed */WDB_ERR_NO_RT_PROC 0x50d /* run-time callout unavail */WDB_ERR_GOPHER_SYNTAX 0x50e /* gopher syntax error */WDB_ERR_NOT_FOUND 0x50f /* object not found */WDB_ERR_HW_REGS_EXHAUSTED 0x510 /* hardware breakpoint registers full */WDB_ERR_INVALID_HW_BP 0x511 /* invalid hardware breakpoint */WDB_ERR_PROC_FAILED 0x5ff /* generic proc failure */WDB_ERR_NO_CONNECTION 0x600 /* not connected */WDB_ERR_CONNECTION_BUSY 0x601 /* someone else connected */WDB_ERR_COMMUNICATION 0x6ff /* generic comm error */</pre></blockquote><h4>ASYNCHRONOUS NOTIFICATION BY THE AGENT</h4><blockquote><p>Asynchronous events can be generated on the target. These includeexceptions, breakpoints, and task exiting. These events are queued on thetarget until the host uploads them with the <b><a href="./wdb.html#WDB_EVENT_GET">WDB_EVENT_GET</a></b> service. Inorder to prevent the host from polling for events, the agent has two waysto notify the host that events are pending. One way is setting the highorder bit in the <b>errCode</b> status of the reply wrapper. The other way is bysending a "notify packet".<p>Normally the agent only sends data to the host in response to RPCrequests. The convention is that if the host receives data when it is notwaiting for a reply, it means that an event is pending on the target. Thetarget server waits for events from other host tools as well as from thetarget. When the target sends an event, the host issues a <b><a href="./wdb.html#WDB_EVENT_GET">WDB_EVENT_GET</a></b>request to upload the event (and keeps uploading events until the highorder bit in the <b>errCode</b> field is clear). The actual notify packet sent bythe agent is a packet that can not be confused with an RPC reply (in caseit sends the notify packet just as the host issues an RPC request). Infact, it sends a bogus RPC request.⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -