Target Control

The following topics are covered in this section:

• Overview of Target Control Concepts
• GUI Interface
• Shell Interface
• Customization Options

---

Overview of Target Control Concepts

A new target control system was introduced with 3.2.0 releases. In the following discussion, this system is referred to as the new system. The previous system is referred to as the old system.

Identifying Targets

In the old target control scheme, the concept of physical and logical targets did not exist. Targets were identified explicitly in the Tools > Target Control dialog. To run on a target you specified it explicitly via the Tools > Target Control dialog.

In the new target control scheme, a logical target is specified at run time. That logical target is mapped to a physical target, on which the application is run.

Physical Targets

A physical target refers to the actual target on which a program may be run. Physical targets include boards (e.g., an mvme1603 PowerPC board), simulators (including memory-only simulators), emulators, and probes. Info about most physical targets is shared among users. Simulators are the exception.

The default implementation of target control operations uses CMVC functionality to control text files (each text file represents a physical target). The implementation is located under a directory specified by the APEX_TARGET_CONTROL environment variable. APEX_TARGET_CONTROL is set in $APEX_EMBEDDED_HOME/bin/apex_embedded.init.

The default value is $APEX_EMBEDDED_HOME/target_control/cmvc.

Each physical target file consists of a series of field and value pairs. Below is an example of a typical physical target file. The fields are explained later in this chapter.

% cat $APEX_BASE/embedded/physical_targets.ss/main.wrk/rebecca
DEFAULT_KERNEL: 
/aloha/products/base/ada/krn_conf.ss/i386.rx_i386.isbc133.ada95.3.0.1.rel/v_
krn_main
IP_NAME_OR_ADDRESS: target-1-161
SERIAL_PORT_HOST: nushuz
SERIAL_PORT_NUMBER: /dev/ttyja

This file is visible to (and shared by) all users. Any user has the ability to create a new file representing a new physical target. Users must "reserve" a physical target before changing information contained in the physical target file. By default, a physical target is reserved by performing a CMVC check_out on the file.

When a user runs a program, they must specify the physical target to run it on. This is done indirectly (and in most cases automatically) via a logical target name.

The current list of physical targets can be viewed via the Tools > Targets dialog.

Storage Location for Physical Targets

Physical Targets are stored as CMVC controlled text files: one file per physical target. The subsystem and view used to store these files is created during Apex installation. The location is defined by the $APEX_PHYSICAL_TARGETS environment variable that is set in $APEX_EMBEDDED_HOME/bin/apex_embedded.init.

The default location is $APEX_BASE/embedded/physical_targets.ss/main.wrk

Notice that this view has no version number in it. It is expected that this same view will be used by multiple versions of Apex. It is unlikely that you will want to change this location. But if such a need does arise, here are the steps required.

1 . Create a new view. It can be under any subsystem.

2 . To switch all users to the new view, edit the value for APEX_PHYSICAL_TARGETS in $APEX_EMBEDDED_HOME/bin/apex_embedded.init.

To switch a single user to the new view, use Tools > Session > Environment to set the value of the APEX_PHYSICAL_TARGETS variable.

Logical Targets

A logical target is a name that is mapped to a physical target. Each user has their own set of mapped logical targets. Logical targets are not shared among users. Each logical target mapped to a physical target has an associated logical target file. These files are kept in $APEX_RATIONAL_DIR/apex_embedded/logical_names. Some users may not set the APEX_RATIONAL_DIR environment variable. In this case ~/.Rational/apex_embedded/logical_names is used. Users may wish to have the same set of logical targets independent of the machine they are running on. In that case they should insure that ~/.Rational or $APEX_RATIONAL_DIR are shared among their machines.

Each logical target file consists of a series of field and value pairs. Below is an example of a typical logical target file. The fields are explained later in this chapter.

% cat ~/.Rational/apex_embedded/logical_names/i386.rx_i386.isbc133
INTERFACE: network
PHYSICAL: rebecca

When the File > Run, File > Download, or File > Debug dialogs are brought up in the context of an embedded view, they have a Logical Target field below the Executable field. The Logical Target field must have a value before program can be run. The default value is supplied via the LOGICAL_TARGET_NAME switch in the view's Policy/Switches file. This switch is obtained from the model when the view is created (or remodeled). Here are some examples:

LOGICAL_TARGET_NAME: power.rx_ppc.issim
LOGICAL_TARGET_NAME: mips.rx_mips1b.idt381
LOGICAL_TARGET_NAME: rh32.rx_rh32p3.board

The user is free to use any name they want as a logical target. They can overwrite the value in the Policy/Switch file. This will change the logical target associated with that view. Alternatively, they can change the contents of the Logical Target field in the File > Run dialog. This will change the logical target for a single execution.

The current list of mapped logical targets can be viewed via the Tools > Targets dialog.

Mapping A Logical Target to A Physical Target

For a logical target to be used, it must be mapped to a physical target. If you attempt to run a program on a logical target that is not mapped to a physical target, a popup will prompt you to map the target.

Part of mapping a logical target to a physical target is choosing a target interface. The target interface indicates how you wish to communicate with the physical target when accessing it via this particular logical target. For example, you may wish to use a serial connection for one logical target, and a network connection for another. Valid interface options are: serial, simulator, memory_simulator, network, VxWorks, LynxOS.

A logical target can be mapped to only one physical target. Multiple logical targets can be mapped to the same physical target.

The Tools > Targets dialog displays the list of mapped logical and physical targets.

Multiple Targets in a Single Apex Session

In the old target control scheme, Apex used a global variable inside Apex_main to keep track of the "current" target. When you ran an embedded application, it referenced this global variable to determine which target to use. This meant there could only be one current target in an Apex session. Using multiple targets required changing the global variable, or starting multiple Apex sessions.

In the new target control scheme, the target used to execute an embedded application is determined by translating the logical target to a physical target. Since the logical target is specified at run time, it is possible to use multiple targets simultaneously.

Simplification of User Interface

In the old target control scheme, you needed to specify the current embedded target before executing a program. This was done via the Tools > Target Control dialog. Simulators were shut down at the end of each Apex session, and had to be restarted manually during the next session.

In the new target control scheme much of this work is no longer necessary. The LOGICAL_TARGET_NAME switch in each view identifies the logical target associated with that view. The mapping from logical targets to physical targets persists from one Apex session to the next. This means that once you have mapped a view's logical target to a physical target, you can visit a view after restarting your Apex session and run your program without any other preparation. Simulators are still shut down at the end of an Apex session. But they are automatically restarted on demand during the next Apex session.

Customizable Features

The following features of the new target control scheme are customizable. These features are described in detail in Customization Options in this document.

• The method for storing information about physical targets. The default method is to create a CMVC-controlled file for each physical target.
• The meaning of "Reserving" a physical target. The default meaning to check_out the CMVC controlled file.
• The actions allowed on a target reserved by someone else. The default is to warn the user they are using a target reserved by another person, but to let the action proceed.
• The meaning of "Resetting" a target. There is no default supplied for most types of targets. Resetting a simulator restarts it.
• The meaning of "Pinging" a target. The default is to use /usr/sbin/ping.

---

GUI Interface

General information about logical and physical target can be obtained from the Tools > Targets dialog.

Tools > Targets

Note: VxWorks Tornado targets have a target server associated with the target. For convenience, the host on which the server is running is added to the physical target name with a '@'. For example, if you have a board named mvme1603_b, and a target server for this board is running on picard, your physical target will be displayed as mvme1603_b@picard.

Starting with the 4.0.0 release, the Targets dialog has been combined with the File > Run, File > Download, and File > Debug dialogs. The combined dialog contains four common fields at the top: Program, Arguments, Context, and Logical Target. Below this are four tabs corresponding to the original dialogs: Run, Debug, Download, and Targets. Select the Targets tab.

The Targets tab provides a list of targets. It also allows you to view and modify information about individual physical and logical targets. The Targets tab is divided into four panes/sections:

• The top pane is titled List of Targets. It contains two columns: "Logical" and "Physical". The Physical column lists all physical targets. The logical column lists the logical target(s) mapped to the physical targets. If more than one logical target is mapped to a physical target, each mapping appears as a seperate pair. If no logical target is mapped to a physical target, the string "<unmapped>" appears in the Logical column. Select the Sort by... Physical radio button to change list to be sorted based on physical target name.

  The list is updated when the dialog is created, and when the Reset button is pressed. Selecting a target will initialize the Physical Target pane with data about the selected Physical Target. If the selected target is mapped, the Logical Target pane will also be initialized.

• The second pane from the top is titled Physical Target. It displays information about a single physical target. When the dialog is created, the Physical Targets pane is uninitialized. Selecting a mapped or unmapped target fills in information about the physical target. Several buttons are activated when a Physical Target is selected:

  Map: The Map button will map a new logical target to the selected physical target. This operation does not remove other mappings to this same physical target. It is perfectly reasonable to have more than one logical target mapped to the same physical target.

  Reserve: In the default implementation, all targets except simulators can be reserved. Click this button to reserve the target. The default implementation is to reserve a target by checking out the CMVC-controlled file associated with that target.

  Unreserve: Click this button to relinquish a target reservation. The default implementation is to unreserve a target by checking in the CMVC-controlled file associated with that target.

  Ping: The Ping button will attempt to determine if a target is alive. By default /usr/sbin/ping is invoked. See the Customization Options section of this document for instructions on changing the default behavior of the Ping button.

  Reset: For simulators, the reset button restarts the simulator. For other targets, the meaning of the functionality must be implemented by the user. See the Customization Options section of this document for instructions.

  Change Info: The Change Info button brings up a new dialog that allows you to change information about the target.

  Discard: Click this button to remove a physical target from the database. The default implementation is to create a deleted CMVC-version of this file. This means that the file can be retrieved via standard CMVC methods if it is found that the target was discarded incorrectly.

• The third pane is titled Logical Target. It displays information about a single logical target. When the dialog is created, the Logical Targets pane is blank. Double-clicking a mapped target fills in information about the logical target. Several buttons are activated when a Logical Target is selected.

  Remap: The Remap button will remove the mapping between the selected logical and physical target, and will map the logical target to a new physical target. This is done via the Map dialog.

  Unmap: The Unmap button will remove the mapping between the selected logical and physical target.

  Change Info: The Change Info button brings up a new dialog that allows you to change information about the target.

• The last pane is titled General Buttons. Below the Logical Target pane are the general buttons. They are described below.

  New Physical Target: Press this button to create a new physical target. You will be shown the same dialog that is seen by selecting File > New > New Physical Target. When you are finished entering data about the physical target, you will be returned to the Tools > Targets menu, and the Physical Target pane will be initialized with data for your new target.

  Refresh Tornado Server List: (VxWorks Only) If you add or remove a Tornado Target Server from the Windriver Registry, you should press this button. Doing so will query the Registry for the list of currently active target servers. It will then update the List of Mapped Targets and the List of Unmapped Physical Targets by adding the target server hosts to the names of Physical Targets. For example, if you have a board named mvme1603_b, and a target server for this board is running on picard, your physical target will be displayed as mvme1603_b@picard.

The OK or Apply buttons are inactive for the Tools > Targets dialog. The Reset button will clear the Physical Target and Logical Target panes, and re-acquire the list of mapped and unmapped targets.

File > New > New Physical Target

This dialog is used to create a new physical target.

At the top of the dialog is information about the context. The context is used to determine which kernel to download, and, if possible, to determine what kind of target you wish to create. The context should be a working view. If you wish to change the context to another view, press the Change Context button. You will be prompted to enter a new context, and the dialog will be reset to the new value.

Below the context section of the dialog is a set of pages: each page corresponding to a different kind of target. Each kind of target has its own set of required input values. The pages and fields are described below.

TDM

Target Name:

Target Name is the name of the physical target file. This value is somewhat arbitrary, but should be a name that permanently identifies the target.

IP Name or Address:

Enter the IP Name or ethernet address of the target here. This will be the value of the IP_NAME_OR_ADDRESS field in the physical target file.

Serial TDM Port:

Ether the serial port (e.g., /dev/ttyja) here. This will be the value of the SERIAL_PORT_NUMBER field in the physical target file.

Simulator

Instruction Cache Size:

At the bottom of the dialog are two toggle buttons: Load Kernel is initialized to the KERNEL_VOX switch value of the current context. By default, this kernel will be loaded onto the target after it has been entered into the physical target database. The value entered will be used for the DEFAULT_KERNEL field of the physical target.

The Reserve Physical Target button will attempt to reserve the target after it has been entered into the physical target database.

---

Shell Interface

Each of the commands listed below can be invoked with the -help option to provide usage information.

Many of the commands listed below take a logical target as a parameter. When you are invoking one of these commands from within a view you may substitute a period (.) for the logical target name. The command will then use the view's LOGICAL_TARGET_NAME value as the logical target name.

apex_discard_target	apex_execute
apex_map_info	apex_map_target
apex_ping_target	apex_reserve_target
apex_reset_target	apex_set_logical_attributes
apex_set_logical_name	apex_set_physical_attributes
apex_simulator	apex_target_info
apex_unmap_target	apex_unreserve_target

---

Customization Options

Steps for Customizing Target Control

Apex allows you to customize target control operations if needed. The best way to do this is to make a copy of the existing implementation, and point Apex at the copy. Do this as follows:

1 . Make a copy of the current implementation (specified by the $APEX_TARGET_CONTROL environment variable)

cp -R $APEX_TARGET_CONTROL <new_location>

2 . Change your $APEX_TARGET_CONTROL environment variable via the Tools > Session > Environment GUI.

3 . Make your changes to files in the new $APEX_TARGET_CONTROL/bin and $APEX_TARGET_CONTROL/doc directories.

4 . Once you are satisfied with the changes, point all users to the new implementation by editing the value of APEX_TARGET_CONTROL in $APEX_EMBEDDED_HOME/bin/apex_embedded.init.

Control of Physical Target Files

By default, physical target files are CMVC controlled. users wishing to change this implementation will need to alter the following files:

set_physical_attributes.ash	This file implements the apex_set_physical_attributes command. If apex_set_physical_attributes has been invoked with a new physical target, set_physical_attributes.ash uses the apex control command to put the new file under CMVC control.
reserve.ash	This file implements the apex_reset_target command. The default implementation uses the apex check_out command.
unreserve.ash	This file implements the apex_unreserve_target command. The default implementation uses the apex check_in command.
discard.ash	This file implements the apex_discard_target command. The default implementation uses the apex discard command.
get_physical_attributes.ash	This file implements the apex_target_info command when collecting information about a physical target. If you relocate the physical target database, this file will need to change.
local_include.ash	This file contains low-level routines to support other customizable commands. Applying customizations to other files may require changes to this file.
get_physical_list.ash	This file supplies an apex shell string_array with one physical target per array entry. If you change the way physical targets (including simulators) are stored, you will need to change this file to locate and report the physical targets.
reset.ash	This file contains a function resetTarget that is called with a physical target name as its only parameter. The default behavior of this function depends on the kind of physical target passed to it. If the target is a simulator, the simulator daemon is killed and restarted. If the simulator has a DEFAULT_KERNEL value, that kernel is downloaded. If the target is anything other than a simulator, the resetBoard function is called. As supplied, this function is just a stub. It warns the user that reset is unimplemented, and returns. If you wish to implement a reset function, edit the resetBoard function.
ping.ash	This file implements the apex_ping_target command. By default /usr/sbin/ping is invoked. To change this, either edit the ping.ash apex_shell script $APEX_BASE/embedded/targets/all.rel/bin/ping.ash, or set the APEX_PING_TARGET_CMD environment variable to the desired command.