📄 c-bkend3.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><html><head><link rel="STYLESHEET" type="text/css" href="wrs.css"><title> Target Server Back End </title></head><body bgcolor="FFFFFF"><p class="navbar" align="right"><a href="index.html"><img border="0" alt="[Contents]" src="icons/contents.gif"></a><a href="c-bkend.html"><img border="0" alt="[Index]" src="icons/index.gif"></a><a href="c-bkend.html"><img border="0" alt="[Top]" src="icons/top.gif"></a><a href="c-bkend2.html"><img border="0" alt="[Prev]" src="icons/prev.gif"></a><a href="c-bkend4.html"><img border="0" alt="[Next]" src="icons/next.gif"></a></p><font face="Helvetica, sans-serif" class="sans"><h3 class="H2"><i><a name="84903">2.3 Writing a New WDB Back End</a></i></h3></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="84905"> </a>The back ends provided by Wind River Systems support a variety of communication alternatives, but not all cases are supported. Customers interested in using an unsupported communication link must write a new back end.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="84906">2.3.1 Overview of Writing a WDB Back End</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="84907"> </a>Developing a back end to communicate with the WDB agent is simple: because all the services are already implemented in the WDB agent, the new back end only needs to transport WDB RPC messages.</p><dd><p class="Body"><a name="84908"> </a>The key development steps are:</p></dl><dl class="margin"><p class="listspace"><ul class="Bullet" type="disc"><li><a name="84909"> </a>Write a back end which utilizes RPC core functions, if necessary. For a new machine, you must write <b class="file">clnt_</b><i class="i">xxx</i><b class="file">.c</b>. </li></ul></p><p class="listspace"><ul class="Bullet" type="disc"><li><a name="84910"> </a>Write a device driver on the target, if necessary.</li></ul></p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="84911">2.3.2 WDB Protocol</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="84913"> </a>This section describes the Wind DeBug (WDB) version 1.0 protocol. It is the protocol used by the Tornado target server back ends that communicate with the WDB agent (WDB RPC, WDB Serial, and NetROM). See <a href="c-bkend1.html#90230">Figure 2-1</a> for a diagram of how these back ends connect to the WDB agent.</p></dl></dl><dl class="margin"><dd><p class="table" callout><table border="0" cellpadding="0" cellspacing="0"><tr valign="top"><td valign="top" width="40"><br><img border="0" alt="*" src="icons/note.gif"></td><td><hr><div class="CalloutCell"><a name="89298"><b class="symbol_UC"><font face="Helvetica, sans-serif" size="-1" class="sans">NOTE: </font></b></a>This section is provided for completeness only. If you want to create a new back end for Tornado, knowledge of the WDB protocol is not needed because the support libraries handle all aspects of the protocol not related to transport. In fact, in order to assure that your back end is not affected by changes in WDB, you should gain access to WDB facilities through the support libraries as shown in the example back ends. To create a non-WDB back end that communicates with a device such as an ICE or a ROM monitor, you also need to implement all the target services required. For details, refer to <a href="c-bkend4.html#85474"><i class="title">2.4 Writing a Non-WDB Back End</i></a>.</div></td></tr><tr valign="top"><td></td><td><hr></td></tr><tr valign="middle"><td colspan="20"></td></tr></table></p callout></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H4"><i><a name="84929">Protocol Overview</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="84932"> </a>WDB 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, see one of the many generally available references on UDP and Sun RPC.</p><dd><p class="Body"><a name="84933"> </a>See <i class="textVariable">installDir</i><b class="file">/share/src/agents/wdb/wdbP.h </b>for some key definitions:</p></dl><dl class="margin"><p class="listspace"><ul class="Dash" type="circle"><li><a name="84934"> </a>The UDP port that the agent accepts requests from, <b class="symbol_UC">WDBPORT</b>, is 0x4321.</li></ul></p><p class="listspace"><ul class="Dash" type="circle"><li><a name="84935"> </a>The agent's RPC program number, <b class="symbol_UC">WDBPROG</b>, is 0x55555555.</li></ul></p><p class="listspace"><ul class="Dash" type="circle"><li><a name="84936"> </a>The agent's RPC version number, <b class="symbol_UC">WDBVERS</b>, is 1.</li></ul></p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H4"><i><a name="84937">Requests Sent to the Agent</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="84939"> </a>A WDB request packet sent to the agent contains the following parts, as shown in <a href="c-bkend3.html#90360">Figure 2-3</a>: <div class="frame"><h4 class="EntityTitle"><a name="90360"><font face="Helvetica, sans-serif" size="-1" class="sans">Figure 2-3: WDB Request Packet</font></a></h4><dl class="margin"><div class="Anchor"><a name="90362"> </a><img class="figure" border="0" src="images/c-bkenda3.gif"></div></dl></div> </p></dl><dl class="margin"><p class="listspace"><ul class="Dash" type="circle"><li><a name="84988"> </a>A 20-byte IP header.</li></ul></p><p class="listspace"><ul class="Dash" type="circle"><li><a name="84989"> </a>An 8-byte UDP header. It consists of four 16-bit words. <b class="symbol_UC">WDBPORT</b> is word 2.</li></ul></p><p class="listspace"><ul class="Dash" type="circle"><li><a name="84990"> </a>A 40-byte RPC request header. It consists of ten 32-bit words. <b class="symbol_UC">WDBPROG</b> is word 3. <b class="symbol_UC">WDBVERS</b> is word 4. The RPC procedure number is word 5.</li></ul></p><p class="listspace"><ul class="Dash" type="circle"><li><a name="84992"> </a>An XDR stream. The first 12 bytes of this stream is WDB-parameter-wrapper information. The rest of the stream is the XDR-encoded parameters for the procedure. (See <i class="textVariable">installDir</i><b class="file">/share/src/agents/wdb</b> for more information on the <b class="symbol_UC">WDB_XDR</b> functions.)</li></ul></p><dl class="margin"><dd><div class="Indent"><a name="84993"> </a>The WDB parameter 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 agent to determine if a corrupted packet has arrived. The third word is a sequence number. The low order two bytes of the sequence number are used to allow the agent to ignore old or duplicated requests (which can occur with UDP transport). The high order two bytes are the <i class="term">host ID</i>. When a host issues a <b class="symbol_UC">WDB_TARGET_CONNECT</b> request, the host ID portion of the sequence number is recorded. If a request arrives from a non-connected host, the RPC fails with the RPC error status <b class="symbol_UC">PROG_UNAVAIL</b> or <b class="symbol_UC">SYSTEM_ERR</b>, depending on whether the agent is already connected to another target server or not. The <b class="symbol_UC">WDB_TARGET_CONNECT</b> request always establishes a new connection, if necessary by dropping the old one. If the host wants to test whether or not the agent is already connected before trying to establish a connection, it should first issue a <b class="symbol_UC">WDB_TARGET_PING</b> request and see if the RPC fails with error status <b class="symbol_UC">PROG_UNAVAIL</b>. If so the connection is busy.</div><br><dd><div class="Indent"><a name="85000"> </a>The routine <b class="symbol_lc">xdr</b><b class="symbol_UC">_WDB_PARAM_WRAPPER</b> is used to encode or decode the entire XDR stream (the procedure parameters plus the 12-byte parameter wrapper). The following example is a code stub from the host routine <b class="routine"><i class="routine">rpcCoreClntCall</i></b><b>( )</b>:</div><br></dl><dl class="margin"><dd><pre class="Code2"><b><a name="85001">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,...);</a></b></pre></dl></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H4"><i><a name="85010">Replies Sent by the Agent</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="85012"> </a>A WDB reply packet sent by the agent contains the following parts, as shown in <a href="c-bkend3.html#90418">Figure 2-4</a>:</p></dl><dl class="margin"><p class="listspace"><ul class="Dash" type="circle"><li><a name="85016"> </a>A 20-byte IP header.</li></ul></p><p class="listspace"><ul class="Dash" type="circle"><li><a name="85017"> </a>An 8-byte UDP header.</li></ul></p><p class="listspace"><ul class="Dash" type="circle"><li><a name="85018"> </a>A 24-byte RPC reply header.</li></ul></p><p class="listspace"><ul class="Dash" type="circle"><li><a name="85020"> </a>An XDR stream. The first 12 bytes of this stream is WDB-reply-wrapper information. The rest of the stream is the XDR-encoded reply from the procedure.</li></ul></p><dl class="margin"><dd><div class="Indent"><a name="85066"> </a>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 the host can issue a <b class="symbol_UC">WDB_EVENT_GET</b> request to upload the event. The rest of the word is the actual error status. <div class="frame"><h4 class="EntityTitle"><a name="90418"><font face="Helvetica, sans-serif" size="-1" class="sans">Figure 2-4: WDB Reply Packet</font></a></h4><dl class="margin"><div class="Anchor"><a name="90420"> </a><img class="figure" border="0" src="images/c-bkend5.gif"></div></dl></div> </div><br></dl></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H4"><i><a name="85068">Reply Errors</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="85070"> </a>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 in the reply wrapper. If the failure is reported in the third word of the RPC header, then the host's <b class="symbol_lc">clnt_call</b> returns an RPC error status. These have conventional meanings according to the RPC specification. In addition, the WDB agent uses a couple of special codes:</p></dl><dl class="margin"><dd><div class="Item"><a name="85071"> </a><b class="symbol_UC">RPC_PROCUNAVAIL</b> </div><dl class="margin"><dl class="margin"><dd><div class="Indent2"><a name="85072"> </a>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.</div><br></dl></dl><dd><div class="Item"><a name="85073"> </a><b class="symbol_UC">RPC_PROGUNAVAIL</b> </div><dl class="margin"><dl class="margin"><dd><div class="Indent2"><a name="85074"> </a>The agent refused to execute the procedure because it is connected to another host.</div><br></dl></dl><dd><div class="Item"><a name="85075"> </a><b class="symbol_UC">RPC_SYSTEMERROR</b> </div><dl class="margin"><dl class="margin"><dd><div class="Indent2"><a name="85076"> </a>The agent refused to execute the procedure because it is not connected to any host. If you were previously connected, the target has rebooted.</div><br></dl></dl></dl><dl class="margin"><dd><p class="Body"><a name="85077"> </a>Even if the RPC call succeeds (meaning that the agent tries to execute your command), the command may still fail. The <b class="command">errCode</b> field in the reply wrapper can be checked; if the lower 31 bits are zero, the command succeeded. (Remember that 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 class="symbol_UC">WDB_ERR_</b><i class="textVariable">XXX. </i>The error-code definitions are located in <i class="textVariable">installDir</i><b class="file">/share/src/agents/wdb/wdb.h</b>.</p><dd><p class="Body"><a name="85079"> </a>The routine <b class="file">xdr</b><b class="symbol_UC">_WDB_REPLY_WRAPPER </b>is used to encode or decode the entire XDR stream (the reply data plus the 12-byte reply wrapper). The following pseudo code shows how it works:</p></dl><dl class="margin"><dd><pre class="Code"><b><a name="85080">wdbReplyWrapper.xdr = outProc; /* reply xdr function */ wdbReplyWrapper.pReply = out; /* where to decode reply */ ⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -