VxWorks Reference Manual : Libraries
symSyncLib - host/target symbol table synchronization
symSyncLibInit( ) - initialize host/target symbol table synchronization
symSyncTimeoutSet( ) - set WTX timeout
This module provides host/target symbol table synchronization. With synchronization, every module or symbol added to the run-time system from either the target or host side can be seen by facilities on both the target and the host. Symbol-table synchronization makes it possible to use host tools to debug application modules loaded with the target loader or from a target file system. To enable synchronization, two actions must be performed:
- 1
- The module is initialized by symSyncLibInit( ), which is called automatically when the configuration macro INCLUDE_SYM_TBL_SYNC is defined.
- 2
- The target server is launched with the -s option.
If synchronization is enabled, symSyncLib spawns a synchronization task on the target, tSymSync. This task behaves as a WTX tool and attaches itself to the target server. When the task starts, it synchronizes target and host symbol tables so that every module loaded on the target before the target server was started can be seen by the host tools. This feature is particularly useful if VxWorks is started with a target-based startup script before the target server has been launched.
The tSymSync task also assures synchronization as new symbols are added by either the target or the host tools. The task waits for synchronization events on two channels: a WTX event from the host or a message queue additon from the target.
The tSymSync task, like all WTX tools, must be able to connect to the WTX registry. To make the WTX registry accissible from the target, do one of the following:
- 1
- Boot the target from a host on the same subnet as the registry.
- 2
- Start the registry on the same host the target boots from.
- 3
- Add the needed routes with routeAdd( ) calls, possibly in a startup script.
Neither the host tools nor the target loader wait for synchronization completion to return. To know when the synchronization is complete, you can wait for the corresponding event sent by the target server, or, if your target server was started with the -V option, it prints a message indicating synchronization has been completed.
The event sent by the target server is of the following format:
SYNC_DONE syncType syncObj syncStatusThe following are examples of messages displayed by the target server indicating synchronization is complete:Added target_modules to target-server.....done Added ttTest.o.68k to target............doneIf synchronization fails, the following message is displayed:Added gopher.o to target............failedThis error generally means that synchronization of the corresponding module or symbol is no longer possible because it no longer exists in the original symbol table. If so, it will be followed by:Removed gopher.o from target..........failedFailure can also occur if a timeout is reached. Call symSyncTimeoutSet( ) to modify the WTX timeout between the target synchronization task and the target server.
Hardware: Because the synchronization task uses the WTX protocol to communicate with the target server, the target must include network facilities. Depending on how much synchronization is to be done (number of symbols to transfer), a reasonable throughput between the target server and target agent is required (the wdbrpc backend is recommended when large modules are to be loaded).
Performance: The synchronization task requires some minor overhead in target routines msgQSend( ), loadModule( ), symAdd( ), and symRemove( ); however, if an application sends more than 15 synchronization events, it will fill the message queue and then need to wait for a synchronization event to be processed by tSymSync. Also, waiting for host synchronization events is done by polling; thus there may be some impact on performance if there are lower-priority tasks than tSymSync. If no more synchronization is needed, tSymSync can be suspended.
Known problem: Modules with undefined symbols that are loaded from the target are not synchronized; however, they are synchronized if they are loaded from the host.
symSyncLibInit( ) - initialize host/target symbol table synchronization
void symSyncLibInit ()
This routine initializes host/target symbol table synchronization. To enable synchronization, it must be called before a target server is started. It is called automatically if the configuration macro INCLUDE_SYM_TBL_SYNC is defined.
N/A
symSyncTimeoutSet( ) - set WTX timeout
UINT32 symSyncTimeoutSet ( UINT32 timeout /* WTX timeout in milliseconds */ )
This routine sets the WTX timeout between target server and synchronization task.
If timeout is 0, the current timeout, otherwise the new timeout value in milliseconds.