Macraigor Systems GNU Tools FAQ...

What is the GNU toolkit and why are you giving it away for free? 

The GNU toolkit consists of the following software utilities:

• GCC - an ANSI C compiler 
  
• G++ - an ANSI tracking C++ compiler
  
• GDB - source and assembly language command line debugger
• GDBTUI - gdb with a simple windowed interface showing source and breakpoints
  
• GAS - GNU assembler
  
• LD - GNU linker
  

Macraigor Systems provides a separate executable, "OcdRemote." This stand-alone utility converts GDB commands to JTAG/BDM signals. 

IE: 

<GDB>--tcp/ip--<OCDRemote>--Macraigor OCDemon Device--JTAG--<Target CPU>

You will need to start OcdRemote in a separate window before starting GDB.

The GNU tools are shareware whose source is provided to all interested parties free of charge by the Free Software Foundation (www.gnu.org). In their words: "The Free Software Foundation (FSF) is dedicated to eliminating restrictions on copying, redistribution, understanding, and modification of computer programs. We do this by promoting the development and use of free software in all areas of computing ...". 

GO TO TOP

What is OcdRemote and how do I use it?

Prior to running Insight/GDB, you must first start OcdRemote. This stand alone utility converts GDB commands to JTAG/BDM signals.

For example: 

<GDB>-tcp/ip-<OCDRemote>-LPTx-Macraigor OCDemon Device-JTAG--<Target CPU>

Use the following command to start OCDRemote using a RAVEN interconnection device on LPT1 and using TCP/IP port 8888 to receive commands from GDB. In Linux it can either be run in the background or from a second shell window. Under Windows it must be run from a second Cygwin "bash" shell window:

/usr/local/bin/OcdRemote -c <cpu type>

OCDRemote takes additional OPTIONAL parameters that allow you to modify it's modes of operation:

OCDRemote -c <CPU type> [,<CPU type>],..] [-p <port number>] [-d <device>] [- a <device address>] [-s <speed>]

where: 

<CPU type> = 
ARM :  ARM7 | ARM9 | LH7A40X | NetSilicon
MIPS:  MIPS32_4Kc | MIPS32_4Ke | AU1x00 | MIPS64 | Tx49
POWER PC: MPC55x | MPC56x | MPC603 | MPC740 | MPC745 | MPC750 | MPC755 |  MPC8xx |   MPC5554 | MPC8240  | MPC8245 | MPC8247 | MPC8248 | MPC825x | MPC826x | MPC8270 | MPC8271 | MPC8272 | MPC8275 | MPC8280 | MPC85x0 | PPC403 | PPC405 | PPC740 | PPC750 | PPC750fx | PPC750gx
INTEL XSCALE : 80200 | 80219 | 80321 | IOP303 | IOP332 | IOP315 | IOP321 | IXC1100 | IXP42x | IXP2400 | IXP2800 | IXP2840 | PXA210 | PXA25x | PXA26x | PXA27x | Xscale-5IR | Xscale-7IR | Xscale-5IRSlave | Xscale-7IRSlave
UNKNOWN : U:<IR SIZE IN BITS>:<BYPASS SIZE IN BITS>

<port number> = tcp/ip port, default = 8888 

<device> = WIGGLER, RAVEN,MPDEMON_SERIAL, MPDEMON_PARALLEL, MPDEMON_ETHERNET, USB, default = RAVEN 

<device address> = WIGGLER/RAVEN/MPDEMON_PARALLLEL: LPT number 1 - 4 
MPDEMON_SERIAL : COM number : 1 - 4 
MPDEMON_ETHERNET : tcp/ip address in the format : xxx.xxx.xxx.xxx
USB : macraigor USB device number : 0 - 15
default = 1 

<speed> = JTAG clock rate 1 - 8, default = 1 (fastest)

 Some Examples :

To connect to an  Xscale IQ80321 CPU using a Wiggler(windows only)  LPT2  at  JTAG speed 1 (380 khz), you would enter :
        OcdRemote -c XSCALE-5IR -d WIGGLER -a 2 -s 1

How do I configure mpDemon to interface directly to GDB (without using OcdRemote)?

mpDemon version 3.0.0.x can now communicate directly with one or more GDB sessions via  ethernet  to it's internal OcdRemote GDB interface.  Initially, prior to starting the Insight/GDB session(s) on your host, you must first configure the mpDemon's OcdRemote for your target board. OcdRemote converts GDB commands to JTAG/BDM signals that control your target board's CPU(s). IE :

[GDB(s)]--<GDB commands>--[mpDemon/OcdRemote]--<JTAG/BDM signals>--[Target]

To configure OcdRemote you must tell it :
    1) The JTAG/BDM Clock Rate - this is the rate at which the mpDemon clocks the
        JTAG/BDM lines on the target.
    2) The JTAG scan chain configuration - what devices are on the target's JTAG/BDM
        scan chain and if there are multiple devices on the scan chain  (two or more CPUs/TAP
        controllers/FPGAs/ect) what order the devices are in.
Using this information the mpDemon creates a GDB monitor TCP/IP port for each active
CPU on the target board's JTAG/BDM scan chain. You gdb session's gdb.ini file should
have the line :
        remote target <mpDemon's ethernet address>:<cpu's GDB monitor tcp/ip port>

This tells GDB to send it's monitor commands to the <GBB monitor tcp/ip port> on
the mpDemon. These commands will be routed by the mpDemon to a single target CPU.
Multiple GDB sessions can be run simulataneously each controlling a different CPU
on the target board.
For example to debug two PPC8248 CPUs on a target system connected
to an mpDemon at ethernet address 192.168.1.4 configured so that :
    CPU 1 used port 8888 and
    CPU 2 used port 8889 you would start two GDB sessions :
The first session would control CPU 1, it's gdb.ini file would contain the line
    remote target 192.168.1.4:8888
The second session would control CPU 2 it's gdb.ini file would contain the line
    remote target 192.168.1.4:8889

The current scan chain configuration and the port(s) GDB session(s) will use to access
a given CPU are displayed on both the

mpDemon's web page:

        Macraigor Systems LLC mpDemon™

System Configuration     OCDREMOTE Bus Configuration
    
Firmware Version     3.0.0.xxx   Index  CPU Type   JTAG Lengths (in Bits)  TCP/IP Port
                                                                               IR        BYPASS
                                                                               TDO <-
Licenses                                        1     PPC8248                                         8888
JTAG Speed:     2                                                   TDI ->
DHCP             off                                     
IP Address        192.168.1.99
IP Mask            255.255.255.0
IP Gateway        192.168.1.1
MAC Address     00:60:bf:0c:0d:0e
    
and mpDemon's Serial Port display:

     Macraigor Systems mpDemon(tm) version 3.0.0.xxx

API Baud Rate  : 115200
Use DHCP?      : No
TCP/IP Address : 192.168.  1. 99
       Mask    : 255.255.255.  0
       Gateway : 192.168.  1.  1
MAC Address    : 00.60.bf.0c.0d.0e
OCDREMOTE      : JTAG SPEED : 2
                 JTAG TDO <- [1]PPC8248=8888 <- TDI

                          
This configuration information only has to be entered once for a given target system.
It is stored in the mpDemon's flash and will remain active until it is changed by the user.

Modifying mpDemon's ODCRemote  JTAG/BDM Clock Rate:

    The JTAG speed parameter can have a value from 1 (the fastest: ~15 mhz) to 8
    (the slowest: ~8 Khz).

    On the Web page :

        1) Click on the OCDREMOTE Configuration hot text  
        2) Select the new JTAG/BDM speed from the "JTAG Speed" dropdown list
        3) Click the Submit Button to store the new value into flash
        4) Click the Reboot Button to restart the mpDemon, the new value will now take effect

    On the Serial Port Display

        1) enter "0<cr>"  to go to the OCDREMOTE menu
        2) enter the new JTAG/BDM clock rate (1 - 8)
        3) enter "n<cr>" after "Do you want to change the JTAG chain?"
        4) enter "r<cr>" to restart the mpDemon, the new value will now take effect.
        
        
Modifying mpDemon's OCDRemote  JTAG Scan Chain Configuration:

    On the Web page :

        1) Click on the OCDREMOTE Configuration hot text  
        2) To :    
            Change the type of CPU already in the list:
                Select the new CPU type from the "CPU Type" dropdown list for that
                position it the scan chain. If the device you wish to add is not a
                CPU (i.e. a TAP controller, FPGA, ect) select the "UNKNOWN" device type and
                enter the length in bits of the device's JTAG Instruction register in the
                JTAG Parameters IR column, and the length in bits of the device when it is
                placed in bypass mode (this is typically: 1) in the JTAG Parameters Bypass
                length column.  
            Add a new CPU to the list :
                Click the Add CPU button, a new CPU of "UNKNOWN" type will be added to the
                bottom of the list. Change the type of CPU to the one you need as above.
            Delete a CPU from the list :
                Next to the CPU you want to remove from the scan chain list, click the
                Delete button. That entry will be removed from the list. The port numbers
                will change to relect the new list order                 
        3) Click the Submit Button to store the new scan chain configuration into flash
        4) Click the Reboot Button to restart the mpDemon, the new values will now take effect

    On the Serial Port Display

        1) enter "0<cr>"  to go to the OCDREMOTE menu
        2) enter "<cr>" to retain the current JTAG/BDM clock rate
        3) enter "y<cr>" after "Do you want to change the JTAG chain?"
        4) at the "Number of Devices in Scan Chain" prompt enter the
            number of devices (CPUs and other devices) in the JTAG/BDM
            scan chain. If you enter "<cr>" the current value shown in
            brackets [] will be retained.
        5) At each "Device [<scan chain index>]" prompt enter enter the name of
            the CPU/device at this location in the scan chain.If the device you
            wish to add is not a CPU (i.e. a TAP controller, FPGA, ect) enter
            the "UNKNOWN:<ir length in bits>:<bypass length in bits>" device type.
            Where <ir length in bits> = the length in bits of the device's JTAG
            Instruction register and
            <bypass length in bits> = the length in bits of the device when it is
            placed in bypass mode (this is typically: 1).
        6) At each "TCP/IP port number : [<cpu's GDB monitor tcp/ip port>]" prompt
            enter "<cr>" this will let OCDREMOTE assign the port number to the CPU.
        7) After all the CPUs have been entered enter any key to return to the main
            menu
        8) enter "r<cr>" to restart the mpDemon, the new values will now take effect

Did Macraigor Systems make changes to the GDB source?

No. Macraigor uses the standard GNU GDB release.

We provide a utility, OcdRemote that looks to GDB like a target based monitor waiting on a TCP/IP port for GDB monitor format commands. Macraigor has added CPU specific commands to OcdRemote that are accessable  via GDB's "monitor" command. In the GDB command window enter "monitor help" for a list of the commands available for your CPU type.  See the answer to "What is OcdRemote and how do I use it" FAQ for more information on how to run OcdRemote.. 

GO TO TOP

What other companies provide software tools that work with Macraigor Systems OCDemon™ interface devices? 

• Accelerated Technology, a division of Mentor Graphics www.acceleratedtechnology.com
  
• ARM www.arm.com/products/DevTools
• DCC-I www.ddci.com
  
• Green Hills Software www.ghs.com
• IAR Systems www.iar.com
  
• Intel www.intel.com/software/products/compilers/embedded/toolsuite
• Marvell  http://www.marvell.com/products/cellular/applications.jsp
  
• Metaware, a division of ARC Interational www.metaware.com
• Metrowerks, a FreeScale company www.metrowerks.com
• Microcross www.microcross.com
  
• Mentor Graphics www.mentor.com/embedded
• Paradigm Systems www.devtools.com
  
• Red Hat Software www.redhat.com
  
• Tasking www.tasking.com
• Viosoft www.viosoft.com
  

GO TO TOP

Step-by-step installation instructions for Cygwin™ under Windows NT/2000/XP

1. On the GNU Tools page of our web site select the "Download Cygwin" hypertext, right click the mouse and select "open"
   
2. In the popup dialog select the Open button. This will automatically download and install cygwinenv-1.5.23-2.exe on your your PC. 
   
3. Your destktop will now contain the icon "Cygwinl" and your Start -> All Programs list will now contain a "Cygwin -> Cywin Bash Shell" entry. A new directory tree : c:\cywin will have been added to your file system. All subsequent GNU Toolkit installations will be put there.
4. Clicking on the"Cygwinl" destop icon or selecting "All Programs->Cywin ->Cywin Bash Shell"  from the Start menu will start up a cywin bash shell window.
   
   

GO TO TOP

Step-by-step installation instructions for Windows NT/2000/XP  GNU Toolkits

NOTE: PRIOR TO RUNNING THIS INSTALLATION: 
- CYGWIN™ MUST BE INSTALLED ON YOUR SYSTEM 
- WINDOWS NT/2000 USERS SHOULD LOG IN AS ADMINISTRATOR 

1. On the GNU Tools page of our web site select either the:  "ARM7T/ARM9T/NetSilicon/Xscale/MX21.Mx31 GNU Toolkit", "PowerPC GnuToolkit", "MIPS32-4Kc/4Ke/Alchemy MIPS64-5kc/TX49", or "i386 GNU Tookit" hypertext, right click the mouse and select "open"
   
2. In the popup dialog select the Open button. This will automatically download and install gnutools-<cpu type>-elf-<version>.exe on your your PC. 
3. Your cywin /usr/local/bin directory will now contain the arm/i386/mips/powerpc Gnu tools : <cpu type>-elf-gcc.exe, <cpu type>-elf-gdb.exe, <cpu type>-elf-ld.exe, ect.  The /usr/local/man directory will now contain man pages for the Gnu tools.
   
4. You should now download and install OcdRemote if you are going to use the GNU tools to debug your target with a Macraigor Wiggler,  Raven, Usb2Demon, UsbWiggler, or Usb2Sprite. This download will also installexample Eclipse/GDB projects to your See the answer to "What is OcdRemote and how do I use it" FAQ for more information on how to download and run OcdRemote.

GO TO TOP

Step-by-step installation instructions for X86 Linux GNU Toolkits 

The Linux based packages are provided as RPM files. You will need the particular rpm package for the processor that you are interested in. This supplies the GNU compilers, assembler, linker,  debugger and source, make, and gdbinit files for several example boards . You will also need to install OcdRemote. This utility runs alongside GDB and serves as a gdb monitor command to the Macraigor API translator. Installing OcdRemote also installes the OCDemon device drivers/libraries. You can then debug your target board via GDB using the Macraigor Systems JTAG OCDemon hardware interconnect devices. All of the compiler rpm packages can be installed together without conflicting.

The GNU processor tools packages are in: 
  mcgr-gnutools-powerpc-<version>.i386.rpm For the PowerPC processor 
  mcgr-gnutools-arm-<version>.i386.rpm For the ARM7T/ARM9T/NetSilicon processors
  mcgr-gnutools-xscale-<version>.i386.rpm For the Intel Xscale processors
  mcgr-gnutools-mips-<version>.i386.rpm For the MIPS32-K4c/4ke-Alchemy processors
  mcgr-gnutools-mips-<version>.i386.rpm For the MIPS64/TX49 processors 

OcdRemote and the Macraigor Drivers are in: 
  mcgr-hwsupport-<version>.i386.rpm
 
The rpm packages can be installed using the rpm command as below. You must run these commands with root privileges. 
  rpm -U mcgr-gnutools-arm-<version>-.i386.rpm 
  rpm -U mcgr-gnutools-powerpc-<version>-.i386.rpm 
  rpm -U mcgr-gnutools-xscale-<version>-.i386.rpm
  rpm -U mcgr-gnutools-mips-<version>-.i386.rpm 
  rpm -U mcgr-hwsupport-<version>-.i386.rpm   

The GNU tools will be installed in the directory /usr/local/bin. This should be added to your PATH environment variable. The cross development tools have the processor name and output format encoded in their name. Thus, the PowerPC GNU debugger GDB will be called powerpc-elf-gdb and the compiler will be named powerpc-elf-gcc. Example applications are placed in /usr/local/macragior/demo/<cpu type>/<target board> directories. The readme.txt file in each directory gives detailed information on how to build and debug the board specific example application using the GNU toolkit.

GO TO TOP

Step-by-step installation instructions for Windows OcdRemote package

To install OcdRemote, the example Eclipse/gdb Projects and the Macraigor drivers on your Windows systems do the following :

1. If you have not already done so, install the Cygwin™ package,  see Step-by-step installation instructions for Cygwin™ under Windows NT/2000/XP for more details on how to do this.
   
2. On the GNU Tools page of our web site select  "Download Windows OcdRemote" or hypertext, right click the mouse and select "open"
   
3. In the popup dialog select the Open button. This will automatically download and install mcgr-hwsupport-<version>.exe
   
4. You will need to reboot your computer after installation completes to install the Macragior Device drivers.

GO TO TOP

What is Cygwin™ and why do I have to install it on my Windows NT/200/XP system before I can install the GNU toolkit? 

The Cygwin™ tools are ports of the popular GNU development tools and utilities for Windows NT/2000/XP. They function through the use of the Cygwin™ library which provides the UNIX system calls and environment that these programs require. As a result, it is possible to easily port many significant UNIX programs without the need for extensive changes to the source code. (for more information on CygwinTM go to Red Hat’s web page www.redhat.com, then search on the keyword "CygwinTM"). 

The GNU tools expect to be running under a "UNIX-like" environment. CygwinTM provides this under Windows through its BASH shell.

GO TO TOP

Where can I get more information about gdb? 

Additional information on Insight is available from the GNU gdb documentation page http://www.gnu.org/software/gdb/documentation.  Gdb Man pages are part of the GNU toolkit install package.  Typing "man <cpu-type>-elf-<utility-name> (for example: "man mips-elf-gdb") in a Cygwin™ Bash window will start the display of that utility's Man pages. Typing "<cpu-type>-elf-gdb --help" in a Bash window displays a brief description of the utility and it's command line options.

GO TO TOP

How do I configure GDB to talk to my target board? 

The gdb "target" command establishes a connection to the remote target to be debugged.

When using Macraigor Interface devices this "target" is the separate executable OcdRemote  or mpDemon OcdRemote typically waiting on the TCP/IP socket <localhost>:8888 for gdb to connect (see "What is OcdRemote and how do I use it").

Your gdb.ini file should contain the line :

# This connects to a OcdRemote executable running on your PC
target remote localhost:8888

This establishes the connection between : 
GDB <-> OcdRemote <-> Wiggler/Raven/UsbDemon/UsbSprite/mpDemon <-> Target

OR the line :

tGO TO TOP

How do I use GDB to set up my target board’s configuration registers? 

The gdb "set" command is used for setting the value of registers. The complete list of known registers can be obtained using the "info reg" command. 

The value of a register can be set with following command: 
  set reg $r1 = 0x44 this will set the r1 register to 44 hex. 

The "reg" portion of the set command is not strictly necessary but is recommended as it adds error checking. With the "reg" flag the register name must be a valid register name or an error is returned. Without the "reg" flag if the name is not recognized as valid register then gdb will create a variable with that name and no error will be flagged.

Macraigor's Ocdremote utility provides a "monitor reg <register-name> [= <value>]" command that differs from gdb's set command in that it immediately writes the value to the cpu rather than waiting until the next time the target is run.  Entering "monitor regnames" will display a list of  the supported target register names.

The setup of a target board’s configuration registers is a good candidate to be included in the gdbinit initialization file. Either "set reg <name> = <value>" or "monitor reg <name> = <value>" commands can be used. See the example Project gdbinit files for more information.

GO TO TOP

Is there example code available? 

Yes.  The OcdRemote download installs example Eclipse/Gdb Projects in the "c:\Program Files\Macraigor Systems\Eclipse Demos\<cpu type>\<target board> directories. There are small example program: source, README, Makefile, ldscript, and gdbinit files that can be built with the supplied tools and downloaded into a specific target board. The examples include a small C program that manipulates some variables and a small assembly source file called crt0.S that contains the actual start code for the target and performs the necessary initialization before the C program "main" function can be called. There are no I/O calls because that would depend on the I/O available in the particular target.
Here is a list of the target boards we provide examples for :

GO TO TOP