# Multi-processor EmbeddedICETM Interface Unit

The GNUPro Toolkit supports communication using GDB to ARM target platforms that can support for Multi-processor EmbeddedICETM Interface Unit (In Circuit Emulator).

## Background

ARM provides a device knows as the Multi-processor EmbeddedICE Interface Unit (hereafter referred to as the Multi-ICE) which allows debugging at the hardware level. Support for this device is provided via the Multi-ICE Server, a Windows application which is provided by ARM on CD-ROM with the Multi-ICE package. The Multi-ICE Server handles the hardware interface, and responds to commands sent to it via an ARM supplied Windows DLL.

The GDB Multi-ICE server is an application which runs on Windows under CygWin. When connected to by a standard ARM GDB client, this program behaves just like an ARM target board running GDB remote stubs. As GDB requests come in, they are translated into corresponding functions and passed on to the Multi-ICE Server, which in turn passes them on to the actual hardware.

## Installation

The Multi-ICE unit must be connected to a computer running the Windows NT operating system.

### Installation of hardware

For complete hardware installation instructions refer to the ARM Multi-ICE User Guideprovided in the '`docs`' subdirectory of the CD-ROM supplied with the ARM Multi-ICE package.

### Installation of software

1. Install the software that came with the Multi-ICE onto the computer that it is attached to. From now on we will refer to this computer as the host computer.
2. Install the GNUPro Toolkit on the host computer.
3. Install the GNUPro Toolkit on the computer you intend to use for development. This can be the same as the computer attached to the Multi-ICE Interface Unit, but need not be.

Note: Certain targets may require jumper modifications, or re-soldered connections. For more detail, see the ARM Multi-ICE User Guide and/or target hardware documentation.

### 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. Please read the Getting Started with eCos manual for configuration file examples for supported target platforms. 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. Later, when a connection is established between the GDB Multi-ICE server and the hardware (ARM supplied) Multi-ICE server, the processor graphic will turn red.
2. Start the GNUPro '`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 user tools are also on your PATH. You will see output similar to the following:

C:\> multi-ice-gdb-server.exe --remote-port 9000 --byte-sex l --config-dialog
Connected to the Multi-Ice target.
Targeted ARM core: ARM7 0
Target characteristics:
Hardware?: YES
Comms Channel?: YES
Endian-ness: LITTLE
Single-Step Support: NO
Load Size: 32768
Custom Load?: NO
No other modules found on debug target.
GDB Server starting on port 9000

3. Changing the default Multi-ICE settings:
It is probably not necessary to change the settings from the command-line given in step 2. However, 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 to respond with Little-Endian. Some GDB responses are byte-order (endian-ness) sensitive. The default here is Big Endian, but since eCos typically runs the hardware in Little Endian mode, this needs to be specified explicitly.

>   `--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 the following output:

C:\> multi-ice-gdb-server --help
--byte-sex {b,l} - Specify the byte-sex of the target on restart.
--config-dialog - Post configuration dialog for Multi-ICE DLL.
--debug - Turn on debugging of remote protocol requests.
--help - Print out this help message.
--rdi-logging - Turn on RDI logging.
--remote-port port - Specify the port to listen for remote connections.
--stop-others - Execution of target stops other modules.
--target-port port - Specify the port to which the target is attached.

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..

(gdb) target remote localhost:2331
Remote debugging using localhost:2331
0x0 in ?? ()
(gdb)

Note: Only one remote GDB can connect to the Multi-ICE server at the same time. When you quit the remote GDB, or issue the '`disconnect`' command, the connection to the 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.

Caution: Some targets do not respond well to the Multi-ICE JTAG reset request. For these targets, use of a physical reset (button, power-off, etc.) may be required.

Furthermore it is recommended that the GDB Multi-ICE server be restarted if the hardware needs to be reset.

## eCos thread debugging using Multi-ICE

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.

## Rebuilding the GDB Multi-ICE Server

The GDB Multi-ICE server is built using Cygwin. The sources for the server itself can be found in the 'src/gdb/multi-ice' subdirectory of the GNUPro tools installation directory. Note that these sources are not installed by default - ensure you enable the appropriate option in the installer when installing the build tools.

Ensure the following files are present in a directory, for example, '`/multi-ice`':

Multi-ICE.def | host.h | rdi_cp.h | toolconf.def
Multi-ICE.dll | rdi_err.h | toolconf.dll | rdi.h
rdi_hif.h | toolconf.h | armtypes.h | rdi100.h
rdi_info.h | toolconf.lib | c150t100.h | rdi150.h
rdi_rdp.h | winrdi.h | findfile.h | rdi_conf.h
rdi_stat.h |  |  |

Assuming the sources to GDB are installed in '`/src/gdb`', and you have made an empty directory to build in called /build:

1. Start a Cygwin bash shell
2. Run the following commands:

> `bash$ cd /build`
> `bash$ /src/gdb/configure --target=arm-elf`
> `bash$ cd multi-ice`
> `bash$ make MULTI_ICE_INCLUDES="-I/multi-ice" MULTI_ICE_LIBS="-L/multi-ice -ltoolconf"`

3. You will now have a multi-ice-gdb-server.exe executable. To be able to run it you will need to ensure it is installed in the same directory as Multi-ICE.dll and toolconf.dll. For example:

> bash$ mkdir /gdbmulti
> bash$ cp multi-ice-gdb-server.exe /multi-ice/Multi-ICE.dll \
> /multi-ice/toolconf.dll /gdbmulti

Remember to check that the cygwin user tools are on your path before running the GDB Multi-ICE server.