LEGAL NOTICES AND DISCLAIMERS

GREEN HILLS SOFTWARE MAKES NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO THE CONTENTS HEREOF AND SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE. Further, Green Hills Software reserves the right to revise this publication and to make changes from time to time in the content hereof without obligation of Green Hills Software to notify any person of such revision or changes.

Copyright (c) 1983-2021 by Green Hills Software. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without prior written permission from Green Hills Software.

Green Hills, the Green Hills logo, CodeBalance, GMART, GSTART, INTEGRITY, MULTI, and Slingshot are registered trademarks of Green Hills Software. AdaMULTI, Built with INTEGRITY, EventAnalyzer, G-Cover, GHnet, GHnetLite, Green Hills Probe, Integrate, ISIM, u-velOSity, PathAnalyzer, Quick Start, ResourceAnalyzer, Safety Critical Products, SuperTrace Probe, TimeMachine, TotalDeveloper, and DoubleCheck are trademarks of Green Hills Software.

All other company, product, or service names mentioned in this book may be trademarks or service marks of their respective owners.

For a listing of Green Hills Software's periodically updated patent marking information, please visit http://www.ghs.com/copyright_patent.html.

PubID: probe4_start-728395

Branch: http://toolsvc/branches/probe-branch-6.6

Date: November 18, 2022


Installing Your Probe


About This Book

This book explains how to install and configure your Green Hills Probe v4 by performing the following steps:

  • Verifying the receipt of all necessary probe hardware and accessories.

  • Adding the Green Hills Probe software to your Green Hills Compiler installation.

  • Physically connecting your probe to your debug target.

  • Physically connecting your probe to your computer’s USB port and/or network port and configuring the probe’s settings.

Once you complete these steps, the probe will be ready to debug your board. You can then create, debug, and collect trace from a simple program in MULTI. Before you begin, review the following sections to ensure familiarity with critical terms, troubleshooting procedures, and the proper installation of MULTI.

[Note] Note

All uses of the term "Green Hills Probe" refer specifically to Green Hills Probe v4. For reference information, detailed information about commands and options, and advanced topics, see the Green Hills Debug Probes User's Guide.


Requirements

Before installing and configuring your Green Hills Probe v4, you must install MULTI and the Green Hills Compiler for each architecture that you plan to use. If you have not installed MULTI yet, do so now. For information about installing MULTI, see the installation document located in the root directory of the installation DVD. The instructions in this guide cover installation with MULTI 6 and 7. If you are using another version, some instructions may differ.


Terms You Should Know

  • Host -- The computer on which you are running MULTI.

  • Target -- The hardware for which you are developing programs.

  • Target Adapter -- An adapter that connects your probe to your target. Target adapters can connect both debug and trace signals to a debug probe.

  • Trace Pod -- A target adapter with active logic that collects trace data and connects the port marked POD to your target's trace port. A trace pod also connects to the debug signals of a target, and allows the Green Hills Probe to control and debug a target.

  • TraceEverywhere (TE) -- The Green Hills interface for trace port adapters that carry trace and debugging signals. TE target adapters adapt a specific target trace port to TE, enabling the probe to trace different targets by swapping TE trace adapters. The Green Hills Probe uses TE target adapters to connect to various debugging ports, such as Nexus, ARM CoreSight, and other debug ports.

  • High-Speed Serial Trace (HSST) -- Trace using a high-speed serial protocol such as Aurora. Because of HSST's high-speed signaling, it requires a target-specific cable plugged directly into the probe with no TE target adapters. HSST often includes a target's regular debug signals allowing the probe to control and debug a target through a single cable.

  • TE Trace Kit -- A target connection kit that consists of a pre-attached cable and trace pod, and a TE target adapter.

  • HSST Kit -- A pod that connects your probe directly to your target for HSST (no adapters required).


When You Encounter Problems

If at any time you receive an error or are unable to continue, see "Troubleshooting". For more information about any of the options or procedures described in this book, see the Green Hills Debug Probes User's Guide.


Verifying Components

All Green Hills Probe v4 boxes contain the following items:


Installing Green Hills Probe v4 Software

Before using your Green Hills Probe v4 with MULTI, you must install the software on the Green Hills Probe v4 CD. The software on the CD includes:

  • USB drivers.

  • Probe firmware for the release marked on the CD. This firmware is installed in install_dir/ghprobe.

  • Host tools for administering a probe and debugging or tracing a target.

  • Project Wizard files that add support for new boards.

  • Documentation, as PDF files and in the MULTI help viewer.

To install the software, follow the instructions provided for your operating system:

Windows

  1. Log in to Windows using an account with administrative privileges. Close MULTI and any other Green Hills Software applications. Make sure that the probe is not connected to your host machine.

  2. Insert the Green Hills Probe v4 CD for your target into the CD-ROM drive of your host machine. If the installation program does not start automatically, run ginstall_win32.exe.

  3. The installer will suggest an installation directory. If this is the directory you would like to install to, click the Easy Install button; otherwise, click Advanced Install to specify an installation directory. The probe should be installed in the directory where the Green Hills Compiler is located (for example, C:\ghs\comp_201854).

Linux

  1. Close MULTI and any other Green Hills Software applications.

  2. Insert the Green Hills Probe v4 CD for your target into the CD-ROM drive of your host machine. If the installation program does not start automatically, run ginstall_linux86.

  3. The installer will suggest an installation directory. If this is the directory you would like to install to, click the Easy Install button; otherwise, click Advanced Install to specify an installation directory. The probe should be installed in the directory where the Green Hills Compiler is located (for example, /usr/ghs/comp_201854).


Connecting Your Probe to Your Target

The following diagram illustrates how your trace pod, adapters, and cables connect to the probe and to each other:

  1. Green Hills Probe v4.

  2. Plug pod connector (3) into slot labeled "POD" on front panel. The pod connector can be inserted either face-up or face-down into the probe. The Green Hills Probe v4 will automatically detect the orientation of the connector and route the signals to the right place.

  3. Pod connector.

  4. HSST trace pod for ARM HSSTP.

  5. ARM HSSTP extension cable (optional).

  6. TE trace pod for various targets.

  7. TraceEverywhere target adapter to adapt the TE trace pod to various targets. (Adapters will vary in appearance and may include a target-specific cable.)

  8. Target-specific extension cable (optional).

Refer to the section below that matches your pod for further connection instructions:

  • "Connecting with TraceEverywhere"

  • "Connecting with HSST"


Connecting with TraceEverywhere

  1. Make sure the probe's power supply is not plugged in to an AC outlet yet.

  2. Connect the TE trace pod to your TE target adapter:

    [Warning] Warning

    Take care when handling the TE trace pod. The heat fins on the sides of the pod can get very warm. Additionally, the probe may detect an error in the link to the TE trace pod due to ESD if the pod is handled by its heat fins. You may see an error message from the probe, debug control may be affected, and any trace data being collected at the time may be lost. If a target/probe debug setup must be handled during an active debugging session, we recommend the use of ESD mitigation measures to minimize the potential for disruption.

  3. Connect the probe end of the cable to the POD port on the front of the probe, and secure it by tightening the large screws on the cable housing. The pod connector can be inserted either face-up or face-down into the probe. The Green Hills Probe v4 will automatically detect the orientation of the connector and route the signals to the right place.

  4. Make sure that your target's power is off, and connect the TE trace kit to your target. If your target has a shrouded MICTOR connector, remove the shroud before connecting the pod to your target.

  5. If we included a MICTOR extension cable with your shipment, we recommend that you use it for the following reasons:

    • It reduces strain on connections.

    • It is helpful for making connections in tight areas.

    • It may improve trace reliability on some targets.

  6. Connect the power supply to the power input connector on the back of the probe and to an AC power outlet. Your probe will turn on as soon as power is connected. You should hear a beep when the probe powers on, and see a boot progress bar on the probe's LCD. After the probe finishes booting, the power indicator on the TE trace pod (indicated by a small lightning bolt icon) should turn green. If your probe fails to boot, see "Troubleshooting".


Connecting with HSST

  1. Make sure the probe's power supply is not plugged in to an AC outlet yet.

  2. Connect the Pod connector into the POD port on the front of the probe, and secure it by tightening the large screws on the cable housing. The pod connector can be inserted either face-up or face-down into the probe. The Green Hills Probe v4 will automatically detect the orientation of the connector and route the signals to the right place.

  3. Make sure that your target's power is off, and connect the HSST trace pod to your target.

  4. Connect the power supply to the power input connector on the back of the probe and then to an AC power outlet. Your probe will turn on as soon as power is connected. You should hear a beep when the probe powers on, and see a boot progress bar on the probe's LCD.


Configuring Your Probe

Your Green Hills probe is equipped with gigabit Ethernet and SuperSpeed USB ports for high-speed connections to your host computer.

  • If you want to connect to your probe over Ethernet, see "Connecting to Your Probe Over Ethernet"

  • If you want to connect to your probe over USB, see "Connecting to Your Probe Over USB"


Connecting to Your Probe Over Ethernet

Your Green Hills Probe ships with DHCP enabled by default. Connect your probe's LAN port to a network switch, and the probe should automatically obtain an IP address. To verify this, press the user buttons on the front of the probe to navigate to the Network menu. You will see information such as your probe's DHCP status, IP address, and hostname. If your probe appears to be correctly configured for DHCP, proceed to "Testing Your Probe's Ethernet Connection".

If your probe's network configuration is incorrect, you can change the configuration with a USB connection. First, connect to the probe via USB and use the probe console to get a probe prompt (see "Connecting to Your Probe Over USB"). Then proceed as follows:

  • To connect your probe to a network using DHCP, see "Configuring a Dynamic IP Address with DHCP".

  • If your network does not support DHCP or you want your probe to use a static IP address, you can configure the settings manually using the instructions in "Configuring a Static IP Address".

[Warning] Warning

The Probe is intended as a debugging device within a trusted network. An additional network authentication and security layer (such as a VPN or corporate firewall) should always be provided to restrict Probe usage to intended users. Green Hills Probes should not be placed directly on the public Internet.


Configuring a Dynamic IP Address with DHCP

At a probe prompt, type setup net. The probe presents the following settings along with default values:

[x] % setup net
Green Hills Probe (tm) Interactive Setup

    To accept the current setting press 'Enter'.
    For information on any option type a '?'.
    Use the 'set' command at a terminal to individually set options.

Network configuration (net):

    dhcp: [on]
    hostname: [ghprobe401234]

Saving options to EEPROM...
Consider running "detect" to set the target setting.

[x] %

  1. dhcp -- Press Enter to accept the default setting (on).

  2. hostname -- Type the hostname for your probe and press Enter. The DHCP server associates this hostname with your probe so that you can connect to your probe by specifying its hostname instead of its IP address. By default, the probe's hostname is ghprobeserial, where serial is your probe's serial number (for example, ghprobe401234). The probe's serial number is located on a sticker affixed to the bottom of the probe.

  3. After the setup command completes, type reboot at a probe prompt to reboot your probe so the changes will take effect.

You have now configured your probe to obtain an IP address using DHCP. Skip to "Testing Your Probe's Ethernet Connection".


Configuring a Static IP Address

If you want to configure your probe to have a static IP address, you might need to contact your network administrator to obtain the following settings:

  • IP address

  • Gateway

  • Netmask

If you set the IP address incorrectly, you could disrupt other devices on your network.

At a probe prompt, type setup net. The probe presents the following settings with their default values:

  1. dhcp -- Type off and press Enter.

  2. ip -- Type an IP address in dotted quad form and press Enter (for example, 192.168.1.150).

  3. netmask -- Type the netmask in dotted quad form and press Enter. The default setting is appropriate for class C networks (most networks are class C). Use a different setting if you are not on a class C network.

  4. gateway -- Type the gateway's IP address in dotted quad form and press Enter.

  5. hostname -- Press enter to accept the default setting. This setting is not used when DHCP is off; it is provided for future protocol support. When transporting your probe between networks with and without DHCP, your probe retains its hostname.

  6. When the probe asks if you want to reboot, press Enter to reboot the probe.

You have now configured your probe to use a static IP address.


Testing Your Probe's Ethernet Connection

After configuring your probe for your network, test the Ethernet connection with Telnet. To connect to the probe through Telnet:

  1. Plug one end of an Ethernet cable into your probe and the other end into a switch or hub that is attached to your network. If the probe detects that it is connected to a network, the Ethernet link status light turns on:

  2. Press the user buttons on the front of the probe to navigate to the Network menu. You will see information such as your probe's DHCP status, IP address, and hostname. Or if you are connected to a probe prompt, you can type set ip to confirm your probe's IP address.

  3. If you are using Windows, select Run from the Start menu, type telnet, and click OK. If you are using Linux, open a shell and type telnet.

  4. At the Telnet prompt, type open ip_address, where ip_address is your probe's IP address that you confirmed above. If Telnet can connect to the probe, you should see text approximating the following:

    Probe Firmware Release Version 6.4.4

Module core built Sun Aug 15 19:34:51 2021
Serial No: 403387
Green Hills Probe v4
Part number 520-GP500-01x
Green Hills Software, Inc
http://www.ghs.com

Type 'info' to list probe information.
Type 'setup' to set the current configuration.
Type 'help' to list the online help.

rv32imc[b] %
    [Note] Note

    If you are using DHCP and your network supports dynamic hostnames, you can also open a connection with open hostname, where hostname is your probe's hostname.

You can now connect to your probe over Ethernet. To configure your probe to debug your target, proceed to "Configuring Probe Options with a Configuration File".


Connecting to Your Probe Over USB

This section explains how to connect your probe to your host machine over USB.

  1. Connect a USB cable to the USB port on the back of your probe and to a USB port on your host machine (or a USB hub connected to your host machine). The USB link status light should turn on:

  2. If you are connecting to a Linux host and the udev rules file is correctly installed, a new device node will be created at /dev/ghprobeXXXXXX, where XXXXXX is the probe's serial number. If the rules file is not installed, copy ghprobe/driver/92-ghprobe.rules from your compiler installation to /etc/udev/rules.d and then unplug your probe's USB cable and plug it in again.

  3. If you are connecting to a Windows host and it reports that it has found a new USB device and asks to search for the appropriate drivers, click Yes. Windows will locate and use the driver you installed from the Green Hills Probe v4 CD.

    [Note] Note

    If Windows cannot find the driver and the Install New Hardware Wizard appears, run the installer on the Green Hills Probe v4 CD. For more information, see "Installing Green Hills Probe v4 Software".

  4. The Green Hills Probe v4 will enumerate as two devices on your host: a Green Hills Probe debug device and a USB serial port. The debug device is used by Green Hills host tools for operations such as sending debug commands to your target or installing firmware updates to your probe. The serial port console provides access to a probe prompt, which can be used for configuration and for target or probe diagnostics.


Connecting to the USB Serial Port Console

The USB Serial Port Console provides access to a probe prompt, which allows for changing the probe's configuration (such as network parameters) or performing probe and target diagnostic tests. To establish a serial connection:

  1. Determine the serial port that the probe has enumerated on your host.

    On Windows: Open Device Manager in the Control Panel and look for a USB serial port under Ports (COM & LPT).

    On Linux: Use the command ls -l /dev/ttyUSB* to list all available USB serial ports. Select the port with the timestamp that corresponds with your probe-to-host USB connection.

  2. On your host machine, open a connection to your USB Console with a serial terminal emulator (such as TeraTerm) using the following settings:

    • Baud Rate -- 230400

    • Data Bits -- 8

    • Parity -- none

    • Stop Bits -- 1

    • Flow Control -- none

  3. Power on (or power cycle) your probe.

  4. If you see the following banner in the serial terminal, the serial connection was successful (the banner may vary depending on your firmware revision):

    [?] % Green Hills Probe, Version 4
Unit Serial Number 404748
Loading...
Booting...

Probe Firmware Release Version 6.4.4

Module core built Sun Aug 15 19:34:51 2021
Serial No: 404748
Green Hills Probe v4
Part number 520-GP500-01x
Green Hills Software, Inc
http://www.ghs.com

Serial: 230400
USB: Enabled
Ethernet: Enabled
IP: DHCP
Gateway: DHCP
Netmask: DHCP
MAC Addr: 00:12:5c:06:28:0c

Starting the initialization sequence.
01234567 done.

Type 'info' to list probe information.
Type 'setup' to set the current configuration.
Type 'help' to list the online help.

[x] %

[Note] Note

The Green Hills Probe v4's USB Serial Port contains a FTDI FT232 USB UART chip. A built-in driver for this chip is present in supported versions of Linux as well as Windows 7 and newer. For older versions of Windows, you must download and install the Virtual COM Port driver from FTDI.


Connecting the Probe Administrator to Your Probe

[Warning] Warning

Currently, the Probe Administrator does not support USB connections on Linux, and has other known issues with USB connections on Windows. If you need to configure your probe with a USB connection, we recommend using the serial port console. Host-specific USB issues will be resolved in a future version of MULTI.

Now that the probe can connect to MULTI, you can use MULTI's Probe Administrator to configure the probe for your target. The Probe Administrator allows you to perform basic tasks such as setting options and updating firmware.

To connect to the Probe Administrator:

  1. On your host machine, run MULTI.

  2. In the MULTI Launcher, select Utilities->Probe Administrator.

  3. In the Probe Administrator, select File->New Probe to open the New Probe dialog box.

  4. In the Probe Name box, type a name for your probe that is easy to remember. This name is for your convenience only and is unrelated to the probe's hostname.

  5. If you connected to your probe over USB, select the USB radio button. If you connected to your probe over Ethernet, select the Ethernet radio button and type your probe's IP address in the IP Address box.

  6. Click OK.

  7. In the Probe Administrator, double-click your probe's name to open a Probe Administration window. You are now connected to your probe with the Probe Administrator.

  8. Click the Prompt tab to open a probe prompt. Configuration and diagnostics instructions in the next few sections will require a probe prompt.


Configuring Probe Options with a Configuration File

Green Hills provides probe configuration files for many different target boards. These files contain tested settings for all target-related configuration options. When you create a new project using MULTI 6.0 or later, a copy of this file will be added to your project under Target Resources. In most cases, this file will be automatically loaded when you connect MULTI to your target; in other cases, a board_info.txt file will contain further target-specific configuration instructions. If you have an earlier version of probe or MULTI software, you can find and load this configuration file manually. To determine if one of these files exists for your board, and to use that file to configure your probe:

  1. In a terminal window or command prompt, navigate to your MULTI install directory for MULTI 5, or your tools install directory for MULTI 6 or newer. Inside that directory, navigate to target\architecture.

  2. If there is a directory that is named after your board, navigate to that directory and look for a file that ends in .cfg or .ghpcfg. When you find the file, run one of the following commands:

    > tools_install\mpadmin -cfgload hostname config_file

    > tools_install\mpadmin -cfgload -usb config_file

    If there is no directory named after your board, or if the directory exists but it does not contain a configuration file, try detecting your target (see next section).


Detecting Your Target

The probe can automatically detect most targets. To detect your target:

  1. Power on your target.

  2. Open a probe prompt via one of the previously described connection methods: telnet, USB serial port console, or Probe Administrator prompt.

  3. At the prompt, type detect. This command configures the Green Hills Probe v4 for the processors on your target board. It is useful even if the prompt indicates that the probe knows what target you are using, because it confirms that the probe is able to see your target and that the target is configured correctly. If the command prints the following message:

    Target has been detected and set to target_string

    where target_string is the name of your target, the detection was successful.

  4. Type save to save the settings changed by detect.

If you have problems detecting your processors, see "Troubleshooting".

[Note] Note

Auto-detection cannot detect every parameter required for a reliable debugging session. If possible, use a supplied configuration file. For more information, see "Configuring Probe Options with a Configuration File".


Running Diagnostics

Now that you have detected your target, run the following diagnostics to make sure that you can communicate with it:

  1. Type selftest to run diagnostic tests on the probe's trace components. If any of the tests fail, ensure that the pod is securely attached to the probe and try again. If selftest still fails, contact Green Hills Support.

  2. Type vb to test the bypass register of all devices on the JTAG scan chain. If your target is configured for SWD mode, use the vswd command instead. (Note that vb and vswd are not supported on PowerPC 5xx, PowerPC 8xx and ColdFire targets. If you are using one of these targets, skip this step.)

  3. If your target has multiple cores, type tl (as in “target list”) to obtain a list of cores and IDs. Then, type t core_id to select a core. Most subsequent commands, including the following diagnostics, control or configure just that core.

  4. Type tr to reset your target. This command verifies that you can reset your target, and is necessary for some targets after testing bypass mode.

  5. Type rr to confirm that the probe can read your target's registers. When successful, this command returns a list of registers, similar to the following output:

    ppc5200[H] % rr
gpr0=0xac5658ad  gpr9=0x805000a0 gpr18=0x24444889 gpr27=0x04100821
gpr1=0x845008a1 gpr10=0x04400880 gpr19=0x8816102c gpr28=0x0446088c
gpr2=0x08421084 gpr11=0x04000801 gpr20=0x2c5058a0 gpr29=0x08101021
gpr3=0x24004800 gpr12=0x04020804 gpr21=0xa0404080 gpr30=0x2c425885
gpr4=0x8c001800 gpr13=0x08001001 gpr22=0x8c041808 gpr31=0xa0024005
gpr5=0x28005000 gpr14=0x2006400d gpr23=0x24144829    lr=0x00000000
gpr6=0xa0044008 gpr15=0x80120024 gpr24=0x885610ad   iar=0x00003ffc
gpr7=0x88141029 gpr16=0x00440089 gpr25=0x205240a4
gpr8=0x205640ac gpr17=0x08121024 gpr26=0x84440888
ppc5200[H] %

  6. Type vr 100 to test the probe's ability to write to registers and read back the values. This command runs the test 100 times.

If you are able to run all of the above commands without errors, your probe is able to communicate with your target and is ready for use with the MULTI Debugger. If any of the diagnostics fail, see "Troubleshooting".

[Note] Note

If you have been using the Probe Administrator with a USB connection, close the Probe Administrator window before proceeding. If you leave the window open, other applications may not be able to connect to your probe over USB.


Creating and Debugging a Program

Before beginning your first MULTI debugging session using your Green Hills Probe v4, you must ensure that your target board is configured properly. This section explains how to create a Top Project that you can use to configure your target, test your debugging environment, and download and debug a “Hello World” program.


Creating a Top Project for Your Program

The Project Wizard is a tool that prompts you for information about your target board and creates a Top Project that contains:

  • Connection Methods that you use to connect to your target through your Green Hills Probe v4.

  • A MULTI board setup (.mbs) script that configures your target.

  • Linker directives files that define memory maps for your target.

To use the Project Wizard to create a Top Project:

  1. On your host machine, open MULTI.

  2. From the MULTI Launcher, click [image] and select Create Project to open the Project Wizard.

  3. Leave the default value in the Name box, and enter a directory for your Top Project in the Directory box. Click the Next button.

  4. In the Operating System list, select Stand-Alone. Click the Next button.

  5. In the Processor Family list, select the processor family to which your target's processor belongs. If you have only installed one processor family for MULTI, the wizard does not display this screen. Click the Next button.

  6. In the Target Board list, select your target board. If your target board is not listed or you are using custom hardware, click the plus sign to the left of the Generic item at the top of the list and select your processor. In this case, you will probably need to customize the board setup script and linker directives files the wizard creates for your target. Click the Finish button to create your Top Project.

  7. When the Project Wizard closes, a dialog box may open to inform you about the newly created Top Project. If so, click the OK button to continue.

  8. After you create a new Top Project, the Add Item to Project dialog box opens. If you are creating a Stand-Alone project, select Hello World (C) and click the Finish button. This adds an example “Hello World” program to your Top Project.

You have now created a Top Project for your target.

For more information about Project Wizard screens and options, see the documentation about creating a new project.


Top Project Structure

After you create a Top Project, the MULTI Project Manager opens. It should look similar to the following window:

There are three projects in the window:

  • dir\default.gpj -- The Top Project.

  • src_hello\hello.gpj -- The example “Hello World” program you added with the Add Item to Project dialog box.

  • tgt\resources.gpj -- The Target Resources project. This project contains files necessary to configure and connect to your target (such as setup scripts and linker directives files).

    • mpserv_standard.mbs -- The board setup script for your target. This script prepares your target for downloading and running a program. You may need to customize this script if you are using custom hardware.

    • name.ld -- Linker directives files for your target. These files help determine how your program is laid out in memory. You may need to customize these files if you are using custom hardware.

      In this example, the src_hello\hello.gpj program is linked using standalone_ram.ld. The tgt\standalone_ram.ld item in the src_hello\hello.gpj program represents the same file as the standalone_ram.ld item in the Target Resources project.

    • board_config.ghpcfg (not available for all targets) -- Probe configuration file containing recommended settings for debugging your target. If present, this file will be automatically queued to be written to your probe on connection. Note that some boards may have multiple configuration files available for different uses (such as trace and non-trace).

    • board_info.txt (not available for all targets) -- Additional notes about your target. If your project contains this file, read its contents before proceeding to the next section.


Building a Program from the Top Project

After you create a Top Project with the Project Wizard, you should test your debugging environment by downloading and running the example “Hello World” program. Before downloading the program, you must build your project.

To build the “Hello World” example project:

  1. Select src_hello\hello.gpj in the Project Manager.

  2. Click [image].

If the build was successful, you should see text similar to the following in the Status pane:

Building hello
Compiling hello.c because hello.o does not exist
Linking hello because it does not exist
Done
Build successful (Mon Jul 23 12:30:00 2018)


Connecting MULTI to Your Target

To connect MULTI to your target:

  1. Verify that all hardware connections are tight and secure, and that both the board and your probe are powered.

  2. In the Project Manager, select src_hello\hello.gpj and click [image] to open the MULTI Debugger.

  3. If you have a Probe Administrator window open and connected to your probe via USB, close that window now. You can only have one USB connection to the probe at a time. Leaving this window open will prevent you from connecting MULTI to your probe in the next few steps.

  4. In the Debugger window, click [image] to open a Connection Chooser window.

  5. In the Connect to a Target list, select the Green Hills Debug Probe (mpserv) connection for your target. For example:

  6. Click the Connect button. When the Connection Chooser prompts you to enter a Probe Name for the new connection, click OK. The Connection Editor window opens.

  7. In the Connection Editor window:

    1. In the Connection tab, select the radio button that corresponds to your connection type (Ethernet or USB). If you connect to your probe over Ethernet, type the probe's hostname or IP address in the Probe Name or IP Address box. If you connect to multiple probes over USB, type the probe's serial number in the Probe Serial Number box to specify which probe you want to connect to, and make sure that there are no active connections to that probe (such as the Probe Administrator).

    2. In the Target Setup script box, leave the default value (mpserv_standard.mbs). This file is the setup script that the Project Wizard generated and placed in your Target Resources project.

    3. In the Probe Config tab, you will see the board_config.ghpcfg file that matches your target (if an appropriate file is available). You can either select a different configuration file, or remove the reference to the file entirely to preserve the probe's current settings.

    4. Click OK.

The MULTI Debugger is now connected to your target.

For more information about the Connection Editor, see the documentation about the Connection Editor.

[Warning] Warning

Do not unplug the USB cable while MULTI is connected to your target over USB.


Downloading and Debugging a Program

To download and run the “Hello World” program:

  1. In the MULTI Debugger, click [image]. The Prepare Target dialog box opens.

  2. In the Prepare Target dialog box, leave the settings at their default values. The project is configured to download the program to RAM. Click OK.

  3. The Initializing Target dialog box opens. This dialog box shows progress as MULTI runs your setup script and downloads the program. It closes when the progress is complete.

If the download and execution of the program are successful, your debugger should show output similar to the following:

I/O: Hello world.
I/O: -----------------------------

If the download was not successful, the Prepare Target dialog opens and displays any errors that occurred during the setup script or while downloading the program. If you are using custom hardware and have not modified the default setup script and/or linker directives files, you should expect some errors in red text in the Prepare Target dialog box.

If this happens, you must modify the default setup script and linker directives files in your Target Resources project to configure your target properly. For more information, see Configuring Target Resources.


Viewing the 'Hello World' Program's Trace Data

This section only applies if you are debugging a target with supported trace data collection. By default, the Green Hills Probe v4 collects trace data every time it halts your target. This means that you can view trace data immediately after the 'Hello World' program terminates. To view the trace data in list form:

  • In the Debugger, select TimeMachine->Trace List

If the Trace List opens and looks similar to the following screen, your trace connection is configured properly:

For more information about browsing trace data, see the documentation about analyzing trace data with the TimeMachine tool suite.


Troubleshooting

This section explains how to troubleshoot problems you may encounter when configuring your probe to detect and communicate with your target. Before looking at a specific topic, make sure that:

  • Your target is powered on.

  • Your probe is powered on.

  • All connections are tight and secure.

  • The supplied ribbon cable is plugged into your target in the proper orientation, in the correct port. Also, check that it is properly aligned (not shifted over by one pin).

As with all problems you may encounter with your probe, consider using the help command to investigate related topics, the set command to view or change option settings, and the support command to output a log that will be helpful to Green Hills Support. For information about these commands, see Chapter 4, “Probe Option Reference”.

If you have checked all the items in the previous list and are still having trouble setting up your Green Hills Probe v4, consult one of the following sections.


Setting Up Your Hardware

This section provides troubleshooting steps for initial probe setup.


The Supplied Ribbon Cable or Pod Does Not Fit in the Target's Debug Header

If the supplied ribbon cable or pod does not fit in one of your target's debug ports:

  • Do not attempt to physically modify the cable or pod.

  • Some targets have more than one debug header. Look for a different debug header that fits.

  • If your Green Hills Probe v4 shipped with adapters for the ribbon cable or pod, try using one of them.


The Green Hills Probe v4 Power Light Is Solid Red

If the power light on your Green Hills Probe v4 is solid red, the probe is off due to a fault. Refer to the probe's LCD display for more information about the fault. If the probe's LCD is off, contact Green Hills Support.

When experiencing a fault, the probe will typically beep in a repeating pattern. If the beep pattern is a high beep followed by a low beep, the probe is overheating. For an overheating probe:

  1. Turn the probe off immediately.

  2. Check to see if any of the probe's vents are obstructed. The vents are located at the front right top (intake) and rear left (exhaust). Remove any found obstructions before turning the probe on again.

  3. Check that the ambient temperature near the probe is below 120 F (50 C).

If none of the vents are obstructed and the ambient temperature is within operating levels, call Green Hills Support.


Corrupted Data is Printed to the Serial Terminal

If your serial terminal emulator is displaying corrupted data when connected to the probe, your terminal's baud rate is probably incorrect. The only supported baud rate on Green Hills Probe v4 is 230400.


Configuring Your Probe to Connect to MULTI

This section provides troubleshooting steps for configuring your probe to connect to your host machine.


Cannot Find Telnet On Windows Vista and Later

The Telnet application is not installed by default on Windows Vista and later systems. To install the Telnet application:

  1. Click the Start button and click Control Panel.

    • If your control panel has the normal view:

      1. Click Programs.

      2. In the Programs and Features group, click Turn Windows Features On or Off.

    • If your control panel has the classic view:

      1. Click Programs and Features.

      2. Click Turn Windows Features On or Off.

  2. Select the Telnet Client check box and click OK.


Cannot Connect to Probe Over Telnet

If you cannot connect to your Green Hills Probe v4 over Telnet, your Ethernet settings are probably incorrect. The easiest way to determine if your probe Ethernet settings are correct is to ping it from your host machine. To ping your probe, from a command prompt, type:

$ ping hostname

where hostname is your probe's hostname, or

$ ping ip_address

where ip_address is your probe's IP address.

If ping is successful, it prints a report similar to the following:

$ ping ghprobe11111

    Pinging ghprobe11111.ghs.com [192.168.100.111] with 32 bytes of data:

    Reply from 192.168.100.111: bytes=32 time<10ms TTL=29
    Reply from 192.168.100.111: bytes=32 time=10ms TTL=29
    Reply from 192.168.100.111: bytes=32 time<10ms TTL=29
    Reply from 192.168.100.111: bytes=32 time<10ms TTL=29

    Ping statistics for 192.168.100.111:
        Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
    Approximate round trip times in milli-seconds:
       Minimum = 0ms, Maximum =  10ms, Average =  2ms

If ping is unsuccessful, it prints a report similar to the following:

$ ping ghprobe11111

    Pinging ghprobe11111.ghs.com [192.168.100.111] with 32 bytes of data:

    Request timed out.
    Request timed out.
    Request timed out.
    Request timed out.

    Ping statistics for 192.168.100.111:
        Packets: Sent = 4, Received = 0, Lost = 4 (100% loss),
    Approximate round trip times in milli-seconds:
        Minimum = 0ms, Maximum =  0ms, Average =  0ms

  • If ping is unsuccessful, verify that an Ethernet cable is plugged in and that the connection light in the upper-right corner of the probe's Ethernet port is illuminated.

    • If it is illuminated, watch the light in the upper-left corner of the Ethernet port. If the light on the left is not flashing periodically, you may need to reconfigure your IP address, netmask, and/or gateway (see "Connecting to Your Probe Over Ethernet" for instructions).

    • If it is not illuminated, try a different cable or connect to a different port on your hub or switch.

  • If ping is successful but you cannot connect to the probe over Telnet, unplug the Ethernet cable from the probe and ping it again, with the cable unattached.

    • If ping is still successful, another device on your network probably has the same hostname or IP address as your probe. Obtain a unique address and hostname from your network administrator and reconfigure the probe (see "Connecting to Your Probe Over Ethernet" for instructions).

    • If ping is no longer successful, or if you have a unique IP address and still have problems, open a Telnet connection from a different host machine. If the problem still persists, contact Green Hills technical support.


Cannot Connect to Probe Over USB

Only one software program can connect to a probe over USB at a time. If you have connected to the probe over USB before, but now are unable to, check that there are no other active USB connections to the probe, such as mpadmin, mpserv, or the Probe Administrator. If there are, close them.

[Note] Note

The Green Hills Probe v4 will enumerate as two USB devices: a debug device and a serial port. You may have one software program connected to each enumerated device at the same time. For example, mpserv can connect to the debug device, while TeraTerm connects to the serial port.

The USB link LED should illuminate when the host machine and the probe have both been booted. If this does not happen:

  1. Check that you have properly installed the USB cable between your host machine and the probe.

  2. If the previous steps do not solve the problem, unplug the USB cable from the probe and plug it back in again.

  3. If the problem persists, contact Green Hills technical support.


Windows is Unable to Start Probe as a USB Device

On some hosts, Windows may report that it is unable to start your device (with error 10) the first time you plug in a probe to the USB port. If this happens, unplug the USB cable and plug it back in. Windows should now be able to start it as a USB device.


Configuring Your Probe for Your Target

This section provides troubleshooting steps for configuring your probe to connect to your target, detect its processors, and read registers. To follow the instructions in this section, your probe must be connected to your target, and your host must be connected to the probe over the serial port. For instructions that explain how to connect to your probe, see "Connecting to the USB Serial Port Console".

If the troubleshooting steps in this section do not address your problem, your target may require extra configuration. For more information, see Usage Notes.


detect Does Not Display a Processor Table

If the detect command does not display a processor table, but returns output similar to the following:

ERROR 1 (general error): Unable to detect target. (jtag_ir_length=0; TDO
held low?) Please use the "set target" command to configure manually.
ERROR 1 (general error): Timeout while trying to determine number
of cores.

The logic high level of the probe may be set incorrectly for your target. See "Configuring the Probe's Logic High Level".

For non-BDM targets, detect requires that the debug_type configuration option matches your target. Please verify that debug_type is set correctly if you have a JTAG, cJTAG, or SWD target.

If the detect command continues to fail, there may be a low-level debug connection problem. See "Diagnosing Low-Level Debug Connection Problems".


detect Sets the Target Settings and then Issues an Error

If the detect command is able to set your target setting but then returns an error, it is likely that the probe cannot reset the target. For more information, see "tr Does Not Reset the Target".


detect Sets the Target Setting to other

If the detect command sets your target setting to other, enter the following command at a probe prompt:

set target ?

Look for your processor in the resulting list. If your processor is listed:

  1. Configure the probe's target setting manually with the following command:

    set target target_string

    where target_string is the string listed for your processor.

  2. Configure the probe's endianness setting:

    set endianness mode

    where mode is either big or little.

If your processor is not listed, it may not be supported. Contact your Green Hills sales representative for more information.


detect Lists Devices Connected to the Probe, but Sets the Target Setting to other

If the detect command lists devices connected to the Probe, but sets the target setting to other, it may be accompanied by one of the following messages:

* - Indicates a core that requires a Probe feature key to debug.

If you receive this message, it indicates that you are connected to a target that is not supported by the default Probe configuration. Access to the debug features of this core may be enabled with a feature key (generally available through an early access agreement or a specific license agreement). If you have received a feature key, install the key, reboot your Probe, and try again. If you are entitled to a key but do not have one, contact Green Hills Support.

+ - Indicates a core whose detected jtag idcode is known to be shared
by many cores, and detect failed to distinguish among them.

If you receive this message, it indicates that you are connected to a target that shares an idcode with several other devices, and the Probe could not determine which one you have. In this case, there are two possibilities:

  • Your target is supported, but you need to specify it manually using the set target command.

  • Your target is not supported, in which case you can contact your sales team to learn when the device will be supported.


detect Sets the Target Setting Incorrectly

Because multiple processors within the same family sometimes have the same PVR or idcode, detect might not set the target to the correct processor. If this happens, set your target setting manually using the instructions in "detect Sets the Target Setting to other".


detect Passes but vb or vswd Fails

PowerPC 5xx, PowerPC 8xx, and ColdFire targets do not support vb or vswd. Do not use these commands if you have one of these targets. If your target supports one or both commands, you may see an error message that approximates the following:

ERROR 13 (test failed): Test failed: in=input, out=output,
i=iter

If you receive the above error (or a general error when running vswd):

  1. The debug clock may be set too fast. The probe detect command uses a clock setting of 10kHz, while the default clock setting is 10MHz. Set the clock to 1MHz by typing the following command at a probe prompt:

    set clock 1MHz

    If vb or vswd work after increasing the clock speed, you can try increasing it slowly to find higher speeds that still work reliably. If 1MHz does not work, try clock settings that are between 10kHz and 1MHz.

  2. You may need to set the probe's logic high level. See "Configuring the Probe's Logic High Level".

  3. If vb or vswd continue to fail after you have configured the probe's clock speed and high logic level, your target setting may have been set incorrectly. For information about solving this problem, see "detect Sets the Target Setting Incorrectly".


detect is Successful but Target Cannot Be Debugged

The detect command may perform operations that change the state of a connected target. In some cases, a target may require a post-detect power cycle in order to be debugged.


tr Does Not Reset the Target

If your target does not reset when you enter the tr command, the debug clock speed might not be set correctly. To adjust the clock speed:

  1. At a probe prompt, type set clock 1MHz to set the clock speed to 1MHz.

  2. Type tr to reset your target.

If tr still does not reset your target:

  • The nHRESET and nTRST lines may be tied together. For more information, see Diagnosing JTAG TAP and CPU Reset Line Problems.


vr Fails or Issues Error 18

If vb or vswd passes, but vr fails or returns an error such as:

ERROR 18: the target is not stopped

the debug clock speed may be set too high. To fix this problem:

  1. At a probe prompt, type the following command to lower the clock speed:

    set clock 1MHz

  2. Type vb (or vswd, if applicable) to confirm that you can communicate with the target. If you are using a BDM target, type tr instead of vb.

  3. Type vr 100 to perform the register test again.


MULTI Reports a "Traceserv Failed to Respond" Error

If MULTI opens a dialog box with the message traceserv failed to respond, and your probe booted less than a minute ago, wait one minute and click the Continue button. When the probe boots, it performs a self test that can take up to one minute. This test must complete before the probe can begin collecting trace data.


The Trace List Is Empty, Near Empty, or Reports an Error

If the Trace List is empty, near empty, or reports No Full Address Broadcast Found, the Green Hills Probe v4 is probably unable to collect trace data from your target. In this case:

  • If you have a TraceEverywhere adapter, make sure it is securely connected to the trace pod. Also make sure that the trace pod is securely connected to the Green Hills Probe v4 body.

  • Make sure the trace outputs are enabled on your board (see "Enabling Your Target's Trace Port").

  • Make sure the Green Hills Probe v4's adapter setting is auto.


General Configuration Instructions

While the previous sections explained how to fix specific problems that you may encounter while configuring your probe, this section explains how to troubleshoot probe problems that are more general in nature.


Diagnosing Low-Level Debug Connection Problems

Use the vta command to troubleshoot low-level debug connection problems. vta verifies that the probe can individually control each pin on the target by individually setting each pin HIGH and LOW, checking for shorts, opens, and stuck-at conditions. For example, vta can detect if the TCK pin is shorted to GND, or if the TMS pin is not making contact with the probe.

To run this test:

  1. If you are using TraceEverywhere (TE), unplug the target adapter from your target.

  2. At a probe prompt, type vta.

The results of a successful test look similar to the following output (only a few lines are shown here):

>vta
Testing arm-20 adapter pins:
                      VTREF passed. [100%]
                    VSUPPLY passed. [100%]
                      NTRST passed. [100%]
                        GND passed. [100%]
                        TDI passed. [100%]
                        GND passed. [100%]
                        TMS passed. [100%]

If a pin has a connection problem, the probe issues an error. For example, if the probe could not bring TDO low, it would print:

TDO was not initially low.

If this test fails and the adapter type is correct, there may be a problem with the adapter on the probe. In this situation:

  • Verify that the adapter is plugged in securely, and the screws are snug.

  • Remove the adapter, inspect it for damage or contaminants, re-install it, and repeat the test.

If the test still fails, the probe or target adapter may be damaged. In this situation:

  • Try a different target adapter

  • Contact Green Hills technical support.

[Note] Note

Some debug pins controlled by the probe (for example, reset lines) are connected to open-drain connections with more than one driver, meaning that the probe cannot drive them HIGH. When you run vta with your target unplugged, it issues the following message for each of these pins, because there is no pull-up resistor on the target adapter to bring the signal HIGH:

PIN could not be brought high.

If PIN is connected to an open-drain connection, this does not necessarily mean that there is a problem with the adapter, but it indicates that there should be a pull-up resistor on the target board for this pin.


Configuring the Probe's Logic High Level

To configure the logic high level for your probe:

  • Type dlh at a probe prompt to detect the correct logic high level for your target.

To set the logic high level manually:

  1. Consult your target's reference manual to confirm its logic high level.

  2. Type the following command at a probe prompt:

    set logic_high level

    where level is the logic high level for your target. To confirm that the probe has updated this setting, type:

    set logic_high

The range of supported logic_high values varies depending on the adapter. Type set logic_high ? to determine the supported values for your currently connected adapter.


Enabling Your Target's Trace Port

In order to collect trace data, you must enable the trace port on your target. If you selected your target in the Project Wizard, it may have provided you with one of the following ways to enable trace:

  • The generated setup script may enable trace ports by default. In this case, you do not need to do anything.

  • The generated setup script may require you to set a variable in the script to enable trace. To check if this is the case, in the Project Manager, open the Target Resources project and double-click mpserv_standard.mbs to edit it.

  • There may be two setup scripts, one that enables trace and one that does not. In this case, you must specify the setup script that enables trace (see the documentation about specifying setup scripts).

  • If you are using High-Speed Serial Trace, you may need to perform additional steps. For more information, see “Additional Considerations for High-Speed Serial Trace”.

If you are using custom hardware, refer to your hardware's manual for information about enabling the trace port, and add the necessary commands to your setup script.


Recovering a Probe That Does Not Boot Properly

If your Green Hills Probe v4 fails to boot, it will report a FAULT code, or it will boot into recovery mode. Recovery mode is a bare probe shell that allows for basic probe diagnostics and firmware reflashing, but does not support debugging or target Ethernet. If you encounter a FAULT code, contact Green Hills Support.

If you want to force your probe into recovery mode, choose Boot to Recovery from the System menu on the probe's LCD. Once in recovery mode, you can update the probe's firmware using the Probe Administrator or mpadmin as described in “Updating Probe Firmware”.


Uninstalling Probe Software

To uninstall probe software on Linux, follow the instructions for using gpatch located at install_dir/restore/readme.txt.

To uninstall probe software on Windows, use the Add/Remove Programs feature in your version of Windows.


Getting Started with the Green Hills Probe v4

Green Hills Software

LEGAL NOTICES AND DISCLAIMERS