Flyswatter Windows How To

This guide will walk you through connecting the Flyswatter and the Beagleboard to your Windows PC, and installing and running OpenOCD. This guide was tested with Windows XP and Windows 7. Instructions are identical on 32-bit and 64-bit versions of Windows unless otherwise noted.

 

Connecting the Flyswatter and the Beagleboard

To hook up the Flyswatter and the Beagleboard, you will need:

  • Flyswatter
    • USB Male A/Male B cable
    • 14-pin JTAG Ribbon Cable
  • Beagleboard
    • 5V1A Power Supply
  • Beagleboard Adapter Kit (product link)
    • JTAG Adapter Board
    • RS-232 Adapter Board
    • 10-pin Ribbon Cable

The cables listed under the Flyswatter ship with the Flyswatter.

 

Connect the RS-232 adapter board to the Flyswatter.

Take the RS-232 adapter board provided in the Beagleboard adapter kit, and connect it to the Flyswatter’s serial UART interface.

Flyswatter RS232adapter.png

 

Connect the 10-pin cable to the Flyswatter.

The adapter board above allows you to connect the 10-pin ribbon cable in the Beagleboard adapter kit to the Flyswatter. Do that now. Pay careful attention to the position of the red stripe. The red stripe should line up with the “1” printed on the adapter board, as in the picture below.

Flyswatter RS232cable.png

 

Connect the other end of the cable to the Beagleboard.

Connect the 10-pin RS-232 cable to the pins to the side of the Beagleboard, the ones next to the power adapter. Make sure the cable is correctly centered over the pins, and again pay attention to the red stripe. It should match up with the “1” printed on the Beagleboard.

Both RS232.png

 

Connect the JTAG adapter board to the Flyswatter.

Find the JTAG adapter board included in the Beagleboard adapter kit, and plug it into the Flyswatter’s JTAG interface. The adapter board should hang out over the edge of the Flyswatter.

Flyswatter jtagadapter.png

 

Connect the Flyswatter and the Beagleboard with the JTAG cable.

Find the 14-pin JTAG ribbon cable that comes with the Flyswatter. Connect one end to the JTAG adapter board, and the other end to the diagonal pins on the Beagleboard. Make sure the red stripe lines up with the “1” printed next to the pins on the Beagleboard, like in the picture.

Bothcables.png

 

Connect the USB cable to the Flyswatter.

Find the USB cable that comes with the Flyswatter. Connect the B end (the square end, not the flat end) to the Flyswatter.

Flyswatter usb.png

 

Connect the power supply to the Beagleboard.

Connect the 5V1A power supply to the Beagleboard. (Your power supply may not look exactly like the one pictured.)

Beagle power.png

 

Plug the power cable into a surge protector or wall outlet.

Green LEDs should light up on the Beagleboard to indicate that it is receiving power.

Both beaglelit.png

 

Plug the USB cable into your PC’s USB port.

You should see the green outermost LED on the Flyswatter light up, to indicate that the Flyswatter is receiving power through the USB connection.

Both lit.png

 

Installing OpenOCD

OpenOCD (Open On-Chip Debugger) is open-source software that interfaces with the Flyswatter. OpenOCD provides debugging and in-system programming for embedded target devices. You will need to compile OpenOCD yourself by following one of these guides.

Windows 7

Compiling OpenOCD Win7

Compiling OpenOCD Win7 D2XX

Also use one of these guides for Windows Vista.

Windows XP

Compiling OpenOCD WinXP

Compiling OpenOCD WinXP D2XX
The first set of instructions uses libFTDI, an open-source driver library for FTDI devices. The second set uses FTD2XX, a closed-source driver library from Future Technology Devices International.

 

Running OpenOCD

Now you are ready to run OpenOCD. Open a command line window; if you’re not sure how to do this, see Running OpenOCD on Windows. Navigate to the folder containing openocd.exe (the openocd-bin folder you created in the compile guide) and type:

cd C:\openocd-bin
openocd -f interface/flyswatter.cfg -f board/ti_beagleboard.cfg -c init -c "reset init"

For more information, see Running OpenOCD on Windows. When you start OpenOCD, its output should look like this:

Beagle startup win.png

JTAG-DP_STICKY_ERROR on startup

The -c init -c “reset init” commands in the OpenOCD startup are a workaround for a bug in OpenOCD that affects the Beagleboard and TI Beagleboard XM. If you start OpenOCD without these commands, you will see errors like this:

Beagle startup err win.png

If you see these errors, then the next time you try to start OpenOCD it will give an error the next time it tries to communicate with the Beagleboard. When you exit OpenOCD you will need to disconnect and reconnect the power cable to the Flyswatter before OpenOCD will be able to communicate with the Beagleboard again.

JTAG Tap Unexpected Errors

On startup you may sometimes encounter this error:

Info : JTAG tap: omap3530.jrc tap/device found: 0x000000ff (mfg: 0x07f, part: 0x0000, ver: 0x0)
Warn : JTAG tap: omap3530.jrc       UNEXPECTED: 0x000000ff (mfg: 0x07f, part: 0x0000, ver: 0x0)
Error: JTAG tap: omap3530.jrc  expected 1 of 1: 0x0b7ae02f (mfg: 0x017, part: 0xb7ae, ver: 0x0)

This output means OpenOCD has failed to initialize the JTAG chain. The -c init -c “reset init” commands are a partial workaround for this error. Look for the following line later in the output:

 Info : JTAG tap: omap3530.jrc tap/device found: 0x0b7ae02f (mfg: 0x017, part: 0xb7ae, ver: 0x0)

If you see this line, everything is fine.

Troubleshooting

Getting OpenOCD to initialize JTAG correctly with the Beagleboard is sometimes difficult. If you are having difficulties beyond those described above, consult the troubleshooting page below.

Beagleboard Troubleshooting: JTAG Tap Unexpected

Telnet Connection

You cannot enter commands directly to OpenOCD. Open a new command window and type:

telnet localhost 4444

You will should see this prompt:

Telnet win.png

You can give commands to OpenOCD through this prompt. If you don’t see the prompt on Windows 7, you may need to enable the Telnet client. See Configuring Windows 7 for OpenOCD.

 

Common OpenOCD Commands

To see a full list of OpenOCD commands, enter help in the telnet window.

reset

Resets the Beagleboard. The output of the Reset command should look like this:

Beagle reset win.png

halt

Sends a halt request to the Beagleboard. If the Beagleboard halts, you will see text output in the telnet window. (If the Beagleboard is already halted, you will see no output.)

Beagle halt win.png

halt [timeout]

You can also use halt followed by a time in milliseconds. OpenOCD waits for the target to halt the specified amount of time, then gives up if the target has not halted. You can use this to avoid OpenOCD hanging because the Beagleboard fails to halt. For example, to send a halt command with a timeout of one second, type:

halt 1000

resume

Enter resume to end a halt. You will not see any text output in the telnet window.

reg

Displays a numbered list of all of the Beagleboard’s registers.

Beagle reg win.png

reg [entry]

Run reg with a register number to display the contents of a register, in hexadecimal. The register number corresponds to the output of the reg command with no arguments, above. You must run the halt command before reading registers.

Beagle reg0 win.png

If you run reg while the Beagleboard is not halted, you will still see the value stored in the register. However, registers change contents very quickly while the device is running; by the time you see the value, the value actually in the register may be different. If you try to run reg while the device is not halted, you will see this:

Beagle reg0 nothalted win.png

 

reg [entry] [value]

Sets the value of a register. The register number corresponds to the output of the reg command with no arguments, above. Make sure the Beagleboard is halted (with the halt command) before you change the value of a register!

You can enter registry values in either decimal, by typing a number by itself, or in hexadecimal, by prefacing the value with 0x.

Beagle regset win.png

 

GDB Debugger

GDB, the GNU Project Debugger is a debugging tool provided with the GNU Compiler Collection (GCC). GDB allows you to stop and start a running program, examine its functioning, and make changes. To install and use GDB with OpenOCD, follow the instructions on the Windows GDB Debugger page below.

Windows GDB Debugger

The GDB debugger page will walk you through installing GDB for use with OpenOCD, and loading and testing a simple program.

OpenOCD

OpenOCD (Open On-Chip Debugger) is open-source software that interfaces with the Flyswatter’s JTAG port. OpenOCD provides debugging and in-system programming for embedded target devices. OpenOCD provides the ability to flash NAND and NOR FLASH memory devices that are attached to the processor on the target system. Flash programming is supported for external CFI compatible flashes (Intel and AMD/Spansion command set) and several internal flashes (LPC2000, AT91SAM7, STR7x, STR9x, LM3 and STM32x).

OpenOCD supports the following cores:

CORE TYPE EXAMPLE PROCESSORS
ARM7TDMI LPC2148, AT91SAM7
ARM720T LH79520, EP7312
ARM9TDMI
ARM920T S3C2410, S3C2440
ARM922T
ARM926EJS S3C2412, STN8811, STN8815
ARM966E STR91XF
ARM11 S3C6400, OMAP2420, MSM7200
ARM1136
ARM1156
ARM1176
CORTEX-M3 LM3S series, STM32 series
CORTEX-A8 OMAP3530 BeagleBoard
CORTEX-A8 DM3730 BeagleBoard-xM
CORTEX-A9 OMAP4430 PandaBoard
XSCALE PXA255, PXA270, IXP42X
MARVEL FEROCEON CPU CORE
MIPS M4K

OpenOCD was originally developed by Dominic Rath at the University of Applied Sciences Augsburg. The OpenOCD source code is now available through the GNU General Public License (GPL).

Installing OpenOCD

Compiling OpenOCD

OpenOCD Ubuntu Package

OpenOCD Patches

OpenOCD Config Files

 

Running OpenOCD

Running OpenOCD on Linux

Running OpenOCD on Windows

OpenOCD Troubleshooting

 

External Links

OpenOCD website: http://openocd.sourceforge.net/

OpenOCD source: http://sourceforge.net/projects/openocd/files/openocd/0.7.0/openocd-0.7.0.tar.gz/download

GNU GPL (OpenOCD license): http://www.gnu.org/licenses/gpl.html

Minicom

Minicom is a Linux program you can use to communicate with embedded target devices, either directly via through your computer’s COM port or with the Flyswatter. This guide is written for Flyswatter and the Beagleboard. Configuration is similar for other target boards.

Minicom is available through the Ubuntu Advanced Packaging Tool (APT).

Configuring Minicom

Install minicom using apt-get. Open a terminal window and type:

$ sudo apt-get install minicom

Run minicom setup as root from the host computer:

$ sudo minicom -s

You'll get a screen as follows:

           +-----[configuration]------+                                        
           | Filenames and paths      |                                        
           | File transfer protocols  |                                        
           | Serial port setup        |                                        
           | Modem and dialing        |                                        
           | Screen and keyboard      |                                        
           | Save setup as dfl        |                                        
           | Save setup as..          |                                        
           | Exit                     |                                        
           | Exit from Minicom        |                                        
           +--------------------------+                                        

Select Serial port setup:

   +-----------------------------------------------------------------------+   
   | A -    Serial Device      : /dev/ttyS1                                |   
   | B - Lockfile Location     : /var/lock                                 |   
   | C -   Callin Program      :                                           |   
   | D -  Callout Program      :                                           |   
   | E -    Bps/Par/Bits       : 9600 8N1                                  |   
   | F - Hardware Flow Control : Yes                                       |   
   | G - Software Flow Control : No                                        |   
   |                                                                       |   
   |    Change which setting?                                              |   
   +-----------------------------------------------------------------------+   
           | Screen and keyboard      |                                        
           | Save setup as dfl        |                                        
           | Save setup as..          |                                        
           | Exit                     |                                        
           | Exit from Minicom        |                                        
           +--------------------------+                                        

Now press E to change those settings:

                   +-----------[Comm Parameters]------------+                  
   +---------------|                                        |--------------+   
   | A -    Serial | Current: 115200 8N1                    |              |   
   | B - Lockfile L|                                        |              |   
   | C -   Callin P|   Speed          Parity          Data  |              |   
   | D -  Callout P|                                        |              |   
   | E -    Bps/Par| A: 300           L: None         S: 5  |              |   
   | F - Hardware F| B: 1200          M: Even         T: 6  |              |   
   | G - Software F| C: 2400          N: Odd          U: 7  |              |   
   |               | D: 4800          O: Mark         V: 8  |              |   
   |    Change whic| E: 9600          P: Space              |              |   
   +---------------| F: 19200                      Stopbits |--------------+   
           | Screen| G: 38400                         W: 1  |                  
           | Save s| H: 57600                         X: 2  |                  
           | Save s| I: 115200        Q: 8-N-1              |                  
           | Exit  | J: 230400        R: 7-E-1              |                  
           | Exit f|                                        |                  
           +-------|                                        |                  
                   | Choice, or <Enter> to exit?            |                  
                   +----------------------------------------+                  

You should get 115200 8N1, press keys I, L, V and W. When you’re done, press Enter.

Now in the previous screen, press F to set Hardware Flow Control to Off. You should have this now:

   +-----------------------------------------------------------------------+   
   | A -    Serial Device      : /dev/ttyS1                                |   
   | B - Lockfile Location     : /var/lock                                 |   
   | C -   Callin Program      :                                           |   
   | D -  Callout Program      :                                           |   
   | E -    Bps/Par/Bits       : 115200 8N1                                |   
   | F - Hardware Flow Control : No                                        |   
   | G - Software Flow Control : No                                        |   
   |                                                                       |   
   |    Change which setting?                                              |   
   +-----------------------------------------------------------------------+   
           | Screen and keyboard      |                                        
           | Save setup as dfl        |                                        
           | Save setup as..          |                                        
           | Exit                     |                                        
           | Exit from Minicom        |                                        
           +--------------------------+                   

Now press A to change the serial device, and type /dev/ttyUSB0.

   +-----------------------------------------------------------------------+
   | A -    Serial Device      : /dev/ttyUSB0                              |
   | B - Lockfile Location     : /var/lock                                 |
   | C -   Callin Program      :                                           |
   | D -  Callout Program      :                                           |
   | E -    Bps/Par/Bits       : 115200 8N1                                |
   | F - Hardware Flow Control : No                                        |
   | G - Software Flow Control : No                                        |
   |                                                                       |
   |    Change which setting?                                              |
   +-----------------------------------------------------------------------+
           | Screen and keyboard      |                                  
           | Save setup as dfl        |                                  
           | Save setup as..          |                                  
           | Exit                     |                                  
           +--------------------------+                                                 
                                                                               

Press Enter to leave this screen, select Save setup as dfl and finally select Exit from Minicom.

Connecting to the Beagleboard with Minicom

Connect the Flyswatter and the Beagleboard and connect the Beagleboard to your computer’s USB port, as described in the Flyswatter How To. Then run minicom as root:

$ sudo minicom

You should get the following screen:

Welcome to minicom 2.2

OPTIONS:                                                                     
Compiled on Sep  8 2008, 17:03:34.                                           
Port /dev/ttyUSB1                                                              
                                                                            
              Press CTRL-A Z for help on special keys                       
                                                                            
                                                                            
                                                                            
Texas Instruments X-Loader 1.41                                              
Starting OS Bootloader...                                                    
                                        
U-Boot 1.3.3 (Jul 10 2008 - 16:33:09)   
                                        
OMAP3530-GP rev 2, CPU-OPP2 L3-165MHz   
OMAP3 Beagle Board + LPDDR/NAND         
DRAM:  128 MB                           
NAND:  256 MiB
In:    serial
Out:   serial
Err:   serial
Audio Tone on Speakers  ... complete
OMAP3 beagleboard.org # 

If you don’t, check the serial port. You’ll have to go back to the config (minicom -s) and get to this screen:

   +-----------------------------------------------------------------------+   
   | A -    Serial Device      : /dev/ttyUSB0                              |   
   | B - Lockfile Location     : /var/lock                                 |   
   | C -   Callin Program      :                                           |   
   | D -  Callout Program      :                                           |   
   | E -    Bps/Par/Bits       : 115200 8N1                                |   
   | F - Hardware Flow Control : No                                        |   
   | G - Software Flow Control : No                                        |   
   |                                                                       |   
   |    Change which setting?                                              |   
   +-----------------------------------------------------------------------+   
           | Screen and keyboard      |                                        
           | Save setup as dfl        |                                        
           | Save setup as..          |                                        
           | Exit                     |                                        
           | Exit from Minicom        |                                        
           +--------------------------+     

Now press A and change /dev/ttyUSB0 for /dev/ttyUSB1, save as dfl, and restart minicom.

If you still don’t get the beagleboard shell, try using other serial terminal program like GtkTerm.

Now we got the beagleboard shell! Congratulations!

First command we wanna try is “help”:

OMAP3 beagleboard.org # help

If you get some output, you’re happy!

If at some point you cannot enter text any more, verify that you have turned off flow control (F and G should be set to No). Also if after a reboot you do not see anything exit (ctrl-A q) and restart minicom.

Flyswatter How To

This guide is for Ubuntu 10.04. For the Windows guide, see Flyswatter Windows How To.

This guide will walk you through connecting the Flyswatter and the Beagleboard to your Linux PC, and installing and running OpenOCD. This guide was written with Ubuntu 10.04.

 

Connecting the Flyswatter and the Beagleboard

To hook up the Flyswatter and the Beagleboard, you will need:

  • Flyswatter
    • USB Male A/Male B cable
    • 14-pin JTAG Ribbon Cable
  • Beagleboard
    • 5V1A Power Supply
  • Beagleboard Adapter Kit (product link)
    • JTAG Adapter Board
    • RS-232 Adapter Board
    • 10-pin Ribbon Cable

The cables listed under the Flyswatter ship with the Flyswatter.

 

Connect the RS-232 adapter board to the Flyswatter.

Take the RS-232 adapter board provided in the Beagleboard adapter kit, and connect it to the Flyswatter’s serial UART interface.

Flyswatter RS232adapter.png

 

Connect the 10-pin cable to the Flyswatter.

The adapter board above allows you to connect the 10-pin ribbon cable in the Beagleboard adapter kit to the Flyswatter. Do that now. Pay careful attention to the position of the red stripe. The red stripe should line up with the “1” printed on the adapter board, as in the picture below.

Flyswatter RS232cable.png

 

Connect the other end of the cable to the Beagleboard.

Connect the 10-pin RS-232 cable to the pins to the side of the Beagleboard, the ones next to the power adapter. Make sure the cable is correctly centered over the pins, and again pay attention to the red stripe. It should match up with the “1” printed on the Beagleboard.

Both RS232.png

 

Connect the JTAG adapter board to the Flyswatter.

Find the JTAG adapter board included in the Beagleboard adapter kit, and plug it into the Flyswatter’s JTAG interface. The adapter board should hang out over the edge of the Flyswatter.

Flyswatter jtagadapter.png

 

Connect the Flyswatter and the Beagleboard with the JTAG cable.

Find the 14-pin JTAG ribbon cable that comes with the Flyswatter. Connect one end to the JTAG adapter board, and the other end to the diagonal pins on the Beagleboard. Make sure the red stripe lines up with the “1” printed next to the pins on the Beagleboard, like in the picture.

Bothcables.png

 

Connect the USB cable to the Flyswatter.

Find the USB cable that comes with the Flyswatter. Connect the B end (the square end, not the flat end) to the Flyswatter.

Flyswatter usb.png

 

Connect the power supply to the Beagleboard.

Connect the 5V1A power supply to the Beagleboard. (Your power supply may not look exactly like the one pictured.)

Beagle power.png

 

Plug the power cable into a surge protector or wall outlet.

Green LEDs should light up on the Beagleboard to indicate that it is receiving power.

Both beaglelit.png

 

Plug the USB cable into your PC’s USB port.

You should see the green outermost LED on the Flyswatter light up, to indicate that the Flyswatter is receiving power through the USB connection.

Both lit.png

 

Installing OpenOCD

OpenOCD (Open On-Chip Debugger) is open-source software that interfaces with the Flyswatter. OpenOCD provides debugging and in-system programming for embedded target devices. You will need to install OpenOCD, either from Ubuntu’s packaging tool or by compiling it yourself.

The easiest way to get OpenOCD is to install it with apt-get. To install OpenOCD with apt-get, follow these instructions:
OpenOCD Ubuntu Package
To compile OpenOCD yourself, follow one of these guides:
Compiling OpenOCD Linux

Compiling OpenOCD Linux D2XX
The first set of instructions uses libFTDI, an open-source driver library for FTDI devices. The second set uses FTD2XX, a closed-source driver library from Future Technology Devices International.

 

Running OpenOCD

Now you are ready to run OpenOCD. If you installed the OpenOCD Ubuntu package, open a terminal window and type the following from any directory:

openocd -f interface/flyswatter.cfg -f board/ti_beagleboard.cfg -c init -c "reset init"

If you compiled OpenOCD yourself, navigate to the openocd-bin directory you created in the compile guide and type:

cd ~/openocd-bin
sudo ./openocd -f interface/flyswatter.cfg -f board/ti_beagleboard.cfg -c init -c "reset init"

For more information, see Running OpenOCD on Linux. When you start OpenOCD, its output should look like this:

Beagle startup.png

JTAG-DP_STICKY_ERROR on startup

The -c init -c “reset init” commands in the OpenOCD startup are a workaround for a bug in OpenOCD that affects the Beagleboard and TI Beagleboard XM. If you start OpenOCD without these commands, you will see errors like this:

Beagle startup err.png

If you see these errors, then the next time you try to start OpenOCD it will give an error the next time it tries to communicate with the Beagleboard. When you exit OpenOCD you will need to disconnect and reconnect the power cable to the Flyswatter before OpenOCD will be able to communicate with the Beagleboard again.

JTAG Tap Unexpected Errors

On startup you may sometimes encounter this error:

Info : JTAG tap: omap3530.jrc tap/device found: 0x000000ff (mfg: 0x07f, part: 0x0000, ver: 0x0)
Warn : JTAG tap: omap3530.jrc       UNEXPECTED: 0x000000ff (mfg: 0x07f, part: 0x0000, ver: 0x0)
Error: JTAG tap: omap3530.jrc  expected 1 of 1: 0x0b7ae02f (mfg: 0x017, part: 0xb7ae, ver: 0x0)

This output means OpenOCD has failed to initialize the JTAG chain. The -c init -c “reset init” commands are a partial workaround for this error. Look for the following line later in the output:

 Info : JTAG tap: omap3530.jrc tap/device found: 0x0b7ae02f (mfg: 0x017, part: 0xb7ae, ver: 0x0)

If you see this line, everything is fine.

Troubleshooting

Getting OpenOCD to initialize JTAG correctly with the Beagleboard is sometimes difficult. If you are having difficulties beyond those described above, consult the troubleshooting page below.

Beagleboard Troubleshooting: JTAG Tap Unexpected

Telnet Connection

You cannot enter commands directly to OpenOCD. Open a new terminal window and type:

telnet localhost 4444

You will should see this prompt:

Telnet.png

You can give commands to OpenOCD through this prompt.

 

Common OpenOCD Commands

To see a full list of OpenOCD commands, enter help in the telnet window.

reset

Resets the Beagleboard. The output of the Reset command should look like this:

Reset.png

halt

Sends a halt request to the Beagleboard. If the Beagleboard halts, you will see text output in the telnet window. (If the Beagleboard is already halted, you will see no output.)

Halt.png

halt [timeout]

You can also use halt followed by a time in milliseconds. OpenOCD waits for the target to halt the specified amount of time, then gives up if the target has not halted. You can use this to avoid OpenOCD hanging because the Beagleboard fails to halt. For example, to send a halt command with a timeout of one second, type:

halt 1000

resume

Enter resume to end a halt. You will not see any text output in the telnet window.

reg

Displays a numbered list of all of the Beagleboard’s registers.

Reg.png

reg [entry]

Run reg with a register number to display the contents of a register, in hexadecimal. The register number corresponds to the output of the reg command with no arguments, above. You must run the halt command before reading registers.

Reg0.png

If you run reg while the Beagleboard is not halted, you will still see the value stored in the register. However, registers change contents very quickly while the device is running; by the time you see the value, the value actually in the register may be different. If you try to run reg while the device is not halted, you will see this:

Reg0 not halted.png

 

reg [entry] [value]

Sets the value of a register. The register number corresponds to the output of the reg command with no arguments, above. Make sure the Beagleboard is halted (with the halt command) before you change the value of a register!

You can enter registry values in either decimal, by typing a number by itself, or in hexadecimal, by prefacing the value with 0x.

Regset.png

 

GDB Debugger

GDB, the GNU Project Debugger is a debugging tool provided with the GNU Compiler Collection (GCC). GDB allows you to stop and start a running program, examine its functioning, and make changes. GDB is installed on Ubuntu 10.04 by default, but you will need a different version of GDB build for embedded targets. Follow the instructions on the GDB Debugger page below.

GDB Debugger

The GDB debugger page will walk you through installing GDB for use with OpenOCD, and loading and testing a simple program.

GDB Debugger

This guide was written for Ubuntu 10.04. For the windows page, see Windows GDB Debugger.

GDB, the GNU Project Debugger is a debugging tool provided with the GNU Compiler Collection (GCC). GDB allows you to stop and start a running program, examine its functioning, and make changes.

 

GDB Support in OpenOCD

The configure script provided with OpenOCD 0.5.0 already compiles OpenOCD to support the GDB debugger. The OpenOCD Ubuntu Package also includes GDB Support. If you have installed OpenOCD according to the guides on the Compiling OpenOCD page, your version of OpenOCD already supports GDB.

The -g flag tells the gcc compiler to build with GDB support. OpenOCD’s configure script already includes the -g flag.

GDB Debugger is provided by default on Ubuntu 10.04. However, this version of GDB is only built to debug programs running on a Linux PC. You will need to download or compile a version of GDB that supports embedded devices. One such GDB build is provided with the CodeSourcery ARM toolchain.

 

Installing the CodeSourcery ARM Toolchain

CodeSourcery provides development tools for use with embedded devices, including a GCC cross-compiler and a GDB build for ARM targets. Download the latest version of the .bin installer from http://www.codesourcery.com/sgpp/lite/arm/portal/release1592. Direct link is here. Save this file anywhere on your computer, then navigate to it in a terminal window.

Run the installer like this:

sh arm-2010.09-51-arm-none-eabi.bin

You should see a loading bar followed by an installer GUI. However, you may see an error stating that the installer doesn’t support the DASH shell.

Arm-none-eabi dash err.png

If you see this error, disable DASH by typing

sudo dpkg-reconfigure -plow dash

This will give you the option to enable DASH by choosing <YES> or disable it by choosing <NO>. Choose no and run the installer again.

 sh arm-2010.09-51-arm-none-eabi.bin

You should see the installer GUI now. The installer is fairly straightforward. This guide will assume that you choose the default option on each page.

Sourcery-install.png

The installer installs the CodeSourcery toolchain to your home directory. Add it to your PATH by editing your environment variables:

sudo cp /etc/environment /etc/backup_environment
sudo gedit /etc/environment

This backs up your environment file and then opens it a text editor. (The backup is just in case something goes wrong; unless you make a mistake, you can delete backup_environment later.) Find the line “Path=…” (probably the only line). Add the following to the end of that line, inside the quotes:

:~/CodeSourcery/Sourcery_G++_Lite/bin

That line should now read something like this:

PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:~/CodeSourcery/Sourcery_G++_Lite/bin"

Restart your computer.

Make sure everything installed correctly by running arm-none-eabi-gcc from anyhere, with no arguments. If everything installed correctly, you will see:

arm-none-eabi-gcc: no input files

 

Starting GDB

In the terminal window, run arm-none-eabi-gdb from any directory.

arm-none-eabi-gdb

Your terminal window should look like the image below, with a prompt reading (gdb) in place of the normal > command prompt.

Eabi-gdb startup.png

 

Connecting to OpenOCD

Run OpenOCD as normal, as described in Running OpenOCD on Linux. To connect to OpenOCD, start GDB as above:

arm-none-eabi-gdb

OpenOCD listens for GDB connections on port 3333. In GDB, connect to OpenOCD by typing target remote localhost:3333. (In this guide if you see (gdb) at the beginning of a command, that means enter that line into the GDB command prompt. Don’t actually type the characters (gdb).)

(gdb) target remote localhost:3333

Before doing anything else, run reset init on the target. Use the monitor command to tell GDB to send the command to OpenOCD, like this:

(gdb) monitor reset init

Monitor reset init.png

This is important. You need to do this while GDB is connected to the OpenOCD, or you won’t be able to halt or reset the target. If you don’t run monitor reset init, you will encounter errors like this:

Gdb packet err.png

 

Sending Commands to OpenOCD

You can send commands to OpenOCD through GDB just like you can through a telnet connection. Type monitor, then the command, then enter. You can see a list of common OpenOCD commands here.

Gdb openocd commands.png

You can use the Linux command cd to change the current working directory in GDB. This changes the current directory only for GDB, not for Linux; when you exit GDB, you will be back in the directory where you started.

To quit GDB, type quit.

 

.gdbinit

Instead of typing commands yourself every time you start GDB, you can create a script to always start GDB with the same series of commands. This script file is named .gdbinit. GDB looks for it in the current working directory.

You can use the script below to have GDB automatically connect to OpenOCD and run reset init on the target. Create a new folder in your home directory called GDB_OpenOCD_init, and a new text file in that folder. Copy the code below into the file:

echo Executing GDB with .gdbinit to connect to OpenOCD.\n
echo .gdbinit is a hidden file. Press Ctrl-H in the current working directory to see it.\n
# Connect to OpenOCD
target remote localhost:3333
# Reset the target and call its init script
monitor reset init
# Halt the target. The init script should halt the target, but just in case
monitor halt

Save the file as .gdbinit and close it. Like any file whose name begins with a period, .gdbinit is a hidden file. To see it, open the folder and press CTRL-H.

To test the init script, start OpenOCD as normal. Then navigate to GDB_OpenOCD_init/ and run CodeSourcery GDB.

cd ~/GDB_OpenOCD_init
arm-none-eabi-gdb

You should see something like the image below. (In this image the target device is the Beagleboard. With different hardware the output of reset init will be different.)

Gdbinit.png

 

Debugging a Program on the Beagleboard

This part of the guide will demonstrate how to run and debug a simple program on the Beagleboard. The program will only work on the Beagleboard, but the commands are the same on other target devices.

 

Installing Packages

For this section you will need the Ubuntu packages git and make. Install the following packages by opening a new terminal window and typing:

sudo apt-get install git make

You may see a message stating that these pachages are already installed. That’s fine.

 

Compiling LEDblink

Navigate to your home directory and use git to clone into https://github.com/mlu/cortal_dendrites.git.

cd ~
git clone https://github.com/mlu/cortal_dendrites.git

You should now have a folder in your home directory called cortal_dendrites/. Navigate to /home/USERNAME/cortal_dendrites/cortex_a8/standalone/LEDblink. This directory contains the source for LEDblink. Run make to compile it.

cd ~/cortal_dendrites/cortex_a8/standalone/LEDblink
make

The folder should now contain a binary file called LEDblink. It also contains a hidden file called .gdbinit. This script should start GDB and load LEDblink, but the file is outdated and no longer works. Delete it so that you can’t accidentally run it later.

rm .gdbinit

 

Loading LEDblink

Start OpenOCD as normal, then open a new terminal window. Run GDB, connect it to OpenOCD, and reset the Beagleboard. You can do this manually:

arm-none-eabi-gdb
(gdb) target remote localhost:3333
(gdb) monitor reset init

…or using the .gdbinit script you created above:

cd ~/GDB_OpenOCD_init
arm-none-eabi-gdb

Beagle usrleds.png

The USR0 and USR1 LEDs on the Beagleboard should now be off. The Beagleboard has just been reset and is halted. Tell the Beagleboard to resume to let it boot. You should see USR0 and USR1 come on.

(gdb) monitor resume

Wait for the lights to come on, and then halt the Beagleboard again.

(gdb) monitor halt

Navigate to the directory containing LEDblink and load it:

(gdb) cd ~/cortal_dendrites/cortex_a8/standalone/LEDblink
(gdb) load LEDblink
(gdb) symbol-file LEDblink

Ledblink load.png

Now run the program by typing:

(gdb) cont

You should see the USR0 and USR1 LEDs pulse on and off in sequence. LEDblink will run forever if you let it. When you’re ready to stop it, press CTRL-C in the GDB terminal. To start it again, type cont again.

 

Breakpoints

When debugging a program it’s often useful to stop it in the middle to see what it’s doing. You can do that with GDB using breakpoints. When you ran the command symbol-file LEDblink above, you loaded a file that allows GDB to map lines and functions in the source code to instructions in the executable. You can now instruct GDB to stop the program when it reaches a particular line or function.

Add a breakpoint associated with line 22 of LEDblink.c, then let LEDblink continue, like this:

(gdb) break 22
(gdb) cont

GDB will run until it hits line 22, then return you to the command prompt. Line 22 is inside a loop that never terminates, so GDB will hit this breakpoint over and over. Each time GDB hits the breakpoint, you can tell it to proceed by typing cont again.

You can have multiple breakpoints at a time. Type:

(gdb) break 30

…to create a second breakpoint at line 30. You can get a list of all breakpoints by typing:

(gdb) info breakpoints

info breakpoints lists your breakpoints by number. You can delete a breakpoint by entering delete followed by a number.

(gdb) delete 1

…deletes Breakpoint 1.

Ledblink breakpoints.png

 

Reading Memory

You can use GDB to read the value stored in a memory address with the x command. Type x followed by a memory address to output the value at that address. GDB assumes that the address is in decimal format unless you preface it with 0x to indicate hexadecimal. Memory addresses are usually expressed in hexadecimal, so remember to type 0x.

(gdb) x 0x49056090

Gdb x.png

The values at 0x49056090 and 0x49056094 control the USR0 and USR1 LEDs. The 22nd bit of each (0x00400000, in hex) controls USR0, and the 21st bit (0x00200000) controls USR1. Writing to 0x49056090 turns a light off, and writing to 0x49056094 turns a light on.
address 0x49056090 = 0x00400000: turn USR0 off

address 0x49056090 = 0x00200000: turn USR1 off

address 0x49056090 = 0x00600000: turn both LEDs off
address 0x49056094 = 0x00400000: turn USR0 on

address 0x49056094 = 0x00200000: turn USR1 on

address 0x49056094 = 0x00600000: turn both LEDs on
You can type x 0x49056090 and x 0x49056094 when LEDblink reaches a breakpoint to see what the program is doing.

 

External Links

GDB man page

Flyswatter

The Flyswatter is a low cost JTAG programmer / debugger for use with ARM (ARM JTAG) and MIPS (MIPS JTAG) cpu cores.

It uses the open source OpenOCD (Open On-Chip Debugger) software to provide debugging and in-system programming of embedded target devices.

Features:

  • USB 2.0 Full Speed device interface (12 Mbits/sec)
  • Can be used to debug and program all ARM and MIPS processors supported by OpenOCD
  • Provides a standard ARM 14-pin (2 x 7)JTAG interface
  • Adds a virtual RS232 serial port to your computer or laptop with full modem signals: TXD, RXD, RTS, CTS, DTR, DSR, DCD, RI
  • Supports target voltages of: 3.3V, 2.5V, 1.8V, 1.5V, 1.2V (voltage range: 1.2V to 3.6V)
  • No external power supply required – the Flyswatter gets its power from the computer’s USB port
  • Open hardware – complete schematic provided
  • Open software – software supported by OpenOCD (open source) debugger
  • Package Includes: Flyswatter board, USB Cable and 8 inch 14-pin JTAG ribbon cable
  • Dimensions: 2.5 inches (width) x 3.0 inches (height)

Supported Devices

OpenOCD supports the following ARM cores:

ARM CORE EXAMPLE PROCESSORS
ARM7TDMI LPC2148, AT91SAM7
ARM720T LH79520, EP7312
ARM9TDMI
ARM920T S3C2410, S3C2440
ARM922T
ARM926EJS S3C2412, STN8811, STN8815
ARM966E STR91XF
ARM11 S3C6400, OMAP2420, MSM7200
ARM1136
ARM1156
ARM1176
CORTEX-M3 LM3S series, STM32 series
CORTEX-A8 OMAP3530 BeagleBoard
CORTEX-A8 DM3730 BeagleBoard-xM
CORTEX-A9 OMAP4430 PandaBoard
XSCALE PXA255, PXA270, IXP42X
MARVEL FEROCEON CPU CORE

OpenOCD also supports the following MIPS cores (requires a MIPS 14-Pin JTAG Adapter):

MIPS CORE EXAMPLE PROCESSORS
MIPS M4K

JTAG Adapters

JTAG Adapters plug into the ARM 14-pin connector located on the Flyswatter and change the pin-out to a different JTAG interface. Three JTAG adapters are available for the Flyswatter:

 

ARM 20 pin JTAG Adapter

ARM 20-Pin JTAG Adapter – This adapter converts the Flyswatter’s JTAG interface into a standard ARM 20-pin configuration. The package also includes 14-pin ribbon cable.

 

BeagleBoard JTAG Adapter

BeagleBoard JTAG Adapter – This adapter converts the Flyswatter’s JTAG interface into a standard TI 14-pin JTAG configuration. The package also includes a serial adapter board that converts the DB-9 Male connector located on the Flyswatter to a 10-Pin ribbon cable. This ribbon cable is used on the BeagleBoard Rev B/C boards to interface to the serial port. The 10-pin ribbon cable is included in the package.

 

MIPS 14-Pin JTAG Adapter

MIPS 14-Pin JTAG Adapter – This adapter converts the Flyswatter’s JTAG interface into a standard MIPS 14-pin JTAG configuration. The package also includes 14-pin ribbon cable.

 

Serial Port

The Flyswatter’s serial port provides you with an independent functional “USB to RS-232” serial device. The serial port is completely independent from OpenOCD on both Linux and Windows. You can use the Flyswatter’s serial port and never have to use OpenOCD or JTAG, or you can use it together with OpenOCD and have both a serial port and JTAG interface operating at the same time for debugging your target device.

For Linux, the RS232 driver for the FT2232 is part of the main kernel tree and is provided in most standard Linux distributions. In Windows, you have to load the Windows driver for the FT2232. Once the driver is loaded, Windows will assign a virtual COM port to the Flyswatter’s serial port. It operates just like a standard COM port. You can use the Flyswatter’s serial port on laptops or PC’s that do not have a 9-pin legacy serial connector.

Serial Port Interface

You can use Minicom to communicate with the Flyswatter’s serial port on Linux. See the Minicom page for setup instructions.

Documents

Documents:

Flyswatter How To

The Flyswatter How To and Flyswatter Windows How To guides show a new user how to connect the Flyswatter to the Beagleboard, and how to install and run OpenOCD and GDB Debugger. To reach the guide, follow the link in the section title.