|
|
Macraigor Eclipse Installation...
Installing and using Macraigor JTAG/BDM Devices with
Eclipse™ 3.3 (Europa)/CDT 4.0 and the Macraigor
GNU Tools Suite on Windows Hosts (printer friendly version here)
Contents:
Introduction
Required Components
Using Demo Projects
OCD Remote Options
Modifying the Demos
Cloning/Renaming an Existing Macraigor Demo Project
Useful
GDB andMonitor Commands
Troubleshooting
The Macraigor GNU Tools Suite (MGTS) is an
implementation and packaging of several of the open-source GNU tools
and utilities along with a program called OCDRemote that provides an
interface between the GDB debugger and a Macraigor On-Chip debug
device. The GNU packages that are included with the MGTS are: binutils
(version 2.17), gcc (version 4.1.1), and gdb (version 6.6). Macraigor
provides two versions of the gdb debugger: *-elf-gdbtui which has a
simple text windowed user interface, and *-elf-gdb with the standard
gdb command line interface. Our pre-built Eclipse™ project
examples show how to integrate *-elf-gdb into the free, open-source
Eclispe IDE. Taken together, these tools and the Eclipse framework
provide a complete environment for cross development targeted at
several families of embedded processors. Macraigor distributes versions
of the MGTS for the following processors:
• ARM
• ColdFire
• MIPS (32 and 64 bit)
• PowerPC
• XScale
This document gives instructions for
installing and configuring the MGTS and Eclipse so that a Macraigor
JTAG/BDM device can be used as the debug connection to the target
processor. Under Windows, the following Macraigor devices are supported
with this environment:
• Wiggler
• Raven
• usb2Demon
• usb2Sprite
• usbWiggler
• mpDemon
In addition to the tools and development
environment, Macraigor also supplies pre-built Eclipse projects for
many industry-standard evaluation boards. These projects provide a
simple way to get the cross-development environment up and running on
actual hardware. The user can then modify and expand these demos to
work with other target hardware and more complex application
development.
There are several components that must be present or
downloaded and installed on your host PC in order to get the Macraigor
GNU Tools Suite working with Eclipse. All of the following components
(except the Java Runtime) are available from the here
on this web site and should be obtained from there. The versions of
these components that Macraigor posts on our web site have been tested
and are known to work together. Although these components can be
obtained directly from other places on the web, there are known to be
incompatibilities with some of the newer versions of things like the
Zylin CDT plug-in. If you want to try using a newer or alternate
version of any of these components, Macraigor will be unable to assist
you if something doesn’t work properly.
The required components are as follows:
1. Cygwin environment
2. GNU C/C++ compiler, GDB and utilities for your target processor
3. Macraigor OCDRemote
4. SUN Java Runtime
5. Eclipse 3.3 (Europa) IDE
6. Eclipse CDT 4.0 Plug-in for C/C++ Development (Zylin custom version)
Installation of each component is explained in detail in
the following sections.
2-1 Cygwin environment
Cygwin is a free package that provides a Linux-like
environment under Windows. This environment is required in order to run
the gnu compiler, debugger and the Macraigor OCDRemote interface. Go to
www.cygwin.com and select the "Install or update now! (using
setup.exe)" link, download/run setup.exe and make the following choices
in the "Cygwin Setup" dialogs:
1. Choose Installation Type: Select “Install From
Internet”
2. Choose Installation Directory: Specify: Root Directory :
"c:\cygwin", Install For : All Users, Default Text File Type :
unix/binary
3. Select Local Package Directory: Specify : "c:\"
4. Select Connection Type: Specify your Internet connection type
5. Choose download sites: Select a site to download from
6. Select Packages:
a) Expand the "Devel" category by clicking on the
"+" sign, then scroll to: "make: The gnu version of
the make utility," click the arrows icon  to replace
"skip: with a version number.
b) Expand the "Libs" category by clicking one the
"+" sign, scroll to "expat: XML parser library
written in C," click the arrows icon to replace "skip" with the version number.
Clicking the NEXT button in the "Select Packages" dialog
box will start the Cygwin Installation.
2-2 GNU C/C++ compiler, GDB and utilities for your
target processor
Macraigor provides pre-built, installable builds of the
gnu tools suite (gcc, binutils, and gdb) for cross-development with
several families of target processor, including ARM (which also works
for Intel XScale), i386 (for AMD embedded target processors), MIPS, and
PowerPC. The tools for each architecture are packaged separately.
Choose the appropriate link here:
ARM7T/ARM9T/ARM11/Xscale/iMX31/NetSilicon
GNU Toolkit v2.05
PowerPC
GNU Toolkit v2.05
MIPS32-4Kc/4Ke/PIC32/Alchemy/MIPS64-5kc/TX49
GNU Toolkit v2.05
i386
GNU Toolkit v2.05
and download and install the appropriate package for your target
processor. Note that all of these packages can coexist, so feel free to
install all the versions of the tools that you might need for various
projects.
2-3 Macraigor OCDRemote
In order to connect the gdb debugger to a target
processor using a Macraigor JTAG or BDM interface device, a utility
called OCDRemote is required. This utility starts up and listens on a
TCP/IP port for a connection from gdb and then translates gdb commands
into JTAG/BDM actions for the target processor using the Macraigor
hardware interface device. Go to
Macraigor
Hardware Support Pkg 2.24 and download and install the OCDRemote
Hardware Support Package. This installation package also includes
several Macraigor utilities that can be helpful in debugging and
correcting connection issues when using Eclipse and the gnu tools.
These utilities are:
• OCDCommander – a
low-level, assembly-only debugger that can be used to check proper
connection of a Macraigor JTAG/BDM interface to the target processor.
• usbDemon Finder – a utility to detect and license Macraigor USB
interface devices that are connected to the host PC.
• JTAG Scan Chain Analyzer – a utility that attempts to analyze a JTAG
scan chain and determine the number of devices present and the identity
of any processors that are found.
These utilities will be available to launch directly from within
Eclipse once the environment has been correctly configured.
Installing this package will also create the demo Eclipse projects that
will be used later. These files will be placed, by default, into
\Program Files\Macraigor Systems\Eclipse Demos.
2-4 SUN Java Runtime
The Eclipse IDE is written entirely in JAVA and
requires that the Java Runtime Environment (JRE) be installed on the
host computer. Many Windows hosts already have the JRE installed. You
can check for an installed JRE by looking in the Windows Control Panel
under “Add or Remove Programs.” If the JRE is installed, there will be
an entry here that looks like the following:
If you do not have the JRE installed, it can be
obtained for free from www.java.com.
Follow the directions to download and install the software and then
check again under “Add or Remove Programs” to be sure that the J2SE
Runtime Environment is available.
2-5 Eclipse 3.3 (Europa) IDE
The Eclipse IDE is an Integrated Development
Environment that provides a graphical framework for running an editor,
compiler, and debugger. Eclipse was originally developed by IBM, but
has since been donated to the open-source community and is now
maintained as a large Open-Source development project.
By installing a few plug-in modules and properly setting up the
environment, Eclipse can be used to write, compile, download, and debug
embedded code on a remote target processor that is connected to the
host machine via a Macraigor JTAG or BDM interface device.
You can download the version of Eclipse 3.3 that Macraigor has tested
with from here:
eclipse-SDK-3.3.1.1-win32.zip
You can also obtain the most recent release of Eclipse from www.eclipse.org.
However, the latest release may not have been tested by Macraigor and
could cause problems with getting the cross-development environment
working properly. In general, newer versions of Eclipse shouldn’t cause
problems but, if you are having trouble getting things to work, please
use the version of Eclipse from the Macraigor web site.
Eclipse is distributed as a single, large zip file. Once you have it
downloaded, extract the contents to the root of your hard drive
(usually “C:”) using
Winzip or another unzipping utility. This is the only installation
that is required. A directory named “eclipse” should have been created
on your drive.
At this point, you should have a working Eclipse installation. This can
be tested by attempting to run Eclipse. The Eclipse installation
doesn’t install a Desktop shortcut. If you’d like to create one, open
Windows Explorer, browse to the \eclipse directory and locate the
“eclipse.exe” file. Right-click on the file name and select Send
To-> Desktop. This will create a shortcut for running Eclipse from
your Desktop.
To run Eclipse, either double-click your newly-created shortcut from
the Desktop or double-click on “eclipse.exe” in Windows Explorer. If
everything is working properly, you should see the Eclipse splash
screen, something like this (note that the version you installed may be
something other than 3.2):
If you don’t see the splash screen, double-check that
you have the JAVA Runtime Environment correctly installed (see section
2-4) and that the Eclipse zip file was properly unzipped.
After a short delay, you should see the “Workspace Launcher” dialog pop
up. It looks like this:
The Workspace location defaults to the current user’s
Documents and Settings directory. We prefer to keep all of the Eclipse
files located together under the \eclipse directory and suggest that
you create the workspace directory there as shown in the picture. This
is not, however, critical and you can locate the workspace anywhere
that you’d like.
After selecting “OK” you should see a progress bar as Eclipse loads and
you should eventually see the Eclipse Welcome Screen that looks like
this:
Click on the Workbench icon as shown in the picture to
bring up the main Eclipse Java Perspective. This is the default mode
that Eclipse runs in. In order to use Eclipse for cross-development of
C/C++ applications we need to install some plug-ins that will allow
Eclipse to build C/C++ applications, run the gdb debugger and connect
the debugger to the Macraigor JTAG/BDM hardware interface. This is
covered in the following sections.
For now, just exit Eclipse.
2-6 Eclipse Embedded CDT 4.0 Plug-in for C/C++
Development (Zylin custom version)
Eclipse was originally created to build and debug JAVA
programs and its basic installation comes configured to handle only
this task. However, Eclipse was designed to be extensible through the
use of plug-in modules that can add functionality and allow it to be
used for other tasks. The CDT (Eclipse C/C++ Development Tooling)
project was created in order to allow Eclipse to be used for writing,
building and debugging C/C++ code. However, for working with embedded
processors in a cross-development environment, the CDT still lacks some
needed functionality. A Norwegian company named Zylin stepped in to
modify CDT so that it could support cross-debugging using the gdb
debugger. We now need to install the Zylin-created CDT plug-in for
Eclipse.
The Zylin plug-in is distributed as two zip files. These zip files are
available for download from the Macraigor web site. As of the writing
of this document, the files that you should get are named:
embeddedcdt4.0-20070830.zip
zylincdt4.0-20070830.zip
Note that these plug-ins are also available directly from the Zylin's
web site. A version that works correctly with all the other packages
and tools will always be available directly from the Macraigor web site.
Once these files are downloaded, unzip them into the \eclipse
directory. No other installation is necessary.
After unzipping the files, start Eclipse again. You should see the Java
Perspective as before. We now need to open the new C/C++ Perspective
that we just installed. Click on the Open Perspective button on the
top-right of the Eclipse window (see the following picture) and select
“Other…”
This will open the “Open Perspective” dialog box as
shown here:
You should see the C/C++ Perspective listed as an option
at the top of the list. Select this and click “OK”. If you don’t see
this option, then the Zylin plug-ins were probably not correctly
unzipped into the \eclipse directory. Double-check that both zip files
were extracted to the same directory where the eclipse.exe file is
located.
Assuming that you selected the C/C++ Perspective and it worked, Eclipse
is now properly installed and configured to work with a Macraigor
JTAG/BDM interface device for developing embedded applications.
The next section will describe how to use a pre-built demo project to
get all the pieces that were just installed working together to provide
a fully integrated cross-development environment.
This section will explain how to import one of the
installed Macraigor demo projects and will go through a simple example
of using Eclipse to build code, connect to the target processor through
a Macraigor JTAG/BDM device, download the code, and perform debugging
tasks.
3-1 Importing a Project
The first step in using a demo project is to import the
project into Eclipse. This essentially opens the project and all of its
files and makes them available in the Eclipse windows for editing.
Start Eclipse, make sure that the C/C++ Perspective is open (see 2-6 if
necessary) and then select File->Import…
You should see the Import dialog window. Click on the “+” next to
General in the main window to expand the options, and you should see an
item named “Existing Projects into Workspace”. This is shown in the
following picture:
Click on “Existing Projects into Workspace” to select it
and then click Next >. In the following Import Projects dialog,
select Browse… to open a navigation window. The default location of the
Macraigor demos is \Program Files\Macraigor Systems\Eclipse Demos.
Browse to this location or to the directory where you chose to install
the Macraigor Eclipse demos. You should see several subdirectories,
including ARM, MIPS, PowerPC and XScale. Select the directory that
corresponds to your target processor (such as PowerPC) and click on
“OK.”
You should now see a list of the available demos for your type of
processor. These demos are pre-configured to work with various standard
evaluation boards that are available from the processor vendor and
other third-party board manufacturers. If you have one of the listed
boards, you can follow through the rest of these instructions and
actually get a small demo program running on your hardware. If you have
a board that isn’t listed, you will probably have to select a demo
project that is similar to your board and then modify the demo to work
on your hardware. See Appendix B for a discussion of how to modify an
existing demo to work with a different board.
The rest of these instructions are going to use the
EmbeddedPlanet_EP8248e demo project as an example. The instructions are
the same regardless of which board/demo you use, so just substitute
your project name where appropriate in the following text and screen
shots.
You should be looking at a list of demo projects for several different
target boards/processors that has a check box next to each demo and all
of the boxes should be checked. We only want to import the demo for the
board we are working with, so click on “Deselect All” to the right of
the list and then click on the check box next to the demo that you wish
to use.
Note that there is an option to “Copy projects into workspace.” If you
don’t intend to modify the project, there is no need to select this.
Eclipse will just work with the files where they are currently located.
If, however, you plan to change the demo to work with a different board
or you think that you might want to experiment with modifying the code,
you can check this box and all of the demo files will be copied into
the Eclipse workspace, giving you your own copy to play with without
changing the files that are distributed by Macraigor.
When you are ready, click “Finish” to load the project into Eclipse.
3-2 Building the Code
You should now be back at the, mostly blank, C/C++
Perspective screen, but your chosen project should be displayed in the
project pane at the upper left of the screen. Click on the “+” next to
the project name to display the files associated with this project. You
should see some source-code files like test.c and crt0.S, along with a
README file (which you are encouraged to open and actually read… just
double click the file name to do so), a makefile, and several files
whose names end in .launch. The .launch files will be explained below.
The first thing that we need to do is compile, assemble and link the
test program. To do this, first click on the “Console” tab near the
bottom of the screen. This window is where the output of the build
process will be displayed. Select the project name by clicking on it,
then right-click. You should see a list of several actions that you can
take on a project. Near the top of the list should be “Build Project”
and “Clean Project”. Select “Clean Project”. This should clean the
project directory and then build (i.e. assemble, compile and link) the
project. Note that, if you prefer to separate the cleaning step from
building, you can pull down the Project menu and uncheck “Build
Automatically.” This will make it so that “Clean” will not
automatically run “Build” and you can manually choose to just “Clean”
and then select “Build” from the right-click menu.
The screen shot below shows what you should see after building the
project. The make file for the project dumps out a list of symbols in
the program after building it. This is what is shown in the console
window. You can scroll the Console window up to see the output from the
various steps in the build process. If everything worked, you should
see a new item listed on the left under the project called “test” with
a picture of a green bug next to it. This is the code that was built
and will be downloaded to the target processor later.
3-3 Debugging the Code
The next step is to download the code to the target
processor and debug it. To do this, we need to use another perspective
called Debug. Find the Open Perspective button on the tab in the
upper-right of the Eclipse window. It looks like this:
Click on this button and select Debug from the menu (note that you can
also open a perspective using the Window-> Open Perspective menu).
After clicking on Debug, the Eclipse windows should change and look
like the following screenshot.
We now need to actually get connected to the target processor through
the Macraigor JTAG/BDM interface device. The demo projects configure
Eclipse to use the gdb debugger in the background, but gdb needs a way
to connect to the processor via the Macraigor device. This task is
handled by the Macraigor OCDRemote program. OCDRemote acts as a
translator for gdb debugging commands. It starts up, initializes the
Macraigor device, establishes a connection to the target processor via
JTAG or BDM, opens a TCP/IP port and then waits for gdb to make a
connection to the port. Once gdb connects, OCDRemote accepts debugging
commands from the TCP/IP port and translates these commands into the
appropriate JTAG/BDM actions for the target processor.
Eclipse doesn’t know anything about OCDRemote or the need for a target
connection, but it does provide a mechanism for running external
programs. The demo projects use this mechanism to start OCDRemote with
the correct arguments for the target processor that we are using and
the specific Macraigor device that is being used. This setup
information is saved in .launch files that are stored as part of the
project.
Find the External Tools button on the Eclipse button bar just under the
menu at the top of the screen. It looks like this:
Clicking on the down-arrow on the right side of the button will open a
Favorites menu and provide a quick way to launch OCDRemote (or other
programs) in the future. For now, we want to look through the details
of the OCDRemote launch configuration, so click on the left side of the
button to open the External Tools interface. The window should look
like the following:
Note that you may have to click on the “+” next to
Program in order to expand the list. As in the above screenshot, you
should see several existing launch configurations. There should be one
with the same name as your project but with “_ocdremote” appended to
it. This is the entry that we need to work with. The other entries
provide an easy way to launch Macraigor utility programs that can be
useful for debugging problems with the environment. Appendix D
discusses how these programs can be used to help find and correct
connection and debugging issues.
Click on the entry that ends in “_ocdremote” and you should see the
details of this particular launch configuration, as shown in the
following picture:
All of the important details about this configuration
are shown on the Main tab. The Location field should be set to the full
path to the OCDRemote executable. This is typically
“C:\Cygwin\usr\local\bin\ocdremote”. If your Cygwin installation is on
a drive other than C: or is installed in a different directory, you can
click on the Browse File System button, find ocdremote.exe and set the
correct location. The working directory can be left as is.
The Arguments window is where program arguments are passed to
OCDRemote, just as if it were being run from a command line. These
arguments need to correctly specify the type of target processor to
connect to and the type of Macraigor interface device that is being
used. The available options for OCDRemote are described and listed in
Appendix A. If you are working with a standard demo board and project,
the –c argument is probably already correct for your processor. The –d
argument, which selects the type of Macraigor device to use, will
generally be pre-set to USB. If you are using a single usb2Demon,
usb2Sprite or usbWiggler, you can leave this argument as it is. If you
are using a different Macraigor device or have multiple Macraigor USB
devices connected to your host computer, you will need to change the
argument to match your hardware interface. Refer to Appendix A for the
available options and examples and change the text as necessary.
The –s option specifies the JTAG/BDM clock speed. This setting is a
divisor on the raw clock speed of the interface device, so lower speed
settings correspond to higher clock rates. Speed 1 is the fastest speed
and 8 is the slowest. The demo projects are generally set to use speed
2 as a precaution. If everything is working for you and you would like
faster downloads and debugging, you can experiment with setting the
speed to 1 and then rechecking that everything still works. Conversely,
if you are having trouble getting connected to your board and/or
downloading code, you can try changing the speed to a slower setting.
If you changed any of the arguments, make sure to click on the Apply
button to save the changes. When everything looks correct, turn on the
target board, make sure that the Macraigor device is properly connected
to the JTAG/BDM header on the board and to the appropriate host
interface cable (USB, Parallel or Ethernet) and then click on the Run
button to start OCDRemote. You should again see the Debug perspective,
but there should now be an entry in the upper-left Debug window showing
that OCDRemote is running. OCDRemote will start up and attempt to
initialize a connection to the target processor. This process takes a
few seconds. If everything works correctly, OCDRemote will output a
startup message to the Console window at the bottom of the screen. A
successful launch of OCDRemote should look like the following screen
shot:
If you get an error message in the console window,
double check that your target board is turned on, that the Macraigor
device is connected properly (with Pin 1 in the correct location) and
that the arguments to OCDRemote match your setup and then try to start
OCDRemote again. If you continue to have problems getting OCDRemote to
start, please refer to the Troubleshooting section below.
Now that OCDRemote is running and waiting for a connection from gdb, we
need to start the debugger. Eclipse and the plug-ins that were
installed provide a seamless integration between the gdb debugger and
the Eclipse environment. All the details of downloading code, setting
breakpoints, reading and writing variables and registers and memory,
etc. are handled by gdb in the background, but the results are
displayed by Eclipse in the windows of the Debug perspective.
In order to run gdb from within Eclipse, we will use another launch
configuration similar to the one used above for OCDRemote. Find the
Debug button on the Eclipse toolbar under the menu options. It looks
like this:
Similar to the External Tools button, the down-arrow on the right side
of the button provides access to a favorites menu that can be used in
the future to quickly launch the debugger. For now, we want to see what
will be done by the Debug launch configuration, so click on the left
side of the button.
You should now see the Debug configuration dialog. There should be a
“+” next to the entry on the left that says, “Embedded debug (Cygwin
hosted GDB)”. Click on the “+” to expand the entry and you should see a
sub-entry with the same name as your project. Click on this name to
select it and you should then see the options for this Debug launch
configuration. The screen should now look like the following screen
shot:
You should see your project name in the Project entry
and “test” under the “C/C++ Application” entry. This is the name of the
application that will be downloaded to the target and debugged. The
“test” file in our case is an ELF file which contains both the object
code that will be downloaded and debug information such as file names
and line numbers of entry points for use by gdb.
Click on the Debugger tab and you should see that the demo is calling
the appropriate target-version of the gdb debugger for your processor.
In this example, it is set to “powerpc-elf-gdb.” Your particular demo
might be using “arm-elf-gdb”, “mips-elf-gdb”, or “i386-elf-gdb.”
Click on the Commands tab. Anything put into the Commands window here
gets passed to gdb. The demos are configured to just pass the command
“source gdbinit” which will cause gdb to open the file “gdbinit” in the
project directory and execute the commands that are in the file. The
gdbinit file for each demo contains commands that will configure the
target board hardware so that RAM is available and so that the
processor is ready to run code. In addition, the commands in gdbinit
will, after loading the code, set a breakpoint at the main() function
of application and then start the processor running. The specific
commands for each target board vary widely and are beyond the scope of
this document. You can look at the gdbinit file for your project by
returning to the C/C++ perspective and double-clicking on “gdbinit” on
the left to edit the file. The file is simply text with one gdb command
per line and should be well-commented.
The remaining two tabs, Source and Common, don’t contain much of
interest to us at the moment. When you are ready, click on the Debug
button at the bottom-right of the window to start gdb, download the
code, and begin to debug the application.
As gdb starts up and runs the commands from the gdbinit file, you
should see messages in the console window at the bottom of the screen.
Once the file has been downloaded, the processor is run and the
breakpoint at main() should be hit. Eclipse will then display the
source code at the location of the breakpoint (which will be in the C
module test.c) and will also display and update the local variables
window. The Debug window should now contain another entry for the debug
process. A sub-entry of this will say something like “Thread[0]
(Suspended)”. This “thread” is the application that was downloaded and
run and it is currently suspended because execution was halted by the
breakpoint at main(). A stack trace is displayed as sub-entries of the
thread and should show that we are currently stopped at main(). A
small, blue arrow on the left of the source window shows the current
location of the Program Counter and various other windows, such as a
register display, are available on tabs in the upper-right window.
You can set software breakpoints in the code by simply double-clicking
in the gray bar on the left of the source window next to the source
line where you want the breakpoint. The following screen shot shows how
Eclipse should look after successfully starting gdb, loading the code,
hitting the breakpoint at main() and then setting another breakpoint
further down in the source file.
Once you have set another breakpoint, you can resume
execution of the program by clicking on the Resume button above the
Debug pane. The button looks like this:
When you click this button, the processor is allowed to
continue running until it hits another breakpoint or is otherwise
stopped or interrupted.
The following screenshot shows Eclipse after the newly-set breakpoint
is hit.
Eclipse provides many other features that would be
found in any typical debugger, including the ability to modify
variables, modify registers, step through source code, instruction
step, display assembly code (with or without inline source statements),
etc. If you have trouble finding a debug feature or action that you
need, please refer to the built-in help system within Eclipse.
Most of the typical debugging tasks that you will need to perform can
be handled within the Eclipse GUI. However, certain target processors
may have features or capabilities that Eclipse can’t access. For
instance, there may be registers that are specific to your particular
PowerPC processor that aren’t displayed in the normal Register window.
This issue is addressed partly by gdb and partly by OCDRemote. The
Console window at the bottom of the screen can also be used for user
input to gdb. If you place the cursor in the Console window and hit
Enter, you will be given a gdb prompt. Here you can type any gdb
command that you could normally enter when using gdb from a command
line (see Appendix C for a list of some useful gdb commands). One of
the commands that gdb implements is called “monitor.” This command
provides a mechanism for passing arbitrary information to a “debug
monitor”. In our case, the debug monitor is OCDRemote. OCDRemote
implements a number of monitor commands for each processor that extend
the functionality of gdb (and, therefore, Eclipse) to cover the
non-standard features of various embedded processors. For example,
OCDRemote is generally capable of displaying ALL the registers that are
available on a given processor. To see what monitor commands are
supported for your processor, place the cursor in the console window,
hit Enter, then type “monitor help.” You will be presented with a list
of monitor commands that can be called for your particular processor.
We have now successfully built, downloaded, and debugged the example
program running live on the evaluation hardware. The final thing that
we might typically want to do is quit the debugger and go back to the
C/C++ perspective in order to fix something in the source code or add
more code. The easiest way to stop execution of the debugger is to
right-click on the thread in the debug window and select “Terminate and
Remove” from the menu that is displayed. This is shown in the following
screenshot.
This command stops the debugger and then cleans up the
debug window by removing all the entries for the gdb debug launch.
Killing the debugger will also cause OCDRemote to exit automatically,
but the entry will still be shown in the Debug pane. To remove it,
right-click on it and select “Remove All Terminated” as shown in the
following screen shot. You should then be back to a blank debug pane
and you can change the perspective back to “C/C++” and continue to work
with your code.
OCDRemote can be configured to run with any Macraigor
hardware device and supports all target processors that Macraigor
Systems has JTAG/BDM support for. It can also be configured to support
target boards with multiple processors on a single scan chain. The
available options for use with OCDRemote are shown below:
Usage:
ocdremote -c <CPU,CPU,...> [-p <port number>] [-d
<device>] [-a <device address>] [-s <speed>]
The –c/--cpu CPU argument takes a list of one or more processor types
and is the only required parameter (the others will default). The
processors must be listed in the order in which they are arranged on
the scan chain. Available target CPU options are:
ARM 7/9/11 Families:
ARM7EJ-S | ARM7TDMI | ARM7TDMI-S | ARM9E-S | ARM9EJ-S | ARM9TDMI |
ARM11 | ARM720T | ARM920T | ARM922T | ARM926EJ-S | ARM940T | ARM946E-S
| LH7A40X | LH7952X | NET+15 | NET+20M | NET+40 | NET+50 | NS7520 |
NS9360 | NS9750 | NS9775 | NSARM9 | OMAP310 | OMAP710 | OMAP1510 |
OMAP5910 | SharpARM7 | SharpARM9 | TI925T | iMX21 | iMX31 |
MIPS 32-bit Family:
Alchemy_AU1x00 | BCM7115 | MIPS32_4Kc | MIPS32_4Ke | Vitesse_V3000 |
MIPS 64-bit Family:
MIPS64 | TX49 |
PowerPC Family:
AMCC440EP | AMCC440GP | AMCC440GX | MPC55X | MPC56X | MPC603 | MPC740 |
MPC745 | MPC750 | MPC755 | MPC8XX | MPC5200B | MPC5554 | MPC8240 |
MPC8245 | MPC8247 | MPC8248 | MPC825X | MPC826X | MPC8270 | MPC8271 |
MPC8272 | MPC8275 | MPC8280 | MPC85X0 | PPC403 | PPC405 | PPC603 |
PPC740 | PPC750 | PPC750FX | PPC750GX |
DSP563XX Family:
dsp563xx |
Intel Xscale Family:
80200 | 80219 | 80321 | 81341 | 81342 | IOP303 | IOP315 | IOP321 |
IOP331 | IOP332 | IOP333 | IXC1100 | IXP42x | IXP46x | IXP23XX |
IXP2400 | IXP2800 | IXP2850 | PXA210 | PXA25x | PXA26x | PXA27x |
XSCALE-5IR |
XSCALE-5IRSLAVE | XSCALE-7IR | XSCALE-CORE3 |
Unknown or Non-Processor Devices
U:<ir bits>:<bypass bits>
The –p/--port argument is used to specify the TCP/IP port number that
will be opened for communication with a remote debugger. This argument
defaults to port 8888
The –d/--device argument specifies which Macraigor interface device is
being used. This argument defaults to RAVEN. Available options are:
RAVEN | USB | MPDEMON_ETHERNET | WIGGLER | MPDEMON_PARALLEL |
MPDEMON_SERIAL
The –a/--address argument indicates the address of the Macraigor
Hardware device. This means different things for different devices. For
Parallel devices (Raven, Wiggler, or mpDemon in Parallel mode), it is
the LPT port number that the device is attached to, allowed values are
1 – 4, and it will default to LPT1. For the mpDemon in Serial mode, it
is the COM port number that it is attached to, allowed values are 1 –
8, and it will default to COM1. For USB devices (usb2Demon, usb2Sprite,
usbWiggler) it is the assigned address for the device, allowed values
are 0 – 16, and it will default to 0. If a single USB device is
attached to the host computer, it will always be at address 0. If
multiple Macraigor USB devices are attached, the assigned address for
each device can be found by running the “usbDemon Finder” utility
application. For the mpDemon in Ethernet mode, it is the TCP/IP address
of the mpDemon, it will not default (i.e. it must be specified) and
must be in the format xxx.xxx.xxx.xxx. Examples of valid configurations
are given at the end of this section.
The –s/--speed argument specifies the JTAG/BDM clock rate to use. This
argument is used as a divisor on the raw clock rate of the Macraigor
device, so lower numbers are faster. Allowed values are 1 – 8. This
argument defaults to 1.
The –b/--baud argument is used only for the mpDemon in serial mode and
specifies the baud rate for the serial connection. Allowed values are
1200 – 115200 baud and this will default to 115200.
Examples:
Wiggler on LPT2 at JTAG speed 1:
OcdRemote -c AMCC440EP -d WIGGLER -a 2 -s 1
Raven on LPT1 at JTAG speed 1 :
OcdRemote -c AMCC440EP -d RAVEN -a 1 -s 1
mpDemon : ethernet - 192.168.1.30 at JTAG speed 2 :
OcdRemote -c AMCC440EP -d MPDEMON_ETHERNET -a 192.168.1.30 -s 2
mpDemon: parallel on LPT1 at JTAG speed 3:
OcdRemote -c AMCC440EP -d MPDEMON_PARALLEL -a 1 -s 3
usb2Demon as USB device 0 at JTAG speed 1:
OcdRemote -c AMCC440EP -d USB -a 0 -s 1
UsbSprite as USB device 2 at JTAG speed 3:
OcdRemote -c AMCC440EP -d USB -a 2 -s 3
UsbWiggler as USB device 0 at JTAG speed 1:
OcdRemote -c AMCC440EP -d USB -a 0 -s 1
If you will be working with either a custom board or an
eval board that we don’t have a pre-configured Eclipse project for, you
will need to create an Eclipse project for your board and configure the
environment to work with your hardware. This section will discuss the
general tasks that will typically need to be done in order to get the
Eclipse environment, gdb, and OCDRemote set up to work with your target
hardware. This section might also be useful if/when you need to expand
one of the demo projects in order to start building an actual, custom
application.
The easiest way to begin working with a new or custom target board is
to start with one of our provided demo projects that is as close as
possible to the target hardware that you will be using. This will
usually involve selecting a project that uses either the same target
CPU type or at least one from the same family of CPUs. Browse through
the existing demo projects, select one that uses a CPU type that is as
close as possible to the one you have and import that project. You can
right-click on the project name in Eclipse and rename the project to
something that makes sense for your board. Note that you will have to
also change the project name reference in the External Tools launch
configuration and the Debug launch configuration. Just open these,
change the names of the configurations and set the project name
references to the new project name.
The first things that may need to be changed in order to work with a
target board that we don’t yet support are the arguments to OCDRemote.
If your target processor is not exactly the same as is used in the
existing demo, refer to Appendix A and find the CPU argument that
matches your processor, then open the External Tools interface
(discussed in section 3-3) and change the command-line arguments that
are passed to OCDRemote. If you aren’t sure of which processor type to
select, you can run OCDCommander (discussed in Appendix D) and try
various options until you find ones that work.
Once you think you have the arguments to OCDRemote correctly set up,
try launching it from Eclipse and check that it starts without any
errors. If you have problems at this stage, refer to Appendix D for
some tips on troubleshooting connection issues.
In order to actually run code on a target CPU, your build must
correctly specify the address of RAM on the target processor when the
code is linked and the gdbinit file must be set up to configure your
board so that, when gdb starts, the board is properly configured to run
code and has RAM available at the address to which the code will be
loaded. We suggest that you first get your board working with the
simple test program that we provide in our demos. Once this works, you
can begin adding your own code modules and developing your own
applications. Each of the required steps is discussed below:
Setting the start address of the program:
The build process must be made aware of the address on the target to
which the code will be loaded in order to correctly link the source
modules. Our demos use the gcc C/C++ compiler and other gnu utilities
to assemble, compile and link the source code. The standard way of
specifying the start address of the code when using gcc is to provide a
linker script that is passed to the build process by the makefile. You
can look at what our make file does by editing it within Eclipse. You
should see an entry for “Makefile” in the Eclipse project pane. You can
double-click on the file name to edit it and read through the build
steps. In our demos, the linker script is named “ldscript”. You should
see this file listed in the Eclipse project pane. You can edit it by
double-clicking on it. Near the top of this file, you should see a line
that looks something like this:
. = <address>
This line sets the starting address of the code and must correspond to
a RAM location on the target hardware where there will be enough room
to hold the downloaded code. Edit this line and set the address to a
location where your board will have RAM available and then rebuild the
code.
Configuring the target hardware:
Now that the build process knows where to place the code, the target
hardware must be configured so that code can be run and so that there
is RAM available at the address specified in the ldscript file. In our
demos, board configuration is handled by a gdb script file called
“gdbinit”. When Eclipse starts gdb, this file is passed to the debugger
to be run. The gdbinit file must contain whatever steps are necessary
to set up RAM and prepare the target CPU for running code.
In general, our demos use the simplest possible method of setting up
RAM and configuring the board. On processors that have on-chip RAM, we
use that. If a particular eval board has boot code already in Flash, we
often just reset the processor and let the boot code run for a few
seconds to get the board configured. For a custom board design, or an
application which will be large and needs to run from the primary DRAM
(as opposed to a small area of on-chip RAM), these methods will
probably be insufficient. Typically, a significant amount of setup may
need to be done on a board, after a hard reset, in order to get a RAM
controller configured and to set up the processor environment so that
code can be run. An example of a more involved gdbinit file can be seen
in the Freescale_MPC8560_ADS demo project. You can import this project
or just open the gdbinit file in this directory to see the steps that
are taken. This example shows that many of the typical steps that need
to be performed for board setup are best done using monitor commands to
directly read/write registers, memory locations and/or memory-mapped
registers. You can find a reference for available monitor commands in
Appendix C.
The process of developing the steps necessary to configure a board when
a debugger starts is somewhat cumbersome from within Eclipse. We
strongly suggest that you use our OCDCommander debugger to develop the
configuration process and, once it is working, translate the necessary
commands into the syntax required by gdb. You can read more about
OCDCommander in Appendix D. It is a very simple debugger with simple
syntax and can run “macro” files that are just like startup scripts.
These macros are just text files that contain a single command per
line. A few example startup macros are included with the OCDCommander
installation and can usually be found in \Program Files\Macraigor
Systems\OCD Commander. You should be able to pick up the required
command syntax from these files. Commander gives you a simple, quick
way to test and modify your startup commands until you get everything
working. Commander provides a built-in memory test command that can be
used to test your memory configuration. Try typing “memtest 2 1024
0x0f000000 4”. This will run a memory test (writing a known pattern to
memory and reading it back) using two iterations with a block size of
1k Bytes. The address of the test will begin at 0x0f000000 and each
write/read will be done as a 4-byte quantity (i.e. a 32-bit word). The
block size can be as large as 16K and allowable size parameters (the
last argument) are 1,2,4,8 or 0, where 0 automatically selects the
largest transfer size supported by the processor.
Once you have a working setup macro using OCDCommander, it is a simple
task to translate the commands into the syntax required by gdb. Open
and look at the gdbinit file in the Freescale_MPC8560_ADS project
directory and you should be able to see the required syntax.
In general, you won’t want to change the configuration settings at the
top of gdbinit or the macros that we define. Add your customized setup
steps to the gdbinit file after these initial sections. Also, you will
probably want to keep the last few commands in the gdbinit file that
load the program, load the symbol table, set a breakpoint at main() and
then run the processor.
Appendix C. Cloning/Renaming an Existing Macraigor Demo Project
You currently have an existing demo Macraigor Eclipse project named aaa in
c:\example\aaa.
You want to clone and rename this project so you can then build your own load image but keep the demo project’s Eclipse settings. Your new project is going to be called bbb and is going to exist in
c:\examples\bbb
To clone an existing Eclipse project and create a new one, do the following :
1) make a copy aaa and all of it's sub directories so you now have :
c:\examples\copy of aaa
2) rename the new project directory to c:\example\bbb
3) in the file c:\example\bbb\.project (note: .project has a period as it's first character) using a text editor (WordPad for example) :
CHANGE : <name>aaa</name> TO <name>bbb</name>
4) gdb launch file :
Rename your gdb launch file to the name of your new project ie old c:\example\bbb\aaa.launch -> new c:example\bbb\bbb.launch
Using a text editor go into c:\example\bbb\bbb.launch :
a) CHANGE: <stringAttribute key=".gdbinit"value="C:\example\aaa\gdbinit"/> TO: <stringAttribute key=".gdbinit"value="C:\example\bbb\gdbinit"/>
b) CHANGE: <stringAttribute key="org.eclipse.cdt.launch.PROJECT_ATTR" value="aaa"/> TO: <stringAttribute key="org.eclipse.cdt.launch.PROJECT_ATTR" value="bbb"/>
c) CHANGE: <listEntry value="/aaa"/> TO: <listEntry value="/bbb"/>
5) ocdremote launch file:
Rename your gdb launch file to the name of your new project ie c:\example\bbb\aaa_ocdremote.launch -> c"\example\bbb\bbb_ocdremote.launch
Using a text editor go into c:\example\bbb\bbb_ocdremote.launch :
CHANGE : <stringAttributekey="org.eclipse.ui.externaltools.ATTR_WORKING_DIRECTORY" value="${workspace_loc:/aaa}"/> TO <stringAttributekey="org.eclipse.ui.externaltools.ATTR_WORKING_DIRECTORY" value="${workspace_loc:/bbb}"/>
You should now be able to :
start Eclipse,
Select File -> Import
Select existing projects into workspace, click NEXT
<Select Root Directory> and Browse to c:\examples\bbb bbb will appear in the projects list,
click the FINISH button to open the bbb project
Finally: copy your load image’s source files to c:\examples\bbb, delete the demo source files, and modify the make file to build your load image. If you change the load image’s output file name (from test.elf to yourname.elf) you will need to go back into c:\example\bbb\bbb.launch:
CHANGE
<stringAttribute key="org.eclipse.cdt.launch.PROGRAM_NAME" value="test.elf"/>
TO
<stringAttribute key="org.eclipse.cdt.launch.PROGRAM_NAME"
value="yourname.elf"/>
Some useful text mode commands to use on the GDB
command line or in the Eclipse console:
| s |
Step, single step a C source code line |
| si |
Step Instruction, single step a
machine code instruction |
| c |
Continue, run the processor after a
step or breakpoint |
| b |
Breakpoint, set a breakpoint at
specified location |
| hbreak |
Hardware Breakpoint - set a hardware
breakpoint at specified location |
| d |
Delete all breakpoints |
| bt |
Print backtrace of all stack frames |
| up |
Select and print stack frame that
called this one |
| ^C |
Control C, stop execution from the
keyboard |
| L |
List, show the source code being
executed |
| x |
Examine, show the contents of memory |
| i r |
Info registers, show the contents of
all registers |
| set |
Set, change the contents of ram or a
register |
| monitor |
Send the following commands to the
debug monitor. See below for monitor commands that the Macraigor
OCDRemote understands. |
Monitor commands implement various functions that are
not available using GDB directly and vary from CPU type to CPU type.
You can get the full list of "monitor" commands by issuing the command
"monitor help" in the console window after GDB has attached to
OCDRemote. The following monitor commands are common to all CPU types
and can be executed from the gdb command line, from the Eclipse console
window after attaching to OCDRemote or from with a gdb command file,
such as gdbinit.
Common OCDRemote monitor commands:
monitor help – Show all available monitor commands for the current CPU
monitor allrun – Synchronized run command for all processors
monitor allstop – Synchronized stop command for all processors
monitor char/short/long <addr> - Read a char/short/long value
from <addr> monitor char/short/long <addr> = <val> -
Write <val> to <addr>
monitor endian [<big|little>] – Set endian mode of OCDRemote
monitor halt – Stop the CPU
monitor reg <regname> - Read the value of the <regname>
register
monitor reg <regname> = <value> - Write <value> to
<regname> register
monitor help regname - Display all available register names
monitor reset – Reset the target CPU and stop at the reset vector
monitor resetrun – Reset the target CPU and run from the reset vector
monitor runfrom <addr> - Start the CPU running at <addr>
monitor set memspace <virtual|physical|#> - Set the memory space
for CPU
monitor set cpu <cpu number> - Set which CPU on the scan chain to
send commands to.
monitor set/clear hbreak [<addr>] – Set or clear a hardware
breakpoint at <addr>
monitor set regbufaddr <addr> - Set location of the register
buffer to <addr>
monitor sleep <seconds> - Do nothing for <seconds> seconds
monitor status – Report the status of the target CPU (running or halted)
monitor sync cpus <on/off> - Turn syncing on or off. Syncing on
will attempt to run/stop all processors simultaneously.
If you are having trouble getting your Eclipse
environment to work with a Macraigor device, please refer to the text
below to see the most likely causes of some of the more common issues.
Many of these issues can be resolved, or at least better characterized,
by using the additional Macraigor utility programs that are provided as
part of the OCDRemote installation package. These programs and their
general uses are described below. Each of these utilities can be
launched from within Eclipse from the External Tools interface. To
access this interface, click on the button that looks like this:
and then select the tool that you wish to run.
OCDCommander:
OCDCommander is a very simple, low-level debugger that was written by
Macraigor and is used extensively internally for our own testing. In
general, if you select the correct connection device at the correct
address and the correct processor type from the Commander startup
screen and everything is connected properly, you should be able to
establish a connection to your processor and then check that you can do
simple things like run and halt the processor, read registers, etc.
Once you get a successful connection using OCDCommander, you can then
use the same configuration settings within Eclipse when you start
OCDRemote.
If you are sure that everything is connected correctly and you still
can’t get a connection using Commander, try slowing down the Speed
setting (low speeds are faster, so set the number higher to go slower).
A speed setting of 6 or 7 is usually slow enough to see if the clock
rate might be your problem. If a slow speed works, you can experiment
with increasing the speed until it doesn’t work and then use the
fastest setting that does work in Eclipse.
If you contact Macraigor with a connection problem, we will almost
always ask you to try the connection with Commander and will often also
ask for a log file. You can save yourself time by trying Commander
first yourself. Checking the box on the opening dialog that says “Start
with logging on” will cause a log file to be generated named
“wigglers.log”. You can email this file to us in order to assist in
addressing your problem.
usbDemon Finder:
This utility is used for several things related to working with
Macraigor USB interface devices. It will start and look for all
Macraigor USB devices that are connected to the host machine and will
then display the serial numbers of each device along with the assigned
device number. This device number is the “address” that must be used
when calling OCDRemote or when setting up OCDCommander. To distinguish
between multiple USB devices, there is a button in the Finder that will
cause the green LED on the device to flash for a visual indication of
which device is currently selected. Even with a single connected USB
device, the Finder can be helpful to ensure that the device is properly
connected and functioning and that the Macraigor USB drivers are
installed correctly. The usbDemon Finder is also used to program
licenses into the USB device. If you are using a Macraigor application
that requires licensing, such as the Flash Programmer, you will need to
use the Finder to set the license code in the USB device.
JTAG Scan Chain Analyzer:
This utility analyzes the JTAG scan chain that the selected device is
connected to and will attempt to identify any processors that it finds
on the chain along with any other JTAG devices that are connected.
Running this utility can be helpful to check that, at the most basic
level, the JTAG connection is working properly. It can also be used to
help identify the type of processor that you are working with and to
detect if there are other, non-processor, devices on the scan chain. We
have often found that some hardware designs will put devices such as
FPGAs on the same scan chain with the processor. This type of
configuration will cause the connection to the processor to fail
initially. Our drivers and OCDRemote are capable of handling designs of
this type (or designs with multiple CPUs), but we have to know what the
configuration of the scan chain looks like. If you are having
unexplained connection problems, try running this utility and make sure
that the reported scan chain and the type of processor(s) are what you
expect. If you find that there are other devices or CPUs on the scan
chain, we can help you to configure OCDRemote so that it can properly
communicate with your processor.
Note that this utility only works for JTAG scan chains. It cannot be
used with CPUs that use a BDM type of interface such as the Freescale
MPC8xx/5xx families of processors.
General tips for finding connection problems:
If you can’t get OCDRemote to start up without errors, there are
several things you can try to verify that the Macraigor hardware is
working, that all of your configuration settings are correct, and that
you are correctly connected to the target processor.
The first thing to check is that your Macraigor device is connected to
the host, the proper drivers are installed and that the device is
communicating properly. If you are using a USB interface device, run
the usbDemon Finder as described above. If you have a Wiggler or a
Raven, you can download a utility called the Raven Tester from the
Macraigor web site. This utility will exercise a Raven to be sure that
it is working properly. For a Wiggler, it can usually determine if the
device is connected, but cannot test it. If you are using an mpDemon
(most often used in Ethernet mode), you can try pinging the address of
the mpDemon from the host machine.
Assuming that your device is responding to these basic connection
tests, the next level of checking is to test that the JTAG interface
and scan chain are working properly. If you are working with a BDM
device, skip to the next paragraph. With a JTAG-based debug interface,
you can run the JTAG Scan Chain Analyzer. This utility, as described
above, will analyze the scan chain and attempt to identify any
processors that it finds. Make sure that the processor(s) reported are
what you expect and that no other, unexpected devices are found on the
chain. If the Scan Chain Analyzer reports an error, the most likely
causes are either a bad connection to the target header (make sure that
the ribbon cable is positioned correctly for Pin 1) or a problem with
your board’s JTAG interface design. We often see custom CPU boards that
are designed in such a way that they won’t work with a Macraigor
interface device. If you are getting errors from the Scan Chain
Analyzer on a custom-designed board, you can email the schematic for
your JTAG interface to us and we can usually quickly spot any potential
problems. See below for how to contact us by email.
If the Scan Chain Analyzer is reporting what you expect (or you are
using a CPU with a BDM interface), the next step is try establishing a
connection using OCDCommander. Start Commander, double-check all of the
initial configuration settings and then try to connect. If Commander
starts without reporting an error, try clicking on the “status” button.
You may see either “running” or “In DEBUG”. If the processor is
reported as running, try clicking on the “reset” button. This should
reset the processor and stop it at the reset vector. Once it stops, try
clicking on the “cpu” button and/or the “regs” button to see if you can
read registers. If this seems to work, type “test 2”. This will run a
write/read test on the registers. If any of the previous suggestions
don’t work in Commander, you can exit, find the wigglers.log file that
should have been created (assuming that you checked “Start with logging
on” on the startup dialog) and email it to us. This file can provide us
with a lot of information about what might be happening.
If all of these things work in Commander, you should be able to use the
same configuration parameters in Eclipse when you start OCDRemote.
Refer back to section 3-3 and Appendix A if you don’t remember how to
configure OCDRemote’s startup parameters.
If you still have problems after trying the above debugging steps, you
can contact Macraigor for help. Our contact information is given below.
We prefer that you contact us via email and include as much information
and detail as possible in your initial email. This will help us to
resolve your problem as quickly as possible. In your email, please
include at least the following information:
- Type of target CPU
- Type of Macraigor device you are using
- Did you run the usbDemon Finder or Raven Tester? If
so, what happened and what, if any, error messages did you get?
- Did you run the JTAG Scan Chain Analyzer? If so,
what happened and what, if any, error messages did you get?
- Did you run OCDCommander? If so, what happened and
what, if any, error messages did you get?
- If you were able to get connected with OCDCommander,
but ran into problems trying to control the processor, what did you
try, what happened, what error messages did you get? If this is the
case, please also include or attach the wigglers.log file with your
email.
- If OCDCommander works, but OCDRemote still won’t
start, what error message is it reporting?
Also include any other information that you think might
be helpful. Is the problem consistent or intermittent? If it is
intermittent, have you observed anything that might correspond to times
that it works or doesn’t work? The more information you can include,
the more likely it is that we will be able to resolve the problem
without having to contact you for further information.
Email support issues to: support@macraigor.com
Eclipse is a trademarks of Eclipse Foundation, Inc.
|
