Tornado API Reference : WTX Tcl Library
wtxtcl Library Part I [Tcl] - wtxtcl Library part I
wtxContextCreate - create a new context on the target
wtxContextKill - kill a context
wtxContextSuspend - suspend a context
wtxContextStatusGet - get the status of a context
wtxContextCont - continue a context stopped at a breakpoint
wtxContextResume - resume a suspended context
wtxContextStep - single step a context by machine instruction
wtxSymFind - locate a symbol in the symbol table
wtxSymAdd - add a new symbol to the symbol table
wtxSymRemove - remove a symbol from the symbol table
wtxSymTblInfoGet - return information about the target server symbol table
wtxObjModuleList - fetch a list of IDs of object modules loaded on the target
wtxObjModuleInfoGet - return information about an object module
wtxObjModuleInfoAndPathGet - return information about an object module
wtxObjModuleFind - find an object module given a name or an ID
wtxObjModuleUnload - unload an object module
wtxMemChecksum - compute the checksum on target memory
wtxMemScan - scan target memory for the presence or absence of a pattern
wtxMemSet - set a block of memory to a specified value
wtxMemAlloc - allocate memory from the agent pool
wtxMemRealloc - reallocate a block of agent pool memory
wtxMemAlign - allocate a block of aligned memory from the agent pool
wtxMemAddToPool - add memory to the agent pool
wtxMemFree - free a block of agent pool memory
wtxMemWrite - write a memory block to the target
wtxMemWidthWrite - write a memory block to the target
wtxMemRead - read target memory into a memory block
wtxMemWidthRead - read memory from the target
wtxMemMove - move a block of memory on the target
wtxRegsGet - read a block of register data from the target
wtxRegsSet - write a block of register data to the target
wtxEventpointAdd - add an agent eventpoint
wtxEventpointList - list the eventpoints known to the agent
wtxEventpointListGet - list the eventpoints known to the agent
wtxEventpointDelete - delete an eventpoint
wtxOpen - open a file for use with virtual I/O
wtxClose - close a target server file
wtxVioCtl - change the characteristics of a virtual I/O channel
wtxVioWrite - virtual I/O write
wtxVioFileList - list the files managed by the target server
wtxConsoleCreate - create a target server console window (UNIX only)
wtxConsoleKill - kill a target server virtual I/O console (UNIX only)
wtxTsInfoGet - get information about the target server
wtxTsVersionGet - return Tornado version
wtxTsLock - lock the target server
wtxTsUnlock - unlock target server
wtxMemInfoGet - return information about the agent pool
wtxTargetAttach - attempt to reattach to the target
wtxTargetReset - reset the target
wtxAgentModeGet - get the WDB agent mode
wtxDirectCall - make a function call in the agent's context
wtxAgentModeSet - set the WDB agent mode
wtxFuncCall - call a function on the target
wtxEventGet - receive an event if any are waiting
wtxEventAdd - send an event to all other tools attached to the target server
wtxRegisterForEvent - provide a regular expression to mask event delivery
wtxGopherEval - request the evaluation of a Gopher script by the agent
wtxTsKill - kill the target server
wtxVioChanGet - claim a VIO channel
wtxVioChanRelease - release a VIO channel
wtxToolIdGet - return the tool identifier of the current tool
wtxCacheTextUpdate - synchronize the instruction and data caches.
wtxEventListGet - get all the events in one call.
wtxObjModuleChecksum - checks validity of target memory.
wtxUnregisterForEvent - ask the target server to not send events matching
wtxExecutableFind - WDB / WTX requests executable path via document name
wtxtcl APIs libary (part I)
wtxContextCreate - create a new context on the target
WTX Tcl
wtxContextCreate CONTEXT_TYPE name priority options stackBase stackSize entry redirIn redirOut
This command creates a new task context on the target. The CONTEXT_TYPE argument typically has the value CONTEXT_TASK. The newly created context has the given name, priority, and options, where name is a string, and priority and options are numbers interpreted by the agent. The parameter stackBase is ignored; the agent allocates a stack for the task. The allocated stack contains stackSize bytes. The new task context begins execution at the address entry and may have up to 10 integer arguments specified, a0...a9.
The context ID of the newly created context.
wtxtcl Library Part I, WTX_CONTEXT_CREATE, wtxtcl, wtxContextResume, wtxContextKill
wtxContextKill - kill a context
WTX Tcl
wtxContextKill [CONTEXT_TYPE] contextId
This function kills the specified context. CONTEXT_TYPE is one of the names of the CONTEXT_TYPE enumeration in the WTX protocol, which may be specified numerically or in string form; CONTEXT_TASK is the default. ContextId is a context ID, perhaps one returned by wtxContextCreate.
WTX Status.
wtxtcl Library Part I, WTX_CONTEXT_KILL, wtxtcl, wtxContextCreate
wtxContextSuspend - suspend a context
WTX Tcl
wtxContextSuspend [CONTEXT_TYPE] contextId
This command suspends the specified context. CONTEXT_TYPE is one of the names of the CONTEXT_TYPE enumeration in the WTX protocol, which may be specified numerically or in string form; if absent, CONTEXT_TASK is assumed. ContextId is a context ID, perhaps one returned by wtxContextCreate.
WTX Status.
wtxtcl Library Part I, WTX_CONTEXT_SUSPEND, wtxtcl, wtxContextCreate, wtxContextResume
wtxContextStatusGet - get the status of a context
WTX Tcl
wtxContextStatusGet [CONTEXT_TYPE] contextId
This command returns the status of the specified context as a string. CONTEXT_TYPE is one of the names of the CONTEXT_TYPE enumeration in the WTX protocol, which may be specified numerically or in string form; if it is omitted, CONTEXT_TASK is assumed. ContextId is a context ID, perhaps one returned by wtxContextCreate. You can use wtxEnumInfo with an argument of CONTEXT_STATUS to see the list of possible context status.
tcl> wtxContextStatusGet CONTEXT_SYSTEM 0 CONTEXT_RUNNING tcl> wtxEnumInfo CONTEXT_STATUS CONTEXT_RUNNING 0x0 CONTEXT_SUSPENDED 0x1
This request is implemented only for system mode context.
The context status.
wtxtcl Library Part I, WTX_CONTEXT_STATUS_GET, wtxtcl, wtxContextCreate, wtxContextResume, wtxContextSuspend
wtxContextCont - continue a context stopped at a breakpoint
WTX Tcl
wtxContextCont [CONTEXT_TYPE] contextId
This function continues the specified context. CONTEXT_TYPE is one of the names of the CONTEXT_TYPE enumeration in the WTX protocol, which may be specified numerically or in string form; if it is omitted, CONTEXT_TASK is assumed. ContextId is a context ID, perhaps one returned by wtxContextCreate.
WTX Status.
wtxtcl Library Part I, WTX_CONTEXT_CONT, wtxtcl, wtxEventpointAdd, wtxContextCreate, wtxContextStep
wtxContextResume - resume a suspended context
WTX Tcl
wtxContextResume [CONTEXT_TYPE] contextId
This command resumes the specified context. It restarts a task that has been suspended (perhaps by wtxContextSuspend). Do not use wtxContextResume to continue a task stopped at a breakpoint; the task simply hits the breakpoint again. Use wtxContextCont.
CONTEXT_TYPE is one of the names of the CONTEXT_TYPE enumeration in the WTX protocol, which may be specified numerically or in string form; if it is omitted, CONTEXT_TASK is assumed. ContextId is a context ID, perhaps one returned by wtxContextCreate.
WTX Status.
wtxtcl Library Part I, WTX_CONTEXT_RESUME, wtxtcl, wtxContextSuspend, wtxContextCreate
wtxContextStep - single step a context by machine instruction
WTX Tcl
wtxContextStep [CONTEXT_TYPE] contextId [startAddr endAddr]
This function runs the specified context in instruction-trace mode. If startAddr and endAddr are given, the context continues to single step instruction by instruction until the step range is exited (either by executing the last instruction in the range or by jumping out the range via a branch or call instruction). CONTEXT_TYPE is one of the names of the CONTEXT_TYPE enumeration in the WTX protocol, which may be specified numerically or in string form; if it is omitted, CONTEXT_TASK is assumed. ContextId is a context ID, perhaps one returned by wtxContextCreate.
WTX Status.
wtxtcl Library Part I, WTX_CONTEXT_STEP, wtxtcl, wtxEventpointAdd, wtxContextCont, wtxContextCreate
wtxSymFind - locate a symbol in the symbol table
WTX Tcl
wtxSymFind [-exact] [-name name | -value value] [-type type]
This function queries the target server symbol table looking for one symbol that exactly matches the specified name or value. If -type is specified, any returned symbol will have the supplied type. If -exact is specified, the name must match exactly. If not, wtxSymFind will consider a symbol to match if it differs from the supplied name only by having one leading underscore (that is, "_foo" could be returned for "foo", if -exact is not set). If a value is specified, the nearest symbol whose value is not greater than the given value is returned.
If a symbol matching the search criteria is found, the following structure is returned:
name address type {symTblId group module}where name is the name of the found symbol, address its address, and type one of the VxWorks symbol type codes. symTblId is currently for internal use.
SYMTBL_SYMBOL_NOT_FOUND if no symbol is found.
-exact should apply to value searches. symTblId, group, and module have NULL values for all searches.
wtxtcl Library Part I, WTX_SYM_FIND, wtxtcl, wtxSymAdd, wtxSymRemove, wtxSymListGet, wtxSymTblInfoGet
wtxSymAdd - add a new symbol to the symbol table
WTX Tcl
wtxSymAdd name value type
This function adds a new symbol to the target server symbol table, with the given name, value, and type. Name is a string, value is an integer, and type is a small integer representing one of the VxWorks symbol type codes.
NONE.
wtxtcl Library Part I, WTX_SYM_ADD, wtxtcl, wtxSymFind, wtxSymRemove, wtxSymListGet, wtxSymTblInfoGet
wtxSymRemove - remove a symbol from the symbol table
WTX Tcl
wtxSymRemove name type
This command removes the symbol with the given name and type from the target server symbol table.
SYMTBL_SYMBOL_NOT_FOUND if the symbol cannot be located.
wtxtcl Library Part I, WTX_SYM_REMOVE, wtxtcl, wtxSymFind, wtxSymAdd, wtxSymListGet, wtxSymTblInfoGet
wtxSymTblInfoGet - return information about the target server symbol table
WTX Tcl
wtxSymTblInfoGet
This function returns a list of information about the target server symbol table.
The returned list contains three elements: the first is the symbol table ID, the second is the number of symbols contained there, and the third is a boolean indicating whether the symbol table permits more than one entry to have the same name.
tcl> wtxSymTblInfoGet 0xa3558 2204 1
None.
wtxtcl Library Part I, WTX_SYM_TBL_INFO_GET, wtxtcl, wtxSymFind, wtxSymAdd, wtxSymRemove, wtxSymListGet
wtxObjModuleList - fetch a list of IDs of object modules loaded on the target
WTX Tcl
wtxObjModuleList
This function fetches the list of IDs of object modules loaded on the target.
A list of object module IDs.
tcl> wtxObjModuleList 0x98860 0x4a5c48
wtxtcl Library Part I, WTX_OBJ_MODULE_LIST, wtxtcl, wtxObjModuleInfoGet, wtxObjModuleFind, wtxObjModuleLoad, wtxObjModuleUnload
wtxObjModuleInfoGet - return information about an object module
WTX Tcl
wtxObjModuleInfoGet objModuleId
This routine returns a list of information about the module specified by objModuleId.
A list with five initial elements: the ID, name, format code, group, and load flags of the module. This is followed by a three-element list for each section in the module: the section flags, the address, and the length of the section.
Section entries are unnamed.
This script prints a table of all loaded object module IDs and their names.
tcl> foreach mod [wtxObjModuleList] { tcl> puts stdout [lrange [wtxObjModuleInfoGet $mod] 0 1] tcl> } 0x98860 vxWorks 0x4a5c48 tc68k.o
wtxtcl Library Part I, WTX_OBJ_MODULE_INFO_GET, wtxtcl, wtxObjModuleList, wtxObjModuleFind, wtxObjModuleLoad, wtxObjModuleUnload
wtxObjModuleInfoAndPathGet - return information about an object module
WTX Tcl
wtxObjModuleInfoAndPathGet objModuleId
This routine returns a list of information about the module specified by objModuleId.
A list with five initial elements: the ID, path and name, format code, group, and load flags of the module. This is followed by a three-element list for each section in the module: the section flags, the address, and the length of the section.
Section entries are unnamed.
This script prints a table of all loaded object module IDs and their names.
tcl> foreach mod [wtxObjModuleList] { tcl> puts stdout [lrange [wtxObjModuleInfoAndPathGet $mod] 0 1] tcl> } 0xcea38 /view/wrs.tor2_0.tempest-a/vobs/wpwr/target/config/mv1604vxWorks 0xe6f20 /view/pas.t2.ref/vobs/wpwr/target/lib/objPPC604gnutest/bcopyTest.o
wtxtcl Library Part I, WTX_OBJ_MODULE_INFO_GET, wtxtcl, wtxObjModuleInfoGet, wtxObjModuleList, wtxObjModuleFind, wtxObjModuleLoad, wtxObjModuleUnload
wtxObjModuleFind - find an object module given a name or an ID
WTX Tcl
wtxObjModuleFind nameOrId
This function finds the name or ID of an object module given the other piece of information.
A list of two elements: the module ID and the module name for the module matching the nameOrId argument if one is found. This function is useful for converting between module names and IDs.
tcl> wtxObjModuleFind tc68k.o 0x4a5c48 tc68k.o
wtxtcl Library Part I, WTX_OBJ_MODULE_FIND, wtxtcl, wtxObjModuleList, wtxObjModuleInfoGet, wtxObjModuleLoad, wtxObjModuleUnload
wtxObjModuleUnload - unload an object module
WTX Tcl
wtxObjModuleUnload nameOrId
This command removes the given object module from the target, reclaiming agent pool memory.
Unload a module given its ID and another one given its name:
tcl> wtxObjModuleUnload 0xfb3008 0 tcl> wtxObjModuleUnload big.o 0
WTX Status.
NONE.
wtxtcl Library Part I, WTX_OBJ_MODULE_UNLOAD_2, wtxtcl, wtxObjModuleList, wtxObjModuleInfoGet, wtxObjModuleLoad, wtxObjModuleFind
wtxMemChecksum - compute the checksum on target memory
WTX Tcl
wtxMemChecksum startAddr nBytes
This function computes and returns the checksum of the block of memory that starts at startAddr and extends nBytes.
The block checksum in hexadecimal.
wtxtcl Library Part I, WTX_MEM_CHECKSUM, wtxtcl, wtxMemWrite, wtxMemRead
wtxMemScan - scan target memory for the presence or absence of a pattern
WTX Tcl
wtxMemScan [-notmatch] startAddr endAddr {-string string | -memblk mblk}
This routine scans the target memory from startAddr to endAddr. When -notmatch is specified, it returns the first address not matching the pattern. Otherwise it returns the first address matching the pattern. The pattern can be specified to be either a string or a block of memory.
The first address matching string or mblk unless -notmatch is specified. When -notmatch is specified, it returns the first address not matching string or mblk.
wtxtcl Library Part I, WTX_MEM_SCAN, wtxtcl, wtxMemWrite, wtxMemRead, wtxMemChecksum
wtxMemSet - set a block of memory to a specified value
WTX Tcl
wtxMemSet startAddr nBytes value
This function fills a block of memory beginning at startAddr and extending nBytes with a 4-byte value.
WTX Status.
wtxtcl Library Part I, WTX_MEM_SET, wtxtcl, wtxMemWrite, wtxMemRead, wtxMemChecksum
wtxMemAlloc - allocate memory from the agent pool
WTX Tcl
wtxMemAlloc nBytes
A memory block of nBytes is allocated from the target pool. To allocate memory from the target run-time, you call its memory manager with wtxFuncCall. Memory obtained from wtxMemAlloc can be freed with wtxMemFree.
The address of the newly allocated block.
wtxtcl Library Part I, WTX_MEM_ALLOC, wtxtcl, wtxMemFree, wtxMemAlign, wtxMemAddToPool
wtxMemRealloc - reallocate a block of agent pool memory
WTX Tcl
wtxMemRealloc address size
This command resizes a block of memory obtained from the wtxMemAlloc service to the new size. Address is the value returned by wtxMemAlloc.
The address of the new block of memory, which may have moved.
wtxtcl Library Part I, WTX_MEM_REALLOC, wtxtcl, wtxMemAlloc, wtxMemFree
wtxMemAlign - allocate a block of aligned memory from the agent pool
WTX Tcl
wtxMemAlign alignment size
A block of memory is obtained which is aligned on an alignment-byte boundary. This function is similar to wtxMemAlloc with the addition of alignment.
The address of the allocated block.
wtxMemFree, wtxMemAlloc
wtxtcl Library Part I, WTX_MEM_ALIGN, wtxtcl
wtxMemAddToPool - add memory to the agent pool
WTX Tcl
wtxMemAddToPool address size
This function adds the block of memory starting at address and spanning size bytes to the agent pool, enlarging it. It is possible to enlarge the agent's pool with memory obtained from the run-time memory manager or with any currently unclaimed memory.
wtxtcl Library Part I, WTX_MEM_ADD_TO_POOL, wtxtcl, wtxMemAlloc, wtxMemFree
wtxMemFree - free a block of agent pool memory
WTX Tcl
wtxMemFree address
This command frees a block of memory obtained by a call to wtxMemAlloc, wtxMemRealloc or wtxMemAlign, returning it to the agent pool.
wtxtcl Library Part I, WTX_MEM_FREE, wtxtcl, wtxMemAlloc, wtxMemAlign
wtxMemWrite - write a memory block to the target
WTX Tcl
wtxMemWrite blockId address [offset] [nBytes]
This command writes the memory block named by blockId to the target memory starting at address. If offset is given, writing starts at that offset in the memory block. If nBytes is absent, the entire memory block (starting at offset if supplied) is written; otherwise nBytes of data are written to target memory.
WTX Status.
wtxtcl Library Part I, WTX_MEM_WRITE, wtxtcl, wtxMemRead, memBlockCreate
wtxMemWidthWrite - write a memory block to the target
WTX Tcl
wtxMemWidthWrite blockId address [width] [offset] [nBytes]
This command writes the memory block named by blockId to the target memory starting at address. If offset is given, writing starts at that offset in the memory block. If nBytes is absent, the entire memory block (starting at offset if supplied) is written; otherwise nBytes of data are written to target memory. If width is given, it must be set to 1 (byte), 2 (word) or 4 (long word), by default, width is set to 4.
Because this request is not implemented on WDB side, wtxMemWidthWrite uses WDB_MEM_WRITE and the width parameter is simply ignored.
WTX Status.
wtxtcl Library Part I, WTX_MEM_WIDTH_WRITE, wtxtcl, wtxMemWidthRead, memBlockCreate
wtxMemRead - read target memory into a memory block
WTX Tcl
wtxMemRead address nBytes
The block of target memory starting at address and spanning nBytes is read into a memory block. The handle of the memory block is returned.
A memory block handle.
wtxtcl Library Part I, WTX_MEM_READ, wtxtcl, wtxMemWrite, memBlockCreate, memBlockGet
wtxMemWidthRead - read memory from the target
WTX Tcl
wtxMemWidthRead address nBytes [width]
The block of target memory starting at address and spanning nBytes is read on width bytes large into a memory block. The handle of the memory block is returned. width can be set to 1 (byte), 2 (word) or 4 (long word), by default width is set to 4.
Because this request is not implemented on WDB side, wtxMemWidthRead uses WDB_MEM_READ and the width parameter is simply ignored.
A memory block handle.
wtxtcl Library Part I, WTX_MEM_WIDTH_READ, wtxtcl, wtxMemWidthWrite, memBlockCreate, memBlockGet
wtxMemMove - move a block of memory on the target
WTX Tcl
wtxMemMove source destination nBytes
The block of memory starting at source and spanning nBytes is moved to destination. Note that the source and destination buffers may overlap.
WTX Status.
wtxtcl Library Part I, WTX_MEM_MOVE, wtxtcl, wtxMemRead, wtxMemWrite
wtxRegsGet - read a block of register data from the target
WTX Tcl
wtxRegsGet CONTEXT_TYPE contextId REG_SET_TYPE offset nBytes
This command reads a section of raw (target format) register data for the given context. CONTEXT_TYPE is one of the values given in the entry for WTX in the API Reference Manual: WTX Protocol . (Use wtxEnumInfo with an argument of CONTEXT_TYPE for information on possible types). Typically the type is CONTEXT_TASK. ContextId is the ID of the task whose register block is to be read. REG_SET_TYPE is the type of register block to read (usually REG_SET_IU or REG_SET_FPU; use wtxEnumInfo with an argument of REG_SET_TYPE for information on other possible types). Offset and nBytes delimit the section of the register block to read. The layout of the register blocks is dependent on the target kernel; for VxWorks, these are the same as the REG_SET layout in the task control block.
A memory-block handle with the uploaded register data. See memBlockCreate for information about memory block handles.
wtxtcl Library Part I, WTX_REGS_GET, wtxtcl, wtxRegsSet, memBlockCreate
wtxRegsSet - write a block of register data to the target
WTX Tcl
wtxRegsSet CONTEXT_TYPE contextId REG_SET_TYPE offset nBytes blockId
This command writes a section of raw (target format) register data for the given context. CONTEXT_TYPE is one of the values given in the entry for WTX in the API Reference Manual: WTX Protocol . (Use wtxEnumInfo with an argument of CONTEXT_TYPE for information on possible types). Typically the type is CONTEXT_TASK. ContextId is the ID of the task whose register block is to be written. REG_SET_TYPE is the type of register block to write (usually REG_SET_IU or REG_SET_FPU; use wtxEnumInfo with an argument of REG_SET_TYPE for information on other possible types). Offset and nBytes delimit the section of the register block to write. The layout of the register blocks is dependent on the target kernel; for VxWorks, these are the same as the REG_SET layout in the task control block. The register block receives data from the memory block blockId.
- block not found
- The block ID does not exist.
- block too small to write that many registers
- The block is too small for the requested data.
wtxtcl Library Part I, * WTX_REGS_SET, wtxtcl, wtxRegsSet, memBlockCreate
wtxEventpointAdd - add an agent eventpoint
WTX Tcl
wtxEventpointAdd EVENT_TYPE eventArg0 [...eventArgN] CONTEXT_TYPE contextId ACTION_TYPE actionArg callRtn callArg
This function adds an agent eventpoint. DETECTION_TYPE, EVENT_TYPE, CONTEXT_TYPE, and ACTION_TYPE are all WTX constants described in the WTX Protocol reference. Use wtxEnumInfo with one of the constants to find out what values you can supply in Tcl. For example:
wtxtcl.ex>wtxEnumInfo CONTEXT_TYPE CONTEXT_SYSTEM 0x1 CONTEXT_GROUP 0x2 CONTEXT_ANY 0x3 CONTEXT_TASK 0x4 CONTEXT_ANY_TASK 0x5 CONTEXT_ISR 0x6 CONTEXT_ISR_ANY 0x7For a complete discussion of events and using wtxtcl to work with them, see the API Programmer's Guide: The WTX Protocol .When CONTEXT_TYPE is set to WTX_CONTEXT_SYSTEM, then only eventpoints in system mode can be added. When CONTEXT_TYPE is set to WTX_CONTEXT_TASK, then only eventpoints in context task can be added.
The eventpoint number, which can be used as a key to wtxEventpointDelete.
wtxtcl Library Part I, WTX_EVENTPOINT_ADD_2, wtxtcl, wtxEventpointDelete, wtxEventpointList, WTX entry in the API Reference Manual: WTX Protocol , API Programmer's Guide: The WTX Protocol
wtxEventpointList - list the eventpoints known to the agent
WTX Tcl
wtxEventpointList
This command returns a list of all eventpoints installed in the agent.
Each item in the returned list has four elements, one for each of the arguments to the wtxEventpointAdd command: DETECTION_TYPE, EVENT_TYPE, CONTEXT_TYPE, and ACTION_TYPE. Each of these lists in turn has two elements, the WTX type and the additional argument.
The returned events are not keyed to eventpoint number.
wtxtcl Library Part I, WTX_EVENTPOINT_LIST, wtxtcl, wtxEventpointAdd, wtxEventpointDelete
wtxEventpointListGet - list the eventpoints known to the agent
WTX Tcl
wtxEventpointListGet
This command returns an eventpoints info list installed in the agent.
Each item in the returned list has five elements: three elements, one for each of the arguments to the wtxEventpointAdd command: EVENT_TYPE, CONTEXT_TYPE, and ACTION_TYPE; and two more elements for the tool identifier and the eventpoint identifier.
CONTEXT_TYPE and ACTION_TYPE lists in has two elements, the WTX type and the additional argument. EVENT_TYPE lists in may have more than two elements, the WTX type and the additional arguments.
wtxtcl Library Part I, WTX_EVENTPOINT_LIST_GET, wtxtcl, wtxEventpointAdd, wtxEventpointDelete
wtxEventpointDelete - delete an eventpoint
WTX Tcl
wtxEventpointDelete epNum
This function removes the eventpoint numbered epNum from the agent.
wtxtcl Library Part I, WTX_EVENTPOINT_DELETE, wtxtcl, wtxEventpointAdd, wtxEventpointList
wtxOpen - open a file for use with virtual I/O
WTX Tcl
wtxOpen [-channel chan] filename flags mode
This command causes the target server to open a file with the given filename, flags, and mode. The flags parameter can be WTX_O_RDONLY or WTX_O_WRONLY or'ed with WTX_O_CREAT. flags can also be an integer as defined in sys/fcntl.h but this is only for backward compatibility and should not be used.
If -channel is specified, virtual I/O on the given channel is redirected to the file.
On UNIX, to create and open the file /tmp/myFile in read-only mode with permissions set to "-r--------" use:
wtxOpen /tmp/myFile WTX_O_CREAT|WTX_O_RDONLY 0400
An integer file descriptor, which can be used with other VIO commands.
The flags and mode parameters are host-dependent.
wtxtcl Library Part I, WTX_OPEN, wtxtcl, wtxClose, wtxVioCtl
wtxClose - close a target server file
WTX Tcl
wtxClose fd
The file descriptor fd, which was obtained by a call to wtxOpen, is closed.
wtxtcl Library Part I, WTX_CLOSE, wtxtcl, wtxOpen, wtxVioCtl
wtxVioCtl - change the characteristics of a virtual I/O channel
WTX Tcl
wtxVioCtl channel VIO_CTL_REQUEST arg
This function issues a virtual I/O control request for the given channel. The only VIO control request supported is WTX_CTL_VIO_REDIRECT, which redirects output to the given file descriptor arg.
wtxtcl Library Part I, WTX_VIO_CTL, wtxtcl, wtxOpen, wtxVioWrite
wtxVioWrite - virtual I/O write
WTX Tcl
wtxVioWrite channel [-string string | -memblk blockId]
This command writes data to a virtual I/O channel. The data can come from a supplied string or a memory block can be written to the VIO channel.
WTX Status.
wtxtcl Library Part I, WTX_VIO_WRITE, wtxtcl, wtxOpen
wtxVioFileList - list the files managed by the target server
WTX Tcl
wtxVioFileList
A list of 7 elements is returned for each file managed by the target server. The elements are:
filename file descriptor (as obtained by wtxOpen) VIO channel (-1 indicates that there is no redirection) file pointer (for internal use) file type (0 for files/sockets; 1 for pipes) mode (as supplied to wtxOpen) status (1 = open, 0 = closed) process id (for VIO consoles)
wtxtcl Library Part I, WTX_VIO_FILE_LIST, wtxtcl, wtxOpen
wtxConsoleCreate - create a target server console window (UNIX only)
WTX Tcl
wtxConsoleCreate name [display]
This command creates an xterm console with the given name on the default X display (as known to the target server) or the given display if that is supplied. The name passed appears in the window manager title bar. The number of buffered lines (default 88) can be changed by setting the environment variable WTX_CONSOLE_LINES to the number of desired buffered lines. Set this variable before launching the target server.
This request is not implemented on Windows. Windows allows only one virtual console and it must be started on the target server command line with the -c option.
For UNIX hosts, a Tcl list of the form:
{consoleName consoleDisplay consolePid fdIn fdOut}
wtxtcl Library Part I, WTX_CONSOLE_CREATE, wtxtcl, wtxOpen, wtxVioCtl
wtxConsoleKill - kill a target server virtual I/O console (UNIX only)
WTX Tcl
wtxConsoleKill pid
This function kills the xterm VIO console whose process ID is pid.
This request is not implemented on Windows. If issued, it returns an error, but does not attempt to kill an existing console.
wtxtcl Library Part I, WTX_CONSOLE_KILL, wtxtcl, wtxConsoleCreate
wtxTsInfoGet - get information about the target server
WTX Tcl
wtxTsInfoGet
This function returns a structure containing information about the target server.
A nested list of data. The structure of the list is given below. For a description of the fields and their values, see WTX_TS_INFO_GET.
0 tgtLinkDesc.name 1 1.0 tgtLinkDesc.type 1.2 tgtLinkDesc.speed 2 2.0 tgtInfo.rtInfo.cpuType 2.1 tgtInfo.rtInfo.hasFpp 2.2 tgtInfo.rtInfo.hasWriteProtect 2.3 tgtInfo.rtInfo.pageSize 2.4 tgtInfo.rtInfo.endian 3 3.0 tgtInfo.rtInfo.rtType 3.1 tgtInfo.rtInfo.rtVersion 4 tgtInfo.rtInfo.bspName 5 tgtInfo.rtInfo.bootline 6 6.0 tgtInfo.rtInfo.memBase 6.1 tgtInfo.rtInfo.memSize 7 7.0 tgtInfo.rtInfo.hostPoolBase 7.1 tgtInfo.rtInfo.hostPoolSize 8 userName 9 startTime 10 accessTime 11 lockMsg 12 pReserved 13 Target Server version 14 Agent version 15 15.0 pTool->toolId 15.1 pTool->toolName 15.2 pTool->toolArgv 15.3 pTool->toolVersion 15.4 pTool->userName
wtxtcl Library Part I, WTX_TS_INFO_GET, wtxtcl, wtxToolAttach
wtxTsVersionGet - return Tornado version
WTX Tcl
wtxTsVersionGet
This function gets a string representing the Tornado version.
wtxtcl Library Part I, wtxtcl, wtxTsInfoGet
wtxTsLock - lock the target server
WTX Tcl
wtxTsLock [seconds]
The target server is locked to the invoking user's user ID. Other users attempting to communicate with the target server will be rejected. If seconds is used, then the target server will be locked only for seconds seconds, otherwise, it will be locked indefinitely.
wtxtcl Library Part I, WTX_TS_LOCK, wtxtcl, wtxTsUnlock
wtxTsUnlock - unlock target server
WTX Tcl
wtxTsUnlock
The target server is unlocked. After this, other users may attach tools to the target server.
wtxtcl Library Part I, WTX_TS_UNLOCK, wtxtcl, wtxTsLock
wtxMemInfoGet - return information about the agent pool
WTX Tcl
wtxMemInfoGet
This routine returns a vector of information about the agent pool.
A list of 11 integers:
current bytes free current bytes allocated cumulative bytes allocated current blocks free current blocks allocated cumulative blocks allocated average free block size average allocated block size cumulative average allocated block size biggest block size (reserved)
wtxtcl Library Part I, WTX_MEM_INFO_GET, wtxtcl, wtxMemAlloc, wtxMemAddToPool
wtxTargetAttach - attempt to reattach to the target
WTX Tcl
wtxTargetAttach
This routine attempts to reattach to a target that has been disconnected or to which the target server is waiting to connect.
WTX Status.
wtxtcl Library Part I, WTX_TARGET_ATTACH, wtxtcl
wtxTargetReset - reset the target
WTX Tcl
wtxTargetReset
The target is reset as if it had been manually rebooted.
This command does not perform a wtxToolDetach nor does it attempt to reestablish communication when the agent comes back up.
wtxtcl Library Part I, WTX_TARGET_RESET, wtxtcl
wtxAgentModeGet - get the WDB agent mode
WTX Tcl
wtxAgentModeGet
The current agent mode is returned as a string. You can use wtxEnumInfo with an argument of AGENT_MODE to see the list of possible values.
tcl> wtxtcl.ex>wtxAgentModeGet AGENT_MODE_TASK tcl> wtxEnumInfo AGENT_MODE AGENT_MODE_TASK 0x1 AGENT_MODE_EXTERN 0x2
wtxtcl Library Part I, WTX_AGENT_MODE_GET, wtxtcl, wtxAgentModeSet
wtxDirectCall - make a function call in the agent's context
WTX Tcl
wtxDirectCall entry [arg0...arg9]
The WDB agent makes a direct function call to the address specified by entry. Up to ten integer arguments may be given, and the integer return value of the function is returned. No task context is created to contain the function call. For that reason, this function should only be used in special circumstances, as it can interfere with the agent's operation.
wtxtcl Library Part I, WTX_DIRECT_CALL, wtxtcl, wtxFuncCall
wtxAgentModeSet - set the WDB agent mode
WTX Tcl
wtxAgentModeSet AGENT_MODE
The WDB agent is placed into the specified AGENT_MODE. To see the values this parameter can take, you can use wtxEnumInfo with an argument of AGENT_MODE.
wtxtcl Library Part I, WTX_AGENT_MODE_SET, wtxtcl, wtxAgentModeGet
wtxFuncCall - call a function on the target
WTX Tcl
wtxFuncCall [-int | -float | -double] [-pri n] [-opt opt] [-rIn fdIn] [-rOut fdOut] addr [a0...a9]
This routine calls the function at addr with up to 10 integer arguments a0...a9. The return type is specified with the -int, -float, or -double flag. The function is called in the context of a task spawned for that purpose. The arguments -pri and -opt can be used to control the priority and option words of that task. The arguments -rIn and -rOut can be used to specify file descriptors for input and output redirection. The called function will use this new assignement when doing I/O, instead of the system-wide global assignement which is used by default.
The ID of the function call. When the called function terminates, a CALL_RETURN event is generated which references this ID and contains the return value.
wtxtcl Library Part I, WTX_FUNC_CALL, wtxtcl, wtxEventGet, wtxContextCreate
wtxEventGet - receive an event if any are waiting
WTX Tcl
wtxEventGet
If there is at least one event in the tool's target server event queue, the first event is dequeued and returned by this command. For a description of the various events, see the entry for WTX in the API Reference Manual: WTX Protocol .
An event in string form. The first element of the list is the event name, followed by the integer parameters of the event. If the event has an attached data block, this is returned as a memory block handle in the last position of the list. If there are no events, an empty string is returned.
For Tcl, events are returned in Tcl list format. The first element of the list is the type of event, and several integer arguments may follow. If an event has an associated data buffer (see WTX), this is returned in the form of a memory block handle (see memBlockCreate).
This is a table of some target server event formats:
TEXT_ACCESS contextId contextType pc fp sp EXCEPTION contextType contextId excVector pESF VIO_WRITE channel mblk CALL_RETURN callId value errnoConsult the WTX reference entry for more information about events and the interpretation of their parameters.
wtxtcl Library Part I, WTX_EVENT_GET, wtxtcl, wtxRegisterForEvent, WTX entry in the API Reference Manual: WTX Protocol
wtxEventAdd - send an event to all other tools attached to the target server
WTX Tcl
wtxEventAdd event
The string event is sent to all tools (except the originating tool).
WTX Status.
wtxtcl Library Part I, WTX_EVENT_ADD, wtxtcl, wtxEventGet, wtxRegisterForEvent
wtxRegisterForEvent - provide a regular expression to mask event delivery
WTX Tcl
wtxRegisterForEvent regex
This request supplies a regular expression to the target server that is used to determine which events should be reported to the tool. (Initially, tools receive no events.) If another regular expression is supplied after this function is called, it supersedes the previous regular expression.
For a complete discussion of events, see the API Programmer's Guide: The WTX Protocol or the reference manual entry for WTX_REGISTER_FOR_EVENT.
To arrange to receive all events, execute:
wtxRegisterForEvent .*
wtxtcl Library Part I, WTX_REGISTER_FOR_EVENT, wtxtcl, wtxEventGet
wtxGopherEval - request the evaluation of a Gopher script by the agent
WTX Tcl
wtxGopherEval script
This request executes the Gopher script on the target and returns the vector of values generated by the script. For a detailed discussion of Gopher, see the WTX entry in the API Reference Manual: WTX Protocol , or the API Programmer's Guide: The WTX Protocol .
Gopher is a small, interpreted language that allows the traversal of simple data structures in target memory. The Gopher execution environment is an abstract machine that consists of two objects: the "pointer" and the "tape". The pointer is an address in the target's address space, and the tape is a one-way write-only area where Gopher results are accumulated. When the Gopher script terminates, the contents of the tape are returned to the tool.
A Tcl list consisting of a group of strings for each data structure member evaluated by the Gopher expression. Tcl automatically interprets the Gopher type codes and creates the list.
This example uses the Gopher script developed in the WTX_GOPHER_EVAL example with appropriate Tcl structures added. The data structures to be evaluated are as follows:
typedef struct _node { UINT32 number; /* number of node */ struct _node * pNext; /* single linked list */ struct _other * pOther; /* pointer to an OTHER */ char * name; /* name of node */ UINT32 value; /* value of node */ } NODE; typedef struct _other { UINT32 x1; /* X Factor One */ UINT32 x2; /* X Factor Two */ } OTHER;Suppose we want a list of the numbers and names of each node in a list, and that the symbol nodeList contains a pointer to the first node. We would start by querying the symbol table for the value of nodeList:
set nodeList [lindex [wtxSymFind -name nodeList] 1]The final Gopher string traverses the _node structure and then obtains the x1 and x2 values from pOther.
wtxGopherEval "$nodeList * { @ < +8 *$ > < +4 * {@@ 0} > * }"The result of this example will consist of a list whose length depends on the number of elements of the struct _node:{name1 value1 x11 x21 name2 value2 ... x1n x2n}
Gopher cannot use symbolic information, so you must compute structure offsets and store only numbers to the Gopher string. (In this example, the strings we have given are executed in the context of wtxGopherEval, so that Tcl variables such as $nodeList are expanded before Gopher interpretation).
The size of the Gopher tape that can be returned is limited to the size of the agent's communication buffer.
wtxtcl Library Part I, WTX_GOPHER_EVAL, wtxtcl
wtxTsKill - kill the target server
WTX Tcl
wtxTsKill OBJ_KILL_REQUEST arg
This command kills the target server the tool is connected to. OBJ_KILL_REQUEST can be either WTX_OBJ_KILL_DESTROY, which simply destroys the target server, or WTX_OBJ_KILL_RESTART, which destroys it and attempts to restart it. Arg is an optional numeric argument; see WTX_OBJ_KILL in the API Reference Manual: WTX Protocol for more details.
wtxtcl Library Part I, WTX_OBJ_KILL, wtxtcl
wtxVioChanGet - claim a VIO channel
WTX Tcl
wtxVioChanGet
This function selects a VIO channel number that is not currently being used by any other tool. The number returned is in the range 1..255 (channel 0 is reserved for system use). It is the responsibility of the tool to open the channel on the target; this function merely allows different tools to coordinate their selection of channel numbers.
When the channel is no longer needed, wtxVioChanRelease should be called.
A VIO channel number. If none are available, the error SVR_NO_VIO_CHANNEL is returned.
wtxtcl Library Part I, WTX_VIO_CHAN_GET, wtxtcl, wtxVioChanRelease
wtxVioChanRelease - release a VIO channel
WTX Tcl
wtxVioChanRelease channel
This function releases a channel obtained by wtxVioChanGet, making it available for other tools.
wtxtcl Library Part I, WTX_VIO_CHAN_RELEASE, wtxtcl, wtxVioChanGet
wtxToolIdGet - return the tool identifier of the current tool
WTX Tcl
wtxToolIdGet
This function returns the tool identifier of the current tool.
The tool identifier of the current tool.
wtxtcl Library Part I, wtxtcl, wtxToolName
wtxCacheTextUpdate - synchronize the instruction and data caches.
WTX Tcl
wtxCacheTextUpdate address nBytes
This function flushes the data chache, then invalidates the instruction cache. This operation forces the instruction cache to fetch code that may have been created via the data path.
WTX Status.
wtxtcl Library Part I, WTX_CACHE_TEXT_UPDATE, wtxtcl
wtxEventListGet - get all the events in one call.
WTX Tcl
wtxEventListGet [nEvents]
This function returns the tool's target server event queue in one call. If more than one event is found, a list is built and returned to the caller. If nEvents is the maximum number of events returned by this request.
Get all events from the target server
tcl> wtxEventListGet {{TOOL_ATTACH windsh 0x4dbe30} {CALL_RETURN 0x382a78 0x6 0} {CALL_RETURN 0x382a78 0x7 0}}Get only 1 event from the target servertcl> wtxEventListGet 1 {TOOL_ATTACH windsh 0x4d8c80}
An element of the returned event list is made of an event string. The first element of the list is the event name, followed by the integer parameters of the event. If the event has an attached data block, this is returned as a memory block handle in the last position of the list. If there are no events, an empty list is returned.
wtxtcl Library Part I, WTX_EVENT_LIST_GET, wtxtcl, wtxEventGet, wtxEventAdd, wtxRegisterForEvent, wtxUnregisterForEvent
wtxObjModuleChecksum - checks validity of target memory.
WTX Tcl
wtxObjModuleChecksum nameOrId
This routine compares object module checksum on target with object module checksum on target server. This is a way to control the target memory integrity. If nameOrId is set to "WTX_ALL_MODULE_CHECK" otherwise only the selected module is checked.
Because Elf modules may have more than one section of text, text sections are gathered in a text segment. But, if on the target memory (or in the module) sections are contiguous, they may not be contiguous in the host memory cache (due to different malloc calls for each sections). Then, checksums cannot be compared for the text segment but only for the first text section.
Check 1 module
tcl> wtxObjModuleChecksum signalTest.o 0Check all the modules tcl> wtxObjModuleChecksum WTX_ALL_MODULE_CHECK
\ce
WTX Status.
wtxtcl Library Part I, WTX_OBJ_MODULE_CHECKSUM, wtxtcl, wtxObjModuleList, wtxMemChecksum
wtxUnregisterForEvent - ask the target server to not send events matching
a regexp
WTX Tcl
wtxUnregisterForEvent regex
This routine registers which events are unwanted. Usually, if we want to filter events notification we have to give the regular expression to wtxRegisterForEvent. A more simple way to do this is to be registered for all the events and to be registered for only those which are unwanted.
Register for all events and get the events when a windsh attached
tcl> wtxRegisterForEvent .* 0 tcl> wtxEventListGet {{TOOL_ATTACH windsh 0x89e38} {CALL_RETURN 0x382a78 0x8 0} {CALL_RETURN 0x382a78 0x9 0}}Register for all events except TOOL_ATTACH and get the events when a windsh attachedtcl> wtxRegisterForEvent .* 0 tcl> wtxUnregisterForEvent TOOL_ATTACH 0 tcl> wtxEventListGet {{CALL_RETURN 0x382a78 0xa 0} {CALL_RETURN 0x382a78 0xb 0}}
WTX Status
wtxtcl Library Part I, WTX_UNREGISTER_FOR_EVENT, wtxtcl, wtxRegisterForEvent, wtxEventGet, wtxEventListGet
wtxExecutableFind - WDB / WTX requests executable path via document name
WTX Tcl
wtxExecutableFind filename
This function returns a pathname for the executable associated with open Windows shell acction on a given type of document. File with filename must exist and have a registered Windows extension (e.g. .html, .doc, .bmp etc) Function works on Win32 only and returns TCL_ERROR if called on Unix.
Input filename can contain \ or / characters as directory seprators in pathname. When wtxExecutableFind returns, returned pathname has forward slashes "/" and may contain spaces. In recent versions of Win32 cannot be longer than 260 bytes and short-name equivavalent is returned. The result may contain the path to the DDE server or DLL.
Full blown Win32 pathname starting with drive letter or pathname in UNC form or [possibly] path to DDE server.
tcl> wtxExecutableFind c:/MyTestDocumentThatDoesExist.htm C:\Program Files\Microsoft Internet\Iexplore.exe
- no association
- There is no association for the specified file type.
- file not found
- The specified file was not found.
- path not found
- The specified path was not found.
- exe file is invalid
- The .EXE file is invalid (non-Win32 .EXE or error in .EXE image).
- out of memory
- System is low on or out of memory.
- unknown error
- System returned unexpected error.
- not implemented
- Not implemented for this platform.
wtxtcl Library Part I, * wtxtcl