Target Configuration

Overview

The emulator communicates with the target through the JTAG chain.  In order to do this, it needs to know what devices are on the JTAG chain. The collective process of discovering these target devices and configuring them for communication is referred to as "target configuration”.

Rather than hard-coding the target configuration process in SourcePoint or the emulator,  a target configuration macro file is used.  This gives the user maximum flexibility to control the target configuration process.  For example, special JTAG commands might be required to unlock a JTAG chain before the emulator can communicate with it.  These commands can be inserted in the target configuration macro.

Simple Targets

Simple targets can use the default target configuration files provided with SourcePoint.  

Use the New Project Wizard (File | Project | New Project) to create a new project file.  Under "Settings basis” select "Use default settings”. This creates a project file with the target configuration event macro set to run a debug procedure called Configure.  The default version of Configure is in config-utils.mac (in the macros directory).  For simple targets it will work unmodified.  

Complex Targets

Examples of complex targets include targets that need special commands to unlock debug capabilities, and targets that don’t scan properly.  On these targets, the default Configure procedure will need to be modified.  

Targets that need to be unlocked.  The changes required are target-dependent, but usually consist of a series of msgscan commands to send special JTAG commands to the target.

Targets that don’t scan properly.  In this case, one or more of the scan commands (jtagscan, apscan, and/or devicescan) is omitted.  The corresponding SourcePoint configure command is used to send the configuration to the emulator.  The configuration typically comes from a special target configuration file created for the particular target, but it can also be manually generated (see below).

Configuration Command Overview

The following is a list of the commands and control variables used in the target configuration process.  For more details refer to the separate command topics for each.

Configuration Commands

jtagtest	Test the JTAG chain.
jtagscan	Causes the emulator to scan the JTAG chain for devices.
jtagconfigure	Sends the SourcePoint JTAG configuration to the emulator.
jtagchain	Display or define a JTAG configuration.
verifyjtagconfiguration	Verifies that the SourcePoint and emulator configurations match.
devicescan	Causes the emulator to scan for devices.
deviceconfigure	Sends the SourcePoint device configuration to the emulator.
verifydeviceconfiguration	Verifies that the SourcePoint and emulator configurations match.
devicelist	Displays a list of all configured devices.
autoconfigure	Performs the same function as the default Configure procedure.
disconnect	Disconnect emulator from target (discard current configuration).
reconnect	Reconnect using the target configuration event macro.
uncorescan	Causes the emulator to scan the JTAG chain(s) for uncore devices.
uncoreconfigure	Sends the SourcePoint uncore configuration to the emulator.

Database Commands

jtagdevices	Display the JTAG device database.
jtagdeviceadd	Add a device to the JTAG database.
jtagdeviceclear	Remove a device from the JTAG database.

Control Variables

num_jtag_chains	The number of JTAG chains.
num_jtag_devices	The number of JTAG devices.
num_all_devices	The number of all devices.
num_processors	The number of processors.
emulatorstate	The emulator connection state (0, 1 or 2; see below).
num_uncore_devices	The number of uncores.

Advanced Topics

The JTAG Device Database

SourcePoint maintains a database of known JTAG devices in targets\jtag-devices.xml.

The Configuration view is used to display and edit the database.  It is accessible by pressing the Configuration button in Options | Target Configuration | Target Devices, and then selecting JTAG Info.

The command language also supports viewing and modifying the database.  The jtagdevices command displays the database.  The jtagdeviceadd and jtagdeviceclear commands add and remove devices.

If you install a new version of SourcePoint, it may include a newer version of the database file.  In this case SourcePoint merges the old and new files, so any user changes to the database are not lost.

Manually Defining the JTAG chain

If the JTAG chain cannot be scanned, and the target you are trying to connect to does not have a target configuration file, then it is possible to manually define the JTAG chain configuration.  This can be accomplished in the JTAG Configuration tab in the Configuration view.  All devices must already exist in the JTAG device database (the JTAG info tab).

The command language also supports defining the JTAG chain configuration.  The jtagchain command displays or sets the devices on the JTAG chain.  The jtagchainclear command clears the devices on the JTAG chain.

What the Configure Procedure Does

The Configure debug procedure (in macros\config-utils.mac) is the default target configuration method. It will work for most targets. Configuration consists of 2 or 3 phases.

The first phase uses the jtagscan and jtagconfigure commands to scan and configure the JTAG chain.  The jtagscan command automatically performs a jtagtest command prior to the scan.  After JTAG configuration is complete the emulatorstate control variable transitions from state 0 (disconnected) to state 1 (JTAG configured).

On targets with uncore devices, the next phase uses the uncorescan and uncoreconfigure commands to scan and configure all the uncore devices on the JTAG chains.

The last phase uses the devicescan and deviceconfigure commands to scan and configure devices.  After successful device configuration, the emulatorstate control variable transitions from state 1 (JTAG configured) to state 2 (fully configured).  The target is now ready for run control.

Manually Executing Configuration Commands and Creating a Target Configuration File

Connecting to a new kind of target for the first time can be a tricky process. The target may have hardware issues, software issues, security issues, or a whole host of other problems that cannot be anticipated.

By using a special target configuration file (manual.tc), and the command line commands listed in previous sections, it is possible for a user to manually discover the target, step by step.

This has the huge benefit of allowing the user to pinpoint exactly where in the connection process that the target is providing difficulties to the standard connection process.

The following describes the general process for manually discovering and configuring a new target for the first time. If there are external requirements by the target (security unlock, physical JTAG chain configuration, etc ) at various stages during the process, it is the user’s job to know what these requirements are, how to carry them out, and when to cause those processes to occur. It is not possible for SourcePoint to know the implementation-specific requirements of any given target, unless Arium has been previously informed of said requirements.

The emulator should be powered up and connected to the target, which should also be powered up. The user should then create a new project file with the "manual.tc" file that is included in the SourcePoint distribution. Tell SourcePoint the address of the emulator (TCP/IP or USB).

SourcePoint will connect to the emulator, and stop. No further automated configuration actions will take place on the part of SourcePoint. From this point on, all steps will be carried out manually by the user in the Command window.  At this point, the emulator is in the disconnected from the target state (emulatorstate control variable = 0).

The user now has the option of using the jtagtest or the jtagscan command. The jtagtest command may be used to manually run any one of the six JTAG tests individually. These tests are:

1) Test for power currently on.

2) Test for reset currently asserted.

3) Determine the IR length of the JTAG chain.

4) Scan the JTAG ID’s on the JTAG chain.

5) Check the integrity of the JTAG chain.

6) Check whether the target supports Adaptive TCK.

If these tests are run one at a time via the jtagtest command, the user can determine, with very fine granularity, what an exact problem may be with the JTAG chain.  Note:  Enable logging with aalog=20987 to view the test results in the Log window.

The jtagscan command runs tests 1 - 5 above automatically, in a predefined order, simulating the automated test that was run in older versions of firmware. This may be done on targets whose JTAG chain the user has confidence in.

Once the jtagscan command has been run successfully, SourcePoint will have sufficient information (i.e. the list of JTAG ID’s) to proceed to the next step. This is to run the jtagconfigure command at the command line.

Once this command has been issued, the firmware in the emulator will be in the JTAG Configured state (emulatorstate control variable = 1), and will be ready to proceed to the next step.

In the case of a target with an uncore, the user should now use the uncorescan command.  This causes the firmware to discover uncores on the JTAG chain.  After this has been successfully completed, the uncoreconfigure command should be issued.  This prepares the firmware for the final stage of configuration.

The user should issue the devicescan command. This causes the emulator to discover what "devices" are in the system ( i.e. processors, ETM’s, etc ). That information is reported to SourcePoint.

After this information has been discovered, the user should issue the deviceconfigure command. When this is done, the STS light on the front of the emulator should turn on. The emulator is now fully configured (emulatorstate control variable = 2)

The last stage is to allow SourcePoint to configure itself by issuing the connect command. After a short delay, SourcePoint should become connected to the emulator and display its debug windows.

SourcePoint and emulator are now fully configured and should be able to debug the target.

The project file should be saved, and a configuration macro should be created (or an existing file should be modified ) to allow SourcePoint to carry out automated connection from now on. This configuration file should include any target specific actions that are required to activate or connect to the target, in the correct locations in the macro file.