Tornado API Reference : WTX C Library
wtx - WTX C library
wtxToolAttach( ) - connect a WTX client to the target server
wtxToolConnected( ) - check to see if a tool is connected to a target server
wtxToolDetach( ) - detach from the target server
wtxInitialize( ) - initialization routine to be called by the WTX client
wtxTerminate( ) - terminate the use of a WTX client handle
wtxErrSet( ) - set the error code for the handle
wtxErrGet( ) - return the last error for a handle
wtxErrHandlerAdd( ) - add an error handler for the WTX handle
wtxErrHandlerRemove( ) - remove an error handler from the WTX handle
wtxErrDispatch( ) - dispatch an error with supplied code for the given handle
wtxErrMsgGet( ) - fetch the last network WTX API error string
wtxErrToMsg( ) - convert an WTX error code to a descriptive string
wtxErrClear( ) - explicitly clear any error status for the tool
wtxErrExceptionFunc( ) - a function to handle an error using longjmp( )
wtxClientDataGet( ) - get the client data associated with the WTX handle
wtxClientDataSet( ) - set the client data associated with the WTX handle
wtxAgentModeGet( ) - get the mode of the target agent
wtxAgentModeSet( ) - set the mode of the target agent
wtxAsyncNotifyEnable( ) - start the asynchronous event notification
wtxAsyncNotifyDisable( ) - stop the asynchronous event notification
wtxBreakpointAdd( ) - create a new WTX eventpoint of type breakpoint
wtxCacheTextUpdate( ) - synchronize the instruction and data caches.
wtxCommandSend( ) - Pass a string to be interpreted by the target server
wtxTargetIpAddressGet( ) - gets target IP address.
wtxCpuInfoGet( ) - gets cpu related information from architecturedb file
wtxEventpointAdd( ) - create a new WTX eventpoint
wtxEventpointDelete( ) - delete an eventpoint from the target
wtxConsoleCreate( ) - create a console window (UNIX only)
wtxConsoleKill( ) - destroy a console (UNIX only)
wtxContextCont( ) - continue execution of a target context
wtxContextCreate( ) - create a new context on the target
wtxContextResume( ) - resume execution of a target context
wtxContextStatusGet( ) - get the status of a context on the target
wtxContextExitNotifyAdd( ) - add a context exit notification eventpoint
wtxContextKill( ) - kill a target context
wtxContextStep( ) - single step execution of a target context
wtxContextSuspend( ) - suspend a target context
wtxEventAdd( ) - send an event to the target server
wtxEventGet( ) - get an event from the target
wtxEventListGet( ) - get all the events in one call.
wtxEventpointList( ) - list eventpoints on the target server
wtxEventpointListGet( ) - list eventpoints on the target server
wtxFileClose( ) - close a file on the target server
wtxFileOpen( ) - open a file on the target server
wtxHwBreakpointAdd( ) - create a new WTX eventpoint of type hardware breakpoint
wtxSymListFree( ) - free memory used to store symbols in a list
wtxResultFree( ) - free the memory used by a WTX API call result
wtxGopherEval( ) - evaluate a Gopher string on the target
wtxLogging( ) - WDB / WTX requests logging controls
wtxMemInfoGet( ) - get information about the target-server-managed memory pool
wtxMemAlloc( ) - allocate a block of memory to the TS-managed target memory pool
wtxMemChecksum( ) - perform a checksum on target memory
wtxMemMove( ) - move a block of target memory
wtxMemFree( ) - free a block of target memory
wtxMemRead( ) - read memory from the target
wtxMemWidthRead( ) - read memory from the target
wtxMemWrite( ) - write memory on the target
wtxMemWidthWrite( ) - write memory on the target
wtxMemSet( ) - set target memory to a given value
wtxMemAddToPool( ) - add memory to the agent pool
wtxMemRealloc( ) - reallocate a block of target memory
wtxMemAlign( ) - allocate aligned target memory
wtxMemScan( ) - scan target memory for the presence or absence of a pattern
wtxObjModuleChecksum( ) - checks validity of target memory.
wtxObjModuleFindId( ) - find the ID of an object module given its name
wtxObjModuleFindName( ) - find object module name given its ID
wtxObjModuleInfoGet( ) - return information on a module given its module ID
wtxObjModuleInfoAndPathGet( ) - return information on a module given its ID
wtxObjModuleList( ) - fetch a list of loaded object modules from the target
wtxObjModuleLoad( ) - Load a multiple section object file
wtxObjModuleLoadStart( ) - Load a multiple section object file asynchronously
wtxObjModuleLoadProgressReport( ) - get the asynchronous load status
wtxObjModuleLoadCancel( ) - Stop an asynchronous load request
wtxObjModuleUnload( ) - unload an object module from the target
wtxObjModuleByNameUnload( ) - unload an object module from the target
wtxRegisterForEvent( ) - ask the WTX server to send events matching a regexp
wtxRegsGet( ) - read register data from the target
wtxRegsSet( ) - write to registers on the target
wtxStrToTgtAddr( ) - convert a string argument to a TGT_ADDR_T value
wtxStrToContextId( ) - convert a string argument to a WTX_CONTEXT_ID_T
wtxStrToContextType( ) - convert a string argument to a WTX_CONTEXT_TYPE value
wtxStrToInt32( ) - convert a string argument to an INT32 value
wtxStrToEventType( ) - convert a string to a WTX event enumeration type
wtxEventToStrType( ) - convert a WTX event enumeration type to a string
wtxServiceAdd( ) - add a new service to the agent
wtxSymAdd( ) - add a symbol with the given name, value, and type
wtxSymAddWithGroup( ) - add a symbol with the given name, value, type and group
wtxSymFind( ) - find information on a symbol given its name or value
wtxSymListGet( ) - get a list of symbols matching the given search criteria
wtxSymListByModuleIdGet( ) - get a list of symbols given a module Id
wtxSymListByModuleNameGet( ) - get a list of symbols given a module name
wtxSymRemove( ) - remove a symbol from the default target server symbol table
wtxSymTblInfoGet( ) - return information about the target server symbol table
wtxTargetReset( ) - reset the target
wtxTsNameGet( ) - get the full name of the currently attached target server
wtxTargetRtTypeGet( ) - get the target-runtime-type information
wtxTargetRtVersionGet( ) - get the target-runtime-version information
wtxTargetCpuTypeGet( ) - get the target CPU type code
wtxTargetHasFppGet( ) - check if the target has a floating point processor
wtxTargetEndianGet( ) - get the endianness of the target CPU
wtxTargetBootlineGet( ) - get the target bootline information string
wtxTargetBspNameGet( ) - get the target board-support-package name string
wtxToolNameGet( ) - return the name of the current tool
wtxTsVersionGet( ) - return the Tornado version
wtxTsKill( ) - kill the target server
wtxTsRestart( ) - restart the target server
wtxUnregisterForEvent( ) - ask the target server to not send events matching
wtxFuncCall( ) - call a function on the target
wtxDirectCall( ) - call a function on the target within the agent
wtxTsInfoGet( ) - get information about the target server, the target, and the link to the target
wtxTsLock( ) - lock the connected target server for exclusive access
wtxTsTimedLock( ) - lock the connected target server a limited time
wtxTsUnlock( ) - unlock the connected target server
wtxVerify( ) - verify that a WTX handle is valid for use
wtxVioChanGet( ) - get a virtual I/O channel number
wtxVioChanRelease( ) - release a virtual I/O channel
wtxVioCtl( ) - perform a control operation on a virtual I/O channel
wtxVioFileList( ) - list the files managed by the target server
wtxVioWrite( ) - write data to a VIO channel
wtxTargetAttach( ) - reattach to the target
wtxProbe( ) - probe to see if the registry service is running
wtxRegister( ) - register the target server with the Tornado registry service
wtxUnregister( ) - unregister the server with the Tornado registry
wtxInfo( ) - allocate and return a descriptor for the named service
wtxInfoQ( ) - return a list of all services registered with the Tornado registry
wtxEach( ) - call a routine to examine each WTX-registered service
wtxTimeoutSet( ) - set the timeout for completion of WTX calls
wtxTimeoutGet( ) - get the current timeout for completion of WTX calls
wtxToolIdGet( ) - return the tool identifier of the current tool
wtxMemDisassemble( ) - get disassembled instructions matching the given address
wtxAsyncEventGet( ) - get an event from the asynchronous event list
wtxAsyncResultFree( ) - free memory used by a wtxAsyncEventGet( ) call result
This module implements a C-language transport-neutral interface to the WTX messaging protocol.
A tool must always call wtxInitialize( ) to initialize a handle that is used in all further WTX calls. The tool can then attach to a target server using a call to wtxToolAttach( ). Each WTX handle can only be connected to one server at a time. After a successful call of wtxToolAttach( ), the handle is considered bound to the specified target server until a call of wtxToolDetach( ) is made; then the handle can be attached to a new target server. When the handle is no longer required, call wtxTerminate( ) to release any internal storage used by the handle. The handle must not be used after wtxTerminate( ) has been called.
#include "wtx.h" HWTX hWtx; /* initialize WTX session handle */ if (wtxInitialize (&hWtx) != WTX_OK) return (WTX_ERROR); /* attach to Target Server named "soubirou" */ if (wtxToolAttach (hWtx, "soubirou", "wtxApp") != WTX_OK) return (WTX_ERROR); /* register for events we want to hear about (all events here) */ if (wtxRegisterForEvent (hWtx, ".*") != WTX_OK) { wtxToolDetach (hWtx); return (WTX_ERROR); } /* core of the WTX application */ . . . . /* detach form the Target Server */ wtxToolDetach (hWtx); /* terminate WTX session */ wtxTerminate (hWtx);Most WTX calls return either a pointer value which is NULL on error or a STATUS value which is WTX_ERROR if an error occurs. A descriptive string can be obtained for the last error that occurred by calling wtxErrMsgGet( ).Note that virtually all WTX calls can fail due to an error in the message transport layer used to carry out WTX requests. Transport errors that are non-recoverable result in the tool being detached from the server and an error code of WTX_ERR_API_TOOL_DISCONNECTED. If a non-fatal error occurs, WTX_ERR_API_REQUEST_FAILED is set, except in the case of a timeout. In that case the error is WTX_ERR_API_REQUEST_TIMED_OUT. In the non-fatal cases, the call may be retried. In the fatal case, retrying the call results in the error WTX_ERR_API_NOT_CONNECTED.
All API calls attempt to check the validity of the API handle provided. The error WTX_ERR_API_INVALID_HANDLE indicates a bad handle. Other pointer arguments are checked and WTX_ERR_API_INVALID_ARG indicates a bad argument value such as a NULL pointer. API calls that require the handle to be connected to a target server generate the WTX_ERR_API_NOT_CONNECTED error if the handle is not connected.
In addition to simple error return values, the C API allows error handlers to be installed on a per handle basis using wtxErrHandlerAdd( ). If an error occurs, the last installed handler is called first. If it returns a TRUE value, then any previously installed handlers are called in reverse order, in other words, last installed, first called. The C API includes macros that use the predefined error handler wtxErrExceptionFunc( ) to support C++ style exception catching. Once an API handle has been initialized using wtxInitiliaze( ), it can be used in the WTX_TRY macro to cause API errors to be treated like exceptions. When this is done, an API call that would normally return an error code actually causes a jump straight to the nearest catch handler as specified using a WTX_CATCH or WTX_CATCH_ALL macro. The previous example is shown below using this style of error handling.
#include "wtx.h" HWTX hWtx; /* initialize WTX session handle */ if (wtxInitialize (&hWtx) != WTX_OK) return (WTX_ERROR); /* Start a block in which errors will be "caught" by a catch block */ WTX_TRY (hWtx) { /* attach to Target Server named "soubirou" */ wtxToolAttach (hWtx, "soubirou", "wtxApp"); /* register for events we want to hear about (all events here) */ wtxRegisterForEvent (hWtx, ".*"); /* core of the WTX application */ . . . . /* detach form the Target Server */ wtxToolDetach (hWtx); } /* Catch a specific error, WTX_ERR_API_NOT_CONNECTED */ WTX_CATCH (hWtx, WTX_ERR_API_NOT_CONNECTED) { fprintf (stderr, "Connection lost, exiting\n"); wtxTerminate (hWtx); exit (0); } /* Catch any other errors in one handler and print error message */ WTX_CATCH_ALL (hWtx) fprintf (stderr, "%s\n", wtxErrMsgGet (hWtx)); /* Finish the try block and resume normal error handling */ WTX_TRY_END (hWtx); /* * Normal error handling is now restored - the WTX_TRY_END macro * must be executed for this to occur. */ /* wtxTerminate() will also detach the tool if already attached */ wtxTerminate (hWtx);In certain circumstances, it may be useful to generate a user-defined error or to simulate an API error from within user code. This may be done using the WTX_THROW macro, which causes execution to jump to the nearest handler for the error thrown or to the nearest "catch all" handler.Many of the C API calls are very similar to the equivalent WTX protocol calls and the user may also refer to the appropriate section in the WTX Protocol reference for further information.
wtx.h
wtxToolAttach( ) - connect a WTX client to the target server
STATUS wtxToolAttach ( HWTX hWtx, /* WTX API handle */ const char * serverName, /* Target Server name */ const char * toolName /* tool name */ )
This routine establishes a connection to the target server called serverName and announces the client as a WTX tool called toolName. If serverName does not contain an @ character, it is used as a regular expression; if it matches more than one (registered) target server name, an error is returned. If serverName contains an @ character then it must be an exact match for a valid target server name.
WTX_OK or WTX_ERROR if the attach fails.
- WTX_ERR_API_ALREADY_CONNECTED
- The handle is already connected to a target server.
- WTX_ERR_API_SERVER_NOT_FOUND
- serverName does not match a target server name using the above criteria.
- WTX_ERR_API_AMBIGUOUS_SERVER_NAME
- serverName matches more than one target server name.
- WTX_ERR_SVR_DOESNT_RESPOND
- serverName is dead : no RPC connection can be achieved
- WTX_ERR_SVR_IS_DEAD
- serverName is dead : server has been found dead
WTX_TOOL_ATTACH, wtxToolDetach( ), wtxToolConnected( ), wtxInfoQ( )
wtxToolConnected( ) - check to see if a tool is connected to a target server
BOOL32 wtxToolConnected ( HWTX hWtx /* WTX API handle */ )
This routine checks if the tool represented by hWtx is currently connected to a target server.
If hWtx is an invalid handle then FALSE is returned.
TRUE if the tool is connected, FALSE otherwise.
wtxErrClear( ), wtxErrGet( )
wtxToolDetach( ) - detach from the target server
STATUS wtxToolDetach ( HWTX hWtx /* WTX API handle */ )
This routine detaches from the target server. The connection status for hWtx is cleared and any memory allocated by the tool attach is freed.
Even if the detach fails internally (for example, the server it is attached to has died), the API still puts the handle into a detached state and performs all necessary internal cleanup. In this case the internal error is not reported since the tool is no longer attached and the handle can subsequently be attached to another server.
WTX_OK or WTX_ERROR.
WTX_TOOL_DETACH, wtxToolAttach( )
wtxInitialize( ) - initialization routine to be called by the WTX client
STATUS wtxInitialize ( HWTX * phWtx /* RETURN: handle to use in subsequent API calls */ )
This routine allocates a handle structure for the tool's use and does any initialization required for use of the WTX interface. All subsequent calls by the tool should use the handle returned in phWtx. If WTX_ERROR is returned and the handle phWtx is zero, then the initialization failed because the internal handle structure could not be allocated. Otherwise use wtxErrMsgGet( ) to find the cause of the error.
WTX_OK or WTX_ERROR if the initialization fails.
- WTX_ERR_API_INVALID_ARG
- The pointer phWtx is NULL.
- WTX_ERR_API_MEMALLOC
- The handle cannot be allocated.
wtxTerminate( ), wtxVerify( )
wtxTerminate( ) - terminate the use of a WTX client handle
STATUS wtxTerminate ( HWTX hWtx /* WTX API handle */ )
This routine destroys the specified context handle so it may no longer be used in WTX API calls. If the tool is attached to a target server, it is first detached. (It is forcibly detached if errors make a normal detach impossible.) Any memory allocated by the handle is freed and the handle is invalidated; any subsequent use causes an abort.
WTX_OK or WTX_ERROR.
wtxInitialize( ), wtxVerify( )
wtxErrSet( ) - set the error code for the handle
STATUS wtxErrSet ( HWTX hWtx, /* WTX API handle */ UINT32 errCode /* error value to set */ )
This routine sets the error value errCode in the handle specified by hWtx so that wtxErrGet( ) can return errCode as the error.
Error handlers for the handle are not called. To set the error code and call the registered error handlers, use wtxErrDispatch( ).
WTX_OK or WTX_ERROR.
wtxErrGet( ), wtxErrMsgGet( ), wtxErrClear( ), wtxErrDispatch( ).
wtxErrGet( ) - return the last error for a handle
WTX_ERROR_T wtxErrGet ( HWTX hWtx /* WTX API handle */ )
This routine returns the last error that occurred for the hWtx handle. The error code is only valid after an error is reported by one of the API calls. To check for an error after a series of API calls use wtxErrClear( ) to clear the error status at the start and call wtxErrGet( ) at the end.
The last error code or WTX_ERROR if the handle is invalid.
wtxErrMsgGet( ), wtxErrSet( ), wtxErrClear( )
wtxErrHandlerAdd( ) - add an error handler for the WTX handle
WTX_HANDLER_T wtxErrHandlerAdd ( HWTX hWtx, /* WTX API handle */ WTX_HANDLER_FUNC pFunc, /* function to call on error */ void * pClientData /* data to pass function */ )
This routine adds a new error handler to the list of registered handlers for the handle hWtx. The last error handler added is the first one called when an error occurs. The function pFunc is called with three arguments, the handle on which the error occurred, the client data pClientData, and a call data parameter which is the error code. If the function returns the value TRUE then each previously registered handler function is called in turn until all are called or one returns the value FALSE.
The following is a sample error handler:
BOOL32 errorHandler ( HWTX hWtx, /* WTX API handle */ void * pClientData, /* client data from wtxErrHandlerAdd() call */ void * errCode /* error code passed from wtxErrDispatch() */ ) { /* print an error message */ fprintf (stderr, "Error %s (%d) from server %s\n", wtxErrMsgGet (hWtx), (WTX_ERROR_T) errCode, /* or use wtxErrGet() */ wtxTsNameGet (hWtx)); /* return TRUE allowing previously installed handlers to be called */ return TRUE; }
A new handler ID or NULL on failure.
- WTX_ERR_API_MEMALLOC
- No memory is available to add the new handler.
wtxErrHandlerRemove( ), wtxErrDispatch( )
wtxErrHandlerRemove( ) - remove an error handler from the WTX handle
STATUS wtxErrHandlerRemove ( HWTX hWtx, /* WTX API handle */ WTX_HANDLER_T errHandler /* Error handler to remove */ )
This function removes the error handler referenced by errHandler from the handler list for hWtx. The error handler ID errHandler must be a valid error handler ID returned by a call of wtxErrHandlerAdd( ).
It is safe for wtxErrHandlerRemove( ) to be called from within an error handler function, even if the call is to remove itself.
WTX_OK or WTX_ERROR.
- WTX_ERR_API_HANDLER_NOT_FOUND
- errHandler is not a valid handler ID.
wtxErrHandlerAdd( ), wtxErrDispatch( )
wtxErrDispatch( ) - dispatch an error with supplied code for the given handle
STATUS wtxErrDispatch ( HWTX hWtx, /* WTX API handle */ WTX_ERROR_T errCode /* error code to register */ )
This function records the error errCode against the handle hWtx and calls all the registered error handlers for it until one returns FALSE.
WTX_OK or WTX_ERROR if the handle is invalid.
wtxErrMsgGet( ) - fetch the last network WTX API error string
const char * wtxErrMsgGet ( HWTX hWtx /* WTX API handle */ )
This routine gets a meaningful string for the last WTX API call that returned WTX_ERROR. The string is only valid after a WTX call has returned an error.
The return value is a pointer to internal data and must not be freed by the caller. Also the string is only valid until the next error occurs or wtxErrClear( ) is called. It must be copied by the caller if the value must be stored.
A pointer to a string or NULL if an error has occurred.
wtxErrClear( ), wtxErrGet( )
wtxErrToMsg( ) - convert an WTX error code to a descriptive string
const char * wtxErrToMsg ( HWTX hWtx, WTX_ERROR_T errCode )
This routine takes an error code which has been returned by a WTX API call and returns a descriptive string. The value returned is a pointer to a string in statically allocated memory. The string must be copied if the value is to be stored and it must not be freed by the caller.
A pointer to an error string.
wtxErrClear( ) - explicitly clear any error status for the tool
STATUS wtxErrClear ( HWTX hWtx /* WTX API handle */ )
This routine clears an error message already recorded. It can be called before a WTX routine if you want to test for an error afterwards by checking whether wtxErrGet( ) returns a non-zero value.
WTX_OK or WTX_ERROR.
wtxErrGet( ), wtxErrMsgGet( ), wtxErrSet( )
wtxErrExceptionFunc( ) - a function to handle an error using longjmp( )
BOOL32 wtxErrExceptionFunc ( HWTX hWtx, /* WTX API handle */ void * pClientData, /* pointer to a jump buffer */ void * pCallData /* error code to return via setjmp() */ )
This function is called as part of the error handling process shown in the discussion of C++ style exception catching in the wtx library description (WTX C Library). The WTX_TRY macro, which registers the error handler wtxErrExceptionFunc( ), is found in wtx.h. pClientData contains the address of jumpBuf from WTX_TRY and pCallData is the error code that is returned by WTX_TRY and should be cast to the type WTX_ERROR_T..
FALSE if pClientData is NULL, otherwise it does not return. It executes a longjmp( ) back to jumpBuf in the WTX_TRY macro, which returns the error code passed back by pCallData.
wtxErrHandlerAdd( ), wtxErrDispatch( )
wtxClientDataGet( ) - get the client data associated with the WTX handle
STATUS wtxClientDataGet ( HWTX hWtx, /* WTX API handle */ void * * ppClientData /* RETURN: pointer to client data pointer */ )
This routine sets the pointer pointed at by ppClientData to the value set by the last call to wtxClientDataSet( ) for the handle hWtx.
WTX_OK or WTX_ERROR.
- WTX_ERR_API_INVALID_ARG
- ppClientData is NULL.
wtxClientDataSet( ) - set the client data associated with the WTX handle
STATUS wtxClientDataSet ( HWTX hWtx, /* WTX API handle */ void * pClientData /* value to associate with handle */ )
This routine causes the value pClientData to be associated with the WTX API handle hWtx. The client data can be used by the caller in any way and, except when in the set and get routines, is not used or altered in any way by the WTX API. The initial value of the client data before it is set is always NULL.
WTX_OK or WTX_ERROR.
wtxClientDataGet( ).
wtxAgentModeGet( ) - get the mode of the target agent
WTX_AGENT_MODE_TYPE wtxAgentModeGet ( HWTX hWtx /* WTX API handle */ )
This routine returns the running mode of the target agent that the current target server is attached to.
typedef enum wtx_agent_mode_type /* debug agent running mode */ { WTX_AGENT_MODE_TASK = 1, /* run in task mode */ WTX_AGENT_MODE_EXTERN = 2, /* run in system mode */ WTX_AGENT_MODE_BI = 3 /* bimodal agent */ } WTX_AGENT_MODE_TYPE;
The current agent running mode or WTX_ERROR.
WTX_AGENT_MODE_GET, wtxTsInfoGet( ), wtxAgentModeSet( )
wtxAgentModeSet( ) - set the mode of the target agent
STATUS wtxAgentModeSet ( HWTX hWtx, /* WTX API handle */ WTX_AGENT_MODE_TYPE agentMode /* debug agent mode */ )
This routine sets the mode of the target agent that the current target server is attached to. A given agent may not support all the possible modes.
typedef enum wtx_agent_mode_type /* debug agent running mode */ { WTX_AGENT_MODE_TASK = 1, /* run in task mode */ WTX_AGENT_MODE_EXTERN = 2, /* run in system mode */ WTX_AGENT_MODE_BI = 3 /* bimodal agent */ } WTX_AGENT_MODE_TYPE;
WTX_OK or WTX_ERROR.
WTX_AGENT_MODE_SET, wtxTsInfoGet( ), wtxAgentModeGet( )
wtxAsyncNotifyEnable( ) - start the asynchronous event notification
STATUS wtxAsyncNotifyEnable ( HWTX hWtx, /* WTX API handle */ FUNCPTR pFunc /* User defined function */ )
This function creates a socket-based link between the target server and the client where events will be sent. If a user defined function is given (pFunc != NULL) then this function is called each time an event is received by the target server, this function must take a WTX_EVENT_DESC as input parameter. If no user defined function is given then received events are just stored in the asynchronous event list, those events can be get using wtxAsyncEventGet( ).
In conjunction with wtxAsyncNotifyEnable( ), wtxRegisterForEvent( ) (or wtxUnregisterForEvent( )) must be used to specify which type of events must be sent to the requester.
Upon calling this function, the wtxEventGet( ) and wtxEventListGet( ) routines will always return nothing.
When an event is coming to the client, the event is put in an WTX_EVENT_DESC structure and passed to the user provided function pointed to by pFunc.
All strings contained in the WTX_EVENT_DESC structure must be copied before to be used because their life duration is depending on the events stream.
The user defined function must take a WTX_EVENT_DESC * as input parameter. It is called each time an event is received by the target server.
This service uses WTX_COMMAND_SEND request of the WTX protocol.
Declaration of a simple event handler.
LOCAL void eventHookRtn /* Hook routine used by the notification */ ( WTX_EVENT_DESC * event /* Event received from the target server */ ) { /* Just print the event string and exit */ if (event->event != NULL) printf ("Received event: %s\n", event->event); }Start of the asynchronous notification from the C API.
/* Initialization */ . . /* Start the notification */ if (wtxAsyncNotifyEnable (wtxh, (FUNCPTR) eventHookRtn) != (UINT32) WTX_OK) return (WTX_ERROR); /* core of the WTX application */ . .
WTX_OK or WTX_ERROR if the request failed.
- WTX_ERR_API_SERVICE_ALREADY_STARTED
- An wtxAsyncNotifyDisable must be called before.
- WTX_ERR_API_CANT_OPEN_SOCKET
- Socket creation, bind or listen failed.
- WTX_ERR_API_CANT_GET_HOSTNAME
- Cannot get name of current host.
WTX_COMMAND_SEND, wtxAsyncNotifyEnable( ), wtxAsyncEventGet( )
wtxAsyncNotifyDisable( ) - stop the asynchronous event notification
STATUS wtxAsyncNotifyDisable ( HWTX hWtx /* WTX API handle */ )
This function sends to the target server an order to stop the asynchronous notification of events.
This service uses WTX_COMMAND_SEND request of the WTX protocol.
WTX_OK or WTX_ERROR if exchange failed.
WTX_COMMAND_SEND, wtxAsyncNotifyEnable( ), wtxAsyncEventGet( )
wtxBreakpointAdd( ) - create a new WTX eventpoint of type breakpoint
UINT32 wtxBreakpointAdd ( HWTX hWtx, /* WTX API handle */ WTX_CONTEXT_TYPE contextType, /* type of context to put bp in */ WTX_CONTEXT_ID_T contextId, /* associated context */ TGT_ADDR_T tgtAddr /* breakpoint address */ )
This routine creates a new eventpoint on the target to represent a breakpoint at the address tgtAddr for the target context contextId. The target server maintains a list of eventpoints created on the target and this can be queried using wtxEventpointList( ). When a context is destroyed on the target or the target is reset, eventpoints are deleted automatically without intervention from the creator.
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;When contextType is set to WTX_CONTEXT_SYSTEM, then only breakpoints in system mode can be added. When contextType is set to WTX_CONTEXT_TASK, then only breakpoints in context task can be added.
The ID of the new breakpoint or WTX_ERROR if the add fails.
WTX_EVENTPOINT_ADD, wtxEventpointAdd( ), wtxEventpointDelete( ), wtxEventpointList( )
wtxCacheTextUpdate( ) - synchronize the instruction and data caches.
STATUS wtxCacheTextUpdate ( HWTX hWtx, /* WTX API handle */ TGT_ADDR_T addr, /* remote addr to update */ UINT32 nBytes /* number of bytes to update */ )
This function flushes the data chache, then invalidates the instruction cache. This operation forces the instruction cache to fetch code that may have been created via the data path.
- WTX_ERR_API_INVALID_ARG
- nBytes is invalid.
WTX_OK or WTX_ERROR if exchange failed.
WTX_CACHE_TEXT_UPDATE, wtxMemRead( ), wtxMemWrite( )
wtxCommandSend( ) - Pass a string to be interpreted by the target server
char * wtxCommandSend ( HWTX hWtx, /* WTX API handle */ char * commandString /* String to be interpreted */ )
This function is used to control the target server behavior. Services availables are: wtxTsKill( ), wtxTsRestart( ), wtxLogging (), wtxTsLock( ), wtxTsUnlock( ), wtxTargetReset( ), wtxAsyncNotifyEnable( ), wtxAsyncNotifyDisable( ).
This service sends a string to the target server which interprets it. If the requested service is not known by tsWtxCommandSend( ), then the string is sent back to the client.
The following is a sample of string
commandString = "wtxTsLock_30"; /* lock the target server for 30s */ commandString = "wtxTsUnlock"; /* Unlock the target server */ commandString = "wtxLoggingOn_/folk/pascal/wtx.txt"; /* wtx log started */
A separator is used ("_") and only some command strings can be recognized by the target server (plus options if needed):
- 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.
- wtxTargetIpAddressGet
- Get the target's IP address (if applicable) in a.b.c.d form.
string containing the command's result.
wtxTsKill( ), wtxTsRestart( ), wtxLogging( ), wtxTsLock( ), wtxTsUnlock( ), wtxTargetReset( ), wtxAsyncNotifyEnable( ), wtxAsyncNotifyDisable( )
wtxTargetIpAddressGet( ) - gets target IP address.
UINT32 wtxTargetIpAddressGet ( HWTX hWtx /* WTX API handle */ )
This routine returns the target's IP address in network byte order. The returned address is the one used by the target server to connect the target.
On error (the target have no IP address), this value will be (UINT32) 0.
the target's IP address in network byte order or 0 on error.
wtxCpuInfoGet( ) - gets cpu related information from architecturedb file
char * wtxCpuInfoGet ( int cpuNum, /* cpu number to get info on */ CPU_INFO cpuInfoType /* cpu info type to get */ )
This function allows to get target CPU related informations. cpuNum specifies the CPU number in data base, while cpuInfoType specifies which parameter to get.
cpuInfoType can be from the following type
typedef enum cpu_info /* available cpu information types */ { CPU_INFO_NONE = 0, /* no info needed */ ARCH_DIR = 1, /* target architecture directory */ LEADING_CHAR = 2, /* symbols prepended character */ DEMANGLER = 3, /* target symbol demangler name */ CPU_NAME = 4 /* target CPU name */ } CPU_INFO;
returned value if not NULL should be freed by caller
a string containing parameter in string format or NULL.
wtxTsInfoGet( )
wtxEventpointAdd( ) - create a new WTX eventpoint
UINT32 wtxEventpointAdd ( HWTX hWtx, /* WTX API handle */ WTX_EVTPT_2 * pEvtpt /* eventpoint descriptor */ )
This routine creates a new eventpoint on the target. This routine is a generic facility for setting breakpoints. An eventpoint specifies the context to which it applies, the type of event to detect (for example breakpoint, context exit), and the action to be taken upon detection of the event (for example, notify the target server of the event).
The target server maintains a list of eventpoints created on the target and this can be queried using wtxEventpointList( ). When a context is destroyed on the target or the target is reset, eventpoints are deleted automatically without intervention from the creator.
When pEvtpt-context.contextType> is set to WTX_CONTEXT_SYSTEM, then only eventpoints in system mode can be added. When pEvtpt-context.contextType> is set to WTX_CONTEXT_TASK, then only eventpoints in context task can be added.
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;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;If contextType is set to WTX_CONTEXT_TASK and contextId set to 0, then it is equivalent to contextType set to WTX_CONTEXT_ANY_TASK.
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 ID of the new eventpoint or WTX_ERROR if the add fails.
WTX_EVENTPOINT_ADD_2, wtxEventpointDelete( ), wtxEventpointList( )
wtxEventpointDelete( ) - delete an eventpoint from the target
STATUS wtxEventpointDelete ( HWTX hWtx, /* WTX API handle */ UINT32 evtptId /* ID of eventpoint to delete */ )
This routine deletes an existing eventpoint in the context given when it was created. The eventpoint is identified by evtptId which is the ID returned by wtxBreakpointAdd( ), wtxContextExitNotifyAdd( )... If the eventpoint has already been deleted on the target (for example, because the context associated with it no longer exists), then the first call of wtxEventpointDelete( ) returns WTX_OK. (The target server ignores the deletion of a valid eventpoint ID that no longer exists on the target.) If the target server eventpoint list does not contain the evtptId, then the error WTX_ERR_SVR_INVALID_EVENTPOINT occurs.
WTX_OK or WTX_ERROR if the delete fails.
WTX_EVENTPOINT_DELETE, wtxBreakpointAdd( ), wtxContextExitNotifyAdd( ), wtxEventpointAdd( ), wtxHwBreakpointAdd( ), wtxEventpointList( )
wtxConsoleCreate( ) - create a console window (UNIX only)
INT32 wtxConsoleCreate ( HWTX hWtx, /* WTX API handle */ const char * name, /* Name of console window */ const char * display, /* Display name eg: host:0 */ INT32 * fdIn, /* RETURN: input file descriptor */ INT32 * fdOut /* RETURN: output file descriptor */ )
This routine creates a new console window. The name passed in name is used as the title for the new window. If name is NULL, a unique name is assigned by the target server. When the target server is running in an X-Window environment, the display parameter identifies the X display device to create the window on. 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. The fdIn and fdOut parameters are pointers to INT32 variables in which are stored the target server file descriptors for the input and output of the new console. wtxVioCtl( ) can be used to redirect VIO input and output to the console.
On UNIX systems the returned ID is actually a process ID of the new console running on the same host as the target server.
This request is not implemented on Windows. Windows allows only one virtual console and it must be started on the target server command line with the -c option.
The ID number of the new console or WTX_ERROR.
- WTX_ERR_API_INVALID_ARG
- Either fdIn or fdOut is NULL.
WTX_CONSOLE_CREATE, wtxConsoleKill( ), wtxVioCtl( )
wtxConsoleKill( ) - destroy a console (UNIX only)
STATUS wtxConsoleKill ( HWTX hWtx, /* WTX API handle */ INT32 consoleId /* id of console to destroy */ )
This routine destroys a console identified by consoleId and created by a previous call to wtxConsoleCreate( ).
This request is not implemented on Windows. If issued, it returns an error, but does not attempt to kill an existing console.
WTX_OK or WTX_ERROR.
WTX_CONSOLE_KILL, wtxConsoleCreate( )
wtxContextCont( ) - continue execution of a target context
STATUS wtxContextCont ( HWTX hWtx, /* WTX API handle */ WTX_CONTEXT_TYPE contextType, /* type of context to continue */ WTX_CONTEXT_ID_T contextId /* id of context to continue */ )
This routine synchronously continues execution of the context contextId on the target after it has stopped at a breakpoint. This routine should be used instead of wtxContextResume( ) when debugging a task to prevent the task hitting the breakpoint a second time.
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;
WTX_OK or WTX_ERROR on failure.
WTX_CONTEXT_CONT, wtxContextResume( ), wtxBreakpointAdd( )
wtxContextCreate( ) - create a new context on the target
WTX_CONTEXT_ID_T wtxContextCreate ( HWTX hWtx, /* WTX API handle */ WTX_CONTEXT_DESC * pContextDesc /* context descriptor */ )
This routine creates a new context using the information in the context descriptor pointed to by pContextDesc which describes parameters for a new task context or a system context. The caller is responsible for freeing information supplied in the context descriptor after the call.
typedef struct wtx_context_desc /* context creation desc. */ { WTX_CONTEXT_TYPE contextType; /* context type */ WTX_RETURN_TYPE returnType; /* int or double */ char * name; /* name */ UINT32 priority; /* priority */ UINT32 options; /* 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 NULL */ INT32 redirOut; /* redir. out file or NULL */ TGT_ARG_T args[WTX_MAX_ARG_CNT]; /* arguments */ } WTX_CONTEXT_DESC;
- WTX_ERR_API_INVALID_ARG
- pContextDesc is invalid
The ID of the new context or WTX_ERROR.
WTX_CONTEXT_CREATE, wtxContextKill( )
wtxContextResume( ) - resume execution of a target context
STATUS wtxContextResume ( HWTX hWtx, /* WTX API handle */ WTX_CONTEXT_TYPE contextType, /* type of context to resume */ WTX_CONTEXT_ID_T contextId /* id of context to resume */ )
This routine synchronously resumes execution of the context contextId on the target after it has been suspended, perhaps by wtxContextSuspend( ). Use wtxContextCont( ) rather than this routine to continue a task from a breakpoint; this routine causes the task to hit the breakpoint again.
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;
WTX_OK or WTX_ERROR on failure.
WTX_CONTEXT_RESUME, wtxContextSuspend( )
wtxContextStatusGet( ) - get the status of a context on the target
WTX_CONTEXT_STATUS wtxContextStatusGet ( HWTX hWtx, /* WTX API handle */ WTX_CONTEXT_TYPE contextType, /* type of context */ WTX_CONTEXT_ID_T contextId /* id of context */ )
This routine returns the status of the context contextId on the target.
typedef enum wtx_context_status /* context status */ { WTX_CONTEXT_RUNNING = 0, /* context is running */ WTX_CONTEXT_SUSPENDED = 1 /* context is suspended */ } WTX_CONTEXT_STATUS;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;
The status of the context or WTX_ERROR.
WTX_CONTEXT_STATUS_GET, wtxContextSuspend( ), wtxContextResume( )
wtxContextExitNotifyAdd( ) - add a context exit notification eventpoint
UINT32 wtxContextExitNotifyAdd ( HWTX hWtx, /* WTX API handle */ WTX_CONTEXT_TYPE contextType, /* type of context */ WTX_CONTEXT_ID_T contextId /* associated context */ )
This routine creates a new eventpoint that notifies the user when the specified context exits by sending a WTX_EVT_CTX_EXIT event. The eventpoint is removed automatically when the context exits or the routine wtxEventpointDelete( ) can be used to remove the eventpoint before the context exits.
When contextType is set to WTX_CONTEXT_SYSTEM, then only eventpoints in system mode can be added. When contextType is set to WTX_CONTEXT_TASK, then only eventpoints in context task can be added.
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;
A unique identifier for the new eventpoint or WTX_ERROR.
WTX_EVENTPOINT_ADD, wtxEventpointAdd( ), wtxEventpointList( ), wtxEventpointDelete( )
wtxContextKill( ) - kill a target context
STATUS wtxContextKill ( HWTX hWtx, /* WTX API handle */ WTX_CONTEXT_TYPE contextType, /* type of context to kill */ WTX_CONTEXT_ID_T contextId /* id of context to kill */ )
This routine synchronously kills the context specified by contextId on the target.
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;
Killing the the system context may result in a reboot of the target. However, the correct way to reboot the target system is by calling wtxTargetReset( ).
WTX_OK or WTX_ERROR if the context kill fails.
WTX_CONTEXT_KILL, wtxTargetReset( )
wtxContextStep( ) - single step execution of a target context
STATUS wtxContextStep ( HWTX hWtx, /* WTX API handle */ WTX_CONTEXT_TYPE contextType, /* type of context to resume */ WTX_CONTEXT_ID_T contextId, /* id of context to step */ TGT_ADDR_T stepStart, /* stepStart pc value */ TGT_ADDR_T stepEnd /* stepEnd PC vale */ )
This routine asynchronously single steps execution of a context on the target. Stepping occurs while stepStart <= PC < stepEnd. If stepStart == stepEnd == 0 then the context is single stepped one machine instruction only. Note that stepStart does not set the initial program counter; this must be done separately.
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;
Stepping is an asynchronous operation so the return of this function does not signify completion of the stepping. After stepping completes, a breakpoint event is generated at the address which terminated the stepping operation.
WTX_OK or WTX_ERROR if the step fails.
WTX_CONTEXT_STEP, wtxContextCont( ), wtxContextSuspend( )
wtxContextSuspend( ) - suspend a target context
STATUS wtxContextSuspend ( HWTX hWtx, /* WTX API handle */ WTX_CONTEXT_TYPE contextType, /* type of context to suspend */ WTX_CONTEXT_ID_T contextId /* id of context being suspended */ )
This routine synchronously suspends execution of a context on the target.
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;
WTX_OK or WTX_ERROR if the suspend fails.
wtxEventAdd( ) - send an event to the target server
STATUS wtxEventAdd ( HWTX hWtx, /* WTX API handle */ const char * event, /* event string to send */ UINT32 addlDataLen, /* length of addl data block in bytes */ const void * pAddlData /* pointer to additional data */ )
This routine sends an event to the target server. The target server adds it to the event list of any attached tool that has selected that event by using wtxRegisterForEvent( ) with a suitable event pattern. The event is not sent back to the tool that generated it.
typedef struct wtx_msg_event_desc /* Event message */ { WTX_CORE wtxCore; /* WTX message core */ WTX_EVENT_DESC eventDesc; /* Event descriptor */ } WTX_MSG_EVENT_DESC;
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;
WTX_OK or WTX_ERROR.
WTX_EVENT_ADD, wtxEventGet( ), wtxEventListGet( ), wtxRegisterForEvent( ), wtxUnregisterForEvent( ).
wtxEventGet( ) - get an event from the target
WTX_EVENT_DESC * wtxEventGet ( HWTX hWtx /* WTX API handle */ )
This routine polls the target server for any events sent to this client tool. It only returns one event at a time. The event descriptor returned is a string containing the primary event data, a length count of additional binary data and a pointer to the additional data. The memory allocated for the event-descriptor result must be freed by the user using wtxResultFree( ). Note that an event descriptor is always returned even when no real event is ready for the tool. In this case the event descriptor is WTX_EVENT_OTHER, addlDataLen is 0, and addlData is NULL.
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;
A pointer to the descriptor for the event received or NULL.
WTX_EVENT_GET, wtxEventAdd( ), wtxEventListGet( ), wtxResultFree( ), wtxStrToEventType( ), wtxStrToInt( ), wtxStrToTgtAddr( )
wtxEventListGet( ) - get all the events in one call.
WTX_EVENT_NODE * wtxEventListGet ( HWTX hWtx, /* WTX API handle */ UINT32 nEvents /* Number of events to return */ )
This function flushes the target server events queue. If more than one event is found, WTX_EVENT_NODE structure is filled with the events found up to the limit fixed by nEvents. If nEvents is equal to 1, then this function is equivalent to wtxEventGet( ). If all the events will have to be flushed, then nEvents must be equal to WTX_ALL_EVENTS.
WTX_EVENT_NODE contains a WTX_EVENT_DESC structure and a pointer to the next WTX_EVENT_NODE (or NULL if it is the last event).
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;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;
A pointer to the event list or NULL if there's no events or if something failed (errCode must be checked).
WTX_EVENT_LIST_GET, wtxEventGet( ), wtxEventAdd( ), wtxRegisterForEvent( ), wtxUnregisterForEvent( )
wtxEventpointList( ) - list eventpoints on the target server
WTX_EVTPT_LIST * wtxEventpointList ( HWTX hWtx /* WTX API handle */ )
This routine returns a pointer to a list of all eventpoints managed by the target server. These include breakpoints and context exit notifications. The list returned is dynamically allocated and should be freed by calling wtxResultFree( )
typedef struct wtx_evtpt_list /* eventpoint list message */ { UINT32 nEvtpt; /* num. eventpoint in list */ WTX_EVTPT * pEvtpt; /* eventpoint list */ } WTX_EVTPT_LIST;
A pointer to a list of eventpoints or NULL on error.
WTX_EVENTPOINT_LIST, wtxEventpointAdd( ), wtxBreakpointAdd( ), wtxContextExitNotifyAdd( )
wtxEventpointListGet( ) - list eventpoints on the target server
WTX_EVTPT_LIST_2 * wtxEventpointListGet ( HWTX hWtx /* WTX API handle */ )
This routine returns a pointer to a list of eventpoints info: eventpoints managed by the target server, the tool identifier and the eventpoint identifier.
typedef struct wtx_evtpt_list_2 /* eventpoint list message */ { UINT32 nEvtpt; /* num. eventpoint in list */ WTX_EVTPT_INFO * pEvtptInfo; /* eventpoint info list */ } WTX_EVTPT_LIST_2;
A pointer to an eventpoints info list or NULL on error.
WTX_EVENTPOINT_LIST_GET, wtxEventpointList( ), wtxBreakpointAdd( ), wtxContextExitNotifyAdd( ), wtxHwBreakpointAdd( ), wtxEventpointAdd( )
wtxFileClose( ) - close a file on the target server
STATUS wtxFileClose ( HWTX hWtx, /* WTX API handle */ INT32 fileDescriptor /* file to close descriptor */ )
This routine closes the file previously opened in a call of wtxFileOpen( ) and cancels any VIO redirection caused by that open.
WTX_OK or WTX_ERROR.
WTX_CLOSE, wtxFileOpen( )
wtxFileOpen( ) - open a file on the target server
INT32 wtxFileOpen ( HWTX hWtx, /* WTX API handle */ const char * fileName, /* file name */ WTX_OPEN_FLAG flags, /* unix style flags */ INT32 mode, /* unix style mode */ INT32 channel /* channel id for redirection */ )
This routine requests that the target server open a file in the host environment and optionally redirects I/O from a VIO channel to it. The user may select which VIO channel is redirected to and from the file by specifying the channel argument.
Valid values for the flags parameter can be:
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 target server runs on a WINDOWS host, the RDONLY flags are not supported. If an RDONLY flag is given for flags variable, a WTX_ERR_SVR_INVALID_FLAGS error will be returned. This is due to the lack of pipe opening on WINDOWS hosts.
fileName must specify a file accessible from the host where the target server is running.
A file descriptor on success or WTX_ERROR if the open fails.
WTX_OPEN, wtxFileClose( )
wtxHwBreakpointAdd( ) - create a new WTX eventpoint of type hardware breakpoint
UINT32 wtxHwBreakpointAdd ( HWTX hWtx, /* WTX API handle */ WTX_CONTEXT_TYPE contextType, /* type of context to put bp in */ WTX_CONTEXT_ID_T contextId, /* associated context */ TGT_ADDR_T tgtAddr, /* breakpoint address */ TGT_INT_T type /* access type (arch dependant) */ )
This routine creates a new eventpoint on the target to represent a hardware breakpoint of type type at the address tgtAddr for the target context contextId. The target server maintains a list of eventpoints created on the target and this can be queried using wtxEventpointList( ). When a context is destroyed on the target or the target is reset, eventpoints are deleted automatically without intervention from the creator.
When contextType is set to WTX_CONTEXT_SYSTEM, then only eventpoints in system mode can be added. When contextType is set to WTX_CONTEXT_TASK, then only eventpoints in context task can be added.
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;
The types of hardware breakpoints vary with the architectures. Generally, a hardware breakpoint can be a data breakpoint or an instruction breakpoint.
The ID of the new breakpoint or WTX_ERROR if the add fails.
WTX_EVENTPOINT_ADD_2, wtxEventpointAdd( ), wtxEventpointDelete( ), wtxEventpointList( ), wtxBreakpointAdd( )
wtxSymListFree( ) - free memory used to store symbols in a list
void wtxSymListFree ( WTX_SYM_LIST * pSymList /* symbol list to free */ )
This routine frees the memory associated with each node in a symbol list.
The symbol list to free is defined by:
typedef struct wtx_sym_list /* Symbol list */ { WTX_SYMBOL * pSymbol; /* Start of symbol list */ } WTX_SYM_LIST;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;
N/A
wtxResultFree( ) - free the memory used by a WTX API call result
STATUS wtxResultFree ( HWTX hWtx, /* WTX API handle */ void * pResult /* pointer to WTX result structure */ )
This routine frees the memory allocated for the result of a WTX API call. pResult must point to a WTX structure that was returned by a WTX API call.
To ensure correct and complete freeing of memory allocated to API call results, use wtxResultFree( ) to free target server call results before calling wtxToolDetach( ) and to free registry call results before calling wtxTerminate( ).
WTX_OK or WTX_ERROR.
wtxGopherEval( ) - evaluate a Gopher string on the target
WTX_GOPHER_TAPE * wtxGopherEval ( HWTX hWtx, /* WTX API handle */ const char * inputString /* Gopher program to evaluate */ )
This routine evaluates the Gopher string inputString and populates the Gopher result tape WTX_GOPHER_TAPE with the result data. It is the caller's duty to free the result tape by calling wtxResultFree( ).
typedef struct wtx_gopher_tape /* Gopher tape */ { UINT16 len; /* Length of tape */ char * data; /* Tape data */ } WTX_GOPHER_TAPE;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 6For an example showing how to format the Gopher result tape, see API Programmer's Guide: The WTX Protocol.
A pointer to the Gopher result tape or NULL on error.
wtx, WTX_GOPHER_EVAL, API Reference Manual: WTX Protocol WTX_GOPHER_EVAL, API Programmer's Guide: The WTX Protocol
wtxLogging( ) - WDB / WTX requests logging controls
STATUS wtxLogging ( HWTX hWtx, /* WTX API handle */ int type, /* LOG_WDB, LOG_WTX or LOG_ALL logging */ int action, /* Logging LOG_ON or LOG_OFF */ char * fileName, /* Logging file name */ int maxSize, /* log file max size */ char * filter /* Filter for the log file. */ )
This function allows control of WDB / WTX requests logging.
Options available for the WTX log request are:
- LOG_ON
- Start the logging service
- LOG_OFF
- Stop the logging service
- filename
- Name where info will be written
- maxSize
- Maximum size of the log file
- regExp
- Regular expression used to filter events
Options available for the WDB log request are:
- LOG_ON
- Start the logging service
- LOG_OFF
- Stop the logging service
- filename
- Name where info will be written
- maxSize
- Maximum size of the log file
By default, there's no maximum size (maxSize is set to WTX_LOG_NO_LIMIT) and regExp is set to "WTX_EVENT_GET".
Start the WTX logging with a file never bigger than 10000 bytes and containing all WTX requests except "WTX_TOOL_ATTACH".
wtxLogging ( hWtx, /* WTX API handle */ LOG_WTX, /* WTX logging */ LOG_ON, /* start logging */ "/folk/pascal/wtx.txt", /* log file name */ 10000, /* log max size */ "WTX_TOOL_ATTACH" /* never printed */ );Start the WTX logging without size limit and with a default WTX requests filter.
wtxLogging ( hWtx, /* WTX API handle */ LOG_WTX, /* WTX logging */ LOG_ON, /* start logging */ "/folk/pascal/wtx.txt", /* log file name */ WTX_LOG_NO_LIMIT, /* no max size */ NULL /* default filter */ );Stop the WTX and the WDB logging in one call: fileName, maxSize and filter are not used in this case and may be set to a default value.
wtxLogging ( hWtx, /* WTX API handle */ LOG_ALL, /* WTX WDB log */ LOG_OFF, /* stop logging */ NULL, /* not used */ WTX_LOG_NO_LIMIT, /* not used */ NULL /* not used */ );
WTX_OK or WTX_ERROR
- WTX_ERR_API_INVALID_ARG
- fileName is NULL or an argument is wrong
wtxMemInfoGet( ) - get information about the target-server-managed memory pool
WTX_MEM_INFO * wtxMemInfoGet ( HWTX hWtx /* WTX API handle */ )
This routine queries the target server to find out information about the target-server-managed target memory pool. The result is a pointer to a WTX_MEM_INFO structure that must be freed by a user call to wtxResultFree( ).
typedef struct wtx_mem_info /* memory information */ { 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_MEM_INFO;
Pointer to the module info or NULL on failure.
WTX_MEM_INFO_GET, wtxMemAlloc( ).
wtxMemAlloc( ) - allocate a block of memory to the TS-managed target memory pool
TGT_ADDR_T wtxMemAlloc ( HWTX hWtx, /* WTX API handle */ UINT32 numBytes /* size to allocate in bytes */ )
This routine allocates numBytes of memory on the target. The block location and alignment are unspecified.
The address of the target memory allocated or NULL on error.
wtxMemChecksum( ) - perform a checksum on target memory
UINT32 wtxMemChecksum ( HWTX hWtx, /* WTX API handle */ TGT_ADDR_T startAddr, /* remote addr to start checksum at */ UINT32 numBytes /* number of bytes to checksum */ )
This routine returns a checksum for numBytes of memory starting at address startAddr. Errors must be detected by using the wtxErrXXX( ) routines.
A checksum value.
wtxMemMove( ) - move a block of target memory
STATUS wtxMemMove ( HWTX hWtx, /* WTX API handle */ TGT_ADDR_T srcAddr, /* remote addr to move from */ TGT_ADDR_T destAddr, /* remote addr to move to */ UINT32 numBytes /* number of bytes to move */ )
This routine moves numBytes from srcAddr to destAddr. Note that the source and destination buffers may overlap.
WTX_OK or WTX_ERROR.
wtxMemFree( ) - free a block of target memory
STATUS wtxMemFree ( HWTX hWtx, /* WTX API handle */ TGT_ADDR_T address /* target memory block address to free */ )
This routine frees a target memory block previously allocated with wtxMemAlloc( ).
WTX_OK or WTX_ERROR.
wtxMemRead( ) - read memory from the target
UINT32 wtxMemRead ( HWTX hWtx, /* WTX API handle */ TGT_ADDR_T fromAddr, /* Target addr to read from */ void * toAddr, /* Local addr to read to */ UINT32 numBytes /* Bytes to read */ )
This routine reads numBytes of memory from the target starting at fromAddr and writes the contents to toAddr.
Because the target agent tests that all memory is readable, this routine can never do a partial read. The return value is always numBytes or WTX_ERROR.
- WTX_ERR_API_INVALID_ARG
- toAddr or numBytes is invalid.
The number of bytes read (see note) or WTX_ERROR.
wtxMemWidthRead( ) - read memory from the target
UINT32 wtxMemWidthRead ( HWTX hWtx, /* WTX API handle */ TGT_ADDR_T fromAddr, /* Target addr to read from */ void * toAddr, /* Local addr to read to */ UINT32 numBytes, /* Bytes to read */ UINT8 width /* Value width in bytes */ )
This routine reads numBytes (on width bytes large) from the target starting at fromAddr and writes the contents to toAddr.
Because the target agent tests that all memory is readable, this routine can never do a partial read. The return value is always numBytes or WTX_ERROR.
This request is not implemented on WDB side, wtxMemWidthRead( ) is mapped on wtxMemRead( ) and the width parameter is simply ignored.
- WTX_ERR_API_INVALID_ARG
- toAddr, numBytes or width is invalid
The number of bytes read (see note) or WTX_ERROR.
WTX_MEM_WIDTH_READ, wtxMemRead( ), wtxMemWidthWrite( )
wtxMemWrite( ) - write memory on the target
UINT32 wtxMemWrite ( HWTX hWtx, /* WTX API handle */ void * fromAddr, /* Local addr to write from */ TGT_ADDR_T toAddr, /* Remote addr to write to */ UINT32 numBytes /* Bytes to read */ )
This routine writes numBytes of memory to toAddr on the target from the local address fromAddr.
Because the target agent tests that all memory is writable, this routine can never do a partial write. The return value is always numBytes or WTX_ERROR.
- WTX_ERR_API_INVALID_ARG
- fromAddr or numBytes is invalid.
The number of bytes written (see note) or WTX_ERROR.
wtxMemWidthWrite( ) - write memory on the target
UINT32 wtxMemWidthWrite ( HWTX hWtx, /* WTX API handle */ void * fromAddr, /* Local addr to write from */ TGT_ADDR_T toAddr, /* Remote addr to write to */ UINT32 numBytes, /* Bytes to read */ UINT8 width /* Width value: 1, 2, 4 bytes */ )
This routine writes numBytes (on width bytes large) at toAddr on the target from the local address fromAddr.
Because the target agent tests that all memory is writable, this routine can never do a partial write. The return value is always numBytes or WTX_ERROR.
This request is not implemented on WDB side, wtxMemWidthWrite( ) is mapped on wtxMemWrite( ) and the width parameter is simply ignored.
- WTX_ERR_API_INVALID_ARG
- fromAddr, numBytes or width is invalid
The number of bytes written (see note) or WTX_ERROR.
WTX_MEM_WIDTH_WRITE, wtxMemWrite( ), wtxMemWidthRead( )
wtxMemSet( ) - set target memory to a given value
UINT32 wtxMemSet ( HWTX hWtx, /* WTX API handle */ TGT_ADDR_T addr, /* remote addr to write to */ UINT32 numBytes, /* number of bytes to set */ UINT32 val /* value to set */ )
This routine sets numBytes at address addr to the value val.
WTX_OK or WTX_ERROR.
wtxMemAddToPool( ) - add memory to the agent pool
STATUS wtxMemAddToPool ( HWTX hWtx, /* WTX API handle */ TGT_ADDR_T address, /* base of memory block to add */ UINT32 size /* size of memory block to add */ )
This function adds the block of memory starting at address and spanning size bytes to the agent pool, enlarging it. It is possible to enlarge the agent pool with memory obtained from the runtime memory manager or with any currently unclaimed memory.
WTX_OK or WTX_ERROR.
WTX_MEM_ADD_TO_POOL, wtxMemInfoGet( ), wtxMemAlloc( ), wtxMemRealloc( ), wtxMemFree( )
wtxMemRealloc( ) - reallocate a block of target memory
TGT_ADDR_T wtxMemRealloc ( HWTX hWtx, /* WTX API handle */ TGT_ADDR_T address, /* memory block to reallocate */ UINT32 numBytes /* new size */ )
This function changes the size of the block starting at address to numBytes bytes and returns the address of the block (which may have moved).
The address of the target memory reallocated or NULL on error.
WTX_MEM_REALLOC, wtxMemAlloc( )
wtxMemAlign( ) - allocate aligned target memory
TGT_ADDR_T wtxMemAlign ( HWTX hWtx, /* WTX API handle */ TGT_ADDR_T alignment, /* alignment boundary */ UINT32 numBytes /* size of block to allocate */ )
This function allocates a block of memory of numBytes bytes aligned on a alignment-byte boundary. alignment must be a power of 2.
The address of the target memory allocated or NULL on error.
wtxMemScan( ) - scan target memory for the presence or absence of a pattern
STATUS wtxMemScan ( HWTX hWtx, /* WTX API handle */ BOOL32 match, /* Match/Not-match pattern boolean */ TGT_ADDR_T startAddr, /* Target address to start scan */ TGT_ADDR_T endAddr, /* Target address to finish scan */ UINT32 numBytes, /* Number of bytes in pattern */ void * pattern, /* Pointer to pattern to search for */ TGT_ADDR_T * pResult /* Pointer to result address */ )
This routine scans the target memory from startAddr to endAddr. When match is set to TRUE, the first address containing the pattern pointed to by pattern is returned. When match is FALSE, the first address not matching pattern is returned. pattern is a pointer to a host array of byte values of length numBytes. If the pattern cannot be found then an error is returned.
WTX_OK or WTX_ERROR.
wtxObjModuleChecksum( ) - checks validity of target memory.
STATUS wtxObjModuleChecksum ( HWTX hWtx, /* WTX API handle */ INT32 moduleId, /* Module Id */ char * fileName /* Module name */ )
This routine compares object module checksum on target with object module checksum in target server memory cache. This is a way to control the target memory integrity. If moduleId is set to WTX_ALL_MODULE_ID or fileName set to "WTX_ALL_MODULE_CHECK" then all modules will be checked.
Because elf modules may have more than 1 section of text, text sections are gathered in a text segment. But, if on the target memory (or in the module) sections are contigous, they may not be contigous 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.
- WTX_ERR_API_MEMALLOC
- fileName buffer cannot be allocated
- WTX_ERR_API_INVALID_ARG
- moduleId or fileName invalid
WTX_OK or WTX_ERROR if exchange failed
WTX_OBJ_MODULE_CHECKSUM, wtxObjModuleList( ), wtxMemChecksum( )
wtxObjModuleFindId( ) - find the ID of an object module given its name
UINT32 wtxObjModuleFindId ( HWTX hWtx, /* WTX API handle */ const char * moduleName /* object module file name */ )
This routine returns the ID of the object module that was loaded from the file with the name moduleName. The object name must not include any directory components as this is not stored in the object module.
The object module ID or WTX_ERROR.
WTX_OBJ_MODULE_FIND, wtxObjModuleFindName( ), wtxObjModuleInfoGet( )
wtxObjModuleFindName( ) - find object module name given its ID
char * wtxObjModuleFindName ( HWTX hWtx, /* WTX API handle */ UINT32 moduleId /* id of module to find object name of */ )
This routine returns the name of the object for the module that has the ID moduleId. The name returned is the name of the object file from which it was loaded and does not include the directory where the object file was loaded. The returned string must be freed by the user calling wtxResultFree( ).
- WTX_ERR_API_INVALID_ARG
- moduleId is invalid
The object module filename or NULL.
WTX_OBJ_MODULE_FIND, wtxObjModuleFindId( ), wtxObjModuleInfoGet( )
wtxObjModuleInfoGet( ) - return information on a module given its module ID
WTX_MODULE_INFO * wtxObjModuleInfoGet ( HWTX hWtx, /* WTX API handle */ UINT32 modId /* id of module to look for */ )
This routine returns a pointer to a module information structure for the module with the supplied ID modId. The module information must be freed by the user calling wtxResultFree( ).
typedef struct wtx_module_info /* object module information */ { 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_MODULE_INFO;where OBJ_SEGMENT is:
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;
- WTX_ERR_API_INVALID_ARG
- modId is invalid
A pointer to the module information structure or NULL on error.
WTX_OBJ_MODULE_INFO_GET, wtxObjModuleList( )
wtxObjModuleInfoAndPathGet( ) - return information on a module given its ID
WTX_MODULE_INFO * wtxObjModuleInfoAndPathGet ( HWTX hWtx, /* WTX API handle */ UINT32 modId /* id of module to look for */ )
This routine returns a pointer to a module information structure for the module with the supplied ID modId. The module information must be freed by the user calling wtxResultFree( ).
This request returned the complete pathname in the name field of the result.
typedef struct wtx_module_info /* object module information */ { 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_MODULE_INFO;where OBJ_SEGMENT is:
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;
- WTX_ERR_API_INVALID_ARG
- modId is invalid
A pointer to the module information structure or NULL on error.
WTX_OBJ_MODULE_INFO_GET, wtxObjModuleInfoGet( ), wtxObjModuleList( )
wtxObjModuleList( ) - fetch a list of loaded object modules from the target
WTX_MODULE_LIST * wtxObjModuleList ( HWTX hWtx /* WTX API handle */ )
This routine queries the target server symbol table for a list of loaded modules. A pointer to the module list is returned and must be freed by the caller using wtxResultFree( ).
typedef struct wtx_module_list /* object module list */ { UINT32 numObjMod; /* number of module in list */ UINT32 * modIdList; /* list of object module id */ } WTX_MODULE_LIST;
A pointer to the module list or NULL on error.
WTX_OBJ_MODULE_LIST, wtxObjModuleInfoGet( )
wtxObjModuleLoad( ) - Load a multiple section object file
WTX_LD_M_FILE_DESC * wtxObjModuleLoad ( HWTX hWtx, /* WTX API handle */ WTX_LD_M_FILE_DESC * pFileDesc /* Module descriptor */ )
This routine loads a module onto the target and into the target server module table. The caller should pass in a pointer to a WTX_LD_M_FILE_DESC structure:
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 user must set the filename field to the name of the file containing the object module and the loadFlag to the loader flags required:
- 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
When no section description is given and nSections is set to zero, the host-based loader allocates memory for the text, data and bss sections of the module using memory from the target memory pool. If the nSections field is non-zero, the user can specify the location to load the sections and the section field points to an array of section descriptors:
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 the load is successful, the return value is a pointer to a file descriptor for the new object module containing the actual information about the file loaded. If there are undefined symbols in the module, undefSymList points to a list of those symbols that were not resolved:
typedef struct wtx_sym_list /* Symbol list */ { WTX_SYMBOL * pSymbol; /* Start of symbol list */ } WTX_SYM_LIST;
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;Use free( ) to free the input WTX_LD_M_FILE_DESC parameter and wtxResultFree( ) to free the output WTX_LD_M_FILE_DESC parameter.
COFF object modules with more than 3 sections are not supported.
Files loaded on the target by the target server can be opened either by the target server or by the client. These two behaviors can be controled by moduleId: "WTX_LOAD_FROM_CLIENT" opens the file where the client is, "WTX_LOAD_FROM_TARGET_SERVER" opens the file where the target server is.
Load a module on the target, the file is opened either by the client or by the target server according to the place where the file is.
... pFileDescIn->filename = "/folk/pascal/Board/ads860/objSampleWtxtclTest2.o"; pFileDescIn->loadFlag = LOAD_GLOBAL_SYMBOLS; pFileDescIn->nSections = 0; pFileDescIn->moduleId = WTX_LOAD_FROM_CLIENT; /* Open the file locally */ if (isTgtSvrLocal) if((pFileDescOut = wtxObjModuleLoad (wtxh, pFileDescIn)) == NULL) return (WTX_ERROR); else { /* Do something */ ... } } else /* The target server opens the file */ { pFileDescIn->moduleId = WTX_LOAD_FROM_TARGET_SERVER; if((pFileDescOut = wtxObjModuleLoad (wtxh, pFileDescIn)) == NULL) return (WTX_ERROR); else { /* Do something */ ... } } ...
A pointer to a WTX_LD_M_FILE_DESC for the new module or NULL on error.
- WTX_ERR_API_MEMALLOC
- A buffer cannot be allocated
- WTX_ERR_API_INVALID_ARG
- filename is NULL
- WTX_ERR_API_FILE_NOT_ACCESSIBLE
- filename doesn't exist or bad permission
- WTX_ERR_API_FILE_NOT_FOUND
- Cant bind the path name to the file descriptor
- WTX_ERR_API_NULL_SIZE_FILE
- File have a null size
- WTX_ERR_API_CANT_READ_FROM_FILE
- Read in file failed
- WTX_ERR_SVR_EINVAL
- Request issued out of sequence. A tool should not submit a load request if it already has one pending.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Cannot allocate memory for internal needs
- 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_LOADER_XXX
- See WTX_OBJ_MODULE_LOAD
WTX_OBJ_MODULE_LOAD_2, wtxObjModuleLoad( ), wtxObjModuleUnload( ), wtxObjModuleList( ), wtxObjModuleInfoGet( ), wtxObjModuleLoadStart( ), wtxObjModuleLoadCancel( ), wtxObjModuleLoadProgressReport( ), API Reference Manual: Target Server Internal Routines, API Programmer's Guide: Object Module Loader
wtxObjModuleLoadStart( ) - Load a multiple section object file asynchronously
STATUS wtxObjModuleLoadStart ( HWTX hWtx, /* WTX API handle */ WTX_LD_M_FILE_DESC * pFileDesc /* Module descriptor */ )
This routine loads a module onto the target and into the target server module table. It returns when the module is in the target server memory, ready to be relocated and downloaded by the target server loader. The caller should pass in a pointer to a WTX_LD_M_FILE_DESC structure:
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 user must set the filename field to the name of the file containing the object module and the loadFlag to the loader flags required:
- 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
When no section description is given and nSections is set to zero, the host-based loader allocates memory for the text, data and bss sections of the module using memory from the target memory pool. If the nSections field is non-zero, the user can specify the location to load the sections and the section field points to an array of section descriptors:
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;
COFF object modules with more than 3 sections are not supported.
Because this routine returns only WTX_OK or WTX_ERROR, the user must call wtxObjModuleLoadProgressReport( ) in order to have the module Id, sections addresses and the undefined symbols.
Files loaded on the target by the target server can be opened either by the target server or by the client. These two behaviors can be controled by moduleId: "WTX_LOAD_FROM_CLIENT" opens the file where the client is, "WTX_LOAD_FROM_TARGET_SERVER" opens the file where the target server is.
Load a module on the target, the file is opened either by the client or by the target server according to the place where the file is.
... pFileDescIn->filename = "/folk/pascal/Board/ads860/objSampleWtxtclTest2.o"; pFileDescIn->loadFlag = LOAD_GLOBAL_SYMBOLS; pFileDescIn->nSections = 0; pFileDescIn->moduleId = WTX_LOAD_FROM_CLIENT; /* Open the file locally */ if (isTgtSvrLocal) { if(wtxObjModuleLoadStart (wtxh, pFileDescIn) == WTX_ERROR) return (WTX_ERROR); else { /* Load is in progress: get its status */ if ((pLoadReport = wtxObjModuleLoadProgressReport (wtxh)) == NULL) return (WTX_ERROR); /* Do something */ ... } } else /* The target server opens the file */ { pFileDescIn->moduleId = WTX_LOAD_FROM_TARGET_SERVER; if(wtxObjModuleLoadStart (wtxh, pFileDescIn) == WTX_ERROR) return (WTX_ERROR); else { /* Load is in progress: get its status */ if ((pLoadReport = wtxObjModuleLoadProgressReport (wtxh)) == NULL) return (WTX_ERROR); /* Do something */ ... } } ...
WTX_OK or WTX_ERROR if something failed
- WTX_ERR_API_MEMALLOC
- A buffer cannot be allocated
- WTX_ERR_API_INVALID_ARG
- filename is NULL
- WTX_ERR_API_FILE_NOT_ACCESSIBLE
- filename doesn't exist or bad permission
- WTX_ERR_API_FILE_NOT_FOUND
- Cant bind the path name to the file descriptor
- WTX_ERR_API_NULL_SIZE_FILE
- File have a null size
- WTX_ERR_API_CANT_READ_FROM_FILE
- Read in file failed
- WTX_ERR_SVR_EINVAL
- Request issued out of sequence. A tool should not submit a load request if it already has one pending.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Cannot allocate memory for internal needs
- 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_LOADER_XXX
- See WTX_OBJ_MODULE_LOAD
WTX_OBJ_MODULE_LOAD_2, wtxObjModuleLoad( ), wtxObjModuleLoadProgressReport( ), wtxObjModuleLoadCancel( ), API Reference Manual: Target Server Internal Routines, API Programmer's Guide: Object Module Loader
wtxObjModuleLoadProgressReport( ) - get the asynchronous load status
WTX_LOAD_REPORT_INFO * wtxObjModuleLoadProgressReport ( HWTX hWtx /* WTX API handle */ )
This routine returns the current load context after a wtxObjModuleLoadStart request.
typedef struct wtx_load_report_info /* Progress info for async. loads */ { int loadState; /* * two value : * LOAD_IN_PROGRESS : * - informations available in * PROGRESSINFO structure. * LOAD_DONE : * - informations available in * MODULEINFO structure. */ union state_info { struct ld_m_file_desc /* object module file descriptor */ { 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; struct progress_info { int state; /* Current State */ int maxValue; /* Maximum value for this state */ int currentValue; /* current value for this state */ } PROGRESS_INFO; } STATE_INFO; } WTX_LOAD_REPORT_INFO;Use free( ) to free the output WTX_LOAD_REPORT_INFO parameter, and when the load is complete, use wtxSymListFree( ) to free the undefined symbols list if it exists, free also filename and section.
Load a module on the target and each second, the load status is evaluated.
... pFileDescIn->filename = "/folk/pascal/Board/ads860/big.o"; pFileDescIn->loadFlag = LOAD_GLOBAL_SYMBOLS; pFileDescIn->nSections = 0; /* Load the module asynchronously */ if (wtxObjModuleLoadStart (wtxh, pFileDescIn) == WTX_ERROR) return (WTX_ERROR); /* Get info about the load */ if ((pLoadReport = wtxObjModuleLoadProgressReport (wtxh)) == NULL) return (WTX_ERROR) else { /* Define some shorthands */ #define progress pLoadReport->STATE_INFO.PROGRESS_INFO #define mod pLoadReport->STATE_INFO.WTX_LD_M_FILE_DESC while (pLoadReport->loadState == LOAD_IN_PROGRESS) { #ifdef WIN32 Sleep (1000); #else sleep (1); #endif /* Print info about the load request */ printf ("\t\tLOAD_IN_PROGRESS"); printf ("\tPHASE: %d\tdone: %d\tremaining: %d\n", progress.state, progress.currentValue, progress.maxValue - progress.currentValue); free (pLoadReport); if ((pLoadReport = wtxObjModuleLoadProgressReport (wtxh)) == NULL) { printf ("\nwtxObjModuleProgressReport failed\n"); return (WTX_ERROR); } } /* The load is done: the module is on the target */ printf ("\t\tLOAD_DONE\n"); /* Do something */ ... /* First free any symbols list */ wtxSymListFree (&pLoadReport->undefSymList); /* Feeing dynamically allocated memory */ if (pLoadReport->filename != NULL) free (pLoadReport->filename); if (pLoadReport->section != NULL) free (pLoadReport->section); free (pLoadReport); ...
A pointer to a WTX_LOAD_REPORT_INFO for the load status or NULL on error.
- WTX_ERR_API_MEMALLOC
- A buffer cannot be allocated
- WTX_ERR_API_INVALID_ARG
- An invalid argument had been received
- WTX_ERR_LOADER_LOAD_CANCELED
- The load had been aborted
- WTX_ERR_LOADER_LOAD_IN_PROGRESS
- The load operation is not finished
- WTX_ERR_LOADER_OBJ_MODULE_NOT_FOUND
- The module was unloaded by another client
- WTX_ERR_SVR_EINVAL
- Request issued out of sequence. A tool should submit a load before issuing this request.
- WTX_ERR_SVR_NOT_ENOUGH_MEMORY
- Cannot allocate memory for internal needs
- 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_LOADER_XXX
- See WTX_OBJ_MODULE_LOAD
WTX_OBJ_MODULE_LOAD_2, wtxObjModuleLoadStart( ), wtxObjModuleLoad( ), wtxObjModuleLoadCancel( ), API Reference Manual: Target Server Internal Routines, API Programmer's Guide: Object Module Loader
wtxObjModuleLoadCancel( ) - Stop an asynchronous load request
STATUS wtxObjModuleLoadCancel ( HWTX hWtx /* WTX API handle */ )
This routine stops an asynchronous load request. If the load had been already done or it can't be found, then it returns an error.
WTX_OK or WTX_ERROR on error.
- WTX_ERR_SVR_INVALID_CLIENT_ID
- Tool not registered
- WTX_ERR_SVR_EINVAL
- Request issued out of sequence. A tool should submit a load before issuing this request.
- WTX_ERR_LOADER_ALREADY_LOADED
- The load is already finished
WTX_COMMAND_SEND, wtxObjModuleLoadStart( ), wtxObjModuleLoadProgressReport( ), API Reference Manual: Target Server Internal Routines, API Programmer's Guide: Object Module Loader
wtxObjModuleUnload( ) - unload an object module from the target
STATUS wtxObjModuleUnload ( HWTX hWtx, /* WTX API handle */ UINT32 moduleId /* id of module to unload */ )
This routine unloads the module specified by moduleId from the target. The module ID is returned when the module is loaded or by one of the information routines.
WTX_OK or WTX_ERROR.
WTX_OBJ_MODULE_UNLOAD_2, wtxObjModuleLoad( ), wtxObjModuleList( ), wtxObjModuleInfoGet( )
wtxObjModuleByNameUnload( ) - unload an object module from the target
STATUS wtxObjModuleByNameUnload ( HWTX hWtx, /* WTX API handle */ char * name /* Name of module to look for */ )
This routine unloads the module specified by name from the target. The module ID is returned when the module is loaded or by one of the information routines.
WTX_OK or WTX_ERROR if exchange failed.
WTX_OBJ_MODULE_UNLOAD_2, wtxObjModuleUnload( ), wtxObjModuleLoad( ), wtxObjModuleList( ), wtxObjModuleInfoGet( )
wtxRegisterForEvent( ) - ask the WTX server to send events matching a regexp
STATUS wtxRegisterForEvent ( HWTX hWtx, /* WTX API handle */ const char * regExp /* Regular expression to select events */ )
This routine takes a string regExp, which is a regular expression, and uses it to specify which events this user is interested in. By default a WTX client receives no event notifications.
WTX_OK or WTX_ERROR.
WTX_REGISTER_FOR_EVENT, wtxUnregisterForEvent( ), wtxEventGet( ), wtxEventListGet( )
wtxRegsGet( ) - read register data from the target
STATUS wtxRegsGet ( HWTX hWtx, /* WTX API handle */ WTX_CONTEXT_TYPE contextType, /* context type to get regs of */ WTX_CONTEXT_ID_T contextId, /* context id to get regs of */ WTX_REG_SET_TYPE regSet, /* type of register set */ UINT32 firstByte, /* first byte of register set */ UINT32 numBytes, /* number of bytes of register set */ void * regMemory /* place holder for reg. values */ )
This routine reads numBytes of raw (target format) register data from the register set regSet starting from the byte at offset firstByte. The data read are stored in local memory at regMemory.
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;
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;
WTX_OK or WTX_ERROR.
wtxRegsSet( ) - write to registers on the target
STATUS wtxRegsSet ( HWTX hWtx, /* WTX API handle */ WTX_CONTEXT_TYPE contextType, /* context type to set regs of */ WTX_CONTEXT_ID_T contextId, /* context id to set regs of */ WTX_REG_SET_TYPE regSet, /* type of register set */ UINT32 firstByte, /* first byte of reg. set */ UINT32 numBytes, /* number of bytes in reg. set. */ void * regMemory /* register contents */ )
This routine writes numBytes of raw (target format) register data to register set regSet starting at offset firstByte. Data is written from local memory at regMemory.
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;
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;
WTX_OK or WTX_ERROR if the register set fails.
wtxStrToTgtAddr( ) - convert a string argument to a TGT_ADDR_T value
TGT_ADDR_T wtxStrToTgtAddr ( HWTX hWtx, /* WTX API handle */ const char * str /* string */ )
This routine takes a string and converts it to a TGT_ADDR_T. The string is part of an event string. See wtxEventGet( ) and the WTX library discussion of WTX events in the API Reference Manual: WTX Protocol.
The address as a TGT_ADDR_T value.
wtxStrToContextId( ) - convert a string argument to a WTX_CONTEXT_ID_T
WTX_CONTEXT_ID_T wtxStrToContextId ( HWTX hWtx, /* WTX API handle */ const char * str /* string */ )
This routine takes a string and converts it to a context ID. The string is part of an event string. See wtxEventGet( ) and the WTX library discussion of WTX events in the API Reference Manual: WTX Protocol.
The context ID.
wtxStrToContextType( ) - convert a string argument to a WTX_CONTEXT_TYPE value
WTX_CONTEXT_TYPE wtxStrToContextType ( HWTX hWtx, /* WTX API handle */ const char * str /* string */ )
This routine takes a string and converts it to a WTX_CONTEXT_TYPE enumeration value. The string is part of an event string. See wtxEventGet( ) and the WTX library discussion of WTX events in the API Reference Manual: WTX Protocol.
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;
The context type or WTX_ERROR on error.
wtxStrToInt32( ) - convert a string argument to an INT32 value
INT32 wtxStrToInt32 ( HWTX hWtx, /* WTX API handle */ const char * str /* string */ )
This routine takes a string and converts it to a signed host integer. The string is part of an event string. See wtxEventGet( ) and the WTX library discussion of WTX events in the API Reference Manual: WTX Protocol.
The string as an INT32 value.
wtxStrToEventType( ) - convert a string to a WTX event enumeration type
WTX_EVENT_TYPE wtxStrToEventType ( HWTX hWtx, /* WTX API handle */ const char * str /* string */ )
This routine is a type converter for the event strings passed to a WTX client by the target server. It converts back to the event enumeration type so event types can be switched on.
If the string is NULL, WTX_EVT_T_NONE is returned. If the string does not match any of the pre-defined events, WTX_EVT_T_OTHER is returned.
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;
The event type or WTX_EVT_T_INVALID on error.
wtxEventToStrType( ) - convert a WTX event enumeration type to a string
const char * wtxEventToStrType ( WTX_EVENT_TYPE event /* WTX Event */ )
This routine is a string converter for the event type passed to the target server. It is the wtxStrToEventType routine counterpart.
If the event is not known , the WTX_EVENT_UNKNOWN string is returned.
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;
a string representing the event, or WTX_EVENT_UNKNOWN on error.
wtxServiceAdd( ) - add a new service to the agent
STATUS wtxServiceAdd ( HWTX hWtx, /* WTX API handle */ UINT32 * wtxSvcNum, /* where to return WTX RPC service number */ UINT32 wdbSvcNum, /* WDB RPC service number */ char * wdbName, /* WDB service name */ char * wdbObjFile, /* WDB service object module */ char * wdbSvcInitRtn, /* WDB svc initialization routine name */ char * wtxObjFile, /* WTX xdr/service DLL file */ char * wtxName, /* WTX service routine name */ char * wtxInProcName, /* WTX service input xdr procedure name */ char * wtxOutProcName /* WTX service output xdr procedure name */ )
This command adds a new service to the target server. The service is provided in WDB- and WTX-level object modules. The WDB object module is downloaded to the target, and the WTX object module is dynamically linked to the target server.
The wtxInProcName and wtxOutProcName arguments are the names of known structure filter procedures used to exchange data with the new service.
wtxObjFile is the name of a dynamically loadable library file that contain the WTX service routine, the service initialization routine, and XDR filters code for the service input and output parameters.
Upon success the service number to be used for future requests to the newly added service is returned in mySvcNumber.
Example:
/* * Add a WTX service called mySvc and get the service number in * mySvcNumber. */ if (wtxServiceAdd ( wtxh, /* our tool handle */ &mySvcNumber, /* where to return service num. */ NULL, NULL, NULL, NULL, /* no WDB items */ "mySvc.so", /* new service DLL */ "mySvcName", /* service routine name */ "xdr_WTX_MY_SVC_IN_PARAM", /* input param XDR filter */ "xdr_WTX_MY_SVC_OUT_PARAM" /* output param XDR filter */ ) != OK) { printf("Error: cannot add mySvc service:%s\n",wtxErrMsgGet(wtxh)); wtxTerminate (wtxh); /* terminate tool connection */ exit(0); } ... /* get our client handle in order to call the newly added service */ pClient = (CLIENT *) wtxh->server->transport; /* set client call timeout */ timeout.tv_sec = 10; timeout.tv_usec = 0; /* Call the newly added service */ rpcStat = clnt_call ( pClient, /* client handle */ mySvcNumber, /* service number */ xdr_WTX_MY_SVC_IN_PARAM, /* request XDR filter */ (char *) pIn, /* ptr to input data */ xdr_WTX_MY_SVC_OUT_PARAM, /* reply XDR filter */ (char *) pOut, /* ptr to result */ timeout /* request timeout value */ );
In the Tornado 1.0 release, wtxServiceAdd( ) can only add WTX services that do not require an additional WDB service. The wdbSvcNum, wdbName, wdbObjFile and wdbSvcInitRtn parameters must be set to NULL.
WTX_OK or WTX_ERROR.
wtx, WTX_SERVICE_ADD
wtxSymAdd( ) - add a symbol with the given name, value, and type
STATUS wtxSymAdd ( HWTX hWtx, /* WTX API handle */ const char * name, /* name of symbol to add */ TGT_ADDR_T value, /* value of symbol to add */ UINT8 type /* type of symbol to add */ )
This routine adds a new symbol with the specified name, value, and type to the target server symbol table.
WTX_OK or WTX_ERROR.
WTX_SYM_ADD, wtxSymFind( ), wtxSymListGet( ), wtxSymRemove( )
wtxSymAddWithGroup( ) - add a symbol with the given name, value, type and group
STATUS wtxSymAddWithGroup ( HWTX hWtx, /* WTX API handle */ const char * name, /* name of symbol to add */ TGT_ADDR_T value, /* value of symbol to add */ UINT8 type, /* type of symbol to add */ UINT16 group /* group of symbol to add */ )
This routine adds a new symbol with the specified name, value, type and group to the target server symbol table.
WTX_OK or WTX_ERROR.
WTX_SYM_ADD, wtxSymFind( ), wtxSymListGet( ), wtxSymRemove( )
wtxSymFind( ) - find information on a symbol given its name or value
WTX_SYMBOL * wtxSymFind ( HWTX hWtx, /* WTX API handle */ const char * symName, /* name of symbol */ TGT_ADDR_T symValue, /* value of symbol */ BOOL32 exactName, /* must match name exactly */ UINT8 symType, /* type of symbol */ UINT8 typeMask /* mask to select type bits */ )
This routine searches for a symbol which matches the supplied search criteria. If symName is non-NULL, the search is for a symbol whose name matches symName. If symName is NULL, the search is for one with value symValue. When searching by name, the exactName flag is used to control whether the name must exactly match symName or only partially. In both value and name searches, a symbol type symType can be supplied to further refine the search. Valid symbol types are defined in a_out.h. To prevent the type being considered in the search set typeMask to 0.
The result of the search is a pointer to a symbol which must be freed by the user calling wtxResultFree( ).
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;
A pointer to the symbol or NULL on error.
WTX_SYM_FIND, wtxResultFree( ).
wtxSymListGet( ) - get a list of symbols matching the given search criteria
WTX_SYM_LIST * wtxSymListGet ( HWTX hWtx, /* WTX API handle */ const char * substring, /* Symbol name substring to match */ const char * moduleName, /* Module name to search in */ TGT_ADDR_T value, /* Symbol value to match */ BOOL32 listUnknown /* List unknown symbols only flag */ )
This routine gets a list of symbols matching given search criteria. substring is a symbol substring to match and value is a target symbol address value to search around. Either string or value should be set to a non-NULL value, but not both. In addition, if listUnknown is set to TRUE then only unknown symbols are listed and substring and value are ignored. If moduleName is non-NULL, it specifies the module to search. Even if no symbols match the search parameters, the pointer returned is not NULL. It points to a WTX_SYM_LIST with a NULL pSymbol field.
The return value must be freed by the caller using wtxResultFree( ).
typedef struct wtx_sym_list /* Symbol list */ { WTX_SYMBOL * pSymbol; /* Start of symbol list */ } WTX_SYM_LIST;
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 symbols allocated by wtxSymListGet( ) should be freed by caller.
A pointer to a list of symbols or NULL on error.
WTX_SYM_LIST_GET, wtxResultFree( )
wtxSymListByModuleIdGet( ) - get a list of symbols given a module Id
WTX_SYM_LIST * wtxSymListByModuleIdGet ( HWTX hWtx, /* WTX API handle */ const char * substring, /* Symbol name substring to match */ UINT32 moduleId, /* Module Id to search in */ TGT_ADDR_T value, /* Symbol value to match */ BOOL32 listUnknown /* List unknown symbols only flag */ )
This routine gets a list of symbols matching given search criteria. substring is a symbol substring to match and value is a target symbol address value to search around. Either string or value should be set to a non-NULL value, but not both. In addition, if listUnknown is set to TRUE then only unknown symbols are listed and substring and value are ignored. If moduleId is non-zero, it specifies the module to search. Even if no symbols match the search parameters, the pointer returned is not NULL. It points to a WTX_SYM_LIST with a NULL pSymbol field.
The return value must be freed by the caller using wtxResultFree( ).
typedef struct wtx_sym_list /* Symbol list */ { WTX_SYMBOL * pSymbol; /* Start of symbol list */ } WTX_SYM_LIST;
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 symbols allocated by wtxSymListGet( ) should be freed by caller.
A pointer to a list of symbols or NULL on error.
WTX_SYM_LIST_GET, wtxSymListGet( ), wtxSymListByModuleNameGet( ), wtxResultFree( )
wtxSymListByModuleNameGet( ) - get a list of symbols given a module name
WTX_SYM_LIST * wtxSymListByModuleNameGet ( HWTX hWtx, /* WTX API handle */ const char * substring, /* Symbol name substring to match */ const char * moduleName, /* Module name to search in */ TGT_ADDR_T value, /* Symbol value to match */ BOOL32 listUnknown /* List unknown symbols only flag */ )
This routine gets a list of symbols matching given search criteria. substring is a symbol substring to match and value is a target symbol address value to search around. Either string or value should be set to a non-NULL value, but not both. In addition, if listUnknown is set to TRUE then only unknown symbols are listed and substring and value are ignored. If moduleName is non-NULL, it specifies the module to search. Even if no symbols match the search parameters, the pointer returned is not NULL. It points to a WTX_SYM_LIST with a NULL pSymbol field.
The return value must be freed by the caller using wtxResultFree( ).
typedef struct wtx_sym_list /* Symbol list */ { WTX_SYMBOL * pSymbol; /* Start of symbol list */ } WTX_SYM_LIST;
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 symbols allocated by wtxSymListGet( ) should be freed by caller.
A pointer to a list of symbols or NULL on error.
WTX_SYM_LIST_GET, wtxSymListGet( ), wtxSymListByModuleIdGet( ), wtxResultFree( )
wtxSymRemove( ) - remove a symbol from the default target server symbol table
STATUS wtxSymRemove ( HWTX hWtx, /* WTX API handle */ const char * symName, /* Name of symbol to remove */ UINT8 symType /* Type of symbol to remove */ )
This routine removes a symbol from the default target server symbol table. symName and symType identify the symbol to remove.
WTX_OK or WTX_ERROR.
WTX_SYM_REMOVE, wtxSymAdd( ), wtxSymFind( ), wtxSymListGet( )
wtxSymTblInfoGet( ) - return information about the target server symbol table
WTX_SYM_TBL_INFO * wtxSymTblInfoGet ( HWTX hWtx /* WTX API handle */ )
This routine queries the target server to find out information about its symbol table. The return value must be freed by the caller using wtxResultFree( ).
typedef struct wtx_sym_tbl_info { UINT32 symTblId; /* Symbol table identifier */ UINT32 symNum; /* Number of symbols */ BOOL32 sameNameOk; /* Name clash policy */ } WTX_SYM_TBL_INFO;
A pointer to the target server symbol-table information structure or NULL on error.
wtxTargetReset( ) - reset the target
STATUS wtxTargetReset ( HWTX hWtx /* WTX API handle */ )
This routine resets the target as if it was manually rebooted. The target server restarts itself and if the reboot is successful, it reconnects to the target. If the call is successful a target reset event, TGT_RESET, is generated and sent to all clients registered to receive them.
The client making the request must reconnect to the target server as restarting the server causes the server connection to be broken.
WTX_OK or WTX_ERROR on failure.
wtxTsNameGet( ) - get the full name of the currently attached target server
const char * wtxTsNameGet ( HWTX hWtx /* WTX API handle */ )
This routine returns the full name of the target server to which the handle hWtx is attached (if any). The string is an internal one and must not be freed by the caller.
The target server name string or NULL if not connected.
wtxTargetRtTypeGet( ) - get the target-runtime-type information
INT32 wtxTargetRtTypeGet ( HWTX hWtx /* WTX API handle */ )
This routine returns a numeric value indicating the runtime type as returned by the target agent.
The runtime type code as a INT32 or WTX_ERROR on error.
wtxTargetRtVersionGet( ) - get the target-runtime-version information
const char * wtxTargetRtVersionGet ( HWTX hWtx /* WTX API handle */ )
This routine returns a string containing the version information for the runtime of the current target. The return value is a pointer to the string in temporary memory; the string must be copied if its value is to be stored.
The version string or NULL on error.
wtxTargetCpuTypeGet( ) - get the target CPU type code
INT32 wtxTargetCpuTypeGet ( HWTX hWtx /* WTX API handle */ )
This routine returns a numeric value indicating the type of the CPU as returned by the target agent.
The CPU type code as a INT32 or WTX_ERROR on error.
wtxTargetHasFppGet( ) - check if the target has a floating point processor
BOOL32 wtxTargetHasFppGet ( HWTX hWtx /* WTX API handle */ )
This routine returns a boolean indicating whether the current target has a floating point processor available. Errors must be detected using wtxErrClear( ) and wtxErrGet( ).
TRUE if it has a floating point processor or FALSE if not or if there was an error.
wtxTargetEndianGet( ) - get the endianness of the target CPU
WTX_ENDIAN_T wtxTargetEndianGet ( HWTX hWtx /* WTX API handle */ )
This routine returns WTX_ENDIAN_BIG if the target has a CPU that uses big-endian byte storage ordering (the most significant byte first) or WTX_ENDIAN_LITTLE if it uses little-endian ordering (the least significant byte first). If an error occurs, the routine returns WTX_ENDIAN_UNKNOWN.
typedef enum wtx_endian_t { WTX_ENDIAN_BIG = 0, WTX_ENDIAN_LITTLE = 1, WTX_ENDIAN_UNKNOWN = WTX_ERROR } WTX_ENDIAN_T;
The CPU endian value or WTX_ENDIAN_UNKNOWN.
wtxTargetBootlineGet( ) - get the target bootline information string
const char * wtxTargetBootlineGet ( HWTX hWtx /* WTX API handle */ )
This routine returns a string containing the target bootline. The return value is a pointer to the string in temporary memory; the string must be copied if it is to be stored.
The bootline string or NULL on error.
wtxTargetBspNameGet( ) - get the target board-support-package name string
const char * wtxTargetBspNameGet ( HWTX hWtx /* WTX API handle */ )
This routine returns a string containing the board-support-package name for the runtime of the current target. The return value is a pointer to the string in temporary memory; the string must be copied if it is to be stored.
The BSP name string or NULL on error.
wtxToolNameGet( ) - return the name of the current tool
char * wtxToolNameGet ( HWTX hWtx /* WTX API handle */ )
This function gets a string representing the name of the current tool. The return value is a pointer to the string in temporary memory; the string must be copied if it is to be stored.
The tool name string or NULL on error.
wtxTsVersionGet( ) - return the Tornado version
char * wtxTsVersionGet ( HWTX hWtx /* WTX API handle */ )
This function gets a string representing the Tornado version. The return value is a pointer to temporary memory and must be copied if it is to be stored.
A pointer to the Tornado version string or NULL on error.
wtxTsKill( ) - kill the target server
STATUS wtxTsKill ( HWTX hWtx /* WTX API handle */ )
This routine kills the target server. The client detaches from the target server at this time. Another attachment can subsequently be made.
WTX_OK or WTX_ERROR.
WTX_OBJ_KILL, wtxToolAttach( )
wtxTsRestart( ) - restart the target server
STATUS wtxTsRestart ( HWTX hWtx /* WTX API handle */ )
This routine restarts the target server. The client detaches from the target server at this time. Another attachment can subsequently be made.
WTX_OK or WTX_ERROR.
WTX_OBJ_KILL, wtxToolAttach( )
wtxUnregisterForEvent( ) - ask the target server to not send events matching
STATUS wtxUnregisterForEvent ( HWTX hWtx, /* WTX API handle */ char * regExp /* Regular expression to select events */ )
a regexp
This routine registers which events are unwanted. Usually, if we want to filter events notification we have to give the regular expression to WTX_REGISTER_FOR_EVENT. A more simple way to do this is to be registered for all the events and to be registered for only those which are unwanted.
WTX_OK or WTX_ERROR if exchange failed
WTX_UNREGISTER_FOR_EVENT, wtxRegisterForEvent( ), wtxEventGet( ), wtxEventListGet( ).
wtxFuncCall( ) - call a function on the target
WTX_CONTEXT_ID_T wtxFuncCall ( HWTX hWtx, /* WTX API handle */ WTX_CONTEXT_DESC * pContextDesc /* pointer to call descriptor */ )
This routine calls the function identified by WTX_CONTEXT_DESC.
typedef struct wtx_context_desc /* context creation desc. */ { WTX_CONTEXT_TYPE contextType; /* context type */ WTX_RETURN_TYPE returnType; /* int or double */ char * name; /* name */ UINT32 priority; /* priority */ UINT32 options; /* 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 NULL */ INT32 redirOut; /* redir. out file or NULL */ TGT_ARG_T args[WTX_MAX_ARG_CNT]; /* arguments */ } WTX_CONTEXT_DESC;Execution starts at entry, with up to 10 integer arguments specified in the array args[]. The return type is specified by setting returnType to WTX_RETURN_TYPE_INT or WTX_RETURN_TYPE_DOUBLE.
Because calling a function creates a task context on the target system, it cannot be used when the target agent is in external mode.
- WTX_ERR_API_INVALID_ARG
- pContextDesc is invalid.
The ID of the function call or WTX_ERROR. When the called function terminates, a CALL_RETURN event is generated which references this ID and contains the return value.
WTX_FUNC_CALL, wtxEventGet( ), wtxDirectCall( ), API Reference Manual: WTX Protocol WTX_FUNC_CALL
wtxDirectCall( ) - call a function on the target within the agent
STATUS wtxDirectCall ( HWTX hWtx, /* WTX API handle */ TGT_ADDR_T entry, /* function address */ void * pRetVal, /* pointer to return value */ TGT_ARG_T arg0, /* function arguments */ TGT_ARG_T arg1, TGT_ARG_T arg2, TGT_ARG_T arg3, TGT_ARG_T arg4, TGT_ARG_T arg5, TGT_ARG_T arg6, TGT_ARG_T arg7, TGT_ARG_T arg8, TGT_ARG_T arg9 )
This routine calls the function at entry, with up to 10 integer arguments arg0... arg9, in the context of the target agent.
The return value of the function called on the target is returned at the address pointed to by pRetVal.
The called function is executed within the target agent allowing tools to call functions when the agent is running in both task and external mode. This service should only be used to call simple functions that return immediately in order to avoid locking access to the target for other tools. It is preferable to use wtxFuncCall( ) to call functions that may take longer to return. If the function called from wtxDirectCall( ) gets an exception, the agent stops and communication with the target board is lost.
This service cannot be used to call functions that return a double.
WTX_OK or WTX_ERROR if cannot call the function or if pRetVal is NULL.
WTX_DIRECT_CALL, wtxFuncCall( )
wtxTsInfoGet( ) - get information about the target server, the target, and the link to the target
WTX_TS_INFO * wtxTsInfoGet ( HWTX hWtx /* WTX API handle */ )
This routine queries the target server to find out information about the currently connected target and target server. The result is a pointer to internal memory that must not be freed by the user. The value in memory may change after any subsequent WTX API calls so it must be copied if the values are to be saved.
typedef struct wtx_ts_info /* TS information message */ { 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_TS_INFO;where WTX_TGT_LINK_DESC is:
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;and WTX_TGT_INFO is:
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;WTX_TOOL_DESC is:
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;with WTX_AGENT_INFO:
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;and WTX_RT_INFO:
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;
This call actively queries the target server for information. Each successful call returns the latest information.
A pointer to the target server information structure or NULL on error.
wtxTsLock( ) - lock the connected target server for exclusive access
STATUS wtxTsLock ( HWTX hWtx /* WTX API handle */ )
This routine locks the target server that the client is connected to so it can only be used by this user and no others. Other clients already connected can continue to use the target server until they disconnect. When a target server is locked the only operations another user may perform are connecting, getting the target server information, and disconnecting.
WTX_OK or WTX_ERROR.
wtxTsTimedLock( ) - lock the connected target server a limited time
STATUS wtxTsTimedLock ( HWTX hWtx, /* WTX API handle */ UINT32 seconds /* duration of lock */ )
This routine locks the target server that the client is connected to so it can only be used by this user and no others. Other clients already connected can continue to use the target server until they disconnect. When a target server is locked the only operations another user may perform are connecting, getting the target server information, and disconnecting.
The target server may be locked indefinitely (seconds = WTX_LOCK_FOREVER), otherwise if the target server must be locked only for a fixed time, then the duration must be set in seconds.
WTX_OK or WTX_ERROR.
WTX_TS_LOCK, wtxTsLock( ), wtxTsUnlock( )
wtxTsUnlock( ) - unlock the connected target server
STATUS wtxTsUnlock ( HWTX hWtx /* WTX API handle */ )
This routine unlocks the target server that the client is connected to so it can be accessed by any user on its access list. The unlock will only succeed if it is being unlocked by the same user that locked it.
WTX_OK or WTX_ERROR.
wtxVerify( ) - verify that a WTX handle is valid for use
BOOL32 wtxVerify ( HWTX hWtx /* WTX API handle */ )
This routine returns WTX_OK if the WTX handle hWtx is valid. If an invalid handle is passed to a WTX routine, the error WTX_ERR_API_INVALID_HANDLE occurs. A handle that has been released using wtxTerminate( ) is invalid.
TRUE if the handle is valid or FALSE if not.
wtxInitialize( ), wtxTerminate( )
wtxVioChanGet( ) - get a virtual I/O channel number
INT32 wtxVioChanGet ( HWTX hWtx /* WTX API handle */ )
This routine returns a free virtual I/O channel number to be used for redirection of target I/O to the host. The returned channel number is an INT32 between 1 and 255. (Channel 0 is reserved for the default console.) When no longer required, the channel number is released using wtxVioChanRelease( ).
The new channel number or WTX_ERROR on failure.
WTX_VIO_CHAN_GET, wtxVioChanRelease( )
wtxVioChanRelease( ) - release a virtual I/O channel
STATUS wtxVioChanRelease ( HWTX hWtx, /* WTX API handle */ INT32 channel /* the channel number to release */ )
This request releases a virtual I/O channel number previously obtained using wtxVioChanGet( ) and returns it to the free-channel-number pool of the target server. Valid channel numbers are in the range 1 to 255.
WTX_OK or WTX_ERROR.
WTX_VIO_CHAN_RELEASE, wtxVioChanGet( )
wtxVioCtl( ) - perform a control operation on a virtual I/O channel
STATUS wtxVioCtl ( HWTX hWtx, /* WTX API handle */ INT32 channel, /* channel to do control operation on */ UINT32 request, /* control operation to perform */ UINT32 arg /* arg for call */ )
This routine performs the special I/O operation specified by request on the virtual I/O channel channel. An operation-specific parameter is supplied to the operation by arg.
WTX_OK or WTX_ERROR.
wtxVioFileList( ) - list the files managed by the target server
WTX_VIO_FILE_DESC ** wtxVioFileList ( HWTX hWtx /* WTX API handle */ )
This routine 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 result is a pointer to a pointer to the first item in a linked list of file descriptors. It must be freed by the caller using wtxResultFree( ). If the list is empty (no files are managed by the target server), the result points to a NULL value.
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;
A pointer to a pointer to the file list or NULL on error.
WTX_VIO_FILE_LIST, wtxFileOpen( ), wtxFileClose( )
wtxVioWrite( ) - write data to a VIO channel
UINT32 wtxVioWrite ( HWTX hWtx, /* WTX API handle */ INT32 channel, /* channel to write to */ void * pData, /* pointer to data to write */ UINT32 numBytes /* number of bytes of data to write */ )
This routine writes at most numBytes of data starting at pData to the virtual I/O channel number channel. The buffer size is 512 bytes; if numBytes is greater than 512, the extra bytes are discarded.
The number of bytes actually written or WTX_ERROR.
WTX_VIO_WRITE, wtxEventGet( ), wtxVioChanGet( )
wtxTargetAttach( ) - reattach to the target
STATUS wtxTargetAttach ( HWTX hWtx /* WTX API handle */ )
This routine reattaches the client to a target that has been disconnected or for which the target server is waiting to connect.
WTX_OK if the target is successfully attached or WTX_ERROR if the target is still unavailable.
wtxProbe( ) - probe to see if the registry service is running
STATUS wtxProbe ( HWTX hWtx /* WTX API handle */ )
This routine returns WTX_OK if the registry service is running. Otherwise it returns WTX_ERROR.
WTX_OK or WTX_ERROR.
wtxRegister( ) - register the target server with the Tornado registry service
WTX_DESC * wtxRegister ( HWTX hWtx, /* WTX API handle */ const char * name, /* service name, NULL to be named */ const char * type, /* service type, NULL for unspecified */ const char * key /* unique service key */ )
This routine registers the named target server with the WTX registry daemon. If the specified name does not conflict with any other registered server, the registry allocates, initializes, and adds a WTX descriptor structure containing a unique RPC program number to its internal tables. If specified, name must be unique for the whole system, and by convention it is a legal C identifier. If name is NULL, a unique name is allocated by the registry and returned to the caller. Only one server can be registered per WTX handle.
The return value is a pointer to internal data and must not be freed by the user.
typedef struct wtx_desc /* server descriptor */ { char * wpwrName; /* name of wpwr service */ char * wpwrType; /* type of service */ char * wpwrKey; /* unique service key */ } WTX_DESC;
A pointer to a WTX_DESC or NULL if the registration failed.
- WTX_ERR_API_SERVICE_ALREADY_REGISTERED
- The server has already registered itself.
- WTX_ERR_API_REGISTRY_UNREACHABLE
- The registry service is not reachable (in other words, the registry daemon is not running).
- WTX_ERR_API_MEMALLOC
- There are insufficient resources to allocate a new WTX descriptor for the server.
- WTX_ERR_REGISTRY_NAME_CLASH
- Name already exists in Tornado registry database.
WTX_REGISTER, wtxUnregister( ), wtxInfo( )
wtxUnregister( ) - unregister the server with the Tornado registry
STATUS wtxUnregister ( HWTX hWtx, /* WTX API handle */ const char * name /* service to unregister, NULL for self */ )
This routine removes the specified descriptor from the Tornado-registry internal table. The name of the server is no longer reserved. Passing NULL for name means unregister the server already registered against the handle hWtx using wtxRegister( ).
WTX_OK or WTX_ERROR if the server could not be unregistered.
- WTX_ERR_API_SERVICE_NOT_REGISTERED
- The server is trying to unregister itself when it has not registered or has already unregistered.
- WTX_ERR_API_REGISTRY_UNREACHABLE
- The registry service is not reachable (in other words, the registry daemon is not running).
WTX_UNREGISTER, wtxRegister( )
wtxInfo( ) - allocate and return a descriptor for the named service
WTX_DESC * wtxInfo ( HWTX hWtx, /* WTX API handle */ const char * name /* service name to lookup */ )
This routine allocates and fills in a descriptor corresponding to the named service. This routine always queries the WTX registry daemon for the named service and allocates and fills a WTX descriptor structure with the results. The descriptor must be deallocated with wtxResultFree( ) when it is no longer needed. Passing NULL for name means to get information on the server already registered against the handle hWtx using wtxRegister( ).
typedef struct wtx_desc /* server descriptor */ { char * wpwrName; /* name of wpwr service */ char * wpwrType; /* type of service */ char * wpwrKey; /* unique service key */ } WTX_DESC;
A pointer to a WTX_DESC or NULL if the service could not be found.
- WTX_ERR_API_SERVICE_NOT_REGISTERED
- name is NULL and no service is registered against the handle.
- WTX_ERR_API_REGISTRY_UNREACHABLE
- The registry service is not reachable (in other words, the registry daemon is not running).
WTX_INFO_GET, wtxInfoQ( )
wtxInfoQ( ) - return a list of all services registered with the Tornado registry
WTX_DESC_Q * wtxInfoQ ( HWTX hWtx, /* WTX API handle */ const char * namePattern, /* regular expression to match svc name */ const char * typePattern, /* regular expression to match svc type */ const char * keyPattern /* regular expression to match svc key */ )
This routine provides the caller with a table of descriptors corresponding to all services registered with the Tornado registry. An unsorted table of descriptors is allocated and returned. There is no guarantee that the table is valid by the time it is inspected. Services may come and go at any time.
typedef struct wtx_desc_q /* server descriptor queue */ { char * wpwrName; /* name of wpwr service */ char * wpwrType; /* type of service */ char * wpwrKey; /* unique service key */ struct wtx_desc_q * pNext; /* next descriptor */ } WTX_DESC_Q;The table of descriptors should be deallocated with wtxResultFree( ).
A pointer to a table of descriptors or NULL if error.
- WTX_ERR_API_REGISTRY_UNREACHABLE
- The registry service is not reachable (in other words, the registry daemon is not running).
- WTX_ERR_API_MEMALLOC
- There are insufficient resources to allocate the WTX_DESC_Q structure for the result value.
- WTX_ERR_REGISTRY_BAD_PATTERN
- One of the given patterns (namePattern, typePattern or keyPattern) is not a valid regular expression.
- WTX_ERR_REGISTRY_NAME_NOT_FOUND
- Info required is not in the registry database.
wtxEach( ) - call a routine to examine each WTX-registered service
STATUS wtxEach ( HWTX hWtx, /* WTX API handle */ const char * namePattern, /* regular expression to match svc name */ const char * typePattern, /* regular expression to match svc type */ const char * keyPattern, /* regular expression to match svc key */ FUNCPTR routine, /* func to call for each svc entry */ void * routineArg /* arbitrary user-supplied arg */ )
This routine calls a user-supplied routine to examine each WTX-registered service; it calls the specified routine once for each service. The routine should be declared as follows:
BOOL32 routine ( WTX_DESC_Q * pDesc, /* entry name */ int arg /* arbitrary user-supplied arg */ )The user-supplied routine should return TRUE if wtxEach( ) is to continue calling it for each entry, or FALSE if it is done and wtxEach( ) can exit.Note that all descriptors are deallocated upon exit.
WTX_OK or WTX_ERROR if the table of descriptors could not be obtained.
- WTX_ERR_API_REGISTRY_UNREACHABLE
- The registry service is not reachable (in other words, the registry daemon is not running).
- WTX_ERR_API_MEMALLOC
- There are insufficient resources to allocate the WTX_DESC_Q structure for the result value.
wtxInfoQ( )
wtxTimeoutSet( ) - set the timeout for completion of WTX calls
STATUS wtxTimeoutSet ( HWTX hWtx, /* WTX API handle */ UINT32 msec /* New timeout value in milliseconds */ )
This routine changes the timeout value for making WTX API calls. When a call takes longer than the value specified by msec (in milliseconds), the call aborts with an error status and the error code is set to WTX_ERR_API_REQUEST_TIMED_OUT.
The timeout for WTX registry calls is unaffected.
WTX_OK or WTX_ERROR.
wtxTimeoutGet( ) - get the current timeout for completion of WTX calls
STATUS wtxTimeoutGet ( HWTX hWtx, /* WTX API handle */ UINT32 * pMsec /* Pointer to timeout value in milliseconds */ )
This routine gets the current timeout value for making WTX API calls. The value is returned in the UINT32 pointed to by pMsec.
WTX_OK or WTX_ERROR.
wtxToolIdGet( ) - return the tool identifier of the current tool
UINT32 wtxToolIdGet ( HWTX hWtx /* WTX API handle */ )
This function returns the tool identifier associated with the given handle hWtx.
The tool identifier or WTX_ERROR on error.
wtxMemDisassemble( ) - get disassembled instructions matching the given address
WTX_DASM_INST_LIST * wtxMemDisassemble ( HWTX hWtx, /* WTX API handle */ TGT_ADDR_T startAddr, /* Inst address to match */ UINT32 nInst, /* number of instructions to get */ TGT_ADDR_T endAddr, /* Last address to match */ BOOL32 printAddr, /* if instruction's address appended */ BOOL32 printOpcodes, /* if instruction's opcodes appended */ BOOL32 hexAddr /* for hex adress representation */ )
This routine gets a list of disassembled instructions matching given address. startAddr indicates where to begin disassembly, while nInst fixes the number of instructions to disassemble.
If endAddr is set, nInst has no matter, and only instructions between startAddr and endAddr are returned.
Formatting options are printAddr to print instruction's address, printOpcodes to print instruction's opcodes, and hexAddr to turn off the "symbolic + offset" address representation.
The returned structure is a 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;Each disassembled instruction has the following format :
{<symbolName>} <size> {<address>} {<opcodes>} {<disassembledInstruction>}The symbolname value is set to the symbol name corresponding to the current address, or to {} if no symbol name matches current instruction address.size represents the instruction size in bytes of memory
address field is set only if prependAddress is set to TRUE. Else an empty list member is returned : {}
opcodes of disassembled instructions are returned if the prependOpcode, else an empty list member is returned : {}.
The disassembledInstruction member is also quoted into curled braces to be easier to reach. The disassembled instruction contains the instruction mnemonic and adress, registers, ... as displayed by the board disassembler.
All the fields are always returned, even if empty, so a disassembled instruction always have the same number of members whatever are the options.
The instruction list allocated by wtxMemDisassemble should be freed by caller with wtxResultFree( ).
A pointer to a list of disassembled instructions or NULL on error.
Getting disassembled instuctions from address 12345 to address 15432, with instruction's address and instruction's opcode prepended :
startAddress = 12345; /* first instruction's address */ endAddress = 15432; /* last instruction's address */ nInst = 0; /* unhandled when endAddress is set */ prependAddress = TRUE; /* instruction's address prepended */ prependOpcode = TRUE; /* opcodes joined to instruction */ hexAddr = FALSE; /* "symbolic + offset" mode turned on */ pWtxDasmInstList = wtxMemDisassemble (hWtx, startAddress, nInst, endAddress, prependAddress, prependOpcode, hexAddr); ... wtxFreeResult (hWtx, pWtxDasmInstList);Getting 25 instructions, starting from address 54321. Address in disassembled instruction are only hexadecimal (not represented by a symbol name + offset). No instruction's addresses, no opcodes.
startAddress = 54321; /* first instruction's address */ endAddress = 0; /* get a known number of instructions */ nInst = 25; /* get 25 disassembled instructions */ prependAddress = FALSE; /* don't join addresses */ prependOpcode = FALSE; /* don't join opcodes */ hexAddr = TRUE; /* "symbolic + offset" mode turned off */ pWtxDasmInstList = wtxMemDisassemble (hWtx, startAddress, nInst, endAddress, prependAddress, prependOpcode, hexAddr); ... wtxFreeResult (hWtx, pWtxDasmInstList);
WTX_MEM_DISASSEMBLE, wtxSymListGet( ), wtxResultFree( ).
wtxAsyncEventGet( ) - get an event from the asynchronous event list
WTX_EVENT_DESC * wtxAsyncEventGet ( HWTX hWtx /* WTX API handle */ )
When the asynchronous event notification is started without user defined function, the only way to get events is to use wtxAsyncEventGet. This routine polls the asynchronous event list for any events sent to this client tool. It only returns one event at a time. The event descriptor returned is a string containing the primary event data, a length count of additional binary data and a pointer to the additional data. The memory allocated for the event-descriptor result must be freed by the user using wtxAsyncResultFree( ).
If the asynchronous event notification is started with a user defined function, then wtxAsyncEventGet( ) will always return a NULL pointer.
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;
A pointer to the descriptor for the event received or NULL.
wtxAsyncNotifyEnable( ), wtxAsyncNotifyDisable( ), wtxAsyncResultFree( ), wtxEventGet( )
wtxAsyncResultFree( ) - free memory used by a wtxAsyncEventGet( ) call result
STATUS wtxAsyncResultFree ( HWTX hWtx, WTX_EVENT_DESC * eventDesc /* pointer to structure to free */ )
This routine frees the memory allocated for the result of a wtxAsyncEventGet( ) call. eventDesc must point to the WTX_EVENT_DESC structure that was returned by wtxAsyncEventGet( ) call.
wtxResultFree( ) cannot be used to free memory used by a
wtxAsyncEventGet( ) call result.
WTX_OK
wtxAsyncEventGet( ), wtxAsyncNotifyEnable( ), wtxAsyncNotifyDisable( )