The target-server architecture of Tornado permits great flexibility, but also introduces a number of housekeeping details to manage situations like the following:

• the target you need to use does not have a server running

• other developers keep interfering with your target over the net

• you want some other developers to have access to your target, but not everyone

The Target menu in the Tornado Launcher offers commands that allow you to manage these chores and related details to do with target servers. The small buttons immediately below the menu bar provide quick access to the same commands.

The following list describes each button and Target menu command:

Button		Menu		Description
		Create		Define and start up a new target server. See 3.5.1 Configuring a Target Server.
		Unregister		Remove the selected target server from the Tornado registry's list of available servers. Do not use this command routinely. Under most circumstances, the registry automatically removes the entry for any target server that has been killed (for example, due to a host system crash). This command can also be used to do so. The registry honors the Unregister command only if the server does not respond to the registry. CAUTION: Even if a target server is not responsive, it is not always appropriate to unregister it; the server may simply be too busy to respond, or a heavy network load may be interfering. The Unregister command reminds you of this possibility and requests confirmation before it takes effect. Make sure the server is really gone before you unregister it.
		Reattach		Reconnect the selected target server to the underlying target. This command is rarely necessary, because target servers attempt to reconnect automatically when required. Use this command after turning on or connecting a target that has been unavailable, if you want to reattach a running server explicitly (rather than by running a tool).
		Reserve		Restrict a target to your own use, or share it with others. See 3.5.2 Sharing and Reserving Target Servers.
		Unreserve		Share a target with others. See 3.5.2 Sharing and Reserving Target Servers.
		Kill		Kill the currently selected target server. CAUTION: Close any tool sessions that use a particular target before you kill that target server. Killing a target server does not immediately destroy any attached tools, but the tools lose the ability to interact with the target. There is no way to reconnect a new target server to such orphaned tool sessions.
		Reboot		Re-initialize the selected target server and reboot its target.

To use a new target, you must first ensure the host and target are connected properly. The details are unique to each target, but 2.4.2 Networking the Host and Target discusses some of the issues that are frequently involved. Your BSP also contains a target-information reference that describes what to do for that particular target. See Help>Manuals contents>BSP Reference.

To configure and launch a target server, select Create from the Target menu, or press the launcher's button. The launcher displays the form shown in Figure 3-4. Many configuration options are available, but you can often skip all the optional parameters, specifying only the target name (and perhaps the serial device, if your target agent is configured for the WDB serial protocol).

Figure 3-4:  Form: Create Target Server

Each time you specify a configuration option, the Target server launch command box near the bottom of the form is updated automatically to show the tgtsvr command options that capture your chosen configuration. (For text fields, the command line is updated when you select another field or press RETURN.) The tgtsvr command is the underlying command that runs in the background for each target server as a UNIX daemon. The text in the Target server launch command box can be edited. Its display has the following uses:

• You can copy the text displayed, and insert it in any UNIX shell script to launch a target server with this configuration automatically.

• You can use the command-line display to explore the meanings of server options interactively, in conjunction with the tgtsvr reference documentation (either online, or in C. Tornado Tools Reference).

• You can type tgtsvr options directly in this box. This allows you to add options that are not generated by the dialog boxes, such as for third-party back-ends.

To start a target server and save your server configuration, press the Launch button at the bottom of the Create Target Server form.

If a server does not respond when you select it, kill it ( ) and try turning on the Verbose toggle near the middle of the Create Target Server form to display diagnostic messages when you start it again.

For targets with network connectivity, only one field is required. Fill in the IP address or network name for the target, in the box headed Target name or IP address. After filling this in, you can launch a server immediately. The launcher saves each configuration automatically (identified with the target-server name); thus, you can retrieve a server's configuration later to add more options.

If your target agent is configured for the WDB serial protocol, you must specify what UNIX device name is connected to the target, in the Serial line device box (entering the device name automatically selects wdbserial as the back end in the Backend list field). You must also fill in a name for the target server in the Target name or IP address box; in this case, the name is completely arbitrary, and is used only to identify your target server.

Specifying the serial line speed is not required if you use the default speed of 9600 bps. However, it is best to use the fastest possible line speed when controlling your target over serial lines. Select the fastest speed your target hardware supports from the scrolling list headed Serial line speed. (The target agent must be compiled with the same speed selected; see Configuration for Serial Connection.)

Each time you press the Launch button, the launcher saves the server configuration. The configuration name is the same name used to register the target server: the contents of the Target name or IP address box, or the name specified under Target server name, if you use this box to define a different name for your server.¹

The following controls are available to manage saved configurations:

Saved configurations scrolling list

Select a configuration by clicking on a server name from this list (top left of the form). The fields of the Create Target Server form are filled in as last specified for that server name. (The last configuration you were working with is selected automatically when you open the form.)

Delete button

Discard any configuration you no longer need by first selecting the configuration name, then pressing this button (in the row at the bottom of the form).

The command buttons at the bottom of the Create Target Server form perform the following functions (see Figure 3-4):

Help

Display reference information for tgtsvr, using your default browser.

Delete

Delete the selected configuration from the Saved configurations list.

Launch

Start a target server using the currently specified configuration, and close the Create Target Server form.

Quit

Discard the Create Target Server form without launching a server or saving.

This section describes all the configuration options you can specify in the Create Target Server form(Figure 3-4), in the order they appear (left to right and top to bottom).

Saved configurations

Select a saved configuration by clicking on a server name from this list.

Target name or IP address

The network name of the target hardware for networked targets, or an arbitrary target-server name for other targets. You must always specify this field.

Target server name

To give the target server its own name (distinct from the network name of the target), specify the name here. If you do not fill in this box, the target server is known by the same name as the target. Use this field to distinguish alternative configurations of a single target.

For serial targets, this box is never necessary, because the required Target name or IP address entry already specifies an arbitrary name for the server.

Authorized users file

To restrict this target server to a particular set of users, specify the name of a file of authorized user IDs here. If you do not specify an authorized-users file, any user on your network may connect to the target whenever it is not reserved. See 3.5.2 Sharing and Reserving Target Servers for more discussion of the authorized-users file.

Object module format

By default, the target server deduces the object-module format by inspecting the host-resident image of the run-time system. You can disable this by explicitly selecting an object format from this list.

Core file

A path on the host to an executable image corresponding to the software running on the target. This box is optional because the target agent reports the original path from where the executable was loaded to the server. However, if the file is no longer in the same location on the host as when your target downloaded it (or if host and target have different views of the file system), you can use this box to specify where to find the image on the host.

Target I/O Redirect

Turn on this toggle to redirect the target's standard input, output, and error. If Virtual console is selected, target I/O is redirected to the console window.

Shell I/O Redirect

Turn on this toggle to start a console window into which the target shell's standard input, output, and error will be directed. (This option is only available when Virtual console is selected.)

Virtual console

Turn on this toggle to display the virtual console for this target server (a dedicated xterm where any output or input through virtual I/O channels takes place).² Examples in this manual that involve input and output streams from target programs assume the target server is running with this option set. See Virtual I/O for a discussion of the role of the virtual console.

Console Display

The name of an X Window System display to use as a target-server virtual console. Fill in this box with the display server name and screen number, in the usual X Window System format hostname:N. If the Display toggle is turned on but this box is not filled in, the virtual console appears on display 0 of the same host that runs this target server. (The alternative display must grant authorization for your host to use it; see your X Window System documentation.)

No symbols

Turn on this toggle to avoid initial loading of the symbol table maintained on the host by the target server.

All symbols

Turn on this toggle to include local symbols as well as global symbols in the target symbol table. The default is to include only global symbols, but during development it can be useful to see all symbols.

Target/Host symbol table synchronization

Turn on this toggle to synchronize target and host symbol tables. Synchronizing the two symbol tables can be useful for debugging. The symbol table synchronization facility must be included in the target image to select this option. For more information see 4.3.3 Configuring VxWorks Components and the reference entry for symSyncLib.

Use portmapper

Turn on this toggle to register a target server with the RPC portmapper. While the portmapper is not needed for Tornado 2.0, this option is included for development environments in which both Tornado 2.0 and Tornado 1.0.1 are in use. When both releases are in use, the portmapper must be used on:

• Any host running a Tornado 2.0 registry that will be accessed by any host running Tornado 1.0.1.

• Any host running a Tornado 2.0 target server that will be accessed by any host running Tornado 1.0.1.

To use the portmapper when either a Tornado registry or target server is started from the command line, the -use_portmapper option must be included. See the registry (wtxregd) and target server (tgtsvr) reference documentation in Tornado User's Guide: Tornado Tools Reference for more information.

Verbose

Turn on this toggle to display target-server status information and error messages in a dedicated window.³

Use this display for troubleshooting. The same status and error information is saved in ~/.wind/launchLog.servername.

Locked

Turn on this toggle to restrict this target server to your own user ID. If you do not turn on this toggle, any authorized user may use or reserve the server after you launch it.

Memory cache size

Specify the size of the target-memory cache (either in decimal or hexadecimal). The target server maintains a cache on the host system, in order to avoid excessive data-transfer transactions with the target. By default, this cache can grow up to a size of 1 MB.

A larger maximum cache size may be desirable if the memory pool used by host tools on the target is very large, because transactions on memory outside the cache are far slower. See Scaling the Target Agent for more information about the memory pool managed by the server on the target.

TSFS Read/Write

Click the Read/Write box to change the option from the default read only. Make this change only when you plan to run WindView; at other times the TSFS option for your target server should be read only.

The TSFS provides the most convenient way to boot a target over a serial connection (see 2.6.7 Booting a Target Without a Network).

TSFS Root directory

Type the path to the files you want the target to be able to access through the target server in the Target Server File System root box. This is where WindView log files are saved. For example:

/usr/windview/logfiles 

If you use the TSFS for booting a target, it is recommended that you use the base Tornado installation directory ($WIND_BASE) or the root directory (/). If you do not do so, you must use the Core File configuration option to specify the location of the VxWorks image (see Core file).

Backend list

If your BSP requires a special communications protocol, select the communications protocol here. The default, wdbrpc, is suitable for targets with IP connectivity. The standard back ends are described in Table 3-1; see also 4.6 Configuring the Target-Host Communication Interface.

Table 3-1:  Communications Back Ends for Target Server

Back End Name		Description
default		Initially selected; implicitly selects wdbrpc.
wdbrpc		Tornado WDB protocol. This back end is the default. It is the most frequently used back end, and supports any kind of IP connection (for example, Ethernet). Serial hardware connections are supported by this back end if your host has SLIP. On a serial connection, this back end supports either system-level or task-level views of the target, depending on the target-agent configuration.
wdbserial		A version of the WDB back end specialized for serial hardware connections; does not require SLIP on the host system. This back end supports either system-level or task-level views of the target, depending on the target-agent configuration.
netRom		A back end that communicates over a proprietary communications protocol for NetROM.
wdbpipe		WDB Pipe back end. The back end for VxWorks target simulators. It supports either system-level or task-level views of the target, depending on the configuration of the target agent.
loopback		Testing back end. This back end is not useful for connecting to targets; it is intended only to exercise the target-server daemon during tests.

Serial line speed

If you choose the wdbserial back end, use this scrolling list to specify the line speed (in bits per second) that your target uses to communicate over its serial line. The default speed is 9600 bps; use the highest possible speed available, in order to maximize the host tools' access to target information.

When you change the line speed, you must also re-compile the target agent with WDB_TTY_BAUD defined to the same speed (Configuration for Serial Connection).

Serial line device

If you choose the wdbserial back end, use this text box to specify the serial device on your host that is connected to the target. The default serial device is /dev/ttya.

Backend Timeout

How many seconds to wait for a response from the agent running on the target system (the default is 3 seconds). This option is supported by the standard wdbrpc, wdbserial, and netrom back ends, but may not have an effect on other back ends.

Backend Resend

How many times to repeat a transaction if the target agent does not appear to respond the first time. This option is supported by the standard wdbrpc, wdbserial, and netrom back ends, but may not have an effect on other back ends.

Backend log file

Log every WDB request sent to the target agent in this file. Back ends that are not based on WDB ignore this option. As with the Verbose toggle, a dedicated window appears to display the log.

Backend log file max size

The maximum size of the backend log file, in bytes. If defined, the file is limited to the specified size and written to as a circular file. That is, when the maximum size is reached, the file is rewritten from the beginning. If the file initially exists, it is deleted. This means that if the target server restarts (for example, due to a reboot), the log file will be reset.

WTX Log file

Log every WTX request sent to the target server in the specified file. If the file exists, log messages will be appended (unless a maximum file size is set in WTX Log file max size, in which case it is overwritten).

WTX Log file max size

The maximum size of the WTX log file, in bytes. If defined, the file is limited to the specified size and written to as a circular file. That is, when the maximum size is reached, the file is rewritten from the beginning. If the file initially exists, it is deleted. This means that if the target server restarts (for example, due to a reboot), the log file will be reset.

WTX Log file filter

Use this field to limit the amount of information written to a WTX log file. Enter a regular expression designed to filter out specific WTX requests. Default logging behavior may otherwise create a very large file, as all requests are logged.

A target server may be made available to the following classes of user:

• the user who started the server

• a single user, who may or may not have started the server

• a list of specified users

• any user⁴

When a target server is available to anyone, its status (shown in the Information panel of the main launcher window; see Figure 3-3) is unreserved. Any user can attach a tool to the target, and any user can also restrict its use.

When you configure a target server, you can arrange for the server to be exclusively available to your user ID every time you launch it, by clicking the Lock toggle in the Create Target Server form. See 3.5.1 Configuring a Target Server. Target servers launched this way have the status locked.

If a target server is not locked by its creator, and if no one else has reserved it, you can reserve the target server for your own use: click on Target>Reserve, or on the launcher button. The target status becomes reserved until you release the target with the Unreserve command ( ). Unreserve on a target that is not reserved has no effect, nor does Unreserve on a target reserved or locked by someone else.

This simple reserve/unreserve locking mechanism is sufficient for many development environments. In some organizations, however, it may be necessary to further restrict some targets to a particular group of users. For example, a Q/A organization may need to ensure certain targets are used only for testing, while still using the reserve/unreserve mechanism to manage contention within the group of testers.

To restrict a target server to a list of users, create a list of authorized users in a file. The format for the file is the simplest possible: one user name per line. The user names are host sign-on names, as used by system files like /etc/passwd (or its network-wide equivalent). You can also use one special entry in the authorization file: a plus sign + to explicitly authorize any user to connect to the target server. (This might be useful to preserve the link between a target server and an authorization file when access to that target need only be restricted from time to time.)

To link an authorization file to a target server, specify the file's full pathname in the Authorized users file box of the Create Target Server screen (see Figure 3-4).

1:  Data for each saved configuration is stored in a file with the same name as the configuration, in the directory .wind/tgtsvr under your home directory.

2:  You can also create a virtual console from any Tornado tool using Tcl, with
wtxConsoleCreate. See Tornado API Guide: WTX TCL API.

3:  To disable the automatic display of log files by the launcher, insert "set noViewers 1" in your ~/.wind/launch.tcl initialization file.

4:  Strictly speaking, there is another layer of authorization defining who is meant by "any user". The file $WIND_BASE/.wind/userlock is a Tornado-wide authorization file, used as the default list of authorized users for any target server without its own authorized-users file. The format of this file is the same format described below for individual target-server authorization files.