Using the ARM Multi-ICE with GDB

Introduction

For some time now, Red Hat has been in possession of a program named the multi-ice-gdb-server, which allows GDB to communicate with the ARM Multi-ICE JTAG emulator.

However a legal issue prevented the software being released. Recently though, ARM were kind enough to release a GPL friendly version of the ARM RDI headers. This has allowed Red Hat to release the sources to the multi-ice-gdb-server.

The server should work with both the 1.x and 2.x versions of the ARM Multi-ICE.

Note: The only supported host is Windows.

Legal status

As explained in great detail in the GNU General Public Licence, this software is supplied without warranty or guarantee of any kind. This software makes use of Dynamically Linked Libraries on Windows, to which the source code is not available. This is a known grey area of the GPL.

Neither Red Hat Inc. nor ARM Ltd. may be held responsible for the obligations that the use of this software puts on you, under the terms of the GNU General Public Licence. It is your responsibility to comply with the terms of the licence.

It is considered likely that under the terms of the GPL it would be a breach of the GPL to distribute this software in binary form. Hence it is provided here on an as-is basis in source form only.

Downloading software for building the multi-ice-gdb-server

To build the multi-ice-gdb-server you must first download and install several pieces of software. Most obviously you must obtain a copy of GDB, and Cygwin on which it depends. At this point you should download and install Cygwin, and download GDB, but not try to install it.

You must also have installed the ARM Multi-ICE server software that came supplied with the Multi-ICE unit.

Next, you should download the RDI 1.5.1 distribution from ARM. The download is available from this page. You should download and install the package in an appropriate location.

Finally, you should download the multi-ice-gdb-server sources.

Preparing to build the multi-ice-gdb-server

Open a Cygwin bash shell window, create a directory to contain the sources and build directory, and change into it, e.g.:

  bash-2.04$ mkdir /tmp/migdb
  bash-2.04$ cd /tmp/migdb

Unarchive the GDB sources, e.g. for GDB 5.1.1, assuming the .tar.gz file had been saved to C:\:

  bash-2.04$ tar -zxvf /cygdrive/c/gdb-5.1.1.tar.gz

Create a GDB multi-ice source directory and unarchive the multi-ice-gdb-server sources, e.g. assuming the multi-ice-gdb-server sources were saved to C:\:

  bash-2.04$ cd gdb-5.1.1/gdb
  bash-2.04$ mkdir multi-ice
  bash-2.04$ cd multi-ice
  bash-2.04$ tar -zxvf /cygdrive/c/multi-ice-gdb.tar.gz

Create a directory for building, and change to it, e.g.:

  bash-2.04$ mkdir /tmp/migdb/build
  bash-2.04$ cd /tmp/migdb/build

Building the multi-ice-gdb-server

First configure the sources, e.g.:

  bash-2.04$ /tmp/migdb/gdb-5.1.1/configure -v --target arm-elf --enable-multi-ice 2>&1 | tee configure.out

If you want to build all of GDB as well, at this point type:

  bash-2.04$ make -w all install 2>&1 | tee make.out

Alternatively to only build the minimum required for the multi-ice-gdb-server, type:

  bash-2.04$ make -w all-libiberty all-bfd 2>&1 | tee make.out

Finally to build the multi-ice-gdb-server itself, change to the multi-ice build directory and type make, supplying the make variables MULTI_ICE_INCLUDES which should point to the location of the ARM RDI 1.5 headers, and MULTI_ICE_LIBS which should point to the location of the ARM Multi-ICE server directory, as well as the location of the GDB multi-ice directory. For example:

  bash-2.04$ cd gdb/multi-ice
  bash-2.04$ make -w MULTI_ICE_INCLUDES="-I/cygdrive/c/Rdi/Headers" \
    MULTI_ICE_LIBS="-L/cygdrive/c/Multi-ICE -L/tmp/migdb/gdb-5.1.1/gdb/multi-ice -ltoolconf" 2>&1 | tee make.out

At this point the build of the multi-ice-gdb-server should be complete. As it needs access to the Multi-ICE.dll file, it is probably easiest to copy it straight alongside the ARM Multi-ICE server software:

  bash-2.04$ cp -i multi-ice-gdb-server.exe /cygdrive/c/Multi-ICE
  bash-2.04$ cp -i /tmp/migdb/gdb-5.1.1/gdb/multi-ice/*.dll /cygdrive/c/Multi-ICE

Running the multi-ice-gdb-server

Connecting to the Multi-ICE server software

1. Start the ARM Multi-ICE server software:

   Start the ARM Multi-ICE server software from the Windows Start menu on the host computer. You will need to set up a Multi-ICE Server configuration file for your hardware. Ensure the board is reset and awakened (if applicable) before trying to make a connection. Use the Multi-ICE server graphical interface to load the configuration file. Once the Multi-ICE server is happy talking to the hardware, the hardware graphic will indicate the processor core model connected to in green.

   Note that certain targets may require jumper modifications, or re-soldered connections. For more details, see the ARM Multi-ICE User Guide.

2. Start the `multi-ice-gdb-server' software

   Open a DOS window or a bash shell and start the multi-ice-gdb-server software on the host computer. If starting a DOS window, ensure the Cygwin DLL is also on your PATH.

   C:\> multi-ice-gdb-server.exe --remote-port 9000 --byte-sex l --config-dialog
   

3. Changing the default MultiICE settings:

   It is probably not necessary to change the settings from the command-line given in step 2. But if your configuration has special requirements, you can configure the connection both to the Multi-ICE Interface Unit and to the remote GDB. The connection to the Multi-ICE Interface Unit can be configured with the ARM Multi-ICE server. The configuration of the remote GDB can be configured by passing arguments to the Multi-ICE GDB server.

   In the command-line given in step 2, the options are interpreted as follows:

   • "--remote-port 9000" specifies the TCP port that GDB clients use to connect to this server. You can use any available port.
   • "--byte-sex l" tells GDB what endian-ness to respond with. Some GDB responses are byte-order (endian-ness) sensitive. The default is to attempt to determine the endianness from the target.
   • "--config-dialog" forces the GDB server to bring up the Multi-ICE configuration dialog when starting. This is required in order to force the Multi-ICE server to connect properly.

   Other available options include:

   • "--debug": setting this turns on GDB protocol tracing - analagous to the GDB command `set remotedebug 1'
   • "--rdi-logging": setting this turns on logging at the RDI level
   • "--target-port <port>": If the target is ID sensitive (the Multi-ICE can actually work with multiple devices simultaneously, each with their own ID), it may be specified with this option.
   • "--stop-others": setting this specifies that a resume stops all the other processors
   • "--help": produces help output.

4. Test the remote connection:

   Run gdb on the development computer by typing the command `arm-elf-gdb <executable>' where `<executable>' is the program to download and debug. Connect to the Multi-ICE GDB server by typing the command: `target remote <hostname:port>', where `<hostname>' is the IP address/hostname of the host computer and `<port>' is the remote port number, 9000 in the above example and 2331 by default. For example, if the host and development computer are the same, type `target remote localhost:9000'. You can then use GDB debugger commands normally.

   NOTE: Only one remote GDB can connect to the GDB Multi-ICE server at the same time. When you quit the remote GDB, or issue the `disconnect' command, the connection to the GDB Multi-ICE server is dropped and the connection is available to another remote GDB. If you attempt to make a second connection while one connection is already established, no error message is generated; the second connection attempt will just time out.

eCos Thread debugging using Multi-ICE

Note: This functionality will not be available until eCos 2.0.

Normally, the Multi-ICE (and the Multi-ICE GDB server) have no knowledge of threads which might be running on the target hardware. In the case of an eCos application, some additional support is provided. If the eCos program has been built with the "CYGHWR_HAL_ARM_ICE_THREAD_SUPPORT" option enabled (found in the eCos Configuration Tool under the ARM architecture-specific flags), then the Multi-ICE GDB server and the eCos application co-operate to provide the thread information.

Note: It is also required that the following options are also enabled:

• CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS
• CYGDBG_HAL_DEBUG_GDB_THREAD_SUPPORT
• CYGDBG_KERNEL_DEBUG_GDB_THREAD_SUPPORT

When an eCos program is built with these options, then the server will call into the program in order to obtain thread information. This can take place at any time and does not require any explicit action on the eCos application side other than being compiled with the appropriate options enabled. The GDB requests are made as anonymous function calls run transparently behind the scenes as far as the running eCos program is concerned.