NIOS2 gdb server under Linux

This page describes the minimal setup required to run the NIOS2 gdb server on a Linux host. It is assumed that the USB Blaster is used as the JTAG interface.

Setting up USB Blaster

1. Make sure your kernel has usbfs enabled. Almost all distro's kernels do. If you have a file named /proc/bus/usb/devices, then you should be OK.
2. If you want to run the jtagd daemon as a non-root user, you may need to create a hotplug script that will give normal users write permission to the USB Blaster device file when it is plugged in. On some Linux distros, usb devices belong to a group named usb, and adding a user to the usb group is sufficient to allow that user access to the USB Blaster. If you wish to have the USB Blaster accessible to all users the permissions can be set automatically by by the hotplug subsystem as follows:
   1. Create an executable shell script named /etc/hotplug/usb/usbblaster containing the following

      #!/bin/sh
      # USB-Blaster hotplug script
      # Allow any user to access the cable
      chmod 666 $DEVICE
       

   2. Add the following lines to /etc/hotplug/usb.usermap to tell the hotplug system to run the above script when it detects the USB Blaster

      #
      # Altera USB-Blaster
      #
      usbblaster 0x03 0x09fb 0x6001 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0
      usbblaster 0x03 0x09fb 0x6002 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0
      usbblaster 0x03 0x09fb 0x6003 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0
       

Some Background

The NIOS2 gdb server doesn't talk directory to the USB Blaster cable. The jtagd daemon is the program that actually talks to the USB Blaster. jtagd listens on localhost port 1309 for connections from applications such as nios2-gdb-server-wrapped and jtagconfig. The jtagconfig program isn't actually required, but it's handy for making sure that the USB Blaster cable and target hardware are functioning.

What's important is that jtagd must be running before jtagconfig or nios2-gdb-server-wrapped can be used.

Required Files

The set of files required to run jtagd, jtagconfig, and the gdb-server are shown below

-rwxr-xr-x 1 grante users  29296 Oct 20  2005 jtagconfig
-rwxr-xr-x 1 grante users 340120 Oct 28 22:51 jtagd
-rw-r--r-- 1 grante users  62452 Oct 30 13:52 jtagd.pgm_parts
-rwxr-xr-x 1 grante users  15440 Oct 28 22:51 libccl_ver.so
-rwxr-xr-x 1 grante users 182208 Oct 28 21:55 libjtag_client.so
-rwxr-xr-x 1 grante users 145229 Oct 28 21:55 nios2-gdb-server-wrapped

The file jtagd.pgm_parts needs to be in /etc/jtagd. I leave the rest of the files in a single directory.

A Startup Script

Along with the files listed above, I have a shellscript called gdb-server.sh shown below:

---

#!/bin/bash

test -f ~/.jtag.conf ||
  {
  echo "you don't have a $HOME/.jtag.conf file.  Creating an empty one"
  touch ~/.jtag.conf
  }

for f in jtagd nios2-gdb-server-wrapped jtagconfig libccl_ver.so libjtag_client.so
  do
  test -f $f || { echo "$f must be in this directory"; exit 1; }
  done

test -f /etc/jtagd/jtagd.pgm_parts ||
  {
  echo -"/etc/jtagd/jtagd.pgm_parts file is missing.  Attempting to create one..."
  test -d /etc/jtagd || mkdir --verbose /etc/jtagd
  cp --verbose jtagd.pgm_parts /etc/jtagd
  echo "OK"
  }

(grep -q usbblaster /etc/hotplug/usb.usermap && test -f /etc/hotplug/usb/usbblaster) ||
  {
  echo "missing config in /etc/hotplug/usb.usermap -- please see usbblaster.readme"
  exit 0
  }

export LD_LIBRARY_PATH=$PWD
set -x
./jtagd
./jtagconfig
exec ./nios2-gdb-server-wrapped --tcpport 8888 --tcppersist

---

The shell script above does the following:

• Creates an empty jtag config file in ~/.jtag.conf if no such file exists. This will prevent warnings from the applications. [It would be nice to know what this file is for, but I haven't been able to find any documentation.]
• Verifies that the required executable and library files are present.
• Copys jtagd.pgm_parts to the /etc/jtagd directory if needed.
• Warns the user if the USB Blaster configuration required for non-root use hasn't been set up.
• Starts the jtagd daemon.
• Runs jtagconfig to display a list of devices found attached to the JTAG chain.
• Starts the gdb-server with options to tell it to listen on TCP port 8888 and to remain running and listen for new connections after the initial connection is closed.

When you run the script above, you should see something like this:

---

$ ./gdb-server.sh 
+ ./jtagd
+ ./jtagconfig
1) USB-Blaster [USB 4-1.1]
  020B30DD   EP2C20
  020A10DD   EPM240

+ exec ./nios2-gdb-server-wrapped --tcpport 8888 --tcppersist
Using cable "USB-Blaster [USB 4-1.1]", device 1, instance 0x00
Processor is already paused
Listening on port 8888 for connection from GDB: 

---

You can then start nios2-elf-gdb and connect to the gdb server using the "target remote" command as shown below:

---

$ nios2-elf-gdb
GNU gdb 6.1
Copyright 2004 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.  Type "show warranty" for details.
This GDB was configured as "--host=i686-pc-linux-gnu --target=nios2-elf".
(gdb) target remote localhost:8888
Remote debugging using localhost:8888
0x08000000 in ?? ()
(gdb) 

---

Happy debugging...