Tornado API Reference : WTX Protocol
WTX - WTX Protocol Requests
INFORMATION - WTX-protocol-requests manual layout
WTX_AGENT_MODE_GET - WTX get debug agent mode
WTX_AGENT_MODE_SET - WTX set debug agent mode
WTX_CLOSE - WTX close a file or pipe
WTX_CONSOLE_CREATE - WTX create a virtual target console (UNIX only)
WTX_CONSOLE_KILL - WTX kill a virtual target console (UNIX only)
WTX_CONTEXT_CONT - WTX continue a context on the target
WTX_CACHE_TEXT_UPDATE - WTX synchronize the instruction and data caches
WTX_COMMAND_SEND - WTX pass a string to be interpreted by the target server
WTX_CONTEXT_CREATE - WTX create a context on the target
WTX_CONTEXT_KILL - WTX destroy a context on the target
WTX_CONTEXT_RESUME - WTX resume a context on the target
WTX_CONTEXT_STATUS_GET - WTX gets the context of a status on the target
WTX_CONTEXT_STEP - WTX step a context on the target
WTX_CONTEXT_SUSPEND - WTX suspend a context on the target
WTX_DIRECT_CALL - WTX call a function on the target within the agent
WTX_EVENTPOINT_ADD - WTX add an eventpoint
WTX_EVENTPOINT_ADD_2 - WTX add an eventpoint
WTX_EVENTPOINT_DELETE - WTX delete an eventpoint
WTX_EVENTPOINT_LIST - WTX return a list of eventpoints
WTX_EVENTPOINT_LIST_GET - WTX return a list of eventpoints
WTX_EVENT_ADD - WTX add an event
WTX_EVENT_GET - WTX get an event
WTX_EVENT_LIST_GET - WTX get all the events in one call
WTX_FUNC_CALL - WTX call a function on the target
WTX_GOPHER_EVAL - WTX evaluate a Gopher program
WTX_INFO_GET - WTX get information about a given server
WTX_INFO_Q_GET - WTX get information about a list of servers
WTX_MEM_ADD_TO_POOL - WTX add memory to the memory pool
WTX_MEM_ALIGN - WTX allocate aligned target memory
WTX_MEM_ALLOC - WTX allocate target memory
WTX_MEM_CHECKSUM - WTX perform a target memory checksum
WTX_MEM_DISASSEMBLE - WTX target memory disassembler
WTX_MEM_FREE - WTX free a block of target memory
WTX_MEM_INFO_GET - WTX get information about the target memory pool
WTX_MEM_MOVE - WTX move target memory
WTX_MEM_WIDTH_READ - WTX target memory read
WTX_MEM_WIDTH_WRITE - WTX target memory write
WTX_MEM_READ - WTX target memory read
WTX_MEM_REALLOC - WTX reallocate target memory
WTX_MEM_SCAN - WTX search for a pattern in target memory
WTX_MEM_SET - WTX target memory set
WTX_MEM_WRITE - WTX target memory write
WTX_OBJ_KILL - WTX object kill
WTX_OBJ_MODULE_CHECKSUM - WTX checks validity of the target memory
WTX_OBJ_MODULE_FIND - WTX find an object module
WTX_OBJ_MODULE_INFO_GET - WTX get information about an object module
WTX_OBJ_MODULE_LIST - WTX list loaded object modules
WTX_OBJ_MODULE_LOAD - WTX load an object module into target memory
WTX_OBJ_MODULE_LOAD_2 - WTX load an object module into target memory
WTX_OBJ_MODULE_UNLOAD - WTX unload an object module
WTX_OBJ_MODULE_UNLOAD_2 - WTX unload an object module
WTX_OPEN - WTX open a file or pipe
WTX_REGISTER - WTX register a server
WTX_REGISTER_FOR_EVENT - WTX register for events
WTX_REGS_GET - WTX get target registers
WTX_REGS_SET - WTX set target registers
WTX_SYM_ADD - WTX add a symbol
WTX_SYM_FIND - WTX find a symbol
WTX_SYM_LIST_GET - WTX get a list of symbols
WTX_SYM_REMOVE - WTX remove a symbol
WTX_SYM_TBL_INFO_GET - WTX get information about a symbol table
WTX_TARGET_ATTACH - WTX attach a target to the target server
WTX_TARGET_RESET - WTX reset a target
WTX_TOOL_ATTACH - WTX attach a tool to a target server
WTX_TOOL_DETACH - WTX detach a tool from a target server
WTX_TS_INFO_GET - WTX get target and target server information
WTX_TS_LOCK - WTX target server lock
WTX_TS_UNLOCK - WTX target server unlock
WTX_UNREGISTER - WTX unregister a server
WTX_UNREGISTER_FOR_EVENT - WTX unregister for events
WTX_VIO_CHAN_GET - WTX get a virtual I/O channel number
WTX_VIO_CHAN_RELEASE - WTX release a virtual-I/O-channel number
WTX_VIO_CTL - WTX virtual I/O control
WTX_VIO_FILE_LIST - WTX list files managed by the target server
WTX_VIO_WRITE - WTX write to a virtual I/O channel
This document contains the Wind River Tool eXchange version 2.0 protocol reference. The WTX protocol is the backbone of the Tornado tools environment. It consists of a set of requests that are issued by tools connected to a target server (such as a shell or a debugger) to debug and monitor a real-time target system.
This document is intended to serve as a reference for implementers of Tornado tools. It should be used along with the WTX C API and WTX Tcl API reference entries.
The diagram below gives an overview of the Tornado environment.
+---------+ +---------+ +---------+ +---------+ | | | | | | | | | Shell | | Debugger| | Browser | | Other | | | | | | | | Tools | +----+----+ +----+----+ +----+----+ +----+----+ | | | | +--------------------+ | +-----------+ | | | | +-----------------------+ WTX | | | | Protocol | | | | +--+--+--+--+---+ | | | Target Server | | | +--+---+--+--+--+ | | | +-------------------+ +-------+ | +---------+ | | | | | Target +---+---+ +---+----+ +---+----+ +---+----+ Communication | WDB | | WDB | | WDB | |Non-WDB | Back Ends | RPC | | NetROM | | Serial | |Back End| +---+---+ +---+----+ +----+---+ +---+----+ | | | | Host | | | | - - - - - - - - - - - - -|- - - - - -|- - - - - - -|- - - - - -|- - - Target (or simulator) | | | | | | | | +---+---+ +---+----+ +----+---+ | |Network| | NetROM | | Serial | | WDB Target Agent |Comm if| |Comm if | |Comm if | | Communication +---+---+ +---+----+ +----+---+ | Interfaces | | | | +-------+ | +---------+ | | | | | +-+---+---+-+ +----+----+ |WDB Target | | Non-WDB | Agents | Agent | | Agent | +-----+-----+ +----+----+ | | +----+----+ | | | | | vxWorks +--------------------+ | | +---------+The Wind River Tools eXchange protocol (WTX) permits a number of tools running on a host system to communicate with one or more host-based target server(s) to operate on targets running VxWorks. Target servers can also be connected to target simulators like VxSIM. A target server is connected to only one target but a tool can be connected to more than one target server at a time.Warning, version 2 of the protocol will replace older version of the requests in the next release.
WTX requests can be categorized by the type of service they provide:
- Session management
- Start and stop a target server, attach and detach from a server, lock and unlock access to a server.
- Information
- Return information about the target server, the target configuration, and the target runtime system.
- Event management
- Notify tools of events such as exceptions that occur on the target, allow tools to send messages to other tools via the target server.
- Context management
- Create, suspend, and kill target contexts (tasks).
- Context debug
- Add and remove breakpoints and single step a task or the system context.
- Register operations
- Set and get target CPU register values.
- Runtime object information
- Return information about target system objects like tasks and semaphores using the Gopher language.
- Object module management
- Load, unload, and get information about object modules loaded on the target system.
- Symbol management
- Manipulate the target-server-resident target symbols by adding, removing, searching, and listing them.
- Target memory operations
- Allocate, free, read, and write target memory as well as search for patterns and perform checksumming; the allocate and free requests operate on a subset of the target memory managed by the target server and called the "target-server-managed target memory pool."
- Service management
- Add and list WTX and agent services.
- Virtual I/O operations
- Target contexts read and write data to and from host files, processes, or tools.
- Registry operations
- Tools obtain information needed to access a given target server.
The WTX protocol is used in two ways: to connect the target server to the registry and to connect tools to the target server.
Tools using WTX rely on the WTX registry daemon wtxregd to be running on a host somewhere on the network and to provide the "key" needed to reach a particular target server. For RPC-based WTX servers, this key is a string including the host name where the target server runs and the RPC program number for the target server.
The key to the WTX registry itself is a well known value. For RPC-based WTX, this key is made of the well known value, WTX_RPC_PROG, defined in wtxrpc.h and a host name given by the environment variable WIND_REGISTRY.
When a target server starts, it first registers itself into the WTX registry using the WTX_REGISTER request. Tools wishing to communicate with that target server ask the WTX registry for the target server key using the WTX_INFO_GET request.
Target Server Registry Tool ------------- -------- ------------------ . register using "name" . (WTX_REGISTER)------------> | generate key and record it | <--------------------- | . Get Target Server key . <----------------(WTX_INFO_GET) . | . return key . | . -----------------------> . . | . . Attach to Target Server . . (WTX_TOOL_ATTACH) . . | . . . . . . . . Detach from Target Server . . (WTX_TOOL_DETACH) . . | . . exit unregister . (WTX_UNREGISTER)------------> | remove Target Server entry | <--------------------- | . exit . .Note that the WTX registry daemon wtxregd must always be running for the Tornado environment to work. wtxregd is usually started as part of the boot procedure of a given host.
A typical example of a WTX shell tool session follows the sequence below:
Shell Tool Target Server ---------- ------------- | ask WTX registry for target server key (WTX_INFO_GET) | attach to target server <-------> record info about tool (WTX_TOOL_ATTACH) reply with tool ID | get target and target server info <-------> reply with info (WTX_TS_INFO_GET) | register for events <-------> record what to announce (WTX_REGISTER_FOR_EVENT) to this tool | load an object module <-------> return status (WTX_OBJ_MODULE_LOAD) | create a task <-------> create the task and (WTX_CONTEXT_CREATE) stop it at entry point | get a list of tasks <-------> return a list of tasks (WTX_GOPHER_EVAL) | set breakpoints <-------> return status (WTX_EVENTPOINT_ADD) | resume a task <-------> return status (WTX_CONTEXT_RESUME) | +---->------+ | | | | | poll for target events | (WTX_EVENT_GET) <-------> reply with a target event ^ (TEXT_ACCESS, EXCEPTION, etc) | . | . | | +----<------+ | close session (WTX_TOOL_DETACH)
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.
There are two ways of been notified when an event occurs: the first method is to poll for the events with WTX_EVENT_GET 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.
WTX events, except VIO_WRITE, 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.
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.
EVENT_SYM_ADDED and EVENT_SYM_REMOVED 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.
Event type T.S. Shell Debugger Windview CTX_START own own CTX_EXIT own own TEXT_ACCESS own own DATA_ACCESS own own EXCEPTION all own VIO_WRITE own own EVTPT_ADDED own all EVTPT_DELETED own all CALL_RETURN all all TGT_RESET yes yes yes yes TS_KILLED yes yes OBJ_LOADED all OBJ_UNLOADED all SYM_ADDED some some SYM_REMOVED some some TOOL_ATTACH all TOOL_DETACH all USER EVTPT_ADDED and EVTPT_DELETED are only generated when a tool add or delete an event point. When a task containing breakpoints ends, then the only event generated is CTX_EXIT (no event EVTPT_DELETED). The tool must update its event points list by removing all event points which match the contextId.
Events strings have the following syntax:
evtName [param1] [param2] [param3] ...where [paramX] is optional and can be either a hexadecimal value (0x12345678) or a string. The event name evtName and the associated parameters are given below. (h) specifies a hexadecimal parameter and (s) a string parameter.
Examples:
CTX_START contextType(h) contextId(h) contextType(h) contextId(h) CTX_EXIT contextType(h) contextId(h) returnVal(h) errnoVal(h) TEXT_ACCESS contextId(h) contextType(h) pc(h) fp(h) sp(h) DATA_ACCESS contextId(h) contextType(h) pc(h) fp(h) sp(h) addr(h) EXCEPTION contextType(h) contextId(h) excVector(h) esfAddr(h) CALL_RETURN callTaskId(h) returnVal(h) errnoVal(h) VIO_WRITE channelId(h) addlData addlDataLen EVTPT_ADDED evtptNum(h) (See WTX_EVENTPOINT_ADD_2) EVTPT_DELETED evtptNum(h) TGT_RESET TS_KILLED OBJ_LOADED objModId(h) objModName(s) OBJ_UNLOADED objModId(h) objModName(s) objModGroup(h) SYM_ADDED symbol(s) symVal(h) SYM_REMOVED symbol(s) symType(s) TOOL_ATTACH toolName(s) TOOL_DETACH toolName(s) TOOL_MSG destination(s) sender(s) message(s) anything(s) USER message(s) UNKNOWN For a breakpoint occurring at address 0x4002344 in task 0x4030090, the event will be the string:
"TEXT_ACCESS 0x4030090 0x3 0x4002344 0x4008008 0x4008608"For a watchpoint occurring at address 0x4040000 in task 0x4030090 with pc equals to 0x4002344, the event will be the string:
"DATA_ACCESS 0x4030090 0x3 0x4002344 0x4008008 0x4008608 0x4040000"For a symbol newSymbol of type text added with value 0x4002344, the event will be the string:
"SYM_ADD newSymbol 0x4002344"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):
"EXCEPTION 0x3 0x4002344 0x10 0x212900"For a task 0x394390 exiting with return value equals to 4 and errno equals to 0, the event will be the string:
"CTX_EXIT 0x3 0x394390 0x4 0"For a task 0x394390 created from task 0x397e10, the event will be the string:
"CTX_START 0x3 0x394390 0x3 0x397e10"For a breakpoint set on the symbol printf in the shell, the event will be the string:
"EVTPT_ADDED 0x1 0x3 0 0x6 0 0 0 0x3 0x1 0x79d18"The event strings are exchanged via the WTX_MSG_EVENT_DESC structure below:
typedef struct wtx_msg_event_desc /* Event message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_EVENT_DESC eventDesc; /* Event descriptor */ } WTX_MSG_EVENT_DESC;where WTX_EVENT_DESC is:
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;The maximum length of an event string (TOOL_EVT_SIZE) is 300 characters.
VIO_WRITE events can carry non-ASCII data. These data are stored in a buffer pointed to by addlData and the buffer size is given by addlDataLen.
All the WTX messages are prefixed WTX_MSG_. They all contain a WTX_CORE 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 errno set by the server. The error codes are defined in wpwr/host/include/wtxerr.h.
typedef struct wtx_core /* WTX message core */ { UINT32 objId; /* identifier */ WTX_ERROR_T errCode; /* service error code */ UINT32 protVersion; /* WTX protocol version */ } WTX_CORE;The protocol version protVersion field should be set to 20 for the current version of the protocol ("2.0").
When used as a server input message, the objId field in WTX_CORE is always set to the tool identifier value. Unused fields in all WTX messages should be set to NULL.
The type of a simple value sent or received, like an integer or an address, is specified with the basic types defined by WTX_VALUE_T.
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 */ } WTX_VALUE_T;The types defined above should always be used to set the valueType field in the WTX_VALUE structure (shown below) in order to specify the type of the passed value.
A parameter or result of simple type is returned in a WTX_VALUE embedded in a WTX_MSG_PARAM or WTX_MS_RESULT message respectively. The type is given by valueType and the value given by value_u.v_xxx.
typedef struct wtx_value /* Simple type value */ { WTX_VALUE_T valueType; /* Value type */ union { INT8 v_int8; /* 8 bit signed value */ INT16 v_int16; /* 16 bit signed value */ INT32 v_int32; /* 32 bit signed value */ UINT8 v_uint8; /* 8 bit unsigned value */ UINT16 v_uint16; /* 16 bit unsigned value */ UINT32 v_uint32; /* 32 bit unsigned value */ double v_double; /* Double value */ BOOL32 v_bool32; /* 32 bit boolean value */ char * v_pchar; /* String value */ void * v_pvoid; /* Void pointer value */ TGT_ADDR_T v_tgt_addr; /* Target address value */ TGT_ARG_T v_tgt_arg; /* Target task arg. value */ } value_u; } WTX_VALUE;A simple type-parameter message has the structure below:
typedef struct wtx_msg_param /* Simple request parameter */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE param; /* Param value of call */ } WTX_MSG_PARAM;A simple type-return-value message has the structure below:
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
When a failure occurs, the WTX requests can return one of the following ERROR codes:
typedef enum wtx_error_t { /* Target Server Errors */ WTX_ERR_SVR_TARGET_NOT_ATTACHED = (WTXERR_BASE_NUM | 1), WTX_ERR_SVR_INVALID_EVENTPOINT = (WTXERR_BASE_NUM | 2), WTX_ERR_SVR_FILE_NOT_FOUND = (WTXERR_BASE_NUM | 3), WTX_ERR_SVR_INVALID_FIND_REQUEST = (WTXERR_BASE_NUM | 4), WTX_ERR_SVR_INVALID_FLAGS = (WTXERR_BASE_NUM | 5), WTX_ERR_SVR_INVALID_FILE_DESCRIPTOR = (WTXERR_BASE_NUM | 6), WTX_ERR_SVR_EINVAL = (WTXERR_BASE_NUM | 7), WTX_ERR_SVR_CANT_START_CONSOLE = (WTXERR_BASE_NUM | 8), WTX_ERR_SVR_INVALID_CONSOLE = (WTXERR_BASE_NUM | 9), WTX_ERR_SVR_NO_SCALABLE_AGENT = (WTXERR_BASE_NUM | 10), WTX_ERR_SVR_CANT_ADD_WTX_SERVICE = (WTXERR_BASE_NUM | 11), WTX_ERR_SVR_NO_VIO_CHANNEL = (WTXERR_BASE_NUM | 12), WTX_ERR_SVR_BKEND_LOG_IN_USE = (WTXERR_BASE_NUM | 13), WTX_ERR_SVR_WTX_LOG_IN_USE = (WTXERR_BASE_NUM | 14), WTX_ERR_SVR_DOESNT_RESPOND = (WTXERR_BASE_NUM | 15), WTX_ERR_SVR_IS_DEAD = (WTXERR_BASE_NUM | 16), WTX_ERR_SVR_BAD_TARGET_CHECKSUM = (WTXERR_BASE_NUM | 17), WTX_ERR_SVR_CHECKSUM_MISMATCH = (WTXERR_BASE_NUM | 18), /* Common Server Errors */ WTX_ERR_SVR_NOT_ENOUGH_MEMORY = (WTXERR_BASE_NUM | 20), WTX_ERR_SVR_ACCESS_DENIED = (WTXERR_BASE_NUM | 21), WTX_ERR_SVR_WIND_BASE_NOT_SET = (WTXERR_BASE_NUM | 22), WTX_ERR_SVR_SERVICE_NOT_AVAILABLE = (WTXERR_BASE_NUM | 23), WTX_ERR_SVR_INVALID_CLIENT_ID = (WTXERR_BASE_NUM | 24), WTX_ERR_SVR_CLIENT_NOT_ATTACHED = (WTXERR_BASE_NUM | 25), WTX_ERR_SVR_TARGET_UNKNOWN = (WTXERR_BASE_NUM | 26), WTX_ERR_SVR_INVALID_DEVICE = (WTXERR_BASE_NUM | 27), WTX_ERR_SVR_CANT_CONNECT_LICENSE_DAEMON = (WTXERR_BASE_NUM | 28), WTX_ERR_SVR_INVALID_LICENSE = (WTXERR_BASE_NUM | 29), /* Registry Errors */ WTX_ERR_REGISTRY_NAME_NOT_FOUND = (WTXERR_BASE_NUM | 30), WTX_ERR_REGISTRY_BAD_PATTERN = (WTXERR_BASE_NUM | 31), WTX_ERR_REGISTRY_NAME_CLASH = (WTXERR_BASE_NUM | 32), WTX_ERR_REGISTRY_DB_DIR_NOT_FOUND = (WTXERR_BASE_NUM | 33), WTX_ERR_REGISTRY_DB_FILE_ERROR = (WTXERR_BASE_NUM | 34), /* Object Module Management Errors */ WTX_ERR_LOADER_TEXT_IN_USE = (WTXERR_BASE_NUM | 40), WTX_ERR_LOADER_ILLEGAL_FLAGS_COMBINATION = (WTXERR_BASE_NUM | 41), WTX_ERR_LOADER_NO_RELOCATION_ROUTINE = (WTXERR_BASE_NUM | 42), WTX_ERR_LOADER_CANT_GET_SEGMENT_ADDRESSES = (WTXERR_BASE_NUM | 43), WTX_ERR_LOADER_UNKNOWN_RELOCATION_ENTRY = (WTXERR_BASE_NUM | 44), WTX_ERR_LOADER_UNKNOWN_COMMAND_FLAG = (WTXERR_BASE_NUM | 45), WTX_ERR_LOADER_UNKNOWN_OBJ_MODULE_FORMAT = (WTXERR_BASE_NUM | 46), WTX_ERR_LOADER_NULL_SIZE_OBJ_MODULE = (WTXERR_BASE_NUM | 47), WTX_ERR_LOADER_OBJ_MODULE_NOT_FOUND = (WTXERR_BASE_NUM | 48), WTX_ERR_LOADER_BAD_CHECKSUM = (WTXERR_BASE_NUM | 49), WTX_ERR_LOADER_CANT_ATTACH_OMF_MANAGER = (WTXERR_BASE_NUM | 50), WTX_ERR_LOADER_OBJ_MODULE_NOT_APPROPRIATE = (WTXERR_BASE_NUM | 51), WTX_ERR_LOADER_RELOCATION_OFFSET_TOO_LARGE= (WTXERR_BASE_NUM | 52), WTX_ERR_LOADER_SYMBOL_NOT_FROM_SDA_SECTION= (WTXERR_BASE_NUM | 53), WTX_ERR_LOADER_MAX_MODULES_LOADED = (WTXERR_BASE_NUM | 54), WTX_ERR_LOADER_RELOCATION_ERROR = (WTXERR_BASE_NUM | 55), WTX_ERR_LOADER_NO_VERIFICATION_ROUTINE = (WTXERR_BASE_NUM | 56), WTX_ERR_LOADER_LOAD_CANCELED = (WTXERR_BASE_NUM | 57), WTX_ERR_LOADER_LOAD_IN_PROGRESS = (WTXERR_BASE_NUM | 58), WTX_ERR_LOADER_ALREADY_LOADED = (WTXERR_BASE_NUM | 59), /* Symbol Management Errors */ WTX_ERR_SYMTBL_INVALID_SYMTBL = (WTXERR_BASE_NUM | 60), WTX_ERR_SYMTBL_SYMBOL_NOT_FOUND = (WTXERR_BASE_NUM | 61), WTX_ERR_SYMTBL_TABLE_NOT_EMPTY = (WTXERR_BASE_NUM | 62), WTX_ERR_SYMTBL_NAME_CLASH = (WTXERR_BASE_NUM | 63), WTX_ERR_SYMTBL_NO_SUCH_MODULE = (WTXERR_BASE_NUM | 64), WTX_ERR_SYMTBL_SYMBOL_NAME_TOO_LONG = (WTXERR_BASE_NUM | 65), /* Target Memory Management Errors */ WTX_ERR_TGTMEM_NOT_ENOUGH_MEMORY = (WTXERR_BASE_NUM | 70), WTX_ERR_TGTMEM_INVALID_POOL_SIZE = (WTXERR_BASE_NUM | 71), WTX_ERR_TGTMEM_INVALID_BLOCK = (WTXERR_BASE_NUM | 72), WTX_ERR_TGTMEM_PAGE_SIZE_UNAVAILABLE = (WTXERR_BASE_NUM | 73), WTX_ERR_TGTMEM_BLOCK_CONFLICT = (WTXERR_BASE_NUM | 74), WTX_ERR_TGTMEM_CANT_UNMAP_UNKNOWN_BLOCK = (WTXERR_BASE_NUM | 75), WTX_ERR_TGTMEM_UNMAPPED_MEMORY = (WTXERR_BASE_NUM | 76), /* generic DLL error codes */ WTX_ERR_DLL_CANT_OPEN_SHARED_FILE = (WTXERR_BASE_NUM | 100), WTX_ERR_DLL_CANT_BIND_FUNCTION = (WTXERR_BASE_NUM | 101), WTX_ERR_DLL_CANT_CLOSE_SHARED_FILE = (WTXERR_BASE_NUM | 102), /* Internal object error codes */ WTX_ERR_OBJ_INVALID_OBJECT = (WTXERR_BASE_NUM | 110), /* Agent error codes */ WTX_ERR_AGENT_UNSUPPORTED_REQUEST = (WTXERR_BASE_NUM | 200), WTX_ERR_AGENT_INVALID_PARAMS = (WTXERR_BASE_NUM | 201), WTX_ERR_AGENT_MEM_ACCESS_ERROR = (WTXERR_BASE_NUM | 202), WTX_ERR_AGENT_AGENT_MODE_ERROR = (WTXERR_BASE_NUM | 203), WTX_ERR_AGENT_RT_ERROR = (WTXERR_BASE_NUM | 204), WTX_ERR_AGENT_INVALID_CONTEXT = (WTXERR_BASE_NUM | 205), WTX_ERR_AGENT_INVALID_VIO_CHANNEL = (WTXERR_BASE_NUM | 206), WTX_ERR_AGENT_INVALID_EVENT = (WTXERR_BASE_NUM | 207), WTX_ERR_AGENT_INVALID_EVENTPOINT = (WTXERR_BASE_NUM | 208), WTX_ERR_AGENT_GOPHER_FAULT = (WTXERR_BASE_NUM | 209), WTX_ERR_AGENT_GOPHER_TRUNCATED = (WTXERR_BASE_NUM | 210), WTX_ERR_AGENT_EVENTPOINT_TABLE_FULL = (WTXERR_BASE_NUM | 211), WTX_ERR_AGENT_NO_AGENT_PROC = (WTXERR_BASE_NUM | 212), WTX_ERR_AGENT_NO_RT_PROC = (WTXERR_BASE_NUM | 213), WTX_ERR_AGENT_PROC_FAILED = (WTXERR_BASE_NUM | 214), WTX_ERR_AGENT_PATTERN_NOT_FOUND = (WTXERR_BASE_NUM | 215), WTX_ERR_AGENT_HW_BP_REGS_EXHAUSTED = (WTXERR_BASE_NUM | 216), WTX_ERR_AGENT_INVALID_HW_BP = (WTXERR_BASE_NUM | 217), WTX_ERR_AGENT_NO_CONNECTION = (WTXERR_BASE_NUM | 220), WTX_ERR_AGENT_CONNECTION_BUSY = (WTXERR_BASE_NUM | 221), WTX_ERR_AGENT_COMMUNICATION_ERROR = (WTXERR_BASE_NUM | 222), WTX_ERR_AGENT_GOPHER_SYNTAX = (WTXERR_BASE_NUM | 223), /* WTX C API error codes */ WTX_ERR_API = (WTXERR_BASE_NUM | 300), WTX_ERR_API_MEMALLOC = (WTXERR_BASE_NUM | 301), WTX_ERR_API_HANDLER_NOT_FOUND = (WTXERR_BASE_NUM | 302), WTX_ERR_API_NOT_CONNECTED = (WTXERR_BASE_NUM | 303), WTX_ERR_API_INVALID_ARG = (WTXERR_BASE_NUM | 304), WTX_ERR_API_SERVER_NOT_FOUND = (WTXERR_BASE_NUM | 305), WTX_ERR_API_ALREADY_CONNECTED = (WTXERR_BASE_NUM | 306), WTX_ERR_API_AMBIGUOUS_SERVER_NAME = (WTXERR_BASE_NUM | 307), WTX_ERR_API_REGS_GET_PARTIAL_READ = (WTXERR_BASE_NUM | 308), WTX_ERR_API_INVALID_HANDLE = (WTXERR_BASE_NUM | 309), WTX_ERR_API_REGISTRY_UNREACHABLE = (WTXERR_BASE_NUM | 310), WTX_ERR_API_SERVICE_NOT_REGISTERED = (WTXERR_BASE_NUM | 311), WTX_ERR_API_SERVICE_ALREADY_REGISTERED = (WTXERR_BASE_NUM | 312), WTX_ERR_API_TOOL_DISCONNECTED = (WTXERR_BASE_NUM | 313), WTX_ERR_API_REQUEST_FAILED = (WTXERR_BASE_NUM | 314), WTX_ERR_API_REQUEST_TIMED_OUT = (WTXERR_BASE_NUM | 315), WTX_ERR_API_FILE_NOT_FOUND = (WTXERR_BASE_NUM | 316), WTX_ERR_API_SERVICE_ALREADY_STARTED = (WTXERR_BASE_NUM | 317), WTX_ERR_API_CANT_OPEN_SOCKET = (WTXERR_BASE_NUM | 318), WTX_ERR_API_CANT_GET_HOSTNAME = (WTXERR_BASE_NUM | 319), WTX_ERR_API_FILE_NOT_ACCESSIBLE = (WTXERR_BASE_NUM | 320), WTX_ERR_API_NULL_SIZE_FILE = (WTXERR_BASE_NUM | 321), WTX_ERR_API_CANT_READ_FROM_FILE = (WTXERR_BASE_NUM | 322), /* WTX Exchange Error Codes */ WTX_ERR_EXCHANGE = (WTXERR_BASE_NUM | 400), WTX_ERR_EXCHANGE_INVALID_HANDLE = (WTXERR_BASE_NUM | 401), WTX_ERR_EXCHANGE_DATA = (WTXERR_BASE_NUM | 402), WTX_ERR_EXCHANGE_MEMALLOC = (WTXERR_BASE_NUM | 403), WTX_ERR_EXCHANGE_NO_SERVER = (WTXERR_BASE_NUM | 404), WTX_ERR_EXCHANGE_INVALID_ARG = (WTXERR_BASE_NUM | 405), WTX_ERR_EXCHANGE_MARSHALPTR = (WTXERR_BASE_NUM | 406), WTX_ERR_EXCHANGE_TIMEOUT = (WTXERR_BASE_NUM | 407), WTX_ERR_EXCHANGE_BAD_KEY = (WTXERR_BASE_NUM | 408), WTX_ERR_EXCHANGE_REQUEST_UNSUPPORTED = (WTXERR_BASE_NUM | 409), WTX_ERR_EXCHANGE_TRANSPORT_UNSUPPORTED = (WTXERR_BASE_NUM | 410), WTX_ERR_EXCHANGE_TRANSPORT_ERROR = (WTXERR_BASE_NUM | 411), WTX_ERR_EXCHANGE_TRANSPORT_DISCONNECT = (WTXERR_BASE_NUM | 412), WTX_ERR_EXCHANGE_NO_TRANSPORT = (WTXERR_BASE_NUM | 413), WTX_ERR_LAST = (WTXERR_BASE_NUM | 0xFFFF) } WTX_ERROR_T;
Many WTX requests can return the WTX_ERR_SVR_NOT_ENOUGH_MEMORY error code indicating that the server process has run out of memory. This failure is not likely to occur but it can be caused by a too small virtual or physical memory configuration on the host where the target server is running.
The WTX protocol can be based on any underlying transport protocol. The current version uses ONC RPC over TCP/IP. This allows tools and target servers to run on the same or different hosts. The RPC program number of the server is embedded in the key returned by the WTX registry daemon wtxregd.
WTX employs the SUN eXternal Data Representation (XDR).
The RPC-based WTX protocol uses the UNIX authentication based on user id and group id in order to restrict the use of the target server to authorized people. See the Tornado User's Guide: Tools for the Windows NT authentication method.
wtx.h wtxtypes.h wtxmsg.h wtxerr.h
Tornado User's Guide, API Reference Manual: WTX Protocol, WTX C Library, WTX Tcl Library
INFORMATION - WTX-protocol-requests manual layout
INPUT: WTX_INPUT_MESSAGE OUTPUT: WTX_OUTPUT_MESSAGE
This paragraph gives a description of what the WTX protocol request does. It gives detailed information about its input and output messages. It also provides guidelines for using the request.
In this document message names and other structure names are represented in caps: THIS_IS_A_WTX_MESSAGE. Fields in the messages are represented in bold: thisIsAfield or thisIsAfield in the THIS_IS_A_WTX_MESSAGE message structure.
The protocol messages are represented as C structures. For example the WTX_CORE message is:
typedef struct wtx_core /* WTX message core */ { UINT32 objId; /* identifier */ WTX_ERROR_T errCode; /* service error code */ UINT32 protVersion; /* WTX protocol version */ } WTX_CORE;Many messages are embedded in other messages. For example, WTX_CORE is embedded in WTX_MSG_PARAM:
typedef struct wtx_msg_param /* Simple request parameter */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE param; /* Param value of call */ } WTX_MSG_PARAM;Thus the errCode field in WTX_CORE can also be referred to as wtxCore.errCode.
This paragraph describes the WTX events that are related to this request. It mentions the events that are either sent to other tools when the request is processed by the target server or target events that can be caused by this request.
This paragraph gives any important hints about the request.
This paragraph gives the values of all hard-coded limits associated with the request such as the maximum number of elements in an array.
This paragraph describes the return value of the request. For example, a typical return value is:
The errCode field in WTX_CORE contains OK, or ERROR if communication with the target fails. If errCode is OK, the val field in WTX_MSG_RESULT contains .......
This paragraph gives the scope of the request: applicable to the target, to the target server, to both, or to the WTX registry.
This paragraph gives an example of input parameters for this request.
This paragraph lists the possible error codes returned by this request.
- A_WTX_ERROR_CODE
- Each error code is described here along with a description of possible causes of failure.
WTX_AGENT_MODE_GET - WTX get debug agent mode
INPUT: WTX_MSG_TOOL_ID OUTPUT: WTX_MSG_RESULT
This request returns the running mode of the debug agent. The mode can be either:
- WTX_AGENT_MODE_TASK
- The agent runs as a task.
- WTX_AGENT_MODE_EXTERN
- The agent runs in external mode.
The tool making the request sends its identifier in the following format:
typedef struct wtx_msg_tool_id /* Tool identifier message */ { WTX_CORE wtxCore; /* WTX message core */ } WTX_MSG_TOOL_ID;The agent mode is returned in a WTX_MSG_RESULT message:
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
The agent mode is the mode at the time the request was made to the target; it might be obsolete by the time it is received by the tool making the request.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or ERROR if communication with the target fails. If errCode is OK, the val field in WTX_MSG_RESULT contains the current agent running mode.
Target only
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_AGENT_MODE_SET - WTX set debug agent mode
INPUT: WTX_MSG_PARAM OUTPUT: WTX_MSG_RESULT
This request sets the running mode of the debug agent. The debug agent mode to set, the value field in WTX_MSG_PARAM, can be:
- MODE_TASK
- The agent runs in task mode allowing only task debugging.
- MODE_EXTERN
- The agent runs in external mode allowing only system and interrupt code debugging.
- MODE_BI
- The agent runs in both external and task modes, switching from one mode to the other when hitting breakpoints.
typedef struct wtx_msg_param /* Simple request parameter */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE param; /* Param value of call */ } WTX_MSG_PARAM;The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
Not all agents support all debugging modes. When an agent does not support a given mode, it returns a WTX_ERR_AGENT_UNSUPPORTED_REQUEST error and remains in the previous mode.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if the given agent mode is invalid.
Target only
- WTX_ERR_AGENT_INVALID_PARAMS
- The requested running mode is not supported by the agent.
- WTX_ERR_AGENT_UNSUPPORTED_REQUEST
- The agent mode set is not supported by the agent.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_CLOSE - WTX close a file or pipe
INPUT: WTX_MSG_PARAM OUTPUT: WTX_MSG_RESULT
This request closes the file specified by the file descriptor in the param field of WTX_MSG_PARAM. If param is a pipe, this request uses the pclose( ) system call to close the pipe; otherwise it calls close( ).
typedef struct wtx_msg_param /* Simple request parameter */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE param; /* Param value of call */ } WTX_MSG_PARAM;After a call to WTX_CLOSE, any data written to the file from a virtual I/O channel is lost. The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to close the specified file or pipe.
Target server only
- WTX_ERR_SVR_INVALID_FILE_DESCRIPTOR
- The file descriptor is invalid.
- EBADF
- The given file descriptor is not an active descriptor; the file may already be closed.
- TIMEOUT
- WTX RPC timeout.
WTX_CONSOLE_CREATE - WTX create a virtual target console (UNIX only)
INPUT: WTX_MSG_CONSOLE_DESC OUTPUT: WTX_MSG_CONSOLE_DESC
This request creates a console tty on a UNIX host that can be connected to target tasks via a virtual I/O channel.
The input message is:
typedef struct wtx_msg_console_desc /* WTX Virtual console desc. */ { WTX_CORE wtxCore; /* WTX message core */ WTX_CONSOLE_DESC wtxConsDesc; /* Console descriptor */ } WTX_MSG_CONSOLE_DESC;where WTX_CONSOLE_DESC is defined as follows:
typedef struct wtx_console_desc /* WTX Virtual console desc. */ { INT32 fdIn; /* Stdin for redirection */ INT32 fdOut; /* Stdout for redirection */ INT32 pid; /* Process identifier */ char * name; /* Console name */ char * display; /* Display name eg: host:0 */ void * pReserved; /* Reserved */ } WTX_CONSOLE_DESC;Only the name field needs to be specified; all the other fields are set to NULL. The name passed in wtxConsDesc.name is used as a title for the console window. The name may be of arbitrary length and content, including blank space. If wtxConsDesc.name is NULL, the console window is assigned an ASCII name of the form "target console n" where n is an integer which increments as new consoles are created. The wtxConsDesc.display field can be used to specify the display host (for example, hostname:0) when running in a X-Window environment. If wtxConsDesc.display is NULL, the display is the host where the target server is running. 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 also adds the console file descriptor(s) to the target server internal-file-descriptor list for use with virtual I/O redirection.
A virtual I/O console is destroyed using WTX_CONSOLE_KILL.
On UNIX-based hosts, the virtual I/O console is an xterm process which is displayed on the host specified by WTX_CONSOLE_DESC.display'.
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.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to create a virtual target console. If errCode is OK, WTX_CONSOLE_DESC contains the console information. The pid field contains the identifier of the virtual console, which is pid is the xterm console process id.
Target server only
- WTX_ERR_SVR_CANT_START_CONSOLE
- Failed to start the virtual target console process.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the target server host to create a virtual console.
- WTX_ERR_SVR_SERVICE_NOT_AVAILABLE
- Console creation not available (Windows host only).
- TIMEOUT
- WTX RPC timeout.
WTX_CONSOLE_KILL - WTX kill a virtual target console (UNIX only)
INPUT: WTX_MSG_PARAM OUTPUT: WTX_MSG_RESULT
This request kills a virtual I/O console specified by its identifier in the value field of WTX_MSG_PARAM. It also removes any file descriptor associated with the console process from the target server internal-file-descriptor list.
typedef struct wtx_msg_param /* Simple request parameter */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE param; /* Param value of call */ } WTX_MSG_PARAM;The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request is not implemented on Windows. If issued, it returns an error, but does not attempt to kill an existing console.
This request has no associated events.
OK, or an ERROR code if unable to kill the virtual console.
Target server only
- WTX_ERR_SVR_INVALID_CONSOLE
- Invalid console.
- WTX_ERR_SVR_INVALID_FILE_DESCRIPTOR
- Invalid file descriptor. This can happen if a WTX_CLOSE request was made on the file descriptor associated with the console.
- TIMEOUT
- WTX RPC timeout.
WTX_CONTEXT_CONT - WTX continue a context on the target
INPUT: WTX_MSG_CONTEXT OUTPUT: WTX_MSG_RESULT
This request continues execution of a context on the remote target. The context to be resumed is specified by contextId.
typedef struct wtx_msg_context /* Context message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_CONTEXT_TYPE contextType; /* Type of context */ WTX_CONTEXT_ID_T contextId; /* Context ID */ } WTX_MSG_CONTEXT;The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;Note that this request is used to resume a context stopped at a breakpoint. It should not be used to resume a context suspended via WTX_CONTEXT_SUSPEND. A suspended or just-created context should be resumed with WTX_CONTEXT_RESUME.
After calling this request, the following events can be generated by the target system:
- TEXT_ACCESS
- An instruction fetch occurred at the specified address (breakpoint).
- DATA_ACCESS
- A data access occurred at the specified address.
- EXCEPTION
- The task got an exception (for example: BUS ERROR, ZERO DIVIDE).
- CONTEXT_EXIT
- The task exited via exit( ).
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to resume the context.
Target only
- WTX_ERR_AGENT_UNSUPPORTED_REQUEST
- Context continue is not supported by the debug agent.
- WTX_ERR_AGENT_INVALID_CONTEXT
- Invalid target system context.
- WTX_ERR_AGENT_NO_RT_PROC
- Target operating system does not support context continue.
- WTX_ERR_AGENT_AGENT_MODE_ERROR
- Attempt to continue the system context while in task mode.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_CONTEXT_CREATE, WTX_CONTEXT_SUSPEND, WTX_CONTEXT_RESUME, WTX_CONTEXT_STEP, WTX_EVENT_GET
WTX_CACHE_TEXT_UPDATE - WTX synchronize the instruction and data caches
INPUT: WTX_MSG_MEM_BLOCK_DESC OUTPUT: WTX_MSG_RESULT
This request 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.
The input message is:
typedef struct wtx_msg_mem_block_desc /* Target memory block */ { WTX_CORE wtxCore; /* WTX message core */ TGT_ADDR_T startAddr; /* Blocks starts from here */ UINT32 numBytes; /* Number of bytes in block */ } WTX_MSG_MEM_BLOCK_DESC;The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to resume the context.
Target only
- TIMEOUT
- WTX RPC timeout.
WTX,
WTX_COMMAND_SEND - WTX pass a string to be interpreted by the target server
INPUT: WTX_MSG_PARAM OUTPUT: WTX_MSG_RESULT
This service sends a string to the target server which interprets it. If the requested service is not known by WTX_COMMAND_SEND, then the string is sent back to the client.
The input message is:
typedef struct wtx_msg_param /* Simple request parameter */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE param; /* Param value of call */ } WTX_MSG_PARAM;The result of this request is returned in a WTX_MSG_RESULT message but the val field is only used when the request is unknown, otherwise, the val field is NULL
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events except if WTX_TARGET_RESET is called where a TGT_RESET event is issued to all tools attached to the target server if the call is successfull.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to reset the target.
Target and target server if WTX_TARGET_RESET is called, otherwise target server.
3 strings that can be used as parameter
value_u.v_pchar = "wtxTsLock 30"; /* lock the target server for 30s */ value_u.v_pchar = "wtxTsUnlock"; /* Unlock the target server */ value_u.v_pchar = "wtxLoggingOn /tmp/wtx.txt"; /* wtx log started */
Only these commands are recognized:
- wdbLoggingOn
- Open the file and log all WDB requests.
- wdbLoggingOff
- Close the file and stop the log.
- wtxLoggingOn
- Open the file and log all WTX requests.
- wtxLoggingOff
- Close the file and stop the log.
- allLoggingOff
- Stop WDB and WTX log.
- wtxAsyncNotifyEnable
- Start the asynchronous notification of events.
- wtxAsyncNotifyDisable
- Stop the asynchronous notification of events.
- wtxObjKillDestroy
- Kill the target server.
- wtxObjKillRestart
- Restart the target server.
- wtxTsLock
- Lock the target server.
- wtxTsUnlock
- Unlock the target server.
- wtxTargetReset
- Reset the target.
- wtxObjModuleLoadCancel
- Cancel the current asynchronous load request
- WTX_ERR_SVR_INVALID_CLIENT_ID
- The tool must be attached to issue this request.
- WTX_ERR_SVR_EINVAL
- Invalid kill request.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_OBJ_KILL, WTX_TS_LOCK, WTX_TS_UNLOCK, WTX_TARGET_RESET
WTX_CONTEXT_CREATE - WTX create a context on the target
INPUT: WTX_MSG_CONTEXT_DESC OUTPUT: WTX_MSG_CONTEXT
This request creates a new context on the remote target. The context is created according to the value specified by the WTX_MSG_CONTEXT_DESC message and left in the suspended state. It can be resumed using WTX_CONTEXT_RESUME.
The WTX_MSG_CONTEXT structure is embedded in the message below:
typedef struct wtx_msg_context_desc /* Context creation desc. */ { WTX_CORE wtxCore; /* WTX message core */ WTX_CONTEXT_TYPE contextType; /* Type of context */ WTX_RETURN_TYPE returnType; /* Int or double */ char * name; /* Task name */ UINT32 priority; /* Task priority */ UINT32 options; /* Task options */ TGT_ADDR_T stackBase; /* Base of stack */ UINT32 stackSize; /* Stack size */ TGT_ADDR_T entry; /* Context entry point */ INT32 redirIn; /* Redir. in file or 0 */ INT32 redirOut; /* Redir. out file or 0 */ TGT_ARG_T args[WTX_MAX_ARG_CNT]; /* Arguments */ void * pReserved; /* Reserved */ } WTX_MSG_CONTEXT_DESC;where WTX_CONTEXT_TYPE is:
typedef enum wtx_context_type /* types of context */ { WTX_CONTEXT_SYSTEM = 0, /* system mode */ WTX_CONTEXT_GROUP = 1, /* process group (not implemented) */ WTX_CONTEXT_ANY = 2, /* any context (not implemented) */ WTX_CONTEXT_TASK = 3, /* specific task or processes */ WTX_CONTEXT_ANY_TASK = 4, /* any task */ WTX_CONTEXT_ISR = 5, /* specific ISR (not implemented) */ WTX_CONTEXT_ISR_ANY = 6 /* any ISR (not implemented) */ } WTX_CONTEXT_TYPE;For a VxWorks-based runtime, a task may be assigned a name as a debugging aid. This name appears in displays generated by various system information facilities such as i( ). The name may be of arbitrary length and content.
The stackBase field is never used by the agent. The agent always allocates a stack from the target system memory pool. The stack size, stackSize, must be an even integer. If stackSize is NULL, the default stack size is 0x5000 bytes. A task control block (TCB) is carved from the stack, as well as any memory required by the task name. The remaining memory is the task's stack and every byte is filled with the value 0xEE for the checkStack facility unless the NO_STACK_FILL option is used.
The entry address entry is the address of the "main" routine of the task. The routine is called after the C environment is set up. The specified routine is called with ten arguments. Should the specified main routine return, a call to exit is automatically made.
Note that ten (and only ten) arguments must be passed for the spawned function.
Bits in the options argument may be set to run with the following modes for VxWorks-based systems:
- VX_FP_TASK
- Execute with floating-point coprocessor support.
- VX_PRIVATE_ENV
- Include private environment support (see envLib).
- VX_NO_STACK_FILL
- Do not fill the stack for use by checkStack.
- VX_UNBREAKABLE
- Do not allow breakpoint debugging.
See the definitions in wpwr/target/h/taskLib.h.
The redirIn and redirOut fields specify the file descriptor to be used for the context standard input and output respectively.
The returnType field is ignored and is set to NULL.
The created context identifier is returned in:
typedef struct wtx_msg_context /* Context message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_CONTEXT_TYPE contextType; /* Type of context */ WTX_CONTEXT_ID_T contextId; /* Context ID */ } WTX_MSG_CONTEXT;where contextType equals WTX_CONTEXT_TASK.
Only the creation of WTX_CONTEXT_TASK is supported.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to create the context. When errCode is OK, the contextId field in WTX_MSG_CONTEXT returns a target-system-assigned context identifier.
Target only
The maximum number of arguments for the created context is 10.
- WTX_ERR_AGENT_UNSUPPORTED_REQUEST
- Context create is not supported by the debug agent.
- WTX_ERR_AGENT_NO_RT_PROC
- The target operating system does not support context creation.
- WTX_ERR_AGENT_RT_ERROR
- The target operating system failed to create the context.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_CONTEXT_KILL, WTX_CONTEXT_RESUME, VxWorks Reference Manual
WTX_CONTEXT_KILL - WTX destroy a context on the target
INPUT: WTX_MSG_CONTEXT OUTPUT: WTX_MSG_RESULT
This request destroys a context on the remote target. The identifier of the context to be destroyed is specified by the contextId field in WTX_MSG_CONTEXT.
typedef struct wtx_msg_context /* Context message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_CONTEXT_TYPE contextType; /* Type of context */ WTX_CONTEXT_ID_T contextId; /* Context ID */ } WTX_MSG_CONTEXT;The result of this request is returned in a WTX_MSG_RESULT message. The val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;For the VxWorks operating system, this request causes a specified task to cease to exist and deallocates the stack and WIND_TCB memory resources. Upon deletion, all routines specified by taskDeleteHookAdd( ) are called in the context of the deleting task.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to destroy the context.
Target only
- WTX_ERR_AGENT_UNSUPPORTED_REQUEST
- Context kill is not supported by the debug agent.
- WTX_ERR_AGENT_INVALID_CONTEXT
- Invalid target system context.
- WTX_ERR_AGENT_NO_RT_PROC
- The target operating system does not support context kill.
- WTX_ERR_AGENT_AGENT_MODE_ERROR
- Attempt to kill a context other than the system context in external mode.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_CONTEXT_CREATE, VxWorks Reference Manual
WTX_CONTEXT_RESUME - WTX resume a context on the target
INPUT: WTX_MSG_CONTEXT OUTPUT: WTX_MSG_RESULT
This request resumes execution of a context on the remote target. The identifier of the context to be resumed is specified by the contextId field in WTX_MSG_CONTEXT.
typedef struct wtx_msg_context /* Context message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_CONTEXT_TYPE contextType; /* Type of context */ WTX_CONTEXT_ID_T contextId; /* Context ID */ } WTX_MSG_CONTEXT;The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;Note that this request is used to resume a just-created context or a context previously suspended by WTX_CONTEXT_SUSPEND. Do not use it to resume a context stopped at a breakpoint because the context simply hits the breakpoint again. A context stopped at a breakpoint is resumed by WTX_CONTEXT_CONT.
After calling this request, the following events can be generated by the target system:
- TEXT_ACCESS
- An instruction fetch occurred at the specified address (breakpoint).
- DATA_ACCESS
- An data access occurred at the specified address.
- EXCEPTION
- The task got an exception (for example, BUS ERROR, ZERO DIVIDE).
- CONTEXT_EXIT
- The task exited via exit( ).
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to resume the context.
Target only
- WTX_ERR_AGENT_UNSUPPORTED_REQUEST
- Context resume is not supported by the debug agent.
- WTX_ERR_AGENT_INVALID_CONTEXT
- Invalid target system context.
- WTX_ERR_AGENT_NO_RT_PROC
- The target operating system does not support context resume.
- WTX_ERR_AGENT_AGENT_MODE_ERROR
- Attempt to resume a context other than the system context in external mode.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_CONTEXT_CREATE, WTX_CONTEXT_SUSPEND, WTX_CONTEXT_CONT, WTX_EVENT_GET, VxWorks Reference Manual
WTX_CONTEXT_STATUS_GET - WTX gets the context of a status on the target
INPUT: WTX_MSG_CONTEXT OUTPUT: WTX_MSG_RESULT
This request returns the status of a context on the remote target. The identifier of the context to get status of is specified by the contextId field in WTX_MSG_CONTEXT.
typedef struct wtx_msg_context /* Context message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_CONTEXT_TYPE contextType; /* Type of context */ WTX_CONTEXT_ID_T contextId; /* Context ID */ } WTX_MSG_CONTEXT;The context status can be either :
- WTX_CONTEXT_RUNNING
- The target context is running.
- WTX_CONTEXT_SUSPENDED
- The target context is suspended.
The context status is returned in a WTX_MSG_RESULT message:
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
The context status is the status at the time the request was made to the target; it might be obsolete by the time it is received by the tool making the request.
This request is implemented only for system mode context, trying to use it for a task mode context will result in a WTX_ERR_AGENT_AGENT_MODE_ERROR error.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or ERROR if communication with the target fails. If errCode is OK, the val field in WTX_MSG_RESULT contains the current context status.
Target only
- WTX_ERR_AGENT_UNSUPPORTED_REQUEST
- Context status get is not supported by the debug agent.
- WTX_ERR_AGENT_INVALID_CONTEXT
- Invalid target system context.
- WTX_ERR_AGENT_NO_RT_PROC
- The target operating system does not support context status get.
- WTX_ERR_AGENT_AGENT_MODE_ERROR
- Attempt to gets the status of a context other than the system context in external mode or attempt to get the status of a task mode context.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_CONTEXT_CREATE, WTX_CONTEXT_SUSPEND, WTX_CONTEXT_CONT
WTX_CONTEXT_STEP - WTX step a context on the target
INPUT: WTX_MSG_CONTEXT_STEP_DESC OUTPUT: WTX_MSG_RESULT
This request steps execution of a context that is stopped at a breakpoint on the remote target. The context to step and the address range to use is specified by:
typedef struct wtx_msg_context_step_desc /* Single step desc. */ { WTX_CORE wtxCore; /* WTX message core */ WTX_CONTEXT context; /* Context to step */ TGT_ADDR_T startAddr; /* Lower bound of step range */ TGT_ADDR_T endAddr; /* Upper bound of step range */ } WTX_MSG_CONTEXT_STEP_DESC;When the startAddr and endAddr fields are set to 0, one instruction is executed.
The context on which WTX_CONTEXT_STEP operates is given in:
typedef struct wtx_context /* Context desc. */ { WTX_CONTEXT_TYPE contextType; /* Type of context */ WTX_CONTEXT_ID_T contextId; /* Context ID */ } WTX_CONTEXT;where contextType can be one of:
typedef enum wtx_context_type /* types of context */ { WTX_CONTEXT_SYSTEM = 0, /* system mode */ WTX_CONTEXT_GROUP = 1, /* process group (not implemented) */ WTX_CONTEXT_ANY = 2, /* any context (not implemented) */ WTX_CONTEXT_TASK = 3, /* specific task or processes */ WTX_CONTEXT_ANY_TASK = 4, /* any task */ WTX_CONTEXT_ISR = 5, /* specific ISR (not implemented) */ WTX_CONTEXT_ISR_ANY = 6 /* any ISR (not implemented) */ } WTX_CONTEXT_TYPE;The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
After calling this request, the following events can be generated by the target system:
- TEXT_ACCESS
- An instruction fetch occurred at the specified address (breakpoint).
- DATA_ACCESS
- A data access occurred at the specified address.
- EXCEPTION
- The task got an exception (for example, BUS ERROR, ZERO DIVIDE).
- CONTEXT_EXIT
- The task exited via exit( ).
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to step the context.
Target only
- WTX_ERR_AGENT_UNSUPPORTED_REQUEST
- Context step is not supported by the debug agent.
- WTX_ERR_AGENT_INVALID_CONTEXT
- Invalid target system context.
- WTX_ERR_AGENT_NO_RT_PROC
- The target operating system does not support context step.
- WTX_ERR_AGENT_AGENT_MODE_ERROR
- Attempt to step in system context while in task mode.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_CONTEXT_CONT, WTX_EVENT_GET
WTX_CONTEXT_SUSPEND - WTX suspend a context on the target
INPUT: WTX_MSG_CONTEXT OUTPUT: WTX_MSG_RESULT
This request suspends a context on the remote target. The identifier of the context to be suspended is specified by the contextId field in WTX_MSG_CONTEXT.
typedef struct wtx_msg_context /* Context message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_CONTEXT_TYPE contextType; /* Type of context */ WTX_CONTEXT_ID_T contextId; /* Context ID */ } WTX_MSG_CONTEXT;The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to suspend the context.
Target only
- WTX_ERR_AGENT_UNSUPPORTED_REQUEST
- Context suspend is not supported by the debug agent.
- WTX_ERR_AGENT_INVALID_CONTEXT
- Invalid target system context.
- WTX_ERR_AGENT_NO_RT_PROC
- The target operating system does not support context suspend.
- WTX_ERR_AGENT_AGENT_MODE_ERROR
- Attempt to suspend a context other than the system context in external mode.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_CONTEXT_CREATE, WTX_CONTEXT_RESUME, VxWorks Reference Manual
WTX_DIRECT_CALL - WTX call a function on the target within the agent
INPUT: WTX_MSG_CONTEXT_DESC OUTPUT: WTX_MSG_RESULT
This request calls a function specified by the entry field in WTX_MSG_CONTEXT_DESC with its arguments, args, on the remote target.
typedef struct wtx_msg_context_desc /* Context creation desc. */ { WTX_CORE wtxCore; /* WTX message core */ WTX_CONTEXT_TYPE contextType; /* Type of context */ WTX_RETURN_TYPE returnType; /* Int or double */ char * name; /* Task name */ UINT32 priority; /* Task priority */ UINT32 options; /* Task options */ TGT_ADDR_T stackBase; /* Base of stack */ UINT32 stackSize; /* Stack size */ TGT_ADDR_T entry; /* Context entry point */ INT32 redirIn; /* Redir. in file or 0 */ INT32 redirOut; /* Redir. out file or 0 */ TGT_ARG_T args[WTX_MAX_ARG_CNT]; /* Arguments */ void * pReserved; /* Reserved */ } WTX_MSG_CONTEXT_DESC;Only the entry and the passed argument fields (args[0]...args[9]) of WTX_MSG_CONTEXT_DESC are needed. The other fields are set to NULL.
This request calls the function in the debug agent context and waits for the function to return.
User Shell Target Server Debug Agent func WTX_DIRECT_CALL -------> | WDB_DIRECT_CALL -----------> | execute func | <--------------------- | <------------------- | get return valueThe function call parameters are passed through a WTX_MSG_CONTEXT_DESC structure. Strings or structure parameters can be passed to functions by previously allocating a block of memory on the target via WTX_MEM_ALLOC and filling this memory block with the string or structure value using WTX_MEM_WRITE.The result of this request is returned in the val field of a WTX_MSG_RESULT message with the type V_UINT32.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to call the function on the target. If errCode is OK, the val field in WTX_MSG_RESULT contains the function return value.
Target and target server
The maximum number of arguments that can be passed to a function is 10, and is stored in WTX_MAX_ARG_CNT.
- WTX_ERR_AGENT_UNSUPPORTED_REQUEST
- Function calling is not supported by the target agent.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_EVENTPOINT_ADD - WTX add an eventpoint
INPUT: WTX_MSG_EVTPT_DESC OUTPUT: WTX_MSG_RESULT
This request adds an eventpoint to one or more contexts. This request is a generic facility for setting breakpoints. An eventpoint specifies the context to which it applies, the type of event to detect (for example data access, breakpoint), and the action to be taken upon detection of the event (for example, notify the target server of the event).
The associated message is:
typedef struct wtx_msg_evtpt_desc /* Eventpoint message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_EVTPT wtxEvtpt; /* Eventpoint */ } WTX_MSG_EVTPT_DESC;The eventpoint parameters are grouped into the structure:
typedef struct wtx_evtpt /* Eventpoint desc. */ { WTX_EVENT event; /* Event to detect */ WTX_CONTEXT context; /* Context descriptor */ WTX_ACTION action; /* Action to perform */ } WTX_EVTPT;where WTX_EVENT is:
typedef struct wtx_event /* Target event */ { WTX_EVENT_TYPE eventType; /* Type of event */ TGT_ARG_T eventArg; /* Event type dependent arg */ } WTX_EVENT;The event types are given by:
WTX_EVENT_CTX_START = 1 /* A target context was created */ WTX_EVENT_CTX_EXIT = 2 /* A target context was deleted */ WTX_EVENT_TEXT_ACCESS = 3 /* A target text access (breakpoint) */The eventArg field is specific to each eventType. WTX_EVENT_TEXT_ACCESS has eventArg equal to the desired address. WDB_EVT_CTX_EXIT and WDB_EVT_CTX_START do not use this field.where WTX_CONTEXT is:
typedef struct wtx_context /* Context desc. */ { WTX_CONTEXT_TYPE contextType; /* Type of context */ WTX_CONTEXT_ID_T contextId; /* Context ID */ } WTX_CONTEXT;The context types are given by:
typedef enum wtx_context_type /* types of context */ { WTX_CONTEXT_SYSTEM = 0, /* system mode */ WTX_CONTEXT_GROUP = 1, /* process group (not implemented) */ WTX_CONTEXT_ANY = 2, /* any context (not implemented) */ WTX_CONTEXT_TASK = 3, /* specific task or processes */ WTX_CONTEXT_ANY_TASK = 4, /* any task */ WTX_CONTEXT_ISR = 5, /* specific ISR (not implemented) */ WTX_CONTEXT_ISR_ANY = 6 /* any ISR (not implemented) */ } WTX_CONTEXT_TYPE;where WTX_ACTION is:
typedef struct wtx_action /* Action descriptor */ { WTX_ACTION_TYPE actionType; /* Action type to perform */ UINT32 actionArg; /* Action dependent argument */ TGT_ADDR_T callRtn; /* Function to ACTION_CALL */ TGT_ARG_T callArg; /* Function argument */ } WTX_ACTION;The action types are given by WTX_ACTION_TYPE and can be or'ed together if multiple actions are needed:
typedef enum wtx_action_type /* type of actions */ { WTX_ACTION_CALL = 1, /* Call a function */ WTX_ACTION_NOTIFY = 2, /* Post the event to the host */ WTX_ACTION_STOP = 4, /* Stop the context */ WTX_ACTION_STOP_ALL = 8 /* not implemented */ } WTX_ACTION_TYPE;The request result is an eventpoint number (type V_UINT32) attributed by the target server and returned in the structure:
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
After calling this request, the following events can be generated by the target system:
- TEXT_ACCESS
- An instruction fetch occurred at the specified address (breakpoint).
- DATA_ACCESS
- A data access occurred at the specified address (watchpoint).
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to add the eventpoint. If errCode is OK, the val field in WTX_MSG_RESULT returns an eventpoint number that is used to refer to that eventpoint.
Target and target server
There is a maximum number of eventpoints that can be set on the target system. This number is defined when the target system is configured and is 50 by default.
This request is replaced by WTX_EVENT_POINT_ADD_2 and will be removed in the next Tornado release.
- WTX_ERR_AGENT_UNSUPPORTED_REQUEST
- Eventpoint add is not supported by the debug agent.
- WTX_ERR_AGENT_INVALID_CONTEXT
- Invalid target system context.
- WTX_ERR_AGENT_INVALID_EVENT
- Invalid eventpoint type.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the target server to store the eventpoint.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_EVENTPOINT_DELETE, WTX_EVENTPOINT_LIST
WTX_EVENTPOINT_ADD_2 - WTX add an eventpoint
INPUT: WTX_MSG_EVTPT_DESC_2 OUTPUT: WTX_MSG_RESULT
This request adds an eventpoint to one or more contexts. This request is a generic facility for setting breakpoints. An eventpoint specifies the context to which it applies, the type of event to detect (for example data access, breakpoint), and the action to be taken upon detection of the event (for example, notify the target server of the event).
The associated message is:
typedef struct wtx_msg_evtpt_desc_2 /* Eventpoint message version 2 */ { WTX_CORE wtxCore; /* WTX message core */ WTX_EVTPT_2 wtxEvtpt; /* Eventpoint version 2 */ } WTX_MSG_EVTPT_DESC_2;The eventpoint parameters are grouped into the structure:
typedef struct wtx_evtpt_2 /* Eventpoint desc. version 2 */ { WTX_EVENT_2 event; /* Event to detect version 2 */ WTX_CONTEXT context; /* Context descriptor */ WTX_ACTION action; /* Action to perform */ } WTX_EVTPT_2;where WTX_EVENT_2 is:
typedef struct wtx_event_2 /* Target event version 2 */ { WTX_EVENT_TYPE eventType; /* type of event */ UINT32 numArgs; /* Number of arguments */ TGT_ARG_T * args; /* List of arguments */ } WTX_EVENT_2;The event types are given by:
WTX_EVENT_CTX_START = 1 /* A target context was created */ WTX_EVENT_CTX_EXIT = 2 /* A target context was deleted */ WTX_EVENT_TEXT_ACCESS = 3 /* A target text access (breakpoint) */ WTX_EVENT_HW_BP = 7 /* A target hardware breakpoint */The eventArg and numArgs fields are specific to each eventType. WTX_EVENT_TEXT_ACCESS has numArgs equal to 1 or 2, args[0] equal to the desired address and args[1] (optional) equal to the breakpoint count. WTX_EVENT_HW_BP has numArgs equal to 3, args[0] equal to the desired address, args[1] equal to the breakpoint count and args[2] equal to the hardware breakpoint access type. All other event types have numArgs equal to zero.WTX_EVENT_HW_BP is supported only on a few architectures (Intel i86, i960JX, i960CX, i960HX, IBM PPC403, Motorola PPC603, PPC604, PPC8xx and Mips R4650). For each of those architectures, the hardware breakpoint access type can accept different values.
Intel i960 processors : args[3] | access type | 0 | data store only 1 | data only (load/store) 2 | data/instruction fetch 3 | any access 4 | instruction Intel i86 processors : args[3] | access type | 0 | instruction 1 | data write (one byte width *) 3 | data read/write (one byte width *) 5 | data write (two bytes width *) 7 | data read/write (two bytes width *) 0xd | data write (four bytes width *) 0xf | data read/write (four bytes width *) * "x bytes width" means break on all accesses between (addr) and (addr + x) IBM PPC403 processor : args[3] | access type | 0 | instruction 1 | data write byte (one byte width *) 2 | data read byte (one byte width *) 3 | data read/write byte (one byte width *) 5 | data write half-word (two bytes width *) 6 | data read half-word (two bytes width *) 7 | data read/write half-word (two bytes width *) 9 | data write word (four bytes width *) 0xa | data read word (four bytes width *) 0xb | data read/write word (four bytes width *) 0xd | data write quad-word (sixteen bytes width *) 0xe | data read quad-word (sixteen bytes width *) 0xf | data read/write quad-word (sixteen bytes width *) * "x bytes width" means break on all accesses between (addr) and (addr + x) Motorola PPC603 processor : args[3] | access type | 0 | instruction Motorola PPC604 and PPC8xx processors : args[3] | access type | 0 | instruction 1 | data read/write 2 | data read 3 | data write Mips R4650 processor : args[3] | access type | 0 | instruction 1 | data write 2 | data read 3 | data read/writewhere WTX_CONTEXT is:
typedef struct wtx_context /* Context desc. */ { WTX_CONTEXT_TYPE contextType; /* Type of context */ WTX_CONTEXT_ID_T contextId; /* Context ID */ } WTX_CONTEXT;The context types are given by:
typedef enum wtx_context_type /* types of context */ { WTX_CONTEXT_SYSTEM = 0, /* system mode */ WTX_CONTEXT_GROUP = 1, /* process group (not implemented) */ WTX_CONTEXT_ANY = 2, /* any context (not implemented) */ WTX_CONTEXT_TASK = 3, /* specific task or processes */ WTX_CONTEXT_ANY_TASK = 4, /* any task */ WTX_CONTEXT_ISR = 5, /* specific ISR (not implemented) */ WTX_CONTEXT_ISR_ANY = 6 /* any ISR (not implemented) */ } WTX_CONTEXT_TYPE;where WTX_ACTION is:
typedef struct wtx_action /* Action descriptor */ { WTX_ACTION_TYPE actionType; /* Action type to perform */ UINT32 actionArg; /* Action dependent argument */ TGT_ADDR_T callRtn; /* Function to ACTION_CALL */ TGT_ARG_T callArg; /* Function argument */ } WTX_ACTION;The action types are given by WTX_ACTION_TYPE and can be or'ed together if multiple actions are needed:
typedef enum wtx_action_type /* type of actions */ { WTX_ACTION_CALL = 1, /* Call a function */ WTX_ACTION_NOTIFY = 2, /* Post the event to the host */ WTX_ACTION_STOP = 4, /* Stop the context */ WTX_ACTION_STOP_ALL = 8 /* not implemented */ } WTX_ACTION_TYPE;The request result is an eventpoint number (type V_UINT32) attributed by the target server and returned in the structure:
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
After calling this request, the following events can be generated by the target system:
- TEXT_ACCESS
- An instruction fetch occurred at the specified address (breakpoint).
- DATA_ACCESS
- A data access occurred at the specified address (watchpoint).
- WTX_EVENT_CTX_START
- A target context was created
- WTX_EVENT_CTX_EXIT
- A target context was deleted
After calling this request, the following event is always generated by the target server:
- EVTPT_ADDED
- An event point had been added.
The event string format is the following:
EVTPT_ADDED: WTX event,
value #1 : event point identifier,
value #2 : context type,
value #3 : context identifier,
value #4 : action type,
value #5 : action arg,
value #6 : call routine,
value #7 : call argument,
value #8 : event type,
value #9 : number of arguments,
value #10 : first argument,
...
value #n : last argument.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to add the eventpoint. If errCode is OK, the val field in WTX_MSG_RESULT returns an eventpoint number that is used to refer to that eventpoint.
Target and target server
There is a maximum number of eventpoints that can be set on the target system. This number is defined when the target system is configured and is 50 by default.
There is as well a maximum number of hardware breakpoints that can be set on the target system. This limit is a hardware limit and can't be changed (two data breakpoints and two instruction breakpoints for i960 targets, four hardware breakpoints for i86 targets, two data breakpoints and two instruction breakpoints for PPC403 targets, one instruction breakpoint for Motorola PPC603 targets, one instruction breakpoint and one data breakpoint for PPC604 targets, two data breakpoints and four instruction breakpoints for Motorola PPC8xx targets, one instruction breakpoint and one data breakpoint for Mips R4650 targets).
The address parameter of a hardware breakpoint command must be 4-bytes aligned, except for data breakpoints on i86, IBM PPC403 and Motorola PPC8xx processors. On i86 and IBM PPC403 processors, the address parameter is 1 byte aligned if width access is 1 byte, 2 bytes aligned if width access is 2 bytes and 4 bytes aligned if width access is 4 bytes. On IBM PPC403 processors only, the address is 16 bytes aligned if width access is 16 bytes. On Motorola PPC8xx processors, the address parameter is 1 byte aligned.
- WTX_ERR_AGENT_UNSUPPORTED_REQUEST
- Eventpoint add is not supported by the debug agent.
- WTX_ERR_AGENT_INVALID_CONTEXT
- Invalid target system context.
- WTX_ERR_AGENT_INVALID_EVENT
- Invalid eventpoint type.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the target server to store the eventpoint.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- WTX_ERR_AGENT_HW_BP_REGS_EXHAUSTED
- Target hardware breakpoint registers are exhausted.
- TIMEOUT
- WTX RPC timeout.
WTX_EVENTPOINT_DELETE - WTX delete an eventpoint
INPUT: WTX_MSG_PARAM OUTPUT: WTX_MSG_RESULT
This request deletes the eventpoint previously added by WTX_EVENTPOINT_ADD and specified by the number in the param field of WTX_MSG_PARAM.
typedef struct wtx_msg_param /* Simple request parameter */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE param; /* Param value of call */ } WTX_MSG_PARAM;Note that param.valueType is set to V_UINT32.
The result of this request is returned in a WTX_MSG_RESULT message. The val field is not used and is always set to NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
After calling this request, the following event is always generated by the target server:
- EVTPT_DELETED
- An event point had been deleted.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to delete the eventpoint.
Target and target server
- WTX_ERR_AGENT_NO_SUCH_EVENTPOINT
- The specified eventpoint does not exist.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_EVENTPOINT_ADD, WTX_EVENTPOINT_LIST
WTX_EVENTPOINT_LIST - WTX return a list of eventpoints
INPUT: WTX_MSG_TOOL_ID OUTPUT: WTX_MSG_EVTPT_LIST
This request returns the list of eventpoints set on the target system.
The tool making the request sends its identifier in:
typedef struct wtx_msg_tool_id /* Tool identifier message */ { WTX_CORE wtxCore; /* WTX message core */ } WTX_MSG_TOOL_ID;The output of this request is a message containing a table of eventpoints:
typedef struct wtx_msg_evtpt_list /* Eventpoint list message */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 nEvtpt; /* Num. eventpoint in list */ WTX_EVTPT * pEvtpt; /* Eventpoint list */ } WTX_MSG_EVTPT_LIST;Each eventpoint is defined by:
typedef struct wtx_evtpt /* Eventpoint desc. */ { WTX_EVENT event; /* Event to detect */ WTX_CONTEXT context; /* Context descriptor */ WTX_ACTION action; /* Action to perform */ } WTX_EVTPT;where WTX_EVENT is:
typedef struct wtx_event /* Target event */ { WTX_EVENT_TYPE eventType; /* Type of event */ TGT_ARG_T eventArg; /* Event type dependent arg */ } WTX_EVENT;The event types are given by:
typedef enum wtx_event_type { WTX_EVENT_NONE = 0, /* No event */ WTX_EVENT_CTX_START = 1, /* A target context was created */ WTX_EVENT_CTX_EXIT = 2, /* A target context was deleted */ WTX_EVENT_TEXT_ACCESS = 3, /* A target text access (breakpoint) */ WTX_EVENT_DATA_ACCESS = 4, /* A target data access (watchpoint) */ WTX_EVENT_EXCEPTION = 5, /* A target exception occurred */ WTX_EVENT_VIO_WRITE = 6, /* A target VIO write occurred */ WTX_EVENT_HW_BP = 7, /* A target breakpoint: obsolete, use */ /* WTX_EVENT_TEXT_ACCESS instead */ WTX_EVENT_CALL_RETURN = 8, /* A target function call returned */ WTX_EVENT_USER = 9, /* A target agent user defined event */ WTX_EVENT_UNKNOWN = 10, /* An unknown target event */ WTX_EVENT_TGT_RESET = 11, /* The target was reset */ WTX_EVENT_SYM_ADDED = 12, /* A symbol added to the sym. table */ WTX_EVENT_SYM_REMOVED = 13, /* A symbol removed from the sym tabl */ WTX_EVENT_OBJ_LOADED = 14, /* An object file was loaded */ WTX_EVENT_OBJ_UNLOADED = 15, /* An object file was unloaded */ WTX_EVENT_TOOL_ATTACH = 16, /* A tool attached to Target Server */ WTX_EVENT_TOOL_DETACH = 17, /* A tool detached from Target Server */ WTX_EVENT_TOOL_MSG = 18, /* A tool to tool message */ WTX_EVENT_TS_KILLED = 19, /* The target server was reset */ WTX_EVENT_EVTPT_ADDED = 20, /* A new event point is added */ WTX_EVENT_EVTPT_DELETED= 21, /* An event point had been deleted */ WTX_EVENT_OTHER = 0x100, /* User defined or unrecognized event */ WTX_EVENT_INVALID = WTX_ERROR /* Invalid/unidentifiable event */ } WTX_EVENT_TYPE;where WTX_CONTEXT is:
typedef struct wtx_context /* Context desc. */ { WTX_CONTEXT_TYPE contextType; /* Type of context */ WTX_CONTEXT_ID_T contextId; /* Context ID */ } WTX_CONTEXT;The context types are given by:
typedef enum wtx_context_type /* types of context */ { WTX_CONTEXT_SYSTEM = 0, /* system mode */ WTX_CONTEXT_GROUP = 1, /* process group (not implemented) */ WTX_CONTEXT_ANY = 2, /* any context (not implemented) */ WTX_CONTEXT_TASK = 3, /* specific task or processes */ WTX_CONTEXT_ANY_TASK = 4, /* any task */ WTX_CONTEXT_ISR = 5, /* specific ISR (not implemented) */ WTX_CONTEXT_ISR_ANY = 6 /* any ISR (not implemented) */ } WTX_CONTEXT_TYPE;where WTX_ACTION is:
typedef struct wtx_action /* Action descriptor */ { WTX_ACTION_TYPE actionType; /* Action type to perform */ UINT32 actionArg; /* Action dependent argument */ TGT_ADDR_T callRtn; /* Function to ACTION_CALL */ TGT_ARG_T callArg; /* Function argument */ } WTX_ACTION;The action types are given by:
typedef enum wtx_action_type /* type of actions */ { WTX_ACTION_CALL = 1, /* Call a function */ WTX_ACTION_NOTIFY = 2, /* Post the event to the host */ WTX_ACTION_STOP = 4, /* Stop the context */ WTX_ACTION_STOP_ALL = 8 /* not implemented */ } WTX_ACTION_TYPE;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to return the eventpoint list.
Target server only
There is a maximum number of eventpoints that can be set on the target system. This number is defined when the target system is configured and is 50 by default. The greatest number of eventpoints that can be returned by this request is WTX_MAX_EVTPT_CNT (256) defined in wtxtypes.h.
This request is replaced by WTX_EVENTPOINT_LIST_GET and will be removed in the next Tornado release.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the target server to store the eventpoint list.
- TIMEOUT
- WTX RPC timeout.
WTX_EVENTPOINT_ADD, WTX_EVENTPOINT_DELETE
WTX_EVENTPOINT_LIST_GET - WTX return a list of eventpoints
INPUT: WTX_MSG_TOOL_ID OUTPUT: WTX_MSG_EVTPT_LIST_2
This request returns the list of eventpoints set on the target system.
The tool making the request sends its identifier in:
typedef struct wtx_msg_tool_id /* Tool identifier message */ { WTX_CORE wtxCore; /* WTX message core */ } WTX_MSG_TOOL_ID;The output of this request is a message containing a table of eventpoints:
typedef struct wtx_msg_evtpt_list_2 /* Eventpoint list message */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 nEvtpt; /* Num. eventpoint in list */ WTX_EVTPT_INFO * pEvtptInfo; /* Eventpoint info list */ } WTX_MSG_EVTPT_LIST_2;Each eventpoint is defined by:
typedef struct wtx_evtpt_2 /* Eventpoint desc. version 2 */ { WTX_EVENT_2 event; /* Event to detect version 2 */ WTX_CONTEXT context; /* Context descriptor */ WTX_ACTION action; /* Action to perform */ } WTX_EVTPT_2;where WTX_EVENT_2 is:
typedef struct wtx_event_2 /* Target event version 2 */ { WTX_EVENT_TYPE eventType; /* type of event */ UINT32 numArgs; /* Number of arguments */ TGT_ARG_T * args; /* List of arguments */ } WTX_EVENT_2;The event types are given by:
typedef enum wtx_event_type { WTX_EVENT_NONE = 0, /* No event */ WTX_EVENT_CTX_START = 1, /* A target context was created */ WTX_EVENT_CTX_EXIT = 2, /* A target context was deleted */ WTX_EVENT_TEXT_ACCESS = 3, /* A target text access (breakpoint) */ WTX_EVENT_DATA_ACCESS = 4, /* A target data access (watchpoint) */ WTX_EVENT_EXCEPTION = 5, /* A target exception occurred */ WTX_EVENT_VIO_WRITE = 6, /* A target VIO write occurred */ WTX_EVENT_HW_BP = 7, /* A target breakpoint: obsolete, use */ /* WTX_EVENT_TEXT_ACCESS instead */ WTX_EVENT_CALL_RETURN = 8, /* A target function call returned */ WTX_EVENT_USER = 9, /* A target agent user defined event */ WTX_EVENT_UNKNOWN = 10, /* An unknown target event */ WTX_EVENT_TGT_RESET = 11, /* The target was reset */ WTX_EVENT_SYM_ADDED = 12, /* A symbol added to the sym. table */ WTX_EVENT_SYM_REMOVED = 13, /* A symbol removed from the sym tabl */ WTX_EVENT_OBJ_LOADED = 14, /* An object file was loaded */ WTX_EVENT_OBJ_UNLOADED = 15, /* An object file was unloaded */ WTX_EVENT_TOOL_ATTACH = 16, /* A tool attached to Target Server */ WTX_EVENT_TOOL_DETACH = 17, /* A tool detached from Target Server */ WTX_EVENT_TOOL_MSG = 18, /* A tool to tool message */ WTX_EVENT_TS_KILLED = 19, /* The target server was reset */ WTX_EVENT_EVTPT_ADDED = 20, /* A new event point is added */ WTX_EVENT_EVTPT_DELETED= 21, /* An event point had been deleted */ WTX_EVENT_OTHER = 0x100, /* User defined or unrecognized event */ WTX_EVENT_INVALID = WTX_ERROR /* Invalid/unidentifiable event */ } WTX_EVENT_TYPE;where WTX_CONTEXT is:
typedef struct wtx_context /* Context desc. */ { WTX_CONTEXT_TYPE contextType; /* Type of context */ WTX_CONTEXT_ID_T contextId; /* Context ID */ } WTX_CONTEXT;The context types are given by:
typedef enum wtx_context_type /* types of context */ { WTX_CONTEXT_SYSTEM = 0, /* system mode */ WTX_CONTEXT_GROUP = 1, /* process group (not implemented) */ WTX_CONTEXT_ANY = 2, /* any context (not implemented) */ WTX_CONTEXT_TASK = 3, /* specific task or processes */ WTX_CONTEXT_ANY_TASK = 4, /* any task */ WTX_CONTEXT_ISR = 5, /* specific ISR (not implemented) */ WTX_CONTEXT_ISR_ANY = 6 /* any ISR (not implemented) */ } WTX_CONTEXT_TYPE;where WTX_ACTION is:
typedef struct wtx_action /* Action descriptor */ { WTX_ACTION_TYPE actionType; /* Action type to perform */ UINT32 actionArg; /* Action dependent argument */ TGT_ADDR_T callRtn; /* Function to ACTION_CALL */ TGT_ARG_T callArg; /* Function argument */ } WTX_ACTION;The action types are given by:
typedef enum wtx_action_type /* type of actions */ { WTX_ACTION_CALL = 1, /* Call a function */ WTX_ACTION_NOTIFY = 2, /* Post the event to the host */ WTX_ACTION_STOP = 4, /* Stop the context */ WTX_ACTION_STOP_ALL = 8 /* not implemented */ } WTX_ACTION_TYPE;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to return the eventpoint list.
Target server only
There is a maximum number of eventpoints that can be set on the target system. This number is defined when the target system is configured and is 50 by default. The greatest number of eventpoints that can be returned by this request is WTX_MAX_EVTPT_CNT (256) defined in wtxtypes.h.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the target server to store the eventpoint list.
- TIMEOUT
- WTX RPC timeout.
WTX_EVENTPOINT_LIST_2
WTX_EVENT_ADD - WTX add an event
INPUT: WTX_MSG_EVENT_DESC OUTPUT: WTX_MSG_RESULT
This request adds an event to the target server tools event list. Only the tools that have registered for the type of event added receive the event. This request can also be used to exchange data between tools. By convention, messages sent between tools start with "TOOL_MSG". For example, a tool message can consist of a Tcl program that can be interpreted by the receiving tool.
The input message is:
typedef struct wtx_msg_event_desc /* Event message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_EVENT_DESC eventDesc; /* Event descriptor */ } WTX_MSG_EVENT_DESC;where WTX_EVENT_DESC is:
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;The event is a string passed in the event field. When additional data are present, such as virtual I/O data sent by the target, addlDataLen contains the number of additional data bytes and addlData points to a buffer containing the data.
The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
All
To send the event "TOOL_MSG hello world", do the following:
/* clear message */ memset ((void *) &wtxMsgEventDesc, 0, sizeof (wtxMsgEventDesc)); /* set event to add */ wtxMsgEventDesc.eventDesc.event = "TOOL_MSG hello world";
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to add the event.
Target server only
The maximum length of an event string is 300 characters.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the target server to add the event.
- TIMEOUT
- WTX RPC timeout.
WTX_EVENT_GET, WTX_REGISTER_FOR_EVENT
WTX_EVENT_GET - WTX get an event
INPUT: WTX_MSG_TOOL_ID OUTPUT: WTX_MSG_EVENT_DESC
This request returns the first available event from the target server event list for the calling tool given in WTX_MSG_TOOL_ID. This request is used by tools to poll the target server for events occurring on the target system and events related to other tools' activities.
The tool making the request sends its identifier in wtxCore.objId.
typedef struct wtx_msg_tool_id /* Tool identifier message */ { WTX_CORE wtxCore; /* WTX message core */ } WTX_MSG_TOOL_ID;The event is a string returned in the WTX_MSG_EVENT_DESC message. The addlDataLen field contains the size and the addlData field contains a pointer to additional data sent by the target in the case of a VIO_WRITE event. The event message is:
typedef struct wtx_msg_event_desc /* Event message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_EVENT_DESC eventDesc; /* Event descriptor */ } WTX_MSG_EVENT_DESC;where WTX_EVENT_DESC is:
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;
All
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to get the event. When errCode is OK, the event field in WTX_EVENT_DESC is the event-string address if an event was available or NULL if no events were present for that tool.
Target server only
The maximum length of the virtual I/O data buffer, WTX_MAX_VIO_DATA, is 512 bytes.
- WTX_ERR_SVR_INVALID_CLIENT_ID
- The tool is not attached to the target server.
- TIMEOUT
- WTX RPC timeout.
WTX_REGISTER_FOR_EVENT, WTX_EVENT_ADD
WTX_EVENT_LIST_GET - WTX get all the events in one call
INPUT: WTX_MSG_TOOL_ID OUTPUT: WTX_MSG_EVENT_LIST
This request returns all available events from the target server event list for the calling tool given in WTX_MSG_TOOL_ID.
The tool making the request sends its identifier in wtxCore.objId.
typedef struct wtx_msg_tool_id /* Tool identifier message */ { WTX_CORE wtxCore; /* WTX message core */ } WTX_MSG_TOOL_ID;The events are returned in the WTX_MSG_EVENT_LIST message bellow:
typedef struct wtx_msg_event_list /* Message for all events */ { WTX_CORE wtxCore; /* WTX message core */ WTX_EVENT_NODE * pEventList; /* List of events */ } WTX_MSG_EVENT_LIST;WTX_MSG_EVENT_LIST contains a pointer to a single linked list of events:
typedef struct wtx_event_node /* WTX event node desc. */ { struct wtx_event_desc event; /* Event descriptor */ struct wtx_event_node * pNext; /* ptr to the next event */ } WTX_EVENT_NODE;Each event is described by the structure:
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;
All
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to get the event. When errCode is OK, the event field in WTX_EVENT_DESC is the event-string address if an event was available. If there's no event, pEventList is NULL.
Target server only
- WTX_ERR_SVR_INVALID_CLIENT_ID
- The tool is not attached to the target server.
- TIMEOUT
- WTX RPC timeout.
WTX_FUNC_CALL - WTX call a function on the target
INPUT: WTX_MSG_CONTEXT_DESC OUTPUT: WTX_MSG_RESULT
This request calls a function specified by the entry field in WTX_MSG_CONTEXT_DESC with its arguments, args, on the remote target.
typedef struct wtx_msg_context_desc /* Context creation desc. */ { WTX_CORE wtxCore; /* WTX message core */ WTX_CONTEXT_TYPE contextType; /* Type of context */ WTX_RETURN_TYPE returnType; /* Int or double */ char * name; /* Task name */ UINT32 priority; /* Task priority */ UINT32 options; /* Task options */ TGT_ADDR_T stackBase; /* Base of stack */ UINT32 stackSize; /* Stack size */ TGT_ADDR_T entry; /* Context entry point */ INT32 redirIn; /* Redir. in file or 0 */ INT32 redirOut; /* Redir. out file or 0 */ TGT_ARG_T args[WTX_MAX_ARG_CNT]; /* Arguments */ void * pReserved; /* Reserved */ } WTX_MSG_CONTEXT_DESC;The type of the function return value must be specified in returnType. The possible return value types are given by:
typedef enum wtx_return_type /* return value type */ { WTX_RETURN_TYPE_INT = 0, /* integer return format */ WTX_RETURN_TYPE_DOUBLE = 1 /* double return format */ } WTX_RETURN_TYPE;Only the entry and the passed arguments (args[0]...args[9]) are needed; all the other parameters are optional and have the following default values when not specified:
- name
- t[num] (for example, t56)
- priority
- 4 (lower than the target-agent task priority in task mode)
- options
- no options
- stackBase
- the stack is allocated from the system memory pool
- stackSize
- the architecture-dependent default stack size
- redirIn
- 0 (stdin)
- redirOut
- 1 (stdout)
The reserved parameter pReserved is set to NULL.
The calling scheme used depends on the availability of a multi-tasking operating system on the target.
For target systems with multi-tasking operating systems, WTX_FUNC_CALL does not wait for the function to return; instead it returns immediately. The return value of the request, the val field in the WTX_MSG_RESULT message, is the context ID of the context used to call the function. Future references to this function call (call return or exception) specify this context ID. The return value of the called routine can be obtained via WTX_EVENT_GET, which returns a CALL_RETURN event.
The function-call scenario in task mode looks like this:
User Shell Target Server Debug Agent OS func() WTX_FUNC_CALL ---------> | WDB_FUNC_CALL -------------> | init task resume task return context ID | <--------------------- run function | . return context ID . | . <------------------- . | . WTX_EVENT_GET function (poll) exit | notify return <----- | get target event <------------ | get return event <---------- check context ID | get return valueFor target systems without multi-tasking, WTX_FUNC_CALL executes the function in the debug-agent context and waits for the function to return. In this case the val field in WTX_MSG_RESULT contains the function return value.The function-call scenario in debug-agent mode looks like this:
User Shell Target Server Debug Agent OS func WTX_FUNC_CALL ---------> | WDB_FUNC_CALL -------------> | execute func | <--------------------- | <------------------- | get return valueThe function-call parameters are passed through a WTX_MSG_CONTEXT_DESC structure. Strings or structure parameters can be passed to functions by previously allocating a block of memory on the target via WTX_MEM_ALLOC and filling this memory block with the string or structure value using WTX_MEM_WRITE.The result of this request is returned in the val field of a WTX_MSG_RESULT message with the type V_UINT32.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
After calling this request, the following events can be generated by the target system:
- CALL_RETURN
- The function has returned and the event contains the function return value and the errno value for the call. This event is announced to all tools.
- TEXT_ACCESS
- An instruction fetch occurred at the specified address while executing the function. This event is also known as "breakpoint".
- DATA_ACCESS
- A data access occurred at the specified address while executing the function. This event is also known as "watchpoint".
- EXCEPTION
- The function call associated with the task got an exception (for example, BUS ERROR, ZERO DIVIDE).
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to call the function on the target. If errCode is OK, the val field in WTX_MSG_RESULT contains the context identifier in which the function call is executed, for multi-tasking target systems. val contains the function return value for other targets.
Target and target server
The maximum number of arguments that can be passed to a function is 10 in task mode and 5 in system mode. It is stored in WTX_MAX_ARG_CNT.
- WTX_ERR_SVR_INVALID_CLIENT_ID
- The tool not attached to the target server.
- WTX_ERR_AGENT_UNSUPPORTED_REQUEST
- Function calling is not supported by the target agent.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the target server.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_EVENT_GET, WTX_MEM_WRITE, WTX_DIRECT_CALL
WTX_GOPHER_EVAL - WTX evaluate a Gopher program
INPUT: WTX_MSG_PARAM OUTPUT: WTX_MSG_GOPHER_TAPE
Gopher is a small, interpreted language that allows the traversal of simple data structures in target memory. This request sends the specified Gopher program to the target for evaluation and returns the result of the evaluation in a Gopher tape. The contents of the target memory specified by the Gopher program are written to the tape.
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 host tool.
The Gopher program is sent to the target server via a string pointed to by param. The valueType of param is set to V_PCHAR which equals 8. (See .../host/include/wtxmsg.h.)
typedef struct wtx_msg_param /* Simple request parameter */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE param; /* Param value of call */ } WTX_MSG_PARAM;The result of the Gopher program execution is returned in the message:
typedef struct WTX_MSG_GOPHER_TAPE /* Gopher tape message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_GOPHER_TAPE tape; /* Gopher tape */ } WTX_MSG_GOPHER_TAPE;which contains the embedded structure:
typedef struct wtx_gopher_tape /* Gopher tape */ { UINT16 len; /* Length of tape */ char * data; /* Tape data */ } WTX_GOPHER_TAPE;The result of the evaluation is contained in tape.data and its length is returned in tape.len.
The Gopher result tape is a byte-packed (opaque) data stream. The data is a series of pairs, each consisting of a type code and its associated data. The type codes are defined in the file .../wpwr/share/src/agents/wdb/wdb.h as follows:
/* gopher stream format type codes */ #define GOPHER_UINT32 0 #define GOPHER_STRING 1 #define GOPHER_UINT16 2 #define GOPHER_UINT8 3 #define GOPHER_FLOAT32 4 #define GOPHER_FLOAT64 5 #define GOPHER_FLOAT80 6The tape is formatted as follows:
+------+ +--> | 0 | | +------+ | | 0xff | <--+ | +------+ | | | 0x1a | <--+ | +------+ | UINT32 | | 0x32 | <--+ | +------+ | | | 0x0d | <--+ | +------+ type +--> | 1 | codes | +------+ | | 'H' | <--+ | +------+ | | | 'i' | <--+ | +------+ | | | 'J' | <--+ STRING | +------+ | | | 'i' | <--+ | +------+ | | | 'm' | <--+ | +------+ | | | NULL | <--+ | +------+ +--> | 3 | +------+ | 0xc3 | <--+ UINT8 +------+ | etc. | | | | | v |The Tcl and C APIs handle this result tape differently. See the API Reference Manual: WTX Tcl Library and WTX C Library.
The following table shows the elements of a Gopher string and their actions on the pointer and the tape:
Item Action ------------- ----------------------------------------- integer Sets the pointer to the value. [+-]integer Increments or decrements the pointer. ! Writes the pointer to the tape. * Replaces the pointer with the value pointed to by the pointer. @[bwl] Writes the value pointed to by the pointer on the tape, and advances the pointer. The `b', `w', or `l' flags may be specified to indicate that an 8-, 16-, or 32-bit value should be written to the tape. The pointer is advanced by the size of the element written. If no flag is given, `l' is assumed. $ The string pointed to by the pointer is written on the tape. {...} The gopher string inside the braces is repeatedly executed while the pointer is not zero. Upon completion, the original pointer value is undisturbed (the string inside the braces works with a local copy of the pointer). <...> The gopher string inside the angle brackets is executed once using a local copy of the pointer. (n ...) The gopher string ... is executed n times, using a local copy of the pointer.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to execute the Gopher program.
Target only
The maximum length of the Gopher tape is 1500 bytes.
- WTX_ERR_AGENT_GOPHER_FAULT
- Evaluating the string results in a read of unavailable memory.
- WTX_ERR_AGENT_GOPHER_TRUNCATED
- The Gopher tape has been truncated to the maximum agent transfer size.
- WTX_ERR_AGENT_GOPHER_SYNTAX
- Syntax error in the input Gopher program string.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with target.
- TIMEOUT
- WTX RPC timeout.
Here is an example of how Gopher can be used to traverse a data structure and collect information from it. Consider these structures:
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 anchored at nodeList, whose elements are defined by NODE. We initialize the Gopher pointer to the value of nodeList, nodeAddr, and then dereference the pointer. Then, while the pointer is not NULL, we reach into the NODE structure and write the number and name elements to the tape. Referring to the table of Gopher elements, we create the following script:
nodeAddr * { @ < +8 *$ > * }First, the pointer is initialized to the value of the symbol nodeList and then dereferenced (*). We now have a pointer to the first element. While the pointer is not NULL ({), we write the number field to the tape (@) and the pointer is advanced. Saving the pointer position, we enter the subroutine (<). We add eight to the value of the pointer (+8), skipping over the pNext and pOther fields. Now the pointer points to the name field. We dereference the pointer at the first character of the name string (*) and write the string to the tape ($). We then exit the subroutine (>), which restores the previous value of the pointer (pointing to pNext). We dereference the pointer (*) at the next element in the list, * or at NULL. If the field is not NULL, the subprogram {...} repeats. At the end, the Gopher tape contains two entries for each node in the list, one numeric and one string value.There are many ways to write a Gopher script. Each of the following is equivalent to the one described above:
nodeAddr * { @ +8 <*$> -8 * } nodeAddr * { <@> <+12 *$> +4 * }Suppose we also want to find the values of x1 and x2 for a particular node. If the pointer points to the pOther member of a node and pOther is not NULL, this Gopher fragment would write the values of x1 and x2 to the tape:
* {@@ 0}The first * replaces the pointer with the value of pOther; the fragment in braces executes only if the pointer is not NULL. The @@ fragment writes x1 * and x2 to the tape, and the final 0 sets the pointer to NULL so that the {...} loop exits. Guarding this fragment in angle brackets (so that it executes with a local copy of the pointer), adding +4 to move the pointer to pOther, and inserting this fragment into our example string, we have:
nodeAddr * { @ < +8 *$ > < +4 * {@@ 0} > * }To send this string to the target for evaluation, use either the Tcl or C API. The output format depends on the API used.
Gopher cannot use symbolic information, so you must compute structure offsets and store only numbers to the Gopher string.
API Programmer's Guide: The WTX Protocol, API Reference Manual: WTX Tcl Library and WTX C Library
WTX_INFO_GET - WTX get information about a given server
INPUT: WTX_MSG_PARAM OUTPUT: WTX_MSG_SVR_DESC
This request returns information about a server using the WTX registry daemon wtxregd. The input parameter is a string containing the name of the server to get information about.
The result is a WTX_SVR_DESC structure containing the name, type, and key associated with the server.
typedef struct wtx_svr_desc /* Server descriptor */ { char * wpwrName; /* Name of wpwr service */ char * wpwrType; /* Type of service */ char * wpwrKey; /* Unique service key */ } WTX_SVR_DESC;The result structure is embedded in a WTX_MSG_SVR_DESC message:
typedef struct wtx_msg_svr_desc /* Server descriptor message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_SVR_DESC wtxSvrDesc; /* Server Descriptor */ } WTX_MSG_SVR_DESC;This request is used to get the RPC number of a target server prior to attaching to it.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to get information about the given server.
WPWR registry only
- WTX_ERR_REGISTRY_NAME_NOT_FOUND
- No server with the given name exists in the registry.
- WTX_ERR_SVR_DOESNT_RESPOND
- Target server is unable to respond. Network may be over loaded, or tagret server is too busy to answer.
- WTX_ERR_SVR_IS_DEAD
- Target server is no longer responding and has been unregistered.
- TIMEOUT
- WTX RPC timeout.
WTX_REGISTER, WTX_UNREGISTER, WTX_INFO_Q_GET
WTX_INFO_Q_GET - WTX get information about a list of servers
INPUT: WTX_MSG_WTXREGD_PATTERN OUTPUT: WTX_MSG_SVR_DESC_Q
This request returns information about a list of servers using the WTX registry daemon wtxregd. The input parameter is a regular expression used to match the names of the servers to get information about.
typedef struct wtx_msg_wtxregd_pattern /* wtxregd pattern */ { WTX_CORE wtxCore; /* WTX message core */ char * name; /* Pattern to match wpwrName */ char * type; /* Pattern to match wpwrType */ char * key; /* Pattern to match wpwrKey */ } WTX_MSG_WTXREGD_PATTERN;The result is a singly linked list of WTX_SVR_DESC structures containing server information.
typedef struct wtx_svr_desc /* Server descriptor */ { char * wpwrName; /* Name of wpwr service */ char * wpwrType; /* Type of service */ char * wpwrKey; /* Unique service key */ } WTX_SVR_DESC;This structure is embedded in:
typedef struct wtx_msg_svr_desc_q /* Server desc. queue message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_SVR_DESC_Q wtxSvrDescQ; /* Server Descriptor Queue */ } WTX_MSG_SVR_DESC_Q;This request is used to list the target servers available on a host or network.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to get information about one of the listed servers.
WPWR registry only
- WTX_ERR_REGISTRY_BAD_PATTERN
- No server name in the registry matches the given pattern.
- WTX_ERR_REGISTRY_NAME_NOT_FOUND
- No server with the given name exists in the registry.
- TIMEOUT
- WTX RPC timeout.
WTX_REGISTER, WTX_UNREGISTER, WTX_INFO_GET
WTX_MEM_ADD_TO_POOL - WTX add memory to the memory pool
INPUT: WTX_MSG_MEM_BLOCK_DESC OUTPUT: WTX_MSG_RESULT
This request adds memory to the target-server-managed memory pool. The memory added need not be contiguous with memory previously assigned to the partition. This request can be used to add memory from a separate memory bank or memory stolen from the target-operating-system memory pool to the target-server-managed target memory pool.
typedef struct wtx_msg_mem_block_desc /* Target memory block */ { WTX_CORE wtxCore; /* WTX message core */ TGT_ADDR_T startAddr; /* Blocks starts from here */ UINT32 numBytes; /* Number of bytes in block */ } WTX_MSG_MEM_BLOCK_DESC;The result of this request is returned in a WTX_MSG_RESULT message. The val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to add memory to the pool.
Target server only
- WTX_ERR_TGTMEM_INVALID_POOL_SIZE
- Additional memory pool size is too small or not an even multiple of the target-memory alignment size.
WTX_MEM_FREE, WTX_MEM_ALLOC, WTX_MEM_INFO_GET
WTX_MEM_ALIGN - WTX allocate aligned target memory
INPUT: WTX_MSG_MEM_BLOCK_DESC OUTPUT: WTX_MSG_RESULT
This request allocates a buffer described by WTX_MSG_MEM_BLOCK_DESC from the target-server-managed memory partition. The size is numBytes, and the function insures that the allocated buffer begins on a memory address evenly divisible by the specified alignment parameter. The alignment parameter is passed in the startAddr field and must be a power of 2.
typedef struct wtx_msg_mem_block_desc /* Target memory block */ { WTX_CORE wtxCore; /* WTX message core */ TGT_ADDR_T startAddr; /* Blocks starts from here */ UINT32 numBytes; /* Number of bytes in block */ } WTX_MSG_MEM_BLOCK_DESC;The allocated block address is returned in a WTX_MSG_RESULT message:
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to allocate memory. If errCode is OK, the val field in WTX_MSG_RESULT returns a pointer to the target address of the allocated block.
Target server only
- WTX_ERR_TGTMEM_NOT_ENOUGH_MEMORY
- Not enough memory in the target-server-managed target memory pool to allocate the requested block size.
- TIMEOUT
- WTX RPC timeout.
WTX_MEM_FREE, WTX_MEM_ALLOC, WTX_MEM_INFO_GET
WTX_MEM_ALLOC - WTX allocate target memory
INPUT: WTX_MSG_PARAM OUTPUT: WTX_MSG_RESULT
This request allocates a block of memory of at least value bytes from the target-server-managed target memory pool and returns a pointer to the target address of this block. The input parameters are contained in WTX_MSG_PARAM:
typedef struct wtx_msg_param /* Simple request parameter */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE param; /* Param value of call */ } WTX_MSG_PARAM;The allocated block address is returned in the val field of WTX_MSG_RESULT with the type TGT_ADDR_T.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to allocate memory. If errCode is OK, the val field in WTX_MSG_RESULT returns a pointer to the target address of the allocated block.
Target server only
- WTX_ERR_TGTMEM_NOT_ENOUGH_MEMORY
- Not enough memory in the target-server-managed target memory pool to allocate the requested block size.
- TIMEOUT
- WTX RPC timeout.
WTX_MEM_FREE, WTX_MEM_REALLOC, WTX_MEM_ADD_TO_POOL, WTX_MEM_INFO_GET
WTX_MEM_CHECKSUM - WTX perform a target memory checksum
INPUT: WTX_MSG_MEM_SET_DESC OUTPUT: WTX_MSG_RESULT
This request performs a checksum on a block of target memory. The WTX_MSG_MEM_SET_DESC message is used to specify the start address startAddr and the length of the block in bytes, specified by numItems, on which to calculate the checksum. The checksum is a 16-bit value as defined by RFC 1071.
typedef struct wtx_msg_mem_set_desc /* Memory setting desc. */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 value; /* Value to set */ UINT8 width; /* Value width 1, 2 or 4 bytes */ TGT_ADDR_T startAddr; /* Set from here */ UINT32 numItems; /* Number of items to set */ } WTX_MSG_MEM_SET_DESC;Note that the width and value fields of WTX_MSG_MEM_SET_DESC are ignored and are set to NULL.
The request result is returned in the val field of WTX_MSG_RESULT with return type V_UINT32. Note that only the lower 16-bits are significant.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;Note that this request probes the target memory prior to evaluating the checksum. The probing is done at the beginning (startAddr) and at the end (startAddr + numItems) of the memory block.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to perform the checksum. If errCode is OK, the 16 lower bits of the value field in WTX_MSG_RESULT contain the calculated checksum.
Target only
- WTX_ERR_AGENT_MEM_ACCESS_ERROR
- The target memory access is invalid.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_MEM_SET, WTX_MEM_READ, WTX_MEM_WRITE
WTX_MEM_DISASSEMBLE - WTX target memory disassembler
INPUT: WTX_MSG_DASM_DESC OUTPUT: WTX_MSG_DASM_INST_LIST
This request returns a list of disassembled instructions from a specified address.
The several options allow different informations for the output disassembled instructions.
Disassembling parameters are stored in the input WTX_MSG_DASM_DESC structure.
typedef struct wtx_msg_dasm_desc /* Instructions desc. to match */ { WTX_CORE wtxCore; /* WTX message core */ TGT_ADDR_T startAddr; /* Disassembling start address */ TGT_ADDR_T endAddr; /* Disassembling end address */ UINT32 nInst; /* Number of instructions to get */ BOOL32 printAddr; /* Prepends instruction address */ BOOL32 printOpcodes; /* Prepends instruction opcodes */ BOOL32 giveMeNext; /* TRUE for a follow-up req */ BOOL32 hexAddr; /* Turn off "symbolic + offset" */ } WTX_MSG_DASM_DESC;Default number of disassembled instructions is set to 10.
When endAddr is set, the nInst parameter is not used anymore as far as only instructions between startAddr and endAddr are disassembled.
When printAddr is TRUE, instruction's address is prepended to the disassembled instruction.
When printOpcodes is TRUE, instruction's opcodes are prepended to the disassembled instruction.
When hexAddr is TRUE, the "symbol + offset" address representation is turned off.
As this request displays symbol names when a disassembled address matches a symbol address, a kind of "symbol synchronization" is performed. If the start address made it impossible to disassemble at a symbol's address (e.g. start address = symbol address - 1) the request synchronizes on the symbol address.
The result of the request is returned in a WTX_MSG_DASM_INST_LIST message.
typedef struct wtx_msg_dasm_inst_list /* Instructions list message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_DASM_INST_LIST instList; /* Symbol list */ BOOL32 moreToCome; /* TRUE if instructions remain */ } WTX_MSG_DASM_INST_LIST;WTX_MSG_DASM_INST_LIST contains a pointer to WTX_DASM_INST_LIST described below :
typedef struct wtx_dasm_inst_list /* Instructions list */ { char * pInst; /* Start of inst list */ UINT32 nextInst; /* Next instruction address */ UINT32 listSize; /* List size */ } WTX_DASM_INST_LIST;When more than 256 lines (including symbols) are to be returned, moreToCome is set to TRUE. At this time, the client should reissue a WTX_MEM_DISASSEMBLE request with giveMeNext set to TRUE. This operation should be repeated until all the disassembled lines have been transfered from the target server, which is indicated by moreToCome set to FALSE. On the first WTX_MEM_DISASSEMBLE request, giveMeNext should be set to FALSE.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to disassemble memory. If errCode is OK, the pInst field in WTX_DASM_INST_LIST points to an uninterrupted string, of disassembled instructions and symbol names, separated by CR characters.
Target server only.
This service returns only 256 disassembled lines if more are specified, this in order to limit the request result.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Target server can not allocate memory for request.
- WTX_ERR_SVR_TARGET_NOT_ATTACHED
- Target is not attached to server. It is impossible to get memory data.
- WTX_ERR_AGENT_MEM_ACCESS_ERROR
- Memory address is protected. Impossible to get memory data.
- TIMEOUT
- WTX RPC timeout.
Disassembling instructions between address 12345 and address 15432, with addresses and opcodes prepended to the disassembled instruction :
wtxMsgDasmDesc.startAddr = 12345; /* first instruction addr */ wtxMsgDasmDesc.endAddr = 15432; /* last instruction addr */ wtxMsgDasmDesc.nInst = 0; /* endAddr is already set */ wtxMsgDasmDesc.printAddr = TRUE; /* prepend addresses */ wtxMsgDasmDesc.printOpcodes = TRUE; /* prepend opcodes */ wtxMsgDasmDesc.hexAddr = FALSE; /* display symbol + offset */ wtxMsgDasmDesc.giveMeNext = FALSE; /* set to FALSE first */Disassembling 14 instruction from address 54321. Addresses in disassembled instructions displayed only in hexa (not symbol + offset)
wtxMsgDasmDesc.startAddr = 54321; /* first instruction addr */ wtxMsgDasmDesc.endAddr = 0; /* doesn't matter here */ wtxMsgDasmDesc.nInst = 14; /* number of ints to get */ wtxMsgDasmDesc.printAddr = FALSE; /* do not prepend addresses */ wtxMsgDasmDesc.printOpcodes = FALSE;/* do not prepend opcodes */ wtxMsgDasmDesc.hexAddr = TRUE; /* display symbol + offset */ wtxMsgDasmDesc.giveMeNext = FALSE; /* set to FALSE first */
WTX_MEM_FREE - WTX free a block of target memory
INPUT: WTX_MSG_PARAM OUTPUT: WTX_MSG_RESULT
This request returns a block of memory to the target-server-managed target free-memory pool. The block is pointed to by WTX_MSG_PARAM and was previously allocated with WTX_MEM_ALLOC, WTX_MEM_REALLOC, or WTX_MEM_ALIGN.
typedef struct wtx_msg_param /* Simple request parameter */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE param; /* Param value of call */ } WTX_MSG_PARAM;The result of this request is returned in a WTX_MSG_RESULT message. The val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if the block was not previously allocated.
Target server only
- WTX_ERR_TGTMEM_INVALID_BLOCK
- The specified block was not allocated with WTX_MEM_ALLOC or WTX_MEM_REALLOC.
WTX_MEM_ALLOC, WTX_MEM_INFO_GET
WTX_MEM_INFO_GET - WTX get information about the target memory pool
INPUT: WTX_MSG_TOOL_ID OUTPUT: WTX_MSG_MEM_INFO
This request returns information including the largest free block, average block size, and current allocated size for the target-server-managed target memory pool.
The tool making the request sends its identifier in the structure:
typedef struct wtx_msg_tool_id /* Tool identifier message */ { WTX_CORE wtxCore; /* WTX message core */ } WTX_MSG_TOOL_ID;The information about the target-server-managed memory pool is returned in the structure:
typedef struct wtx_msg_mem_info /* Memory information */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 curBytesFree; /* Number of free bytes */ UINT32 curBytesAllocated; /* Cur. # of bytes alloc. */ UINT32 cumBytesAllocated; /* Cum. # of bytes alloc. */ UINT32 curBlocksFree; /* Cur. # of free blocks */ UINT32 curBlocksAlloc; /* Cur. # of blocks alloc. */ UINT32 cumBlocksAlloc; /* Cum. # of blocks alloc. */ UINT32 avgFreeBlockSize; /* Average free blocks size */ UINT32 avgAllocBlockSize; /* Average alloc. blocks size */ UINT32 cumAvgAllocBlockSize; /* Cum. avg alloc. block size */ UINT32 biggestBlockSize; /* Size of biggest block */ void * pReserved; /* Reserved */ } WTX_MSG_MEM_INFO;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to get memory information.
Target server only
- TIMEOUT
- WTX RPC timeout.
WTX_MEM_MOVE - WTX move target memory
INPUT: WTX_MSG_MEM_MOVE_DESC OUTPUT: WTX_MSG_RESULT
This request copies a target memory area to another target memory area. Note that the source and destination buffers may overlap.
The source field of the WTX_MSG_MEM_MOVE_DESC structure holds the source address and the destination field holds the destination address.
typedef struct wtx_msg_mem_move_desc /* Target memory move desc. */ { WTX_CORE wtxCore; /* WTX message core */ TGT_ADDR_T source; /* Copy from here */ TGT_ADDR_T destination; /* To there */ UINT32 numBytes; /* Number of bytes to copy */ } WTX_MSG_MEM_MOVE_DESC;Note that this request probes the target memory prior to copying it. The probing is done at the beginning (source) and the end (source + numBytes) of the source block and at the beginning (destination) and the end (destination + numBytes) of the destination block.
The request result is returned in:
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if the target addresses are invalid.
Target only
- WTX_ERR_AGENT_MEM_ACCESS_ERROR
- The target memory access is invalid.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_MEM_WIDTH_READ - WTX target memory read
INPUT: WTX_MSG_MEM_WIDTH_READ_DESC OUTPUT: WTX_MSG_MEM_WIDTH_COPY_DESC
This request reads a block of target memory into a host buffer. The structure WTX_MSG_MEM_WIDTH_READ_DESC is used to specify the target start address source, the length in bytes of the block to read, numBytes and the access to the memory made on width bytes. The destination field specifies the host address where the memory block is to be copied. The caller of this request must have allocated enough space to hold the number of bytes to read.
typedef struct wtx_msg_mem_width_read_desc /* Target memory read desc. */ { WTX_CORE wtxCore; /* WTX message core */ TGT_ADDR_T source; /* Source mem. address */ UINT32 destination; /* Destination mem. address */ UINT32 numBytes; /* Number of bytes to read */ UINT8 width; /* Value width 1, 2 or 4 bytes */ } WTX_MSG_MEM_WIDTH_READ_DESC;The request result is returned in a WTX_MSG_MEM_WIDTH_COPY_DESC message where the data read from the target are pointed to by the source field.
typedef struct wtx_msg_mem_width_copy_desc /* Target memory copy desc. */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 source; /* Encode from here */ TGT_ADDR_T destination; /* Decode to here */ UINT32 numBytes; /* Bytes to copy/bytes copied */ UINT8 width; /* Value width 1, 2 or 4 bytes */ } WTX_MSG_MEM_WIDTH_COPY_DESC;Note that this request probes the target memory prior to reading it. The probing is done at the beginning (source) and at the end (source + numBytes) of the memory block.
This request has no associated events.
width must be set to 1, 2 or 4 (bytes).
The request is not implemented on the WDB side. In this release it is mapped on WTX_MEM_READ in the target server.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to read the memory block. If errCode is OK, WTX_MSG_MEM_WIDTH_COPY_DESC shows that numBytes have been copied to memory starting at destination.
Target and target server
- WTX_ERR_AGENT_MEM_ACCESS_ERROR
- The target memory access is invalid.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the target server to hold the target buffer copy.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_MEM_WIDTH_WRITE - WTX target memory write
INPUT: WTX_MSG_MEM_WIDTH_COPY_DESC OUTPUT: WTX_MSG_RESULT
This request writes a host buffer to the target memory. The structure WTX_MSG_MEM_WIDTH_COPY_DESC is used to specify the host-buffer start address (source), the length of the block to write in bytes (numBytes) and the access to the memory made on width bytes. The destination field specifies the target address where the memory block is to be copied.
typedef struct wtx_msg_mem_width_copy_desc /* Target memory copy desc. */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 source; /* Encode from here */ TGT_ADDR_T destination; /* Decode to here */ UINT32 numBytes; /* Bytes to copy/bytes copied */ UINT8 width; /* Value width 1, 2 or 4 bytes */ } WTX_MSG_MEM_WIDTH_COPY_DESC;The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;Note that this request probes the target memory prior to writing it. The probing is done at the beginning (destination) and at the end (destination + numBytes) of the memory block.
This request has no associated events.
width must be set to 1, 2 or 4 (bytes).
The request is not implemented on the WDB side. In this release it is mapped on WTX_MEM_READ in the target server.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to write the memory block.
Target and target server
- WTX_ERR_AGENT_MEM_ACCESS_ERROR
- The target memory access is invalid.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_MEM_SET, WTX_MEM_CHECKSUM, WTX_MEM_READ
WTX_MEM_READ - WTX target memory read
INPUT: WTX_MSG_MEM_READ_DESC OUTPUT: WTX_MSG_MEM_COPY_DESC
This request reads a block of target memory into a host buffer. The structure WTX_MSG_MEM_READ_DESC is used to specify the target start address source, and the length in bytes of the block to read, numBytes. The destination field specifies the host address where the memory block is to be copied. The caller of this request must have allocated enough space to hold the number of bytes to read.
typedef struct wtx_msg_mem_read_desc /* Target memory read desc. */ { WTX_CORE wtxCore; /* WTX message core */ TGT_ADDR_T source; /* Source mem. address */ UINT32 destination; /* Destination mem. address */ UINT32 numBytes; /* Number of bytes to read */ } WTX_MSG_MEM_READ_DESC;The request result is returned in a WTX_MSG_MEM_COPY_DESC message where the data read from the target are pointed to by the source field.
typedef struct wtx_msg_mem_copy_desc /* Target memory copy desc. */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 source; /* Encode from here */ TGT_ADDR_T destination; /* Decode to here */ UINT32 numBytes; /* Bytes to copy/bytes copied */ } WTX_MSG_MEM_COPY_DESC;Note that this request probes the target memory prior to reading it. The probing is done at the beginning (source) and at the end (source + numBytes) of the memory block.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to read the memory block. If errCode is OK, WTX_MSG_MEM_COPY_DESC shows that numBytes have been copied to memory starting at destination.
Target and target server
- WTX_ERR_AGENT_MEM_ACCESS_ERROR
- The target memory access is invalid.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the target server to hold the target buffer copy.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_MEM_SET, WTX_MEM_CHECKSUM, WTX_MEM_WRITE
WTX_MEM_REALLOC - WTX reallocate target memory
INPUT: WTX_MSG_MEM_BLOCK_DESC OUTPUT: WTX_MSG_RESULT
WTX_MEM_REALLOC changes the size of the block referenced by startAddr to numBytes bytes and returns a pointer to the (possibly moved) block. If unable to honor a reallocation request, WTX_MEM_REALLOC leaves the startAddr block unaltered.
typedef struct wtx_msg_mem_block_desc /* Target memory block */ { WTX_CORE wtxCore; /* WTX message core */ TGT_ADDR_T startAddr; /* Blocks starts from here */ UINT32 numBytes; /* Number of bytes in block */ } WTX_MSG_MEM_BLOCK_DESC;The reallocated block address is returned in a WTX_MSG_RESULT message:
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to reallocate memory. If errCode is OK, the val field in WTX_MSG_RESULT returns a pointer to the target address of the reallocated block.
Target server only
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory in the target-server-managed target memory pool to allocate the requested block size.
- TIMEOUT
- WTX RPC timeout.
WTX_MEM_FREE, WTX_MEM_ALLOC, WTX_MEM_ADD_TO_POOL, WTX_MEM_INFO_GET
WTX_MEM_SCAN - WTX search for a pattern in target memory
INPUT: WTX_MSG_MEM_SCAN_DESC OUTPUT: WTX_MSG_RESULT
This request searches a block of target memory for a given pattern. When match is TRUE, the memory area between startAddr and endAddr is searched for the pattern pointed to by pattern. If match is FALSE, this request returns the first address between startAddr and endAddr that does not match pattern.
typedef struct wtx_msg_mem_scan_desc /* Target memory scan desc. */ { WTX_CORE wtxCore; /* WTX message core */ BOOL32 match; /* TRUE for matching pattern */ TGT_ADDR_T startAddr; /* Start addr. for scanning */ TGT_ADDR_T endAddr; /* End addr. for scanning */ UINT32 numBytes; /* Number of bytes in pattern */ void * pattern; /* Byte pattern to look for */ } WTX_MSG_MEM_SCAN_DESC;If a match is found, the address at which it is found is returned in the val field of:
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;Note that this request probes the target memory prior to scanning it. The probing is done at the beginning (startAddr) and at the end (endAddr) of the memory block to scan.
This request has no associated events.
The maximum length of the pattern to search for, WTX_MAX_PATTERN_LEN, is 512 bytes.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to find the pattern in memory.
Target only
- WTX_ERR_AGENT_MEM_ACCESS_ERROR
- The target memory access is invalid.
- WTX_ERR_AGENT_PATTERN_NOT_FOUND
- The specified pattern is not found.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_MEM_SET, WTX_MEM_CHECKSUM, WTX_MEM_WRITE
WTX_MEM_SET - WTX target memory set
INPUT: WTX_MSG_MEM_SET_DESC OUTPUT: WTX_MSG_RESULT
This request sets a block of target memory to a given value. The message WTX_MSG_MEM_SET_DESC is used to specify the start address (startAddr), the number of items to set (numItems), and the value to set (value). The width field is ignored. The item is always a byte, and width is set to NULL. startAddr must be a target address.
typedef struct wtx_msg_mem_set_desc /* Memory setting desc. */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 value; /* Value to set */ UINT8 width; /* Value width 1, 2 or 4 bytes */ TGT_ADDR_T startAddr; /* Set from here */ UINT32 numItems; /* Number of items to set */ } WTX_MSG_MEM_SET_DESC;The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;Note that this request probes the target memory prior to setting it. The probing is done at the beginning (startAddr) and at the end (startAddr + numBytes) of the memory block.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to set the memory.
Target only
- WTX_ERR_AGENT_MEM_ACCESS_ERROR
- The target memory access is invalid.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_MEM_WRITE - WTX target memory write
INPUT: WTX_MSG_MEM_COPY_DESC OUTPUT: WTX_MSG_RESULT
This request writes a host buffer to the target memory. The structure WTX_MSG_MEM_COPY_DESC is used to specify the host-buffer start address (source) and the length of the block to write in bytes (numBytes). The destination field specifies the target address where the memory block is to be copied.
typedef struct wtx_msg_mem_copy_desc /* Target memory copy desc. */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 source; /* Encode from here */ TGT_ADDR_T destination; /* Decode to here */ UINT32 numBytes; /* Bytes to copy/bytes copied */ } WTX_MSG_MEM_COPY_DESC;The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;Note that this request probes the target memory prior to writing it. The probing is done at the beginning (destination) and at the end (destination + numBytes) of the memory block.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to write the memory block.
Target and target server
- WTX_ERR_AGENT_MEM_ACCESS_ERROR
- The target memory access is invalid.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_MEM_SET, WTX_MEM_CHECKSUM, WTX_MEM_READ
WTX_OBJ_KILL - WTX object kill
INPUT: WTX_MSG_TOOL_ID OUTPUT: WTX_MSG_RESULT
This request kills or restarts any WTX-capable server (for example, a target server). Note that the WTX server replies to the WTX_OBJ_KILL request prior to committing suicide or restarting so that the tool issuing the request can gracefully exit.
The tool making the request sends its identifier and the type of kill operation in WTX_MSG_KILL_DESC.
typedef struct wtx_msg_kill_desc /* Kill descriptor message */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 request; /* Object kill flag */ WTX_VALUE arg; /* Object kill additional arg */ } WTX_MSG_KILL_DESC;The request parameter is set to WTX_OBJ_KILL_DESTROY to destroy the server or WTX_OBJ_KILL_RESTART to restart the server.
The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if the given tool identifier is invalid.
Target server only
- WTX_ERR_SVR_INVALID_CLIENT_ID
- The tool must be attached to issue this request.
- WTX_ERR_SVR_EINVAL
- Invalid kill request.
- TIMEOUT
- WTX RPC timeout.
WTX_OBJ_MODULE_CHECKSUM - WTX checks validity of the target memory
INPUT: WTX_MSG_MOD_NAME_OR_ID OUTPUT: WTX_MSG_RESULT
This request compares object module checksum on target with object module checksum on target server. This is a way to control the target memory integrity.If moduleId = WTX_ALL_MODULE_ID or fileName is set to "WTX_ALL_MODULE_CHECK" then all modules will be checked. The checksum is a 16-bit value as defined by RFC 1071.
The object module ID or name is passed via:
typedef struct wtx_msg_mod_name_or_id /* Module name or identifier */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 moduleId; /* Module Id */ char * filename; /* Module file name */ } WTX_MSG_MOD_NAME_OR_ID;Either moduleId or filename is used, but not both. The other field is set to NULL.
The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
Because Elf modules may have more than 1 section of text, text sections are gathered in a text segment. 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 for each sections). Then checksums cannot be compared for the text segment but only for the first text section.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to find the given object module.
Target and target server
- WTX_ERR_LOADER_OBJ_MODULE_NOT_FOUND
- The specified module ID or module name is invalid.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the target server.
- WTX_ERR_SVR_BAD_TARGET_CHECKSUM
- Target checksum cannot be computed
- WTX_ERR_SVR_CHECKSUM_MISMATCH
- Target checksum and cache checksum differ
- TIMEOUT
- WTX RPC timeout.
WTX_OBJ_MODULE_LOAD, WTX_OBJ_MODULE_INFO_GET, WTX_OBJ_MODULE_LIST
WTX_OBJ_MODULE_FIND - WTX find an object module
INPUT: WTX_MSG_MOD_NAME_OR_ID OUTPUT: WTX_MSG_MOD_NAME_OR_ID
This request returns the module ID and the name of an object module given its name or identifier.
The object module ID or name is passed via:
typedef struct wtx_msg_mod_name_or_id /* Module name or identifier */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 moduleId; /* Module Id */ char * filename; /* Module file name */ } WTX_MSG_MOD_NAME_OR_ID;Either moduleId or filename is used, but not both. The other field is set to NULL.
The output is a message containing the name and the identifier of the object module if found, or an error otherwise.
typedef struct wtx_msg_mod_name_or_id /* Module name or identifier */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 moduleId; /* Module Id */ char * filename; /* Module file name */ } WTX_MSG_MOD_NAME_OR_ID;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to find the given object module.
Target server only
- WTX_ERR_LOADER_OBJ_MODULE_NOT_FOUND
- The given object module ID or name does not exist in the target server.
- TIMEOUT
- WTX RPC timeout.
WTX_OBJ_MODULE_LOAD, WTX_OBJ_MODULE_INFO_GET, WTX_OBJ_MODULE_LIST
WTX_OBJ_MODULE_INFO_GET - WTX get information about an object module
INPUT: WTX_MSG_MOD_NAME_OR_ID OUTPUT: WTX_MSG_MODULE_INFO
This request returns information about the core file or a object module loaded on the target. The request can be made using the module name or the module identifier via the WTX_MSG_MOD_NAME_OR_ID message. Either moduleId or filename is used, but not both. The other field is set to NULL.
If moduleId is not null and filename is equal to WTX_OBJ_MODULE_PATHNAME_GET, then a wtxObjModuleInfoAndPathGet request is called, otherwise this is a wtxObjModuleInfoGet request.
typedef struct wtx_msg_mod_name_or_id /* Module name or identifier */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 moduleId; /* Module Id */ char * filename; /* Module file name */ } WTX_MSG_MOD_NAME_OR_ID;The result of this request is module information including the module identifier, the module filename, the number of segments, and the address and length of each segment returned in a structure:
typedef struct wtx_msg_module_info /* Object module information */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 moduleId; /* Module Id */ char * moduleName; /* Module name */ char * format; /* Object file format */ UINT32 group; /* Group number */ int loadFlag; /* Flags used to load mod. */ UINT32 nSegments; /* Number of segments */ OBJ_SEGMENT * segment; /* Segment description */ void * pReserved; /* Reserved */ } WTX_MSG_MODULE_INFO;Each segment description is stored in the structure:
typedef struct obj_segment /* Object module segment */ { UINT32 flags; /* Segment flags */ TGT_ADDR_T addr; /* Segment address */ UINT32 length; /* Segment length */ UINT32 reserved1; /* Reserved */ UINT32 reserved2; /* Reserved */ } OBJ_SEGMENT;The list of unknown symbols for a given module can be obtained with the WTX_SYM_LIST_GET service.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to get the object module information. If errCode is OK, WTX_MSG_MODULE_INFO contains information about the object module.
Target server only
- WTX_ERR_LOADER_OBJ_MODULE_NOT_FOUND
- The specified module ID or module name is invalid.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the target server.
- TIMEOUT
- WTX RPC timeout.
WTX_OBJ_MODULE_LOAD, WTX_OBJ_MODULE_LIST, WTX_SYM_LIST_GET
WTX_OBJ_MODULE_LIST - WTX list loaded object modules
INPUT: WTX_MSG_TOOL_ID OUTPUT: WTX_MSG_MODULE_LIST
This request returns a list of object modules loaded on the target system. This list includes the core file and the objects that were successfully loaded using the WTX_OBJ_MODULE_LOAD service. Note that this list contains not only the objects loaded by the tool making the request but all the objects currently loaded by the target server.
Information about object modules can be obtained via the WTX_OBJ_MODULE_INFO_GET request.
The tool making the request sends its identifier in WTX_MSG_TOOL_ID.
typedef struct wtx_msg_tool_id /* Tool identifier message */ { WTX_CORE wtxCore; /* WTX message core */ } WTX_MSG_TOOL_ID;The output is a message containing the number of object modules loaded and a table containing all the loaded object module identifiers:
typedef struct wtx_msg_module_list /* Object module list */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 numObjMod; /* Number of module in list */ UINT32 * modIdList; /* List of object module id */ } WTX_MSG_MODULE_LIST;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to get the object module list. If errCode is OK, the numObjMod field in WTX_MSG_MODULE_LIST returns the number of loaded object modules and modIdList points to a list of object module identifiers.
Target server only
The maximum number of modules that this request can return is 1000. It is stored in WTX_MAX_MODULE_CNT.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the target server to store the return list.
- TIMEOUT
- WTX RPC timeout.
WTX_OBJ_MODULE_LOAD, WTX_OBJ_MODULE_INFO_GET, WTX_OBJ_MODULE_FIND, WTX_SYM_LIST_GET
WTX_OBJ_MODULE_LOAD - WTX load an object module into target memory
INPUT: WTX_MSG_LD_M_FILE_DESC OUTPUT: WTX_MSG_LD_M_FILE_DESC
This request loads an object module from the file described in WTX_MSG_LD_M_FILE_DESC. The filename must be the full path of the object module file to load. The input WTX_MSG_LD_M_FILE_DESC must be freed with free( ) and the output WTX_MSG_LD_M_FILE_DESC must be freed with wtxResultFree( ).
The object module can be of any object module format depending on the target CPU and the toolchain used. The module is properly relocated according to the relocation commands in the file. Unresolved externals are linked to symbols found in the system symbol table. Symbols in the module being loaded can optionally be added to the system symbol table.
As the module is loaded, any unresolved external references are resolved by looking up the missing symbols in the system symbol table maintained by the target server. If found, those references are correctly linked to the new module. If unresolved external references cannot be found in the system symbol table, they are returned to the caller in a list pointed to by undefSymList in WTX_MSG_LD_M_FILE_DESC. Even if unresolved external references are present, the errCode field in WTX_CORE contains OK after the module is loaded unless some other error occurs. Note that loading is continued to facilitate debugging. Only code that does not contain undefined symbols can actually be executed.
The symbols defined in the module being loaded may optionally be added to the system symbol table, depending on the value of loadFlag in WTX_MSG_LD_M_FILE_DESC. (Values are defined in wpwr/host/../include/loadLib.h.)
- LOAD_NO_SYMBOLS
- No symbols are added to the system symbol table
- LOAD_LOCAL_SYMBOLS
- Only local symbols are added to the system symbol table
- LOAD_GLOBAL_SYMBOLS
- Only external symbols are added to the system symbol table
- LOAD_ALL_SYMBOLS
- All symbols are added to the system symbol table
- LOAD_FULLY_LINKED
- No relocation is required
- LOAD_HIDDEN_MODULE
- Load the module but make it invisible to WTX_MSG_MODULE_LIST
- LOAD_COMMON_MATCH_NONE
- Allocate common symbols, but do not search for any matching symbols (the default)
- LOAD_COMMON_MATCH_USER
- Allocate common symbols, but search for matching symbols in user-loaded modules
- LOAD_COMMON_MATCH_ALL
- Allocate common symbols, but search for matching symbols in user-loaded modules and the target-system core file
- LOAD_BAL_OPTIM
- Use branch-and-link optimization (for i960 targets only)
- LOAD_CPLUS_XTOR_AUTO
- C++ ctors/dtors management is explicitly turned on
- LOAD_CPLUS_XTOR_MANUAL
- C++ ctors/dtors management is explicitly turned off
- LOAD_MODULE_INFO_ONLY
- Create and initialize a module, do not load a file
When no section description is given, nSections in WTX_MSG_LD_M_FILE_DESC should be set to NULL. The memory for the sections is allocated from the target-server-managed target memory pool.
typedef struct wtx_msg_ld_m_file_desc /* Object module file desc. */ { WTX_CORE wtxCore; /* WTX message core */ char * filename; /* Object file name */ INT32 loadFlag; /* Behavior control flags */ UINT32 moduleId; /* Module identifier */ UINT32 nSections; /* Number of sections */ LD_M_SECTION * section; /* Section description */ WTX_SYM_LIST undefSymList; /* List of undefined symbols */ } WTX_MSG_LD_M_FILE_DESC;Each section of an object module is described by:
typedef struct ld_m_section /* Object module section desc. */ { UINT32 flags; /* SEC_LOAD, etc. */ TGT_ADDR_T addr; /* Section address */ UINT32 length; /* Section length */ } LD_M_SECTION;If there are no undefined symbols, undefSymList is NULL. Otherwise, the undefined symbols are returned in the singly linked list pointed to by undefSymList:
typedef struct wtx_sym_list /* Symbol list */ { WTX_SYMBOL * pSymbol; /* Start of symbol list */ } WTX_SYM_LIST;Each undefined symbol in this list is described by:
typedef struct wtx_symbol /* Symbol descriptor */ { UINT32 status; /* Ret. val. for FIND request */ UINT32 symTblId; /* Symbol table id */ char * name; /* Symbol name */ BOOL32 exactName; /* FALSE if _name is OK */ TGT_ADDR_T value; /* Symbol value */ UINT8 type; /* Symbol type */ UINT8 typeMask; /* Symbol type mask for lookup */ UINT16 group; /* Symbol group */ char * moduleName; /* Module name */ void * pReserved; /* Reserved */ struct wtx_symbol * next; /* ptr to next symbol in list */ } WTX_SYMBOL;
If the load is successful, the other tools attached to the target server are notified of the loading with a OBJ_LOADED moduleId event.
COFF object modules with more than three sections are not supported.
If the module was previously loaded, it is unloaded prior to being reloaded.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to load the specified object module. If errCode is OK, the moduleId field in WTX_MSG_LD_M_FILE_DESC returns the object module identifier, nSections contains the number of sections, and, if necessary, undefSymList contains the list of unresolved external references.
Target and target server
This request is replaced by WTX_OBJ_MODULE_LOAD_2 and will be removed in the next Tornado release.
- WTX_ERR_LOADER_UNKNOWN_OBJ_MODULE_FORMAT
- Invalid object module format.
- WTX_ERR_LOADER_NULL_SIZE_OBJ_MODULE
- The object module is empty.
- WTX_ERR_LOADER_ILLEGAL_FLAGS_COMBINATION
- Loading flags are conflicting.
- WTX_ERR_LOADER_UNKNOWN_COMMAND_FLAG
- Loading flags are invalid.
- WTX_ERR_LOADER_NO_RELOCATION_ROUTINE
- The relocation routine for this CPU/object format combination was not found.
- WTX_ERR_LOADER_UNKNOWN_RELOCATION_ENTRY
- Not supported or invalid relocation entry found in the object module.
- WTX_ERR_TGTMEM_NOT_ENOUGH_MEMORY
- Not enough memory in the target-server-managed target memory pool to store the object module segments.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the target server to store the object module symbols.
- ENOENT
- The file referred to by filename does not exist.
- EACCESS
- File access denied.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_OBJ_MODULE_UNLOAD, WTX_OBJ_MODULE_LIST, WTX_OBJ_MODULE_INFO_GET, WTX_OBJ_MODULE_FIND, API Reference Manual: Target Server Internal Routines, API Programmer's Guide: Object Module Loader
WTX_OBJ_MODULE_LOAD_2 - WTX load an object module into target memory
INPUT: WTX_MSG_FILE_LOAD_DESC OUTPUT: WTX_MSG_LD_M_FILE_DESC
This request loads an object module from the file described in WTX_MSG_FILE_LOAD_DESC. The filename must be the full path of the object module file to load. The input WTX_MSG_FILE_LOAD_DESC must be freed with free( ) and the output WTX_MSG_LD_M_FILE_DESC must be freed with wtxResultFree( ).
The object module can be of any object module format depending on the target CPU and the toolchain used. The module is properly relocated according to the relocation commands in the file. Unresolved externals are linked to symbols found in the system symbol table. Symbols in the module being loaded can optionally be added to the system symbol table.
The load request can have two different behaviors controled by a flag set in the moduleId field (this field is an output field, then it is free on input). moduleId can be set to either "WTX_LOAD_FROM_CLIENT" or "WTX_LOAD_FROM_TARGET_SERVER". In the first case (default), the file is opened locally where the client is and sent to the target server in packets of 8 kb. Then, the target server re-built it and the transfer is complete, the target server loads it on the target. In the second case (old behavior), only the file name and the other arguments are sent to the target server. It opens the file and loads it on the target. This allows the user to open a file on a Unix (or Windows) file system and send it to a target server running on Windows (or Unix).
As the module is loaded, any unresolved external references are resolved by looking up the missing symbols in the system symbol table maintained by the target server. If found, those references are correctly linked to the new module. If unresolved external references cannot be found in the system symbol table, they are returned to the caller in a list pointed to by undefSymList in WTX_MSG_LD_M_FILE_DESC. Even if unresolved external references are present, the errCode field in WTX_CORE contains OK after the module is loaded unless some other error occurs. Note that loading is continued to facilitate debugging. Only code that does not contain undefined symbols can actually be executed.
The symbols defined in the module being loaded may optionally be added to the system symbol table, depending on the value of loadFlag in WTX_MSG_LD_M_FILE_DESC. (Values are defined in wpwr/host/../include/loadLib.h.)
- LOAD_NO_SYMBOLS
- No symbols are added to the system symbol table
- LOAD_LOCAL_SYMBOLS
- Only local symbols are added to the system symbol table
- LOAD_GLOBAL_SYMBOLS
- Only external symbols are added to the system symbol table
- LOAD_ALL_SYMBOLS
- All symbols are added to the system symbol table
- LOAD_FULLY_LINKED
- No relocation is required
- LOAD_NO_DOWNLOAD
- The module is not loaded on the target
- LOAD_HIDDEN_MODULE
- Load the module but make it invisible to WTX_MSG_MODULE_LIST
- LOAD_COMMON_MATCH_NONE
- Allocate common symbols, but do not search for any matching symbols (the default)
- LOAD_COMMON_MATCH_USER
- Allocate common symbols, but search for matching symbols in user-loaded modules
- LOAD_COMMON_MATCH_ALL
- Allocate common symbols, but search for matching symbols in user-loaded modules and the target-system core file
- LOAD_BAL_OPTIM
- Use branch-and-link optimization (for i960 targets only)
- LOAD_CPLUS_XTOR_AUTO
- C++ ctors/dtors management is explicitly turned on
- LOAD_CPLUS_XTOR_MANUAL
- C++ ctors/dtors management is explicitly turned off
- LOAD_MODULE_INFO_ONLY
- Create and initialize a module, do not load a file
The information about the module are passed in a WTX_MSG_FILE_LOAD_DESC structure which is a super set of the WTX_LD_M_FILE_DESC structure.
typedef struct wtx_msg_file_load_desc /* File descriptor */ { WTX_CORE wtxCore; /* WTX message core */ struct wtx_ld_m_file_desc fileDesc; /* Obj mod file desc */ char * buffer; /* Slice of file */ UINT32 flags; /* Load mode flag */ INT32 numItems; /* Number of items sent */ INT32 fileSize; /* File size */ INT32 numPacket; /* Current packet sent */ } WTX_MSG_FILE_LOAD_DESC;When no section description is given, nSections in WTX_LD_M_FILE_DESC should be set to NULL. The memory for the sections is allocated from the target-server-managed target memory pool.
typedef struct wtx_ld_m_file_desc /* Object module file desc. */ { char * filename; /* Object file name */ INT32 loadFlag; /* Behavior control flags */ UINT32 moduleId; /* Module identifier */ UINT32 nSections; /* Number of sections */ LD_M_SECTION * section; /* Section description */ WTX_SYM_LIST undefSymList; /* List of undefined symbols */ } WTX_LD_M_FILE_DESC;The load result (module Id, sections description and undefined symbols) is returned in a WTX_MSG_LD_M_FILE_DESC structure.
typedef struct wtx_msg_ld_m_file_desc /* Object module file desc. */ { WTX_CORE wtxCore; /* WTX message core */ char * filename; /* Object file name */ INT32 loadFlag; /* Behavior control flags */ UINT32 moduleId; /* Module identifier */ UINT32 nSections; /* Number of sections */ LD_M_SECTION * section; /* Section description */ WTX_SYM_LIST undefSymList; /* List of undefined symbols */ } WTX_MSG_LD_M_FILE_DESC;Each section of an object module is described by:
typedef struct ld_m_section /* Object module section desc. */ { UINT32 flags; /* SEC_LOAD, etc. */ TGT_ADDR_T addr; /* Section address */ UINT32 length; /* Section length */ } LD_M_SECTION;If there are no undefined symbols, undefSymList is NULL. Otherwise, the undefined symbols are returned in the singly linked list pointed to by undefSymList:
typedef struct wtx_sym_list /* Symbol list */ { WTX_SYMBOL * pSymbol; /* Start of symbol list */ } WTX_SYM_LIST;Each undefined symbol in this list is described by:
typedef struct wtx_symbol /* Symbol descriptor */ { UINT32 status; /* Ret. val. for FIND request */ UINT32 symTblId; /* Symbol table id */ char * name; /* Symbol name */ BOOL32 exactName; /* FALSE if _name is OK */ TGT_ADDR_T value; /* Symbol value */ UINT8 type; /* Symbol type */ UINT8 typeMask; /* Symbol type mask for lookup */ UINT16 group; /* Symbol group */ char * moduleName; /* Module name */ void * pReserved; /* Reserved */ struct wtx_symbol * next; /* ptr to next symbol in list */ } WTX_SYMBOL;
If the load is successful, the other tools attached to the target server are notified of the loading with a OBJ_LOADED moduleId event.
COFF object modules with more than three sections are not supported.
If the module was previously loaded, it is unloaded prior to being reloaded.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to load the specified object module. If errCode is OK, the moduleId field in WTX_MSG_LD_M_FILE_DESC returns the object module identifier, nSections contains the number of sections, and, if necessary, undefSymList contains the list of unresolved external references.
Target and target server
- WTX_ERR_LOADER_ILLEGAL_FLAGS_COMBINATION
- Loading flags are conflicting.
- WTX_ERR_LOADER_NO_RELOCATION_ROUTINE
- The relocation routine for this CPU/object format combination was not found.
- WTX_ERR_LOADER_CANT_GET_SEGMENT_ADDRESSES
- Segments addresses are unspecified
- WTX_ERR_LOADER_UNKNOWN_RELOCATION_ENTRY
- Not supported or invalid relocation entry found in the object module.
- WTX_ERR_LOADER_UNKNOWN_COMMAND_FLAG
- Loading flags are invalid.
- WTX_ERR_LOADER_UNKNOWN_OBJ_MODULE_FORMAT
- Invalid object module format.
- WTX_ERR_LOADER_NULL_SIZE_OBJ_MODULE
- The object module is empty.
- WTX_ERR_LOADER_OBJ_MODULE_NOT_FOUND
- Module doesn't exist
- WTX_ERR_LOADER_BAD_CHECKSUM
- Current checksum doesn't match the old one
- WTX_ERR_LOADER_CANT_ATTACH_OMF_MANAGER
- Enable to attach the omf loader
- WTX_ERR_LOADER_OBJ_MODULE_NOT_APPROPRIATE
- Cannot determine target endianness
- WTX_ERR_LOADER_RELOCATION_OFFSET_TOO_LARGE
- Relocation value does not fit
- WTX_ERR_LOADER_SYMBOL_NOT_FROM_SDA_SECTION
- Referenced symbol does not belong to SDA
- WTX_ERR_LOADER_MAX_MODULES_LOADED
- Cannot load any module
- WTX_ERR_LOADER_RELOCATION_ERROR
- Relocation sections are not supported
- WTX_ERR_LOADER_NO_VERIFICATION_ROUTINE
- Cannot verify if the module is for the correct architecture
- WTX_ERR_LOADER_LOAD_CANCELED
- An asynchronous load request had been aborted
- WTX_ERR_LOADER_LOAD_IN_PROGRESS
- An asynchronous load request is in progress
- WTX_ERR_LOADER_ALREADY_LOADED
- An asynchronous load request is finished
- WTX_ERR_TGTMEM_NOT_ENOUGH_MEMORY
- Not enough memory in the target-server-managed target memory pool to store the object module segments.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the target server to store the object module symbols.
- WTX_ERR_SVR_EINVAL
- Tool or context not found or unknown load status
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
- set by the open function or by the loader.
WTX_OBJ_MODULE_UNLOAD, WTX_OBJ_MODULE_LIST, WTX_OBJ_MODULE_INFO_GET, WTX_OBJ_MODULE_FIND, API Reference Manual: Target Server Internal Routines, API Programmer's Guide: Object Module Loader
WTX_OBJ_MODULE_UNLOAD - WTX unload an object module
INPUT: WTX_MSG_PARAM OUTPUT: WTX_MSG_RESULT
This request unloads an object module specified by its identifier in the param field of WTX_MSG_PARAM from the target system.
typedef struct wtx_msg_param /* Simple request parameter */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE param; /* Param value of call */ } WTX_MSG_PARAM;Unloading an object module does the following:
- (1)
- It frees the space allocated for segments, unless WTX_OBJ_MODULE_LOAD was called with specific addresses, in which case the user is responsible for freeing the space.
- (2)
- It removes all symbols associated with the object module from the system symbol table.
- (3)
- It removes the module descriptor from the module list.
Once the module is unloaded, any calls from other modules to functions in that module will fail unpredictably. The user is responsible for ensuring that no modules are unloaded that are used by other modules.
The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
If the unloading is successful, the other tools attached to the target server are notified of the unloading with a OBJ_UNLOADED moduleId event.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to unload the specified object module.
Target server only
This request is replaced by WTX_OBJ_MODULE_UNLOAD_2 and will be removed in the next Tornado release.
- WTX_ERR_LOADER_OBJ_MODULE_NOT_FOUND
- Invalid object module.
- WTX_ERR_LOADER_TEXT_IN_USE
- The object module code is used by operating-system hooks and cannot be removed.
- TIMEOUT
- WTX RPC timeout.
WTX_OBJ_MODULE_LOAD, WTX_OBJ_MODULE_LIST, WTX_OBJ_MODULE_INFO_GET, WTX_OBJ_MODULE_FIND
WTX_OBJ_MODULE_UNLOAD_2 - WTX unload an object module
INPUT: WTX_MSG_MOD_NAME_OR_ID OUTPUT: WTX_MSG_RESULT
This request unloads an object module specified by its identifier in the moduleId field of WTX_MSG_MOD_NAME_OR_ID or by its filename in the filename field from the target system.
typedef struct wtx_msg_mod_name_or_id /* Module name or identifier */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 moduleId; /* Module Id */ char * filename; /* Module file name */ } WTX_MSG_MOD_NAME_OR_ID;Unloading an object module does the following:
- (1)
- It frees the space allocated for segments, unless WTX_OBJ_MODULE_LOAD was called with specific addresses, in which case the user is responsible for freeing the space.
- (2)
- It removes all symbols associated with the object module from the system symbol table.
- (3)
- It removes the module descriptor from the module list.
Once the module is unloaded, any calls from other modules to functions in that module will fail unpredictably. The user is responsible for ensuring that no modules are unloaded that are used by other modules.
The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
If the unloading is successful, the other tools attached to the target server are notified of the unloading with a OBJ_UNLOADED moduleId event.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to unload the specified object module.
Target server only
- WTX_ERR_LOADER_OBJ_MODULE_NOT_FOUND
- Invalid object module.
- WTX_ERR_LOADER_TEXT_IN_USE
- The object module code is used by operating-system hooks and cannot be removed.
- TIMEOUT
- WTX RPC timeout.
WTX_OBJ_MODULE_LOAD, WTX_OBJ_MODULE_LIST, WTX_OBJ_MODULE_INFO_GET, WTX_OBJ_MODULE_FIND
WTX_OPEN - WTX open a file or pipe
INPUT: WTX_MSG_OPEN_DESC OUTPUT: WTX_MSG_RESULT
This request opens the file specified by filename in WTX_MSG_OPEN_DESC for reading or writing as specified by the flags parameter and returns a descriptor for that file. If the filename starts with |, the file is opened as a pipe using the popen( ) system call. Otherwise, the file is opened using the open( ) system call.
typedef struct wtx_msg_open_desc /* File opening descriptor */ { WTX_CORE wtxCore; /* WTX message core */ char * filename; /* Filename */ WTX_OPEN_FLAG flags; /* Unix style open flags */ INT32 mode; /* Unix style mode */ INT32 channel; /* Channel id for redirection */ } WTX_MSG_OPEN_DESC;The flags parameter can have one of the following values:
typedef enum wtx_open_flag /* flag for WTX_OPEN */ { WTX_O_RDONLY = 0x1000, /* Open for reading only */ WTX_O_WRONLY = 0x1001, /* Open for writing only */ WTX_O_CREAT = 0x1400 /* Open with file create */ } WTX_OPEN_FLAG;or host-specific flags (O_RDONLY etc...) as defined in sys/fcntl.h. The latter are accepted for backward compatibility but should no longer be used.
If the file to open is a real file, flags must have one of the following values:
- WTX_O_RDONLY
- Open for reading only.
- WTX_O_WRONLY
- Open for writing only.
- WTX_O_CREAT
- If the file exists, this flag has no effect. Otherwise, the file is created, and the owner ID of the file is set to the effective user ID of the process.
If the file to open is a pipe, flags must have one of the following values:
- WTX_O_RDONLY
- Open for reading only.
- WTX_O_WRONLY
- Open for writing only.
Upon opening, the specified file is redirected to the virtual I/O channel specified by channel. If channel is set to -1, no virtual I/O redirection is performed at open time; redirection could be performed later using the WTX_VIO_CTL request. If a channel number is used, it is obtained by a request to WTX_VIO_CHAN_GET.
The request result has the V_INT32 type and is returned in:
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
O_RDWR is not supported so it is considered an invalid flag. When the target server runs on Windows NT or Windows 95, opening a pipe is not supported.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to open the specified file. If errCode is OK, the val field in WTX_MSG_RESULT returns the file descriptor associated with the open file or pipe.
Target server only
The maximum number of simultaneously open files depends on the operating system where the target server is running; a common limit is 128 open files.
- WTX_ERR_SVR_INVALID_FLAGS
- Invalid open flags.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the target server.
- EACCESS, EFAULT etc...
- Underlying open( ) errors.
- TIMEOUT
- WTX RPC timeout.
WTX_CLOSE, WTX_VIO_WRITE, WTX_VIO_CTL, WTX_VIO_FILE_LIST, /&WTX_VIO_CHAN_GET
WTX_REGISTER - WTX register a server
INPUT: WTX_MSG_SVR_DESC OUTPUT: WTX_MSG_SVR_DESC
This request registers a server described in WTX_SVR_DESC by giving its name and type and returns a unique key for that server using the WTX registry daemon wtxregd. The server name, name, can be any string but for convenience should be of the form "serverName@host". The server type, type, is "tgtsvr" for target servers or "registry" for the WTX registry daemon itself.
Input parameters are passed in:
typedef struct wtx_svr_desc /* Server descriptor */ { char * wpwrName; /* Name of wpwr service */ char * wpwrType; /* Type of service */ char * wpwrKey; /* Unique service key */ } WTX_SVR_DESC;embedded in the message:
typedef struct wtx_msg_svr_desc /* Server descriptor message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_SVR_DESC wtxSvrDesc; /* Server Descriptor */ } WTX_MSG_SVR_DESC;The unique key is a string returned in key. This key is made of a concatenation of the type of inter-process-communication mechanism, the host name where the server is running, an inter-process communication-dependent value, a version number, and extra information about the inter-process communication. For example, for an RPC-based system, the key can be rpc/aven/570425345/1/tcp.
As an input parameter key is set to NULL.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if registration fails. If successful, this request returns a unique key in the wpwrKey field of WTX_SVR_DESC.
WPWR registry only
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the server.
- WTX_ERR_REGISTRY_NAME_CLASH
- A server of the same name is already registered.
- TIMEOUT
- WTX RPC timeout.
WTX_UNREGISTER, WTX_INFO_GET, WTX_INFO_Q_GET
WTX_REGISTER_FOR_EVENT - WTX register for events
INPUT: WTX_MSG_EVENT_REG_DESC OUTPUT: WTX_MSG_RESULT
This request allows a tool to register to be notified of a particular type of event. It then obtains the events with WTX_EVENT_GET requests. Only events that a tool has registered for are announced to the tool.
The register-for-event descriptor is a regular expression pointed to by evtRegExp. This regular expression is used by the target server to find event strings that match.
typedef struct wtx_msg_event_reg_desc /* WTX event register desc. */ { WTX_CORE wtxCore; /* WTX message core */ char * evtRegExp; /* Register event reg. expr. */ } WTX_MSG_EVENT_REG_DESC;The event types are given by:
typedef enum wtx_event_type { WTX_EVENT_NONE = 0, /* No event */ WTX_EVENT_CTX_START = 1, /* A target context was created */ WTX_EVENT_CTX_EXIT = 2, /* A target context was deleted */ WTX_EVENT_TEXT_ACCESS = 3, /* A target text access (breakpoint) */ WTX_EVENT_DATA_ACCESS = 4, /* A target data access (watchpoint) */ WTX_EVENT_EXCEPTION = 5, /* A target exception occurred */ WTX_EVENT_VIO_WRITE = 6, /* A target VIO write occurred */ WTX_EVENT_HW_BP = 7, /* A target breakpoint: obsolete, use */ /* WTX_EVENT_TEXT_ACCESS instead */ WTX_EVENT_CALL_RETURN = 8, /* A target function call returned */ WTX_EVENT_USER = 9, /* A target agent user defined event */ WTX_EVENT_UNKNOWN = 10, /* An unknown target event */ WTX_EVENT_TGT_RESET = 11, /* The target was reset */ WTX_EVENT_SYM_ADDED = 12, /* A symbol added to the sym. table */ WTX_EVENT_SYM_REMOVED = 13, /* A symbol removed from the sym tabl */ WTX_EVENT_OBJ_LOADED = 14, /* An object file was loaded */ WTX_EVENT_OBJ_UNLOADED = 15, /* An object file was unloaded */ WTX_EVENT_TOOL_ATTACH = 16, /* A tool attached to Target Server */ WTX_EVENT_TOOL_DETACH = 17, /* A tool detached from Target Server */ WTX_EVENT_TOOL_MSG = 18, /* A tool to tool message */ WTX_EVENT_TS_KILLED = 19, /* The target server was reset */ WTX_EVENT_EVTPT_ADDED = 20, /* A new event point is added */ WTX_EVENT_EVTPT_DELETED= 21, /* An event point had been deleted */ WTX_EVENT_OTHER = 0x100, /* User defined or unrecognized event */ WTX_EVENT_INVALID = WTX_ERROR /* Invalid/unidentifiable event */ } WTX_EVENT_TYPE;When a tool attaches to the target server using WTX_TOOL_ATTACH, it does not register for any event. To register for all events, a tool uses WTX_REGISTER_FOR_EVENT with the .* regular expression which matches any event string.
Note that this request can be used at any time to change the events that the tool wants to be notified of.
The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
Registering for all exception events can be done with:
/* register for exception events */ wtxMsgEventRegDesc.evtRegExp = "EXCEPTION"
All
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to register for events.
Target server only
- WTX_ERR_SVR_INVALID_CLIENT_ID
- The tool is not attached to the target server.
- TIMEOUT
- WTX RPC timeout.
WTX_REGS_GET - WTX get target registers
INPUT: WTX_MSG_REG_READ OUTPUT: WTX_MSG_MEM_XFER_DESC
This request returns one or more register value(s) as raw (target format) data for a given context. A WTX_MSG_REG_READ message contains the information needed to get the register(s). context.contextType specifies the type of context and context.contextId gives the context identifier. The memRegion.baseAddr field is used to specify the first byte of the register set to get and memRegion.size is used to specify the number of bytes of the register set to get.
typedef struct WTX_MSG_REG_READ /* Register(s) to get */ { WTX_CORE wtxCore; /* WTX message core */ WTX_REG_SET_TYPE regSetType; /* Type of register set */ WTX_CONTEXT context; /* Associated context */ WTX_MEM_REGION memRegion; /* Register block subregion */ } WTX_MSG_REG_READ;WTX_MEM_REGION is:
typedef struct wtx_mem_region /* Memory region descriptor */ { TGT_ADDR_T baseAddr; /* Mem. region base address */ UINT32 size; /* Mem. region size */ UINT32 attribute; /* Mem. region attributes */ } WTX_MEM_REGION;and WTX_CONTEXT is:
typedef struct wtx_context /* Context desc. */ { WTX_CONTEXT_TYPE contextType; /* Type of context */ WTX_CONTEXT_ID_T contextId; /* Context ID */ } WTX_CONTEXT;WTX_REG_SET_TYPE is one of:
typedef enum wtx_reg_set_type /* types of registers */ { WTX_REG_SET_IU = 0, /* integer unit reg. set */ WTX_REG_SET_FPU = 1, /* float. point unit reg. set */ WTX_REG_SET_MMU = 2, /* memory managmt unit reg set */ WTX_REG_SET_CU = 3, /* cache unit reg. set */ WTX_REG_SET_TPU = 4, /* time process. unit reg. set */ WTX_REG_SET_SYS = 5 /* system registers */ } WTX_REG_SET_TYPE;and WTX_CONTEXT_TYPE is one of:
typedef enum wtx_context_type /* types of context */ { WTX_CONTEXT_SYSTEM = 0, /* system mode */ WTX_CONTEXT_GROUP = 1, /* process group (not implemented) */ WTX_CONTEXT_ANY = 2, /* any context (not implemented) */ WTX_CONTEXT_TASK = 3, /* specific task or processes */ WTX_CONTEXT_ANY_TASK = 4, /* any task */ WTX_CONTEXT_ISR = 5, /* specific ISR (not implemented) */ WTX_CONTEXT_ISR_ANY = 6 /* any ISR (not implemented) */ } WTX_CONTEXT_TYPE;
The register-set definition depends on the CPU type and the underlying operating system. For example, for Motorola 68k processors running VxWorks, the register set is defined as follows:
typedef struct reg_set /* REG_SET - 680x0 register set */ { ULONG dataReg[8]; /* data registers */ ULONG addrReg[8]; /* address registers */ USHORT pad; /* pad SR to a long */ USHORT sr; /* status register (must be second to last) */ INSTR *pc; /* program counter (must be last) */ } REG_SET;To get the address registers a0 through a7, set the memRegion fields as follows:
/* point to a0 first byte in reg set */ memRegion.baseAddr = 32; /* get 8 * 4 bytes corresponding to a0-a7 */ memRegion.size = 32;The register contents are returned as a block of memory of size memXfer.numBytes pointed to by memXfer.source.
typedef struct wtx_mem_xfer /* Memory transfer */ { UINT32 numBytes; /* Num. of bytes to transfer */ TGT_ADDR_T destination; /* Destination address */ char * source; /* Source address */ } WTX_MEM_XFER;The WTX_MEM_XFER structure is embedded in the message below:
typedef struct wtx_msg_mem_xfer_desc /* Memory transfer message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_MEM_XFER memXfer; /* Mem. transfer desc. */ } WTX_MSG_MEM_XFER_DESC;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to get the registers. If errCode is OK, memXfer.numBytes returns the number of bytes in the subset of the register set returned and memXfer.source returns the address of a block containing the register values.
Target only
- WTX_ERR_AGENT_INVALID_CONTEXT
- Invalid target system context.
- WTX_ERR_AGENT_UNSUPPORTED_REQUEST
- The request is not supported by the debug agent.
- WTX_ERR_AGENT_NO_RT_PROC
- The target runtime system does not implement a get-register procedure.
- WTX_ERR_AGENT_INVALID_PARAMS
- The requested registers are invalid.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_REGS_SET - WTX set target registers
INPUT: WTX_MSG_REG_WRITE OUTPUT: WTX_MSG_RESULT
This request sets the target registers for a particular context with raw (target format) register data. The information needed to set the register(s) is passed in a WTX_MSG_REG_WRITE message. context.contextType specifies the type of context and context.contextId specifies the context identifier. memXfer.destination is used to specify the first byte of the register set to set, memXfer.numBytes is used to specify the number of bytes in the register set to set, and memXfer.source specifies the address of a memory block that contains the register value(s) to set.
typedef struct wtx_msg_reg_write /* Register(s) to set */ { WTX_CORE wtxCore; /* WTX message core */ WTX_REG_SET_TYPE regSetType; /* Type of register set */ WTX_CONTEXT context; /* Associated context */ WTX_MEM_XFER memXfer; /* New value of register(s) */ } WTX_MSG_REG_WRITE;WTX_CONTEXT is:
typedef struct wtx_context /* Context desc. */ { WTX_CONTEXT_TYPE contextType; /* Type of context */ WTX_CONTEXT_ID_T contextId; /* Context ID */ } WTX_CONTEXT;WTX_REG_SET_TYPE is one of:
typedef enum wtx_reg_set_type /* types of registers */ { WTX_REG_SET_IU = 0, /* integer unit reg. set */ WTX_REG_SET_FPU = 1, /* float. point unit reg. set */ WTX_REG_SET_MMU = 2, /* memory managmt unit reg set */ WTX_REG_SET_CU = 3, /* cache unit reg. set */ WTX_REG_SET_TPU = 4, /* time process. unit reg. set */ WTX_REG_SET_SYS = 5 /* system registers */ } WTX_REG_SET_TYPE;and WTX_CONTEXT_TYPE is one of:
typedef enum wtx_context_type /* types of context */ { WTX_CONTEXT_SYSTEM = 0, /* system mode */ WTX_CONTEXT_GROUP = 1, /* process group (not implemented) */ WTX_CONTEXT_ANY = 2, /* any context (not implemented) */ WTX_CONTEXT_TASK = 3, /* specific task or processes */ WTX_CONTEXT_ANY_TASK = 4, /* any task */ WTX_CONTEXT_ISR = 5, /* specific ISR (not implemented) */ WTX_CONTEXT_ISR_ANY = 6 /* any ISR (not implemented) */ } WTX_CONTEXT_TYPE;The register(s) contents are contained in:
typedef struct wtx_mem_xfer /* Memory transfer */ { UINT32 numBytes; /* Num. of bytes to transfer */ TGT_ADDR_T destination; /* Destination address */ char * source; /* Source address */ } WTX_MEM_XFER;
The register-set definition depends on the CPU type and the underlying operating system. For example, for Motorola 68k processors running VxWorks, the register set is defined as follows:
typedef struct reg_set /* REG_SET - 680x0 register set */ { ULONG dataReg[8]; /* data registers */ ULONG addrReg[8]; /* address registers */ USHORT pad; /* pad SR to a long */ USHORT sr; /* status register (must be second to last) */ INSTR *pc; /* program counter (must be last) */ } REG_SET;Set the address registers a4 through a5 by setting the memXfer fields as shown below:
/* buffer where a4-a5 values are stored */ memXfer.source = buf; /* point to a4 first byte in reg set */ memXfer.destination = 48; /* set 2 * 4 bytes corresponding to a4-a5 */ memXfer.numbytes = 8;The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to set registers for the given context.
Target only
- WTX_ERR_AGENT_INVALID_CONTEXT
- Invalid target system context.
- WTX_ERR_AGENT_UNSUPPORTED_REQUEST
- The request is not supported by the debug agent.
- WTX_ERR_AGENT_NO_RT_PROC
- The target runtime system does not implement a set-register procedure.
- WTX_ERR_AGENT_INVALID_PARAMS
- The requested registers are invalid.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_SYM_ADD - WTX add a symbol
INPUT: WTX_MSG_SYMBOL_DESC OUTPUT: WTX_MSG_RESULT
This request adds a symbol of specified name, type, value, and group to the target-server-managed symbol table. The symbol information is contained in the message WTX_MSG_SYMBOL_DESC:
typedef struct wtx_msg_symbol_desc /* Symbol message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_SYMBOL symbol; /* Symbol */ } WTX_MSG_SYMBOL_DESC;where WTX_SYMBOL is:
typedef struct wtx_symbol /* Symbol descriptor */ { UINT32 status; /* Ret. val. for FIND request */ UINT32 symTblId; /* Symbol table id */ char * name; /* Symbol name */ BOOL32 exactName; /* FALSE if _name is OK */ TGT_ADDR_T value; /* Symbol value */ UINT8 type; /* Symbol type */ UINT8 typeMask; /* Symbol type mask for lookup */ UINT16 group; /* Symbol group */ char * moduleName; /* Module name */ void * pReserved; /* Reserved */ struct wtx_symbol * next; /* ptr to next symbol in list */ } WTX_SYMBOL;Only the name, value, type, and group fields need to be specified in WTX_SYMBOL. The other fields are ignored and are set to NULL.
The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;The default target server system symbol table allows multiple symbols with the same name to be added (in other words, name clashes are allowed).
If the symbol is successfully added, the other tools attached to the target server are notified of the new symbol by a SYM_ADDED name value event. Note that there are no events associated with symbols added by the WTX_OBJ_MODULE_LOAD request.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to add the symbol.
Target server only
The maximum length of a symbol name is 256 characters.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the target server to store the symbol.
- WTX_ERR_SYMTBL_SYMBOL_NAME_TOO_LONG
- The symbol name exceeds the maximum symbol-name length (256 characters).
- TIMEOUT
- WTX RPC timeout.
WTX_SYM_FIND - WTX find a symbol
INPUT: WTX_MSG_SYMBOL_DESC OUTPUT: WTX_MSG_SYMBOL_DESC
This request finds a symbol of equivalent name, type, or value in the specified symbol table. The WTX_SYM_FIND search process is based on specified fields in WTX_SYMBOL:
typedef struct wtx_symbol /* Symbol descriptor */ { UINT32 status; /* Ret. val. for FIND request */ UINT32 symTblId; /* Symbol table id */ char * name; /* Symbol name */ BOOL32 exactName; /* FALSE if _name is OK */ TGT_ADDR_T value; /* Symbol value */ UINT8 type; /* Symbol type */ UINT8 typeMask; /* Symbol type mask for lookup */ UINT16 group; /* Symbol group */ char * moduleName; /* Module name */ void * pReserved; /* Reserved */ struct wtx_symbol * next; /* ptr to next symbol in list */ } WTX_SYMBOL;WTX_SYMBOL is embedded in the following message:
typedef struct wtx_msg_symbol_desc /* Symbol message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_SYMBOL symbol; /* Symbol */ } WTX_MSG_SYMBOL_DESC;Note that fields in WTX_SYMBOL other that name, exactName, value, and type are ignored and are set to NULL.
- If value only is specified, search for value.
- If name only is specified, search for name.
- If value and type are specified, search for value and type.
- If name and type are specified, search for name and type.
When exactName is TRUE, WTX_SYM_FIND returns OK only for a symbol name exactly matching. When exactName is FALSE, symbols with a prefixed underscore (for example, _unSymbol) are returned as matches.
The request result is returned in a WTX_MSG_SYMBOL_DESC message filled with all the information about the symbol.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to find the symbol. If errCode is OK, WTX_MSG_SYMBOL_DESC is filled with all the symbol information.
Target server only
- WTX_ERR_SVR_INVALID_FIND_REQUEST
- Illegal combination of name, value, and type.
- WTX_ERR_SYMTBL_SYMBOL_NOT_FOUND
- The symbol is not found in the symbol table.
- TIMEOUT
- WTX RPC timeout.
WTX_SYM_FIND, WTX_SYM_ADD, WTX_SYM_REMOVE
WTX_SYM_LIST_GET - WTX get a list of symbols
INPUT: WTX_MSG_SYM_MATCH_DESC OUTPUT: WTX_MSG_SYM_LIST
This request lists all symbols in the system symbol table whose names match a given regular expression or whose values are around a given value. The name matching regular expression or the value for address lookup are passed in the message below:
typedef struct wtx_msg_sym_match_desc /* Symbol lookup descriptor */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 symTblId; /* Symbol table to look at */ BOOL32 matchString; /* Match string if TRUE, look */ /* Around adrs if FALSE */ TGT_ADDR_T adrs; /* Addr. around which to look */ char * stringToMatch; /* Substring to match */ BOOL32 byModuleName; /* TRUE if module name is given */ union { UINT32 moduleId; /* Module identifier */ char * moduleName; /* or module name */ } module; BOOL32 listUnknownSym; /* Get unknown symbols if TRUE */ BOOL32 giveMeNext; /* TRUE for a follow-up req */ } WTX_MSG_SYM_MATCH_DESC;When matchString is TRUE, the search is made using the regular expression found in stringToMatch. Otherwise the search is done by value around the value given in adrs.
When matchString is FALSE, this request lists the symbols in the system symbol table that are near a specified value. The symbols that are displayed include:
- symbols whose values are immediately less than the specified value
- symbols with the specified value
- succeeding symbols, until a maximum of 12 symbols have been listed
This request also returns symbols that are local.
In addition, moduleId or moduleName can be used to list symbols only in a given object module. If moduleId and moduleName are NULL, matching symbols in all object modules are listed.
Note that the symTblId field is not used and is set to NULL.
Symbols are returned in the WTX_MSG_SYM_LIST message below:
typedef struct wtx_msg_sym_list /* Symbol list message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_SYM_LIST symList; /* Symbol list */ BOOL32 moreToCome; /* TRUE if symbols are remaining */ } WTX_MSG_SYM_LIST;WTX_MSG_SYM_LIST contains a pointer to a singly linked list of symbols:
typedef struct wtx_sym_list /* Symbol list */ { WTX_SYMBOL * pSymbol; /* Start of symbol list */ } WTX_SYM_LIST;Each symbol is described by the structure:
typedef struct wtx_symbol /* Symbol descriptor */ { UINT32 status; /* Ret. val. for FIND request */ UINT32 symTblId; /* Symbol table id */ char * name; /* Symbol name */ BOOL32 exactName; /* FALSE if _name is OK */ TGT_ADDR_T value; /* Symbol value */ UINT8 type; /* Symbol type */ UINT8 typeMask; /* Symbol type mask for lookup */ UINT16 group; /* Symbol group */ char * moduleName; /* Module name */ void * pReserved; /* Reserved */ struct wtx_symbol * next; /* ptr to next symbol in list */ } WTX_SYMBOL;When more than 250 symbols need to be returned, moreToCome is set to TRUE. At this time the client should reissue a WTX_SYM_LIST_GET request with giveMeNext set to TRUE. This operation should be repeated until all the symbol list has been transferred from the target server, which is indicated by moreToCome set to FALSE. On the first WTX_SYM_LIST_GET, giveMeNext must be set to NULL.
When listUnknownSym is set to TRUE and a module name is given, this request returns the list of unknown symbols for the module.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to list the symbols. If errCode is OK, the pSymbol field in WTX_SYM_LIST points to a singly linked list of symbols.
Target server only
This service returns a maximum of 250 symbols when the search is name-based in order to limit the size of the request result. When the search is made around a given value, no more than 12 symbols are returned.
- TIMEOUT
- WTX RPC timeout.
WTX_SYM_FIND, WTX_SYM_ADD, WTX_SYM_REMOVE
WTX_SYM_REMOVE - WTX remove a symbol
INPUT: WTX_MSG_SYMBOL_DESC OUTPUT: WTX_MSG_RESULT
This request removes a symbol of specified name and type from the target-server-managed symbol table.
Only the name and value fields must be specified in WTX_SYMBOL. The other fields are ignored and are set to NULL.
The input message is:
typedef struct wtx_msg_symbol_desc /* Symbol message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_SYMBOL symbol; /* Symbol */ } WTX_MSG_SYMBOL_DESC;where WTX_SYMBOL is:
typedef struct wtx_symbol /* Symbol descriptor */ { UINT32 status; /* Ret. val. for FIND request */ UINT32 symTblId; /* Symbol table id */ char * name; /* Symbol name */ BOOL32 exactName; /* FALSE if _name is OK */ TGT_ADDR_T value; /* Symbol value */ UINT8 type; /* Symbol type */ UINT8 typeMask; /* Symbol type mask for lookup */ UINT16 group; /* Symbol group */ char * moduleName; /* Module name */ void * pReserved; /* Reserved */ struct wtx_symbol * next; /* ptr to next symbol in list */ } WTX_SYMBOL;The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;If symTblId is NULL, the system symbol table is used.
If the symbol is successfully removed, the other tools attached to the target server are notified of the symbol removal by a SYM_REMOVED name event. Note that there are no events associated with symbols removed by the WTX_OBJ_MODULE_UNLOAD request.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to remove the symbol.
Target server only
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the target server.
- WTX_ERR_SYMTBL_SYMBOL_NOT_FOUND
- The symbol does not exist in the symbol table.
- TIMEOUT
- WTX RPC timeout.
WTX_SYM_TBL_INFO_GET - WTX get information about a symbol table
INPUT: WTX_MSG_PARAM OUTPUT: WTX_MSG_SYM_TBL_INFO
This request returns information about a symbol table specified by param. Symbol table information includes the current number of symbols in the symbol table and the name clash policy.
If param.value_u.v_uint32 is 0, information about the system symbol table is returned.
typedef struct wtx_msg_param /* Simple request parameter */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE param; /* Param value of call */ } WTX_MSG_PARAM;The result is returned in the structure:
typedef struct wtx_msg_sym_tbl_info /* Symbol table information */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 symTblId; /* Symbol table identifier */ UINT32 symNum; /* Number of symbols */ BOOL32 sameNameOk; /* Name clash policy */ } WTX_MSG_SYM_TBL_INFO;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to get the symbol table information. If errCode is OK, the symNum field in WTX_MSG_SYM_TBL_INFO contains the number of symbols and sameNameOk is TRUE if symbols of the same name are allowed.
Target server only
- TIMEOUT
- WTX RPC timeout
WTX_TARGET_ATTACH - WTX attach a target to the target server
INPUT: WTX_MSG_TOOL_ID OUTPUT: WTX_MSG_RESULT
This request attempts to attach the target to the target server. It is used after a target is rebooted or started to attach an already-running but not connected target server. This is necessary because the target has no way to notify the target server that it just started.
typedef struct wtx_msg_tool_id /* Tool identifier message */ { WTX_CORE wtxCore; /* WTX message core */ } WTX_MSG_TOOL_ID;The result of this request is returned in a WTX_MSG_RESULT message. The val field is not used and is always set to NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;Note that all WTX requests except WTX_TOOL_ATTACH, WTX_TOOL_DETACH, WTX_OBJ_KILL, and WTX_TS_INFO_GET attempt to re-attach the target server to the target if it is found not to be attached.
None.
The errCode field in WTX_CORE contains OK, or an ERROR code if the target cannot be attached. OK is also returned if the target is already attached.
Target and target server
- WTX_ERR_SVR_TARGET_NOT_ATTACHED
- The attempt to attach the target failed. This could be related to the target not running or to a target-link failure.
- TIMEOUT
- WTX RPC timeout.
WTX_TARGET_RESET - WTX reset a target
INPUT: WTX_MSG_TOOL_ID OUTPUT: WTX_MSG_RESULT
This request resets the target. If the target is successfully reset, the target server is restarted after 1 second.
Note that the tool making the WTX_TARGET_RESET request needs to re-attach to the target server if the call is successful since the connection with the target server will be lost because of the target server restarting.
The tool making the request sends its identifier in WTX_MSG_TOOL_ID.
typedef struct wtx_msg_tool_id /* Tool identifier message */ { WTX_CORE wtxCore; /* WTX message core */ } WTX_MSG_TOOL_ID;The result is returned in:
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
If the call is successful, a TGT_RESET event is issued to all tools attached to the target server.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to reset the target.
Target and target server
- TIMEOUT
- WTX RPC timeout.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
WTX_TOOL_ATTACH, WTX_TOOL_DETACH
WTX_TOOL_ATTACH - WTX attach a tool to a target server
INPUT: WTX_MSG_TOOL_DESC OUTPUT: WTX_MSG_TOOL_DESC
This request attaches a tool to the target server. It adds the tool to the target server event-tool database. It must be the first call made to the target server. It returns a unique tool identifier that is used in all subsequent calls to the target server. Before issuing this request, a tool must ask the wtxregd daemon for the key associated with the target server.
The WTX_TOOL_DESC structure is used to send information about the tool to the target server and to return the tool identifier. Only the toolName field must be set as an input parameter. All the other fields are optional and are set to NULL if not used.
typedef struct wtx_tool_desc /* Tool descriptor */ { UINT32 id; /* Unique tool identifier */ char * toolName; /* Tool name */ char * toolArgv; /* Tool argv parameters */ char * toolVersion; /* Tool version */ char * userName; /* User name */ void * pReserved; /* Reserved */ struct wtx_tool_desc * next; /* ptr to next tool desc. */ } WTX_TOOL_DESC;WTX_TOOL_DESC is embedded in the WTX_MSG_TOOL_DESC message:
typedef struct wtx_msg_tool_desc /* Tool desc. message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_TOOL_DESC wtxToolDesc; /* Tool descriptor */ } WTX_MSG_TOOL_DESC;If toolName starts with "-" the tool is not added to the list of attached tools of the target server. This allows tools like the Tornado launcher to be hidden from the target server attached-tools list.
The target server does not automatically announce events to a tool attached by WTX_TOOL_ATTACH. To receive announcements, the tool must register for events using WTX_REGISTER_FOR_EVENT.
If the call is successful, a TOOL_ATTACH toolId event is issued to all the other tools attached to the target server.
The errCode field in WTX_CORE contains OK, or an ERROR code if the target server is not connected to a target or if a tool with the same name is already attached to the target server. If errCode is OK, the id field in WTX_TOOL_DESC contains a unique tool identifier and toolName contains the name of the tool.
Target server only
Attaching a Wind Shell tool version 1.0 used by user "Philippe" can be done by setting WTX_TOOL_DESC with:
/* clear tool descriptor message */ memset (&wtxMsgToolDesc.wtxToolDesc, 0, sizeof (wtxMsgToolDesc)); /* fill tool descriptor part of input message */ wtxMsgToolDesc.wtxToolDesc.toolName = "windsh"; wtxMsgToolDesc.wtxToolDesc.toolVersion = "1.0"; wtxMsgToolDesc.wtxToolDesc.userName = "Philippe";
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the target server.
- TIMEOUT
- WTX RPC timeout.
WTX_TOOL_DETACH, WTX_REGISTER_FOR_EVENT
WTX_TOOL_DETACH - WTX detach a tool from a target server
INPUT: WTX_MSG_TOOL_ID OUTPUT: WTX_MSG_RESULT
This request detaches a tool (previously attached with WTX_TOOL_ATTACH) specified by WTX_MSG_TOOL_ID from the target server. It removes the tool from the target server event-tool database.
typedef struct wtx_msg_tool_id /* Tool identifier message */ { WTX_CORE wtxCore; /* WTX message core */ } WTX_MSG_TOOL_ID;The result of this request is returned in a WTX_MSG_RESULT message. Note that the val field is not used and is always set to NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
If the call is successful, a TOOL_DETACH toolId event is issued to all the other tools attached to the target server.
The errCode field in WTX_CORE contains OK, or an ERROR code if the tool was not previously attached.
Target server only
To detach the tool whose ID is 0x270560 use:
wtxMsgTooId.wtxCore.objId = 0x270560;
- WTX_ERR_SVR_INVALID_CLIENT_ID
- Invalid client ID.
- TIMEOUT
- WTX RPC timeout.
WTX_TS_INFO_GET - WTX get target and target server information
INPUT: WTX_MSG_TOOL_ID OUTPUT: WTX_MSG_TS_INFO
This request returns information about the target server, the link between the target and the target server, and the target itself. It also returns information about all the tools attached to the target server.
The tool making the request sends its identifier, previously obtained by calling WTX_TOOL_ATTACH, in WTX_MSG_TOOL_ID.
typedef struct wtx_msg_tool_id /* Tool identifier message */ { WTX_CORE wtxCore; /* WTX message core */ } WTX_MSG_TOOL_ID;The information returned by this request is stored in a WTX_MSG_TS_INFO structure:
typedef struct wtx_msg_ts_info /* TS information message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_TGT_LINK_DESC tgtLinkDesc; /* Target link descriptor */ WTX_TGT_INFO tgtInfo; /* Info obtained from Target */ WTX_TOOL_DESC * pWtxToolDesc; /* Info about attached Tools */ char * version; /* Target Server version */ char * userName; /* Target server user name */ char * startTime; /* Target server start time */ char * accessTime; /* Target server access time */ char * lockMsg; /* Lock/authorization message */ void * pReserved; /* Reserved */ } WTX_MSG_TS_INFO;The target-to-target-server link information is stored in WTX_TGT_LINK_DESC:
typedef struct wtx_tgt_link_desc /* Link descriptor */ { char * name; /* Target/host link name */ UINT32 type; /* Target/host link type */ UINT32 speed; /* Target/host link speed */ } WTX_TGT_LINK_DESC;Target information is stored in WTX_TGT_INFO:
typedef struct wtx_tgt_info /* Target information */ { WTX_AGENT_INFO agentInfo; /* Info on the agent */ WTX_RT_INFO rtInfo; /* Info on the run time system */ } WTX_TGT_INFO;Target-agent information is stored in:
typedef struct wtx_agent_info /* Target agent information */ { char * agentVersion; /* WDB agent version */ UINT32 mtu; /* Max. transfer size (bytes) */ UINT32 mode; /* Available agent modes */ } WTX_AGENT_INFO;Target-operating-system information is stored in:
typedef struct wtx_rt_info /* Target runtime information */ { UINT32 rtType; /* Runtime type */ char * rtVersion; /* Run time version */ UINT32 cpuType; /* Target processor type */ BOOL32 hasFpp; /* Floating point unit avail. */ BOOL32 hasWriteProtect;/* Text write protect avail. */ UINT32 pageSize; /* Size of a page */ UINT32 endian; /* Endianness (LITTLE or BIG) */ char * bspName; /* Board support package name */ char * bootline; /* Boot file name */ TGT_ADDR_T memBase; /* Target main mem. base addr. */ UINT32 memSize; /* Target main mem. size */ UINT32 numRegions; /* Number of mem. regions */ WTX_MEM_REGION * memRegion; /* Mem. region descriptor(s) */ TGT_ADDR_T hostPoolBase; /* Tgtsvr mem. pool */ UINT32 hostPoolSize; /* Tgtsvr mem. pool size */ } WTX_RT_INFO;where WTX_MEM_REGION is:
typedef struct wtx_mem_region /* Memory region descriptor */ { TGT_ADDR_T baseAddr; /* Mem. region base address */ UINT32 size; /* Mem. region size */ UINT32 attribute; /* Mem. region attributes */ } WTX_MEM_REGION;The information about attached tools is returned in a singly linked list of the WTX_TOOL_DESC structure:
typedef struct wtx_tool_desc /* Tool descriptor */ { UINT32 id; /* Unique tool identifier */ char * toolName; /* Tool name */ char * toolArgv; /* Tool argv parameters */ char * toolVersion; /* Tool version */ char * userName; /* User name */ void * pReserved; /* Reserved */ struct wtx_tool_desc * next; /* ptr to next tool desc. */ } WTX_TOOL_DESC;Note that some fields in the return structure may be NULL if the related information is not available.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if the target is not attached to the target server.
Target server only
- WTX_ERR_SVR_TARGET_NOT_ATTACHED
- The target is not attached to the target server.
- TIMEOUT
- WTX RPC timeout.
WTX_TS_LOCK - WTX target server lock
INPUT: WTX_MSG_TS_LOCK OUTPUT: WTX_MSG_RESULT
This request is used to disable target server access for other users. The access lock can be removed using the WTX_TS_UNLOCK request. The lockType field is used to lock the target server a certain amount of time or indefinitely if this field is set to 0. Access to the target server is restricted to the user who issues the request.
typedef struct wtx_msg_ts_lock /* Lock message */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 lockType; /* Lock type to use */ } WTX_MSG_TS_LOCK;The result of this request is returned in a WTX_MSG_RESULT message. The val field is not used and is always set to NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if the lock descriptor is invalid.
Target server only
- TIMEOUT
- WTX RPC timeout.
WTX_TS_UNLOCK - WTX target server unlock
INPUT: WTX_MSG_TS_UNLOCK OUTPUT: WTX_MSG_RESULT
This request is used to unlock access to a target server previously locked by a WTX_TS_LOCK request. The force field is ignored. Target server access is granted to the default authorized users.
typedef struct wtx_msg_ts_unlock /* Unlock message */ { WTX_CORE wtxCore; /* WTX message core */ BOOL32 force; /* Force unlock type to use */ } WTX_MSG_TS_UNLOCK;The result of this request is returned in a WTX_MSG_RESULT message. The val field is not used and is always set to NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if the unlock descriptor is invalid.
Target server only
- TIMEOUT
- WTX RPC timeout.
WTX_UNREGISTER - WTX unregister a server
INPUT: WTX_MSG_PARAM OUTPUT: WTX_MSG_RESULT
This request unregisters a server using the WTX registry daemon wtxregd. The input parameter is a string containing the name of the server to unregister.
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to unregister the server.
WPWR registry only
- WTX_ERR_REGISTRY_NAME_NOT_FOUND
- No server with the given name exists in the registry.
- TIMEOUT
- WTX RPC timeout.
WTX_REGISTER, WTX_INFO_GET, WTX_INFO_Q_GET
WTX_UNREGISTER_FOR_EVENT - WTX unregister for events
INPUT: WTX_MSG_EVENT_REG_DESC OUTPUT: WTX_MSG_RESULT
This routine registers which events are unwanted.
typedef struct wtx_msg_event_reg_desc /* WTX event register desc. */ { WTX_CORE wtxCore; /* WTX message core */ char * evtRegExp; /* Register event reg. expr. */ } WTX_MSG_EVENT_REG_DESC;The regular expression in evtRegExp should match a list of events that the client tool does not want to be notified of.
All.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to unregister for events.
Target server only
- WTX_ERR_SVR_INVALID_CLIENT_ID
- The tool is not attached to the target server.
- TIMEOUT
- WTX RPC timeout.
WTX_REGISTER_FOR_EVENT, WTX_EVENT_GET, WTX_EVENT_LIST_GET, WTX_EVENT_ADD
WTX_VIO_CHAN_GET - WTX get a virtual I/O channel number
INPUT: WTX_MSG_TOOL_ID OUTPUT: WTX_MSG_RESULT
This request returns a free virtual I/O channel number to be used for redirection of target I/O to the host. The return channel number is a value between 1 and 255. Channel number 0 is the default channel. It is used by the default console when the target server -C option is used.
When no longer used, the channel number should be returned to the target server virtual I/O channel pool by means of the WTX_VIO_CHANNEL_RELEASE request.
The tool making the request sends its identifier in WTX_MSG_TOOL_ID.
typedef struct wtx_msg_tool_id /* Tool identifier message */ { WTX_CORE wtxCore; /* WTX message core */ } WTX_MSG_TOOL_ID;The channel number is returned as a 32-bit integer (type V_INT32) in:
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if there is no available channel number in the target server. If errCode is OK, the val field in WTX_MSG_RESULT returns a virtual I/O channel number.
Target server only
- WTX_ERR_SVR_NO_VIO_CHANNEL
- All target server channel numbers are in use.
- TIMEOUT
- WTX RPC timeout.
WTX_VIO_CHAN_RELEASE, WTX_VIO_CTL, WTX_VIO_FILE_LIST
WTX_VIO_CHAN_RELEASE - WTX release a virtual-I/O-channel number
INPUT: WTX_MSG_PARAM OUTPUT: WTX_MSG_RESULT
This request releases a virtual-I/O-channel number previously obtained by means of WTX_VIO_CHAN_GET and returns it to the free-channel-number pool of the target server. Valid channel numbers are in the range 1 to 255.
The channel number is passed as a 32-bit integer in WTX_MSG_PARAM.
typedef struct wtx_msg_param /* Simple request parameter */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE param; /* Param value of call */ } WTX_MSG_PARAM;The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if the channel number is invalid.
Target server only
- WTX_ERR_AGENT_INVALID_VIO_CHANNEL
- The virtual-I/O-channel number is not in the range 1...255.
- TIMEOUT
- WTX RPC timeout.
WTX_VIO_CHAN_GET, WTX_VIO_CTL, WTX_VIO_FILE_LIST
WTX_VIO_CTL - WTX virtual I/O control
INPUT: WTX_MSG_VIO_CTL_DESC OUTPUT: WTX_MSG_RESULT
This request performs a special function on the virtual I/O channel specified by the channel field of WTX_MSG_VIO_CTL_DESC. The input of this request is given by:
typedef struct wtx_msg_vio_ctl_desc /* VIO control descriptor */ { WTX_CORE wtxCore; /* WTX message core */ INT32 channel; /* VIO channel number */ UINT32 request; /* Control operation */ UINT32 arg; /* Control argument */ } WTX_MSG_VIO_CTL_DESC;The only currently supported control request, specified by request is:
- VIO_REDIRECT
- This request redirects the data from virtual-I/O-channel number channel to the arg file previously obtained with WTX_CONSOLE_CREATE or WTX_OPEN.
On a VxWorks-based target, virtual I/O channels can be created using:
/* initialize virtual I/O driver */ /* this routine should only be called once */ if (vioDrv != OK) return (ERROR); /* create virtual I/O channel 0 with a 512 bytes read buffer */ /* a 512 bytes write buffer and give it the name "/vio" */ if (vioDevCreate ("/vio", 0, 512, 512) != OK) return (ERROR); /* open a file on VIO channel 4 */ if ((fd = open ("/vio/4", O_RDWR, 0)) == ERROR) return (ERROR);The redirection is performed on the host with:/* open host file */ if ((fdHost = open ("/tmp/testfile", O_RDWR, 0)) == ERROR) return (ERROR); /* fill WTX_MSG_VIO_CTL_DESC structure */ wtxMsgVioCtlDesc.request = VIO_REDIRECT; wtxMsgVioCtlDesc.channel = 4; wtxMsgVioCtlDesc.arg = fdHost;Any data read or written to /vio/4 is transferred to or from the host and redirected to /tmp/testfile by the target server.The result of this request is returned in a WTX_MSG_RESULT message but the val field is not used and is always NULL.
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to perform the given request on the given channel.
Target server only
- WTX_ERR_SVR_INVALID_FILE_DESCRIPTOR
- Invalid WTX file descriptor.
- WTX_ERR_SVR_EINVAL
- Invalid WTX I/O control request.
- TIMEOUT
- WTX RPC timeout.
WTX_OPEN, WTX_VIO_WRITE, WTX_CLOSE, WTX_VIO_CHAN_GET
WTX_VIO_FILE_LIST - WTX list files managed by the target server
INPUT: WTX_MSG_TOOL_ID OUTPUT: WTX_MSG_VIO_FILE_LIST
This request returns a list of all the target-server-managed files along with information about each file including its name, state, and associated virtual-I/O-channel redirection.
The tool making the request sends its identifier in WTX_MSG_TOOL_ID.
typedef struct wtx_msg_tool_id /* Tool identifier message */ { WTX_CORE wtxCore; /* WTX message core */ } WTX_MSG_TOOL_ID;Each file, along with its information, is returned in a WTX_VIO_FILE_DESC structure:
typedef struct wtx_vio_file_desc /* Virtual file descriptor */ { char * name; /* File or device name */ INT32 fd; /* File descriptor */ INT32 channel; /* Channel for redirection */ INT32 fp; /* File pointer for streams */ INT32 type; /* File type */ INT32 mode; /* Open mode (O_RDONLY ...) */ INT32 status; /* Open or closed */ INT32 addlInfo; /* Extra info. (eg: process id) */ struct wtx_vio_file_desc * next; /* ptr to next desc. for list */ } WTX_VIO_FILE_DESC;The output of the WTX_VIO_FILE_LIST request is a singly linked list of WTX_VIO_FILE_DESC:
typedef struct wtx_msg_vio_file_list /* VIO files list message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VIO_FILE_DESC * pVioFileList; /* VIO file list */ } WTX_MSG_VIO_FILE_LIST;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if there is not enough memory on the target server to return the file list.
Target server only
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Not enough memory on the target server to store the VIO file list.
- TIMEOUT
- WTX RPC timeout.
WTX_OPEN, WTX_CLOSE, WTX_VIO_CHAN_GET
WTX_VIO_WRITE - WTX write to a virtual I/O channel
INPUT: WTX_MSG_VIO_CTL_DESC OUTPUT: WTX_MSG_RESULT
This request writes data to a target virtual I/O channel. The virtual-I/O-channel number to write to is obtained by a WTX_VIO_CHAN_GET request.
typedef struct wtx_msg_vio_copy_desc /* Virtual I/O data */ { WTX_CORE wtxCore; /* WTX message core */ UINT32 channel; /* Virtual I/O channel */ UINT32 maxBytes; /* Maximum bytes to transfer */ void * baseAddr; /* Base address of data */ } WTX_MSG_VIO_COPY_DESC;WTX_VIO_WRITE attempts to write maxBytes starting at host address baseAddr to virtual I/O channel number channel. The number of bytes actually written is limited by the smaller of the size of the virtual I/O device driver on the target or the maximum transmit unit (MTU) of the connection between the target server and the target.
On VxWorks-based targets, reading data from a virtual I/O channel can be done as follows:
/* open a virtual I/O file associated with virtual I/O channel 4 */ if ((fd = open ("/vio/4", 2, 0)) == ERROR) return (ERROR); /* allocate room for data read */ if ((buff = malloc (1000)) == NULL) return (ERROR); /* read up to 100 bytes of data from virtual I/O channel 0 */ if ((numBytesRead = read (fd, buff, 100)) == ERROR) return (ERROR);This request result is returned in:
typedef struct wtx_msg_result /* Simple request result */ { WTX_CORE wtxCore; /* WTX message core */ WTX_VALUE val; /* Result value of call */ } WTX_MSG_RESULT;
This request has no associated events.
The errCode field in WTX_CORE contains OK, or an ERROR code if unable to write to the specified channel. If errCode is OK, the val field in WTX_MSG_RESULT contains the number of bytes actually written.
Target only
- WTX_ERR_AGENT_INVALID_VIO_CHANNEL
- This virtual I/O channel is not available on the target system.
- WTX_ERR_AGENT_COMMUNICATION_ERROR
- Failure while communicating with the target.
- TIMEOUT
- WTX RPC timeout.
WTX_VIO_CTL, WTX_VIO_READ, WTX_VIO_CHAN_GET