📄 c-wtx4.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><html><head><link rel="STYLESHEET" type="text/css" href="wrs.css"><title> The WTX Protocol </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-wtx.html"><img border="0" alt="[Index]" src="icons/index.gif"></a><a href="c-wtx.html"><img border="0" alt="[Top]" src="icons/top.gif"></a><a href="c-wtx3.html"><img border="0" alt="[Prev]" src="icons/prev.gif"></a><a href="c-wtx5.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="85250">4.4 WTX Tcl API</a></i></h3></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="85252"> </a>This section introduces the WTX Tcl API and gives a series of interactive examples for using Tcl to communicate with a target server. These examples not only explain the WTX Tcl API, but also demonstrate how the WTX Protocol works. For this reason, users who plan to work primarily with the WTX C API (see <a href="c-wtx5.html#85723"><i class="title">4.5 WTX C API</i></a>) may benefit from working through these Tcl examples.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="85256">4.4.1 Description</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="85257"> </a>The WTX Tcl API provides a binding of the WTX protocol to the Tcl language. This allows you to write Tcl scripts that interact with the WTX environment. Every WTX protocol request is available to the Tcl interface. Tornado provides a standalone Tcl interpreter, as well as an object library that allows the WTX-Tcl binding to be included in other applications. The WTX Tcl API is based on Tcl version 8.0, and on UNIX hosts includes the Extended Tcl 8.0 package. </p><dd><p class="Body"><a name="85258"> </a>For each WTX protocol request (for example, <b class="symbol_UC">WTX_MEM_READ</b>), there is a corresponding Tcl command (<b class="tclProc">wtxMemRead</b>). The names of all WTX Tcl API commands are derived from the protocol request names according to <a href="x-codetcl.html#83307"><i class="title">A. Tcl Coding Conventions</i></a>; in other words, underscores are removed and all words but the first are capitalized. </p><dd><p class="Body"><a name="85259"> </a>Each WTX Tcl command has an online reference entry in HTML format under <b class="guiLabel"><font face="Helvetica, sans-serif" size="-1" class="sans">Tornado API Guide>WTX Tcl Library</font></b>. For information on the online reference material, see the <i class="title">Tornado User's Guide: Documentation Guide</i> and <i class="title">Tornado Getting Started</i>. Most WTX Tcl API commands also return a brief syntax message if they are invoked without arguments.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="85261">4.4.2 Starting a <b class="command">wtxtcl</b> Session</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="85263"> </a>One of the interactive tools in Tornado is called <b class="command">wtxtcl</b>, a standalone Tcl interpreter for the WTX extensions. All Tornado tools also include their own Tcl interpreter, because Tcl is the language of much of the Tornado implementation. All the interpreters have access to the WTX extensions. However, <b class="command">wtxtcl</b> is an ideal environment for experimenting with and testing the WTX interface because it contains only the WTX extensions.</p><dd><p class="Body"><a name="85264"> </a>When you call <b class="command">wtxtcl</b>, Tornado responds with the <b class="command">wtxtcl</b> prompt; you may begin typing Tcl<b class="command"> </b>commands immediately. Invoking <b class="command">wtxtcl</b> with an argument identifies a file of Tcl commands to execute.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="85265">4.4.3 Attaching to a Target Server</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="85267"> </a>Before the majority of <b class="command">wtxtcl</b> commands can be used, you must attach to an active target server. The Tornado registry maintains a list of available target servers for a site or workgroup. Use <b class="tclProc">wtxInfoQ</b> to determine what servers are active by querying the contents of the Tornado registry.</p><dl class="margin"><dd><pre class="Code2"><b><a name="85269"></b><tt class="output">wtxtcl> </tt><b>wtxInfoQ </b><tt class="output">{vxsim7@aven tgtsvr rpc/aven/147.11.80.6/570425345/1/tcp/42781} {mv147@aven tgtsvr rpc/aven/147.11.80.6/570425347/1/tcp/44830} {jim@dnestr tgtsvr rpc/dnestr/147.11.80.4/570425345/1/tcp/52411} {wtxregd@aven registry rpc/aven/147.11.80.6/570425344/1/tcp/52157}</tt><b></a></b></pre></dl><dd><p class="Body"><a name="85274"> </a>The routine returns a series of three-element lists, each of the form <b class="symbol_lc">{</b><i class="textVariable">name type key</i><b class="symbol_lc">}</b>. The Tornado registry includes information about itself (note the fourth line of the output). To limit the returned information, you can use regular expressions on the <b class="tclProc">wtxInfoQ</b> command to qualify each of the three fields. For example, to see only target servers running on host <b class="symbol_lc">aven</b>, type:</p><dl class="margin"><dd><pre class="Code2"><b><a name="85275"></b><tt class="output">wtxtcl> </tt><b>wtxInfoQ @aven$ tgtsvr .* </b><tt class="output">{vxsim7@aven tgtsvr rpc/aven/147.11.80.6/570425345/1/tcp/42781} {mv147@aven tgtsvr rpc/aven/147.11.80.6/570425347/1/tcp/44830} </tt><b></a></b></pre></dl><dd><p class="Body"><a name="85278"> </a>Each of the three arguments is a regular expression that qualifies the corresponding field in the output, and an entry is returned only if it matches all regular expressions provided. </p><dd><p class="Body"><a name="85279"> </a>After learning the name of a target server, you must attach to it in order to carry out further WTX transactions:</p><dl class="margin"><dd><pre class="Code2"><b><a name="85280"></b><tt class="output">wtxtcl> </tt><b>wtxToolAttach t80-202@aven myTool </b><tt class="output">t80-202@aven</tt><b></a></b></pre></dl><dd><p class="Body"><a name="85282"> </a>The string <b class="symbol_lc">myTool</b> is a name you choose to represent your Tcl session. The target server records it and reports this name to any tool that requests a list of attached tools. You can see <b class="symbol_lc">myTool</b> in the list of attached tools on the Tornado launcher (UNIX) or the <b class="guiLabel"><font face="Helvetica, sans-serif" size="-1" class="sans">Manage Target Servers</font></b> dialog box (Windows) if your target server is selected.</p><dd><p class="Body"><a name="85284"> </a>The value returned by this command, <b class="symbol_lc">t80-202@aven</b>, is called the <i class="term">WTX Tcl handle</i>, and can be used to refer to this connection when multiple connections are made in a single <b class="command">wtxtcl</b> session.</p><dd><p class="Body"><a name="85285"> </a>Once a target server is attached, you may use any WTX Tcl command. The examples in the remainder of this section assume that a target server is attached.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="85287">4.4.4 Obtaining Target Server Information</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="85289"> </a>You can learn about the architecture and about other tools connected to the target server with <b class="tclProc">wtxTsInfoGet</b>:</p></dl><dl class="margin"><dd><pre class="Code"><b><a name="85291"></b><tt class="output">wtxtcl> </tt><b><a href="../../tornado-api/wtxtcl/wtdoc.html#wtxTsInfoGet" >wtxTsInfoGet</a></b><tt class="output"> {WDB Agent RPC} {255 0} {5 1 0 8192 1234} {1 5.4} {Motorola MVME162} / aven:/installDir/target/config/mv162/vxWorks {0 4194304} {0x96c60 223546} chrisc {Fri Jan 8 17:59:38 1999} {Fri Jan 8 17:59:38 1999} unreserved 0 myTool 2.0</tt><b></a></b><dd> <b><a name="85293"></b><tt class="output">{0x1a5278 wtxtcl {} {} myself@aven}</tt><b></a></b></pre></dl><dl class="margin"><dd><p class="Body"><a name="85294"> </a>For a detailed explanation of the fields in this structure, see the online reference material under<b class="guiLabel"><font face="Helvetica, sans-serif" size="-1" class="sans">Tornado API Guide>WTX Protocol</font></b>.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="85295">4.4.5 Working with Memory</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="85298"> </a>To read a block of memory from the target, use <b class="tclProc">wtxMemRead</b>, specifying the base address and the size of the block:</p><dl class="margin"><dd><pre class="Code2"><b><a name="85299"></b><tt class="output">wtxtcl> </tt><b>wtxMemRead 0x2000 256 </b><tt class="output">mblk0</tt><b></a></b></pre></dl><dd><p class="Body"><a name="85302"> </a>The command returns a <i class="term">memory block handle</i>. This short string is used by a variety of Tcl commands that work with memory. These commands are provided to avoid the overhead of converting target memory to a string representation, and to make manipulating memory easier. It is often convenient to save memory block handles in variables:</p><dl class="margin"><dd><pre class="Code2"><b><a name="85303"></b><tt class="output">wtxtcl> </tt><b>set mb [wtxMemRead 0x2000 256] </b><tt class="output">mblk1</tt><b></a></b></pre></dl><dd><p class="Body"><a name="85305"> </a>To print the memory block, you can use <b class="tclProc">memBlockGet</b> with the handle as a parameter:</p><dl class="margin"><dd><pre class="Code2"><b><a name="85306"></b><tt class="output">wtxtcl> </tt><b>memBlockGet $mb </b><tt class="output">0x03 0x00 0x00 0x39 0x82 0x10 0x60...</tt><b></a></b></pre></dl><dd><p class="Body"><a name="85308"> </a>The target server manages a block of memory on the target. You can allocate such a block from the host using <b class="tclProc">wtxMemAlloc</b>. You can write to allocated memory, and read it back to verify that the write took place:</p><dl class="margin"><dd><pre class="Code2"><b><a name="85310"></b><tt class="output">wtxtcl> </tt><b>set mem [wtxMemAlloc 256]</a></b><dd> <b><a name="89489"></b><tt class="output">0x5897d0</tt><b> </b><tt class="output">wtxtcl> </tt><b>wtxMemWrite $mb $mem </b><tt class="output">0 wtxtcl> </tt><b>set ver [wtxMemRead $mem 256] </b><tt class="output">mblk2 wtxtcl> </tt><b>memBlockGet $ver </b><tt class="output">0x03 0x00 0x00 0x39 0x82 0x10 0x60...</tt><b></a></b></pre></dl><dd><p class="Body"><a name="85316"> </a>You can also work with parts of memory blocks, free blocks, write memory blocks to binary files or pipes, fill and checksum blocks of memory, and so on. For more information, see the online reference material under <b class="guiLabel"><font face="Helvetica, sans-serif" size="-1" class="sans">Tornado API Guide>WTX Protocol </font></b>and<b class="guiLabel"><font face="Helvetica, sans-serif" size="-1" class="sans"> WTX Tcl Library</font></b><i class="title">.</i><b class="tclProc"></b></p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="85318">4.4.6 Disassembling Memory</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="85321"> </a>To disassemble a block of memory from the target, use <b class="tclProc">wtxMemDisassemble</b>, specifying the base address and the number of instructions (default 10). The following example is from a PowerPC target:</p><dl class="margin"><dd><pre class="Code2"><b><a name="85322"></b><tt class="output">wtxtcl> </tt><b>wtxSymListGet -name "^printf$" </b><tt class="output">{printf 0x13e7bc 0x5 0 1 vxWorks} wtxtcl> </tt><b>wtxMemDisassemble -opcodes 0x13e7bc </b><tt class="output">{printf} 4 {} {9421ff80} {stwu r1, 0xff80(r1)} {} 4 {} {7c0802a6} {mfspr r0, LR} {} 4 {} {90010084} {stw r0, 0x84(r1)} {} 4 {} {90610008} {stw r3, 0x8(r1)} {} 4 {} {9081000c} {stw r4, 0xc(r1)} {} 4 {} {90a10010} {stw r5, 0x10(r1)} {} 4 {} {90c10014} {stw r6, 0x14(r1)} {} 4 {} {90e10018} {stw r7, 0x18(r1)} {} 4 {} {9101001c} {stw r8, 0x1c(r1)} {} 4 {} {91210020} {stw r9, 0x20(r1)}</tt><b></b><tt class="output"></tt><b></a></b></pre></dl></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="90668">4.4.7 <i class="term"></i>Working with the Symbol Table</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="85339"> </a>The target server symbol table can be queried and modified from <b class="command">wtxtcl</b>. The reason for doing this is to learn the address of a routine to call, the entry point for a task, or the address of a variable in order to read its value. Symbols can be looked up by name or value:</p><dl class="margin"><dd><pre class="Code2"><b><a name="85340"></b><tt class="output">wtxtcl> </tt><b>wtxSymFind -name taskDelay </b><tt class="output">_taskDelay 0x22ed4 0x5 0 0 "" wtxtcl> </tt><b>wtxSymFind -value 0x226b4 </b><tt class="output">_taskSuspend 0x226b4 0x5 0 0 ""</tt><b></a></b></pre></dl><dd><p class="Body"><a name="85344"> </a>For convenience, you can define a procedure that returns the value member of the symbol list for a given symbol name. Further examples assume the presence of this procedure (<b class="tclProc">symbol</b>). In order to use it, define it by typing it as shown:</p><dl class="margin"><dd><pre class="Code2"><b><a name="85346"></b><tt class="output">wtxtcl> </tt><b>proc symbol {name} \ {return [lindex [wtxSymFind -name $name] 1]} </b><tt class="output">wtxtcl> </tt><b>symbol taskDelay </b><tt class="output">0x22ed4</tt><b></a></b></pre></dl><dd><p class="Body"><a name="85351"> </a>To query a list of symbols using a regular expression, use <b class="tclProc">wtxSymListGet</b>:</p><dl class="margin"><dd><pre class="Code2"><b><a name="85352"></b><tt class="output">wtxtcl> </tt><b>wtxSymListGet -name ^taskD.* </b><tt class="output">{taskDeleteHookAdd 0x14b624 0x5 0 1 vxWorks} {taskDeleteTable 0x1a2368 0x9 0 1 vxWorks} {taskDeleteHookDelete 0x14b6b4 0x5 0 1 vxWorks} {taskDeleteForce 0x15ff48 0x5 0 1 vxWorks} {taskDelete 0x15ff1c 0x5 0 1 vxWorks} {taskDelay 0x1617cc 0x5 0 1 vxWorks} {taskDestroy 0x15ffa0 0x5 0 1 vxWorks}...</tt><b></a></b></pre></dl><dd><p class="Body"><a name="85358"> </a>You can also use <b class="tclProc">wtxSymListGet</b> to obtain a list of the symbols found near a given value:</p><dl class="margin"><dd><pre class="Code2"><b><a name="85359"></b><tt class="output">wtxtcl> </tt><b>wtxSymListGet -value 0x68000 </b><tt class="output">{_ip_output 0x67ae0 0x5 0 0 vxWorks} {_ip_insertoptions 0x681ac 0x5 0 0 vxWorks} {_ip_optcopy 0x68320 0x5 0 0 vxWorks} ...</tt><b></a></b></pre></dl></dl></dl>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -