wtx.html

vxworks相关论文

</pre>

Note that the WTX registry daemon <b><a href="../../tornado/tools/wtxregd.html#top" >wtxregd</a></b> must always be running for the 
Tornado environment to work.  <b><a href="../../tornado/tools/wtxregd.html#top" >wtxregd</a></b> is usually started as part of the
boot procedure of a given host.
<p>
</blockquote><h4>TOOL SESSION</h4><blockquote><p>
A typical example of a WTX shell tool session follows the sequence below:
<p>
<pre>          Shell Tool                           Target Server
          ----------                           -------------
               |
        ask WTX registry
      for target server key
         (WTX_INFO_GET)
               |
      attach to target server   &lt;-------&gt;   record info about tool 
        (WTX_TOOL_ATTACH)                     reply with tool ID
               |
         get target and
       target server info       &lt;-------&gt;      reply with info
        (WTX_TS_INFO_GET)
               |
       register for events      &lt;-------&gt;    record what to announce
     (WTX_REGISTER_FOR_EVENT)                    to this tool
               |
      load an object module     &lt;-------&gt;       return status
      (WTX_OBJ_MODULE_LOAD)
               |
          create a task         &lt;-------&gt;     create the task and
      (WTX_CONTEXT_CREATE)                   stop it at entry point
               |
        get a list of tasks     &lt;-------&gt;    return a list of tasks
        (WTX_GOPHER_EVAL)
               |
        set breakpoints         &lt;-------&gt;        return status
      (WTX_EVENTPOINT_ADD)
               |
          resume a task         &lt;-------&gt;        return status
      (WTX_CONTEXT_RESUME)
               |
   +----&gt;------+
   |           |
   |           |
   |  poll for target events
   |     (WTX_EVENT_GET)        &lt;-------&gt;    reply with a target event
   ^                                        (TEXT_ACCESS, EXCEPTION, etc)
   |           .
   |           .
   |           |
   +----&lt;------+
               |
          close session
        (WTX_TOOL_DETACH)
</pre>

</blockquote><h4>WTX EVENTS</h4><blockquote><p>
The WTX protocol allows host tools to be notified of events occurring on the
target and about certain actions performed by other tools.  It also allows
tools to register for particular events or types of events they wish to be
notified of or events they don't want to be notified of.
<p>
There are two ways of been notified when an event occurs: the first method
is to poll for the events with <b><a href="./wtx.html#WTX_EVENT_GET">WTX_EVENT_GET</a></b> and to process each event; 
the second method is to start the asynchronous notification of events
and give a user-defined routine which will be called each time an event
occurs on the target server.
<p>
WTX events, except <b>VIO_WRITE</b>, are strings. Registering for an event
consists in giving the target server a regular expression that matches
the event the tool wants to be notified of.
<p>
The table below gives the list of possible events and a list of tools that
are generally interested in being notified of these events.  In this table,
"own" means that a tool needs only to be notified of events that occur in a 
context it has created; "all" means notify the tool of all events of this 
type in all contexts.  This table is an example. Each tool designer must 
decide what events are useful to the tool.
<p>
<table>
<tr valign=top>
<th align=left>Event type       </th><th align=left> <b>T.S</b>. </th><th align=left> Shell </th><th align=left> Debugger </th><th align=left> Windview</tr>
<tr><td colspan="5"><hr></tr>
<tr valign=top>
<td align=left><b>CTX_START</b>        </td><td align=left>      </td><td align=left> own   </td><td align=left> own      </td><td align=left></tr>
<tr valign=top>
<td align=left><b>CTX_EXIT</b>         </td><td align=left>      </td><td align=left> own   </td><td align=left> own      </td><td align=left></tr>
<tr valign=top>
<td align=left><b>TEXT_ACCESS</b>      </td><td align=left>      </td><td align=left> own   </td><td align=left> own      </td><td align=left></tr>
<tr valign=top>
<td align=left><b>DATA_ACCESS</b>      </td><td align=left>      </td><td align=left> own   </td><td align=left> own      </td><td align=left></tr>
<tr valign=top>
<td align=left>EXCEPTION        </td><td align=left>      </td><td align=left> all   </td><td align=left> own      </td><td align=left></tr>
<tr valign=top>
<td align=left><b>VIO_WRITE</b>        </td><td align=left>      </td><td align=left> own   </td><td align=left> own      </td><td align=left></tr>
<tr valign=top>
<td align=left><b>EVTPT_ADDED</b>      </td><td align=left>      </td><td align=left> own   </td><td align=left> all      </td><td align=left></tr>
<tr valign=top>
<td align=left><b>EVTPT_DELETED</b>    </td><td align=left>      </td><td align=left> own   </td><td align=left> all      </td><td align=left></tr>
<tr valign=top>
<td align=left>                 </td><td align=left>      </td><td align=left>       </td><td align=left>          </td><td align=left></tr>
<tr valign=top>
<td align=left><b>CALL_RETURN</b>      </td><td align=left>      </td><td align=left> all   </td><td align=left> all      </td><td align=left></tr>
<tr valign=top>
<td align=left>                 </td><td align=left>      </td><td align=left>       </td><td align=left>          </td><td align=left></tr>
<tr valign=top>
<td align=left><b>TGT_RESET</b>        </td><td align=left> yes  </td><td align=left> yes   </td><td align=left> yes      </td><td align=left> yes</tr>
<tr valign=top>
<td align=left>                 </td><td align=left>      </td><td align=left>       </td><td align=left>          </td><td align=left></tr>
<tr valign=top>
<td align=left><b>TS_KILLED</b>        </td><td align=left>      </td><td align=left> yes   </td><td align=left> yes      </td><td align=left></tr>
<tr valign=top>
<td align=left>                 </td><td align=left>      </td><td align=left>       </td><td align=left>          </td><td align=left></tr>
<tr valign=top>
<td align=left><b>OBJ_LOADED</b>       </td><td align=left>      </td><td align=left> all   </td><td align=left>          </td><td align=left></tr>
<tr valign=top>
<td align=left><b>OBJ_UNLOADED</b>     </td><td align=left>      </td><td align=left> all   </td><td align=left>          </td><td align=left></tr>
<tr valign=top>
<td align=left>                 </td><td align=left>      </td><td align=left>       </td><td align=left>          </td><td align=left></tr>
<tr valign=top>
<td align=left><b>SYM_ADDED</b>        </td><td align=left>      </td><td align=left> some  </td><td align=left> some     </td><td align=left></tr>
<tr valign=top>
<td align=left><b>SYM_REMOVED</b>      </td><td align=left>      </td><td align=left> some  </td><td align=left> some     </td><td align=left></tr>
<tr valign=top>
<td align=left>                 </td><td align=left>      </td><td align=left>       </td><td align=left>          </td><td align=left></tr>
<tr valign=top>
<td align=left><b>TOOL_ATTACH</b>      </td><td align=left>      </td><td align=left> all   </td><td align=left>          </td><td align=left></tr>
<tr valign=top>
<td align=left><b>TOOL_DETACH</b>      </td><td align=left>      </td><td align=left> all   </td><td align=left>          </td><td align=left></tr>
<tr valign=top>
<td align=left>USER             </td><td align=left>      </td><td align=left>       </td><td align=left>          </td><td align=left></tr>
<tr valign=top>
<td align=left></tr>
</tr>

</table>

<b>EVENT_SYM_ADDED</b> and <b>EVENT_SYM_REMOVED</b> are only generated when a symbol
is added or removed from a shell session.  Symbols added or removed during
object module load or unload do not generate events in order to limit the
number of events sent to tools.
<p>
<b>EVTPT_ADDED</b> and <b>EVTPT_DELETED</b> are only generated when a tool add or
delete an event point. When a task containing breakpoints ends, then 
the only event generated is <b>CTX_EXIT</b> (no event <b>EVTPT_DELETED</b>). The tool must
update its event points list by removing all event points which match 
the contextId.
<p>
Events strings have the following syntax:
<p>
<pre>        <i>evtName</i> [<i>param1</i>] [<i>param2</i>] [<i>param3</i>] ...
</pre>

where [<i>paramX</i>] is optional and can be either a hexadecimal value
(0x12345678) or a string.  The event name <i>evtName</i> and the associated
parameters are given below.  (h) specifies a hexadecimal parameter and (s)
a string parameter.
<p>
<table>
<tr valign=top>
<td align=left><b>CTX_START</b>    </td><td align=left> contextType(h) </td><td align=left> contextId(h)   </td><td align=left> contextType(h) </td><td align=left> contextId(h)</tr>
<tr valign=top>
<td align=left><b>CTX_EXIT</b>     </td><td align=left> contextType(h) </td><td align=left> contextId(h)   </td><td align=left> returnVal(h) </td><td align=left> errnoVal(h)</tr>
<tr valign=top>
<td align=left><b>TEXT_ACCESS</b>  </td><td align=left> contextId(h)   </td><td align=left> contextType(h) </td><td align=left> pc(h)        </td><td align=left> fp(h)    </td><td align=left> sp(h) </tr>
<tr valign=top>
<td align=left><b>DATA_ACCESS</b>  </td><td align=left> contextId(h)   </td><td align=left> contextType(h) </td><td align=left> pc(h)        </td><td align=left> fp(h)    </td><td align=left> sp(h)  </td><td align=left> addr(h)</tr>
<tr valign=top>
<td align=left>EXCEPTION    </td><td align=left> contextType(h) </td><td align=left> contextId(h)   </td><td align=left> excVector(h) </td><td align=left> esfAddr(h)</tr>
<tr valign=top>
<td align=left><b>CALL_RETURN</b>  </td><td align=left> callTaskId(h)  </td><td align=left> returnVal(h)   </td><td align=left> errnoVal(h)</tr>
<tr valign=top>
<td align=left><b>VIO_WRITE</b>    </td><td align=left> channelId(h)   </td><td align=left> addlData       </td><td align=left> addlDataLen</tr>
<tr valign=top>
<td align=left><b>EVTPT_ADDED</b>  </td><td align=left> evtptNum(h)    </td><td align=left> (See <b><a href="./wtx.html#WTX_EVENTPOINT_ADD_2">WTX_EVENTPOINT_ADD_2</a></b>)</tr>
<tr valign=top>
<td align=left><b>EVTPT_DELETED</b></td><td align=left> evtptNum(h)</tr>
<tr valign=top>
<td align=left><b>TGT_RESET</b></tr>
<tr valign=top>
<td align=left><b>TS_KILLED</b></tr>
<tr valign=top>
<td align=left><b>OBJ_LOADED</b>   </td><td align=left> objModId(h)    </td><td align=left> objModName(s)</tr>
<tr valign=top>
<td align=left><b>OBJ_UNLOADED</b> </td><td align=left> objModId(h)    </td><td align=left> objModName(s)  </td><td align=left> objModGroup(h)</tr>
<tr valign=top>
<td align=left><b>SYM_ADDED</b>    </td><td align=left> symbol(s)      </td><td align=left> symVal(h)</tr>
<tr valign=top>
<td align=left><b>SYM_REMOVED</b>  </td><td align=left> symbol(s)      </td><td align=left> symType(s)</tr>
<tr valign=top>
<td align=left><b>TOOL_ATTACH</b>  </td><td align=left> toolName(s)</tr>
<tr valign=top>
<td align=left><b>TOOL_DETACH</b>  </td><td align=left> toolName(s)</tr>
<tr valign=top>
<td align=left><b>TOOL_MSG</b>     </td><td align=left> destination(s) </td><td align=left> sender(s)      </td><td align=left> message(s)   </td><td align=left> anything(s)</tr>
<tr valign=top>
<td align=left>USER         </td><td align=left> message(s)</tr>
<tr valign=top>
<td align=left></tr>
<tr valign=top>
<td align=left>UNKNOWN</tr>
<tr valign=top>
<td align=left></tr>
</tr>

</table>

Examples:
<p>
For a breakpoint occurring at address 0x4002344 in task 0x4030090, the event
will be the string:
<p>
<pre>    "TEXT_ACCESS 0x4030090 0x3 0x4002344 0x4008008 0x4008608"
</pre>

For a watchpoint occurring at address 0x4040000 in task 0x4030090 with pc
equals to 0x4002344, the event will be the string:
<p>
<pre>    "DATA_ACCESS 0x4030090 0x3 0x4002344 0x4008008 0x4008608 0x4040000"
</pre>

For a symbol <b>newSymbol</b> of type text added with value 0x4002344, the event
will be the string:
<p>
<pre>    "SYM_ADD newSymbol 0x4002344"
</pre>

For a divide-by-zero exception in context 0x4002344 with exception stack
frame at address 0x212900 (assuming that 0x10 is the exception vector 
associated with zero divide):
<p>
<pre>    "EXCEPTION 0x3 0x4002344 0x10 0x212900"
</pre>

For a task 0x394390 exiting with return value equals to 4 and errno equals
to 0, the event will be the string:
<p>
<pre>    "CTX_EXIT 0x3 0x394390 0x4 0"
</pre>

For a task 0x394390 created from task 0x397e10, the event will be the string:
<p>
<pre>    "CTX_START 0x3 0x394390 0x3 0x397e10"
</pre>

For a breakpoint set on the symbol <b>printf</b> in the shell, the event will be
the string:
<p>
<pre>    "EVTPT_ADDED 0x1 0x3 0 0x6 0 0 0 0x3 0x1 0x79d18"
</pre>

The event strings are exchanged via the <b>WTX_MSG_EVENT_DESC</b> structure below:
<p>
<pre>
typedef struct wtx_msg_event_desc  	/* Event message    */
    {
    WTX_CORE		wtxCore;	/* WTX message core */

    WTX_EVENT_DESC	eventDesc;	/* Event descriptor */
    } WTX_MSG_EVENT_DESC;</pre>

<p>
where <b>WTX_EVENT_DESC</b> is:
<p>
<pre>
typedef struct wtx_event_desc		/* WTX event desc.        */
    {
    char *		event;		/* Event descriptor       */
    INT32		addlDataLen;	/* Additional data length */
    char *		addlData;	/* Additional data (VIO)  */
    } WTX_EVENT_DESC;</pre>

<p>
The maximum length of an event string (<b>TOOL_EVT_SIZE</b>) is 300 characters.
<p>
<b>VIO_WRITE</b> events can carry non-ASCII data.  These data are stored in a
buffer pointed to by <b>addlData</b> and the buffer size is given by <b>addlDataLen</b>.
<p>
</blockquote><h4>WTX MESSAGES FORMAT</h4><blockquote><p>
All the WTX messages are prefixed <b>WTX_MSG_</b>.  They all contain a <b>WTX_CORE</b>
structure which carries the identifier of the tool making the request, the
protocol version, and an error code field which is used to carry OK (0)
when the call succeeds or an error status (a value other than 0) when the
call fails.  The error status corresponds to the <b>errno</b> set by the
server.  The error codes are defined in <b>wpwr/host/include/wtxerr.h</b>.
<p>
<pre>
typedef struct wtx_core			/* WTX message core */
    {
    UINT32       objId;			/* identifier */
    WTX_ERROR_T  errCode;		/* service error code */
    UINT32       protVersion;		/* WTX protocol version */
    } WTX_CORE;</pre>

<p>
The protocol version <b>protVersion</b> field should be set to 20 for the current
version of the protocol ("2.0").
<p>
</blockquote><h4>IMPORTANT</h4><blockquote><p>
When used as a  server input message, the <b>objId</b> field in <b>WTX_CORE</b>
is always set to the tool identifier value.  Unused fields in all
WTX messages should be set to NULL.
<p>
</blockquote><h4>BASIC DATA TYPES</h4><blockquote><p>
The type of a simple value sent or received, like an integer or an address,
is specified with the basic types defined by <b>WTX_VALUE_T</b>.
<p>
<pre>
typedef enum wtx_value_t	/* Simple types definitions */
    {
    V_INT8		= 0,	/* 8  bit signed integer    */
    V_INT16		= 1,	/* 16 bit signed integer    */
    V_INT32		= 2,	/* 32 bit signed integer    */
    V_UINT8		= 3,	/* 8  bit unsigned integer  */
    V_UINT16		= 4,	/* 16 bit unsigned integer  */
    V_UINT32		= 5,	/* 32 bit unsigned integer  */
    V_DOUBLE		= 6,	/* Double floating point    */
    V_BOOL32		= 7,	/* 32 bit boolean           */
    V_PCHAR		= 8,	/* Character pointer        */
    V_PVOID		= 9,	/* Void pointer             */
    V_TGT_ADDR		= 10,	/* Target address           */
    V_TGT_ARG		= 11	/* Target task argument     */