Tornado Reference : Tornado Tools

tgtsvr

NAME

tgtsvr - the target board server

SYNOPSIS

tgtsvr  [-A.llsyms] [-B.ackend backendName] [-Bd.ebug fileName]
        [-Bm.ax size] [-b.ps linespeed] [-Br.esend number]
        [-Bt.imeout timeout] [-C.onsole] [-c.ore fileName]
        [-d.evice device] [-display ]
        [-f.ormat formatName] [-h.elp] [-hfc] [-L.ock]
        [-m.emory nbytes] [-n.ame serverName] [-N.osyms]
        [-p.ort portNumber] [-R TSFS_root] [-redirectIO]
        [-redirectShell] [-RW] [-s.ynchro] [-use_portmapper]
        [-u.sers fileName] [-V.erbose] [-v.ersion]
        [-Wd.ebug fileName] [-Wf.ilter request] [-Wm.ax size] 
        targetName [backend specific options]

DESCRIPTION

The target server is the Tornado component that allows development tools, such as the shell (see windsh) or a debugger, to communicate with a remote target system, such as VxWorks. The Tornado tools are autonomous programs running on a cross-development host. They are attached to a particular target server when they begin executing.

The server communicates with the target system through an interface called the target agent. This agent is either integrated with the target system (for instance, as a task), or independent from it. When tgtsvr is started, it identifies the target agent by means of the only required argument: the name of a target board running the target agent.

The name of the target board is linked with the name of the host machine where the target server runs, to form a unique identifier used throughout the working session by all tools. This name is recorded in the name database of the Tornado Service Registry (see wtxregd). The form of this identifier is targetName@serverHost. For instance, tPad@aven refers to the target named tPad as represented by a target server running on the host aven.

An alternative target name, however, may be specified with the -n option if the board name is already in use.

Tools may use truncated identifiers, if the short names match a unique name among all names registered by the Tornado Registry (see launch and wtxregd). Any unique substring in the board name is sufficient, and the "@" extension may be omitted as well.

The target server gets requests from the Tornado tools. These requests, depending on their type, may either be satisfied by the target server itself, or require that the target server in turn send requests to the target agent.

Locating the Target Executable

The target server depends on a host-resident image of the target executable. By default (if the -c option is not specified), the target server queries the agent running on the target for this path name. The default works well for the common situation where the runtime code is downloaded from the host. However, in some situations (for example, if the target is running a standalone version of VxWorks generated from another host), the target agent cannot supply a useful path for the executable on the host. In this situation, use the -c option to specify the path explicitly. Environment variables and ~ are recognized and expanded by the target server as follow:

`~`, if given as first character of the pathname, is expanded to the user's home directory, or if another user is specified ("~joe"), `~` will expanded to joe's home directory. WIN32 users, `~` will be expanded to the environment variable "$HOME", or "$HOMEDRIVE$HOMEPATH" if "$HOME" is not defined. If none of these variables are defined, `~` will be ignored.

Environment variables can be set by using "$VAR", "$(VAR)" and "{VAR}" notation. They will be expanded to the value set up on the target server's environment, or will be ignored if they are not defined.

"~/$(VXWORKS).exe" pathname will be expanded to "/home/joe/proj/vxWorks.exe" if the user's home directory is "/home/joe", and VXWORKS is set to "proj/vxWorks".

Authentication and Access Permission

The target server allows for user access permission to be restricted. The resource file $WIND_BASE/.wind/userlock can be created to hold a list of authorized user IDs (a single + sign means that universal access is allowed). If this file does not exist, the target server will assume that no user restriction will apply. Alternative resource files may be specified with the -u option. A target server restricted in this way refuses any requests from tools started by an unauthorized user.

It is also possible to lock a target server with the -L option. Then only the user that starts the target server can connect tools to that server (see also the Reserve and Unreserve menu items of launch).

Target Server Components

The target server is made up of the following units:

• communication unit with the tools.
• communication unit, or back end, with the target agent.
• object module management unit (loader, unloader).
• target symbol table management unit.
• target memory management unit.
• virtual input/output management unit.

WTX Protocol

Communication between the target server and the Tornado tools is done via the RPC/XDR mechanism. Tools' requests and target servers' answers or events follow the formats defined by the Wind River Tool Exchange (WTX) messaging protocol. There is no requirement for the Tornado tools and the target server to operate from the same host machine. They may be distributed across a network.

If the -Wd option is specified, all WTX requests are logged in a log file. The default behaviour is to append log messages at the end of the log file (if it does not exists, it will be created). If the -Wm option is also specified, the file size will be limited to the given value, and written as a circular file: i.e. when this value is reached, the file is rewritten from the begining. If the file exists, it will be erased.

Note that a tool can be connected to more than one target server allowing for managing data coming from several remote target systems.

The -Wf option can be used to filter a particular WTX request in the log file. The default filter is set to "WTX_EVENT_GET" to avoid thousands of such request when a wind shell version 1 is connected to the target server.

Back Ends

The target server's back end is the intermediary for all communication with the target agent. Thus, the back end must be designed to use whatever communication protocol and transport layer the agent uses. Because not all agents can use the default protocol (WDB over RPC/XDR) and transport layer (Ethernet), alternative back ends can be specified explicitly. Custom back ends are also possible.

The following back ends are supported by Wind River Systems (see <$WIND_BASE>/host/<$WIND_HOST_TYPE>/lib/backend):

wdbrpc (default)

The Tornado WDB RPC back end. It is the most frequently used, and supports either Ethernet or serial connections. This back end supports either system-level or task-level views of the target.

wdbpipe

This back end is to be used on all simulators. It is based on named pipes on UNIX hosts and mailslots for windows hosts.

wdbserial

A version of the WDB back end supporting only serial hardware connection. Note that in order to use this back end the serial connection should only use the "Tx", "Rx" and "Gnd" signals by default. When the -hfc (hardware flow control) option is used, the "RTS", "CTS" and "DTR" signals are also supported.

netrom

A proprietary communications protocol for NetROM, a networked ROM emulator from Applied Microsystems Corporation.

loopback

A testing back end. This back end is not useful for connecting to targets; it is used only to exercise the target server daemon during tests.

Use the -B option to select an alternative back end.

If the target agent is connected through the wdbserial back end, target server options -d and -b allow the tty device and the serial line speed to be specified, respectively. The -hfc option activates hardware flow control on the serial link.

If the target agent is connected through the wdbrpc backend, the -p option allows to specify the UDP port number.

If the communication link between the target server and the target agent is slow, it may be necessary to adjust the back end timeout value (with the -Bt option), as well as the back-end retry count (with the -Br option).

Back ends may also provide their own set of options (see Tornado API Guide for details). The back end options are shown first. These options can be viewed with:

    tgtsvr -B <bkendName> -h

The WDB requests can be logged on a file by using the -Bd option. The default behaviour is to append log messages at the end of the log file (if it does not exists, it will be created). If the -Bm option is also specified, the file size will be limited to the given value, and written as a circular file: i.e. when this value is reached, the file is rewritten from the begining. If the file exists, it will be erased.

Object Module Management

The target server may handle object modules from various format (currently, a.out COFF, ELF, SOM, and pecoff). The core file is analyzed in order to determine what object module format will be used for the working session. It is possible to bypass this determination with the -f option followed by a format name. Supported format names can be found in the resource file: $WIND_BASE/host/resource/target/architecturedb. The target server can be extended to support new Object Module Format (see "Object Module Loader" in Tornado API Guide ).

Target Symbol Table

The target server maintains (on the host) a symbol table for the target executable. It builds this symbol table from an input file called the core file. The symbols and memory locations obtained from this file are used to calculate relocation information when linking other user modules. The target server normally obtains the location of the core file from the target agent (in which case it is the file originally used as the executable for the agent itself). However, because the core file may no longer be in the location where it was used to load the agent, a path name for it can also be specified explicitly with the -c option (see Locating the Target Executable above for giving an alternate path name).

It is also possible to prevent the target server from building the target symbol table from the core file with the -N option. If the target server is started with this option, the first file to be loaded must be a "fully-linked" object file (an object file with no external references). Any subsequent modules loaded may be relocatable; the server calculates relocation information by reference to that first loaded object file.

Using the -A option forces the target server to include all global and local symbols from the core file in the target server symbol table.

Target Memory Management

The target server manages the target agent memory pool on the remote system. This memory pool is mainly used by the loader when object files are downloaded. The target server automatically increases the size of the agent memory pool when necessary (when there is not enough room to load a file, for example). A cache is implemented so that memory-related requests from Tornado tools may be satisfied at the target server level, avoiding the transfer of data from the real target memory. This cache has a default maximum size of 1 MB.

The -m option allows to specify a maximum size for the cache. This may be required when the agent memory pool size becomes greater than the maximum size of the cache. In this situation, the memory-related requests that fall outside the cache are satisfied at the target level, and thus are substantially slower.

The Tornado browser provides a graphical view of the target agent memory pool utilization.

Virtual Input/Output Mechanism

The target server can redirect data through virtual Input/Output channels. For target tasks to have access to this mechanism, a Virtual I/O Driver must be included in the target system. When this driver is included, any task on the target may open a virtual channel to read from, or write to, that channel. On the host, any tool may open the same virtual channel to write to, or read from, that channel. Thus the target server acts as an I/O dispatcher, multiplexing whatever physical communications layer is available to allow run-time tasks and host tools to communicate easily.

When the target server is started with the -C option, a console window attached to virtual channel 0 is displayed. On UNIX, this window can be displayed on a specified X server (including a host other than where the target server is running) with the -display option. The number of buffered lines (default 88) can be changed by setting the environment variable WTX_CONSOLE_LINES to the number of desired buffered line. Set this variable before starting your UNIX target server.

This permits any task on the target to open virtual I/O channel 0 to send characters to, or read characters from, this window. If started with -redirectIO, a redirection of target standard I/O is automatically done. If -redirectIO is set, but -C flag is not set, the target I/O will be redirected to the target server, but, since no console will be present to display the informations, events will be sent to the connected WTX tools.

The target server can also be used as a virtual target shell console: The shell is running on the target, and its I/O are done from the target server virtual console. To do this, use the -redirectShell flag in conjonction with -C flag. The target server will automatically redirect the target shell I/O into the default target server console. The shell must be included in the target system. This feature is usefull if target is only accessible through back end and actions which cannot be done via windsh (like loading object from a file system local to the target) have to be performed.

CAVEAT

Redirecting target I/O into the target server's console may lead side effects:

• If you use -redirectIO when a target shell is running, its I/O will also get redirected in the target server's console. You will see a double echo (one echo for the target server console, and another one by the target shell itself), and the target Shell input will be lost when the target server stops. Use the -redirectShell in conjonction with -redirectIO option to avoid this.
• -redirectIO and -redirectShell flags are not exclusives. They can be jointly used. But in this case, only the target shell will get its input from the target server's console. Other tasks pending on a read on their stdin will pend forever (unless the targetShell is destroyed).
• If you use Windsh with a target server which has -redirectIO and -C set, remember that windsh also redirects the I/O. So if you try

      scanf ("%s", buf)
  

  from the command line the input will be done by the windsh, not from the target server's console.
• If you use windsh with a target server which has not set -redirectIO and try a command which launches another task which wants to write messages, you won't see them: the child tasks get their I/O reset to the global I/O descriptors (if the target server was launched with -C, those outputs will be sent in the target server's console). Setting -redirectIO without -C will permit to see the task's child output into the windsh which launched them. But be aware that ALL TOOLS will be notified of the target's task ouptut.
• Using -redirectShell, if the shell cannot be redirected to the target server console, the characters typed in the console window won't be echoed, since that the shell's job to echo each typed characters.

Target Server File System (TSFS)

Other virtual I/O channels are available for general file I/O. Target tasks can use these channels to access the host's file system just as they would access target connected file systems. This type of virtual I/O is referred to as the Target Server File System or TSFS.

The part of the host's file system visible to targets using the TSFS is specified with the -R root option. For example, if a root of "/users/john" is specified, the target will only be able to access files on the host's file system within and below /users/john.

By default, the host's files are accessible for reading only by target processes using the TSFS. To make the files accessble for reading and writing, -RW should be specified. When -RW is specified, access to the target server is automatically restricted to host processes with the same user ID as the target server, as if the -L option was specified.

OPTIONS

-A | -Allsyms

Include all local and global core-file symbols in the target symbol table.

-B backendName | -Backend backendName

Specify an alternative back end to communicate with the target agent. The default is a back end using the WDB protocol based on the RPC/XDR mechanism. Back end names can be deduced from the names of the files in <$WIND_BASE>/host/<$WIND_HOST_TYPE>/lib/backend (just remove the extension).

-Bd fileName | -Bdebug fileName

Log every WDB request sent to the target agent in the specified file. If the file already exists, log messages will be appened to it (unless the -Bm flag is set). Back ends that are not based on WDB RPC ignore this option.

-Bm size | -Bmax size

Max size in bytes for the WDB logging file. If this flag is set, the file size will be limited to the given value, and written as a circular file: i.e. when this value is reached, the file is rewritten from the begining. If the file exists, it will be erased. So, be aware that if the target server restarts (due to a target reboot, for example), the WDB log file will be reset.

-b linespeed | -bps linespeed

Specify the speed of a serial link used to communicate with a target agent. The default value is 9600 bps.

-Br number | -Bresend number

Specify the number of times the back end should attempt to repeat a request to the target agent, if a transmission fails. Default: three retries. Some back ends may ignore this option.

-Bt timeout | -Btimeout timeout

Specify the timeout, in seconds, for back-end transactions with the target agent. Default: one second. Some back ends may ignore this option.

-C | -Console

Start a console window. Target tasks can perform I/O through this window using virtual channel 0.

-c fileName | -core fileName

By default, the target server gets the name of the core file (the executable initially running on the target) from the target agent. If the target agent does not have this information (or if its information is out of date), use this option to specify a path to the core file explicitly.

-d device | -device device

Specify the tty device used to communicate with a target agent. The default device is "/dev/ttya" on Solaris, "/dev/tty0p0" on HP-UX and "COM2" on Windows.

-display hostName:0

(UNIX only) Specify the X server to contact in order to display the virtual console window.

-f formatName | -format formatName

Name of the alternate object module format (for example, a.out or COFF) that will be managed by the target server.

-h | -help

Print a help message summarizing tgtsvr usage and options.

-hfc

Activate hardware flow control on a serial link using "RTS", "CTS" and "DTR" signals. This option is available only with the wdbserial back end.

-L | -Lock

Restrict access to this target server to processes running under the same user ID as the server.

-m nbytes | -memory nbytes

Set the size of the agent memory pool cache managed by the target server (default is 1 MB).

-n serverName | -name serverName

Specify an alternative name for the target server (instead of the default, based on the target's name). Target server's name should be constituted by alphanumeric characters only.

-N | -Nosyms

Do not use a core file to build the target symbol table.

-p portNumber | -port portNumber

Specify the UDP port number to communicate with a target agent when the wdbrpc back end is used. The default port number is 0x4321.

-R root

Establish the root of the host's file system visible to target processes using the Target Server File System.

-redirectIO

Redirect the target global stdin, stdout and stderr in the target server. If -C flag is not set, WTX events will be sent to all WTX tools when characters come from the target.

-redirectShell

Start a console window with target shell stdin, stdout and stderr redirected in it. This flag is valid only if -C flag is set.

-RW

Allow read and write access to host files by target processes using the Target Server File System. When this option is specified, access to the target server is restricted as if -L were also specified.

-s | -synchro

Synchronize target and host symbol tables. The symbol table synchronization facility must also be included in the target image; see the reference entry for symSyncLib.

-use_portmapper

Use the local portmapper to register the target server rpc services. This flag MUST be set if tornado tools version 1.x have to connect to this target server.

-u fileName | -users fileName

Specify a file containing a list of authorized users. Only users whose IDs appear as lines in this file will be able to connect tools to the target server, unless the file contains the character + on a line by itself (which authorizes all users).

-V | -Verbose

Turn on the target server's verbose mode. By default, the target server is silent. In verbose mode, it displays information, warning and error messages on the standard output.

-v | -version

Identify the version of the target server.

-Wd fileName | -Wdebug fileName

Log every WTX request sent to the target server in the specified file. If the file exists, log messages will be appened to it (unless the -Wm flag is set).

-Wf request | -Wfilter request

Remove WTX request from the WTX log file. The default WTX log behaviour is to log every requests the target server is servicing. This may lead to a huge file. This flag allows to reduce the amount of information by giving a regular expression to filter out WTX requests.

-Wm size | -Wmax size

Max size in bytes for the WTX logging file. If this flag is set, the file size will be limited to the given value, and written as a circular file: i.e. when this value is reached, the file is rewritten from the begining. If the file exists, it will be erased. So, be aware that if the target server restarts (due to a target reboot, for example), the WTX log file will be reset.

EXAMPLES

Start a target server on target with IP address equal to "147.108.108.1" in verbose mode and give it the name "myTargetServer".

    tgtsvr -V -name myTargetServer 147.108.108.1

Display the flags handled by the "wdbpipe" backend.

    tgtsvr -h -B wdbpipe

Start a target server named "myTargetServer" on VxWorks simulator number "0" with WDB request log going to file "/tmp/vxsim0Wdb.log"

    tgtsvr -B wdbpipe -Bd /tmp/vxsim0Wdb.log vxsim0 -n myTargetServer

Specify a core file to the target server attached to a serial line on COM2 at 38400 bauds (Windows). Note that the target name flag can be anything in this case it is only used to build the target server name.

    tgtsvr -c D:\tornado\target\config\mv1604\vxWorks -V -B wdbserial -b 38400 myTarget

Start a target server with a target shell console on target called "arm7tBoard". VxWorks should be configured to include the target shell for this to work.

    tgtsvr -C -redirectShell -V arm7tBoard 

Start a target server in verbose mode on target called "arm7tBoard" with all target I/O redirected in the target server's console.

    tgtsvr -C -redirectIO -V arm7tBoard 

ENVIRONMENT VARIABLES

WIND_BASE

root location of the Tornado tree.

WIND_REGISTRY

host on which the Tornado Registry daemon runs (see wtxregd).

FILES

The following resource files are required by the target server:

$WIND_BASE/.wind/userlock

default authorization file (list of authorized users).

$WIND_BASE/host/resource/target/architecturedb

supported targets resource base.

SEE ALSO

tgtsvr, wtxregd, launch, browser, windsh, Tornado User's Guide , Tornado API Guide