6.5. MDI Devices
Prev | Chapter 6. Sourcery G++ Debug Sprite | Next

## 6.5. MDI Devices

The Sourcery G++ Debug Sprite for MIPS supports MDI (Microprocessor Debug Interface) devices. Each MDI device is identified by a target number and device number; these form the `path` part of the device URL, and the `hostname` and `port` must be empty or omitted. Thus, the `device-url` has the form:

    mdi:///targetnum/devicenum[?device-options]

You can also use the environment variables `GDBMDITARGET` and `GDBMDIDEVICE` to provide defaults for the `targetnum` and `devicenum`.

The following `device-options` are permitted:

`lib=`filename``

  This option specifies the MDI library to load. It is equivalent to setting the `GDBMDILIB` environment variable.

`cfg=`filename``

  Some MDI target libraries, such as MIPSsim, require a configuration file. (This is distinct from the Sprite's own `board-file`.) You can use this option to specify the file. It is equivalent to setting the `GDBMIPSSIMCONFIG` environment variable.

`rst=`seconds``

  This option can be used to specify a delay after the target is reset by the Sprite. If the value of `seconds` is greater than zero, then execution is resumed for the specified number of seconds; this can be used to allow power-on firmware to initialize the memory controller and peripherals. Then the target is halted again and queried for configuration.

  If the value of `seconds` is `-1`, then the target is queried immediately without reset. This is the same effect as passing the `-a` command-line option to the Sprite, which allows the Sprite to attach to a running program.

  This option is equivalent to setting the `GDBMDICONNRST` environment variable. If neither the option nor the environment variable are provided, the default is to reset the target and query it immediately unless the `-a` option is specified.

`group=/`targetn`/`devicen``

  This option may be specified multiple times and is cumulative. Each of the specified devices is opened and queried and they are all treated as threads of execution, subject to being enabled or active; if a device is disabled or has no active thread contexts associated with it, it is not visible to GDB but is still under control of the Sprite in case its state changes. This option cannot be used in combination with the `team=` option.

`team=/`targetn`/`devicen``

  This option may be specified multiple times and is cumulative. The specified devices are not opened, but are associated with the base device by means of the MDI team mechanism for the purpose of synchronization. The specified devices may still be opened and controlled by another debugger (such as another instance of the Debug Sprite) independently. This option cannot be used in combination with the `group=` option.

Before you can connect to a target using the MDI API, you must tell the Debug Sprite which shared library or DLL to load for your simulator or device. On Linux hosts you should add the directory containing the shared library files to your `LD_LIBRARY_PATH` environment variable. On Windows hosts, add the directory containing the DLLs to your `PATH` environment variable. Then, either set the environment variable `GDBMDILIB` to the base name of the MDI library before starting the Debug Sprite, or use the `lib=` device option to specify the library to load.

Similarly, the `-i` command-line option can only probe for devices if you have set the `PATH` or `LD_LIBRARY_PATH` environment variable appropriately, and specify an MDI library using either the `GDBMDILIB` environment variable or the `lib=` device option. Otherwise, it reports only the generic `device-url` syntax.

For example, to use an FS2 probe on a Windows host to debug a MIPS Malta board, first add the directory containing the MDI DLLs to your `PATH`. Then you can invoke the Sprite from GDB using a command line similar to:

    (gdb) target remote | mips-sde-elf-sprite \
    'mdi:/2/2?lib=jnetfs2mdilib.dll&rst=7' malta

The quotes are required to prevent special characters in the `device-url` from being interpreted by the shell.

In the above command, the `rst=7` option provides for a sufficient delay for the board's reset code to execute on connection. Since this takes several seconds, GDB may time out waiting for the Sprite to respond. You can prevent this by issuing this command before you connect to the Sprite:

    (gdb) set remotetimeout 10

To use the Sprite with MIPSsim, a configuration file is required. The configuration files provided with the MIPSsim distribution are intended for use with standalone execution from the command line, rather than running the program from the debugger. So, make a copy and comment out the `APP_FILE` setting. It is also recommended that you comment out `TRACE_FILE` as well, since the trace files can be very large.

To connect to MIPSsim using the Sprite on a Linux host, first set your `LD_LIBRARY_PATH` and `GDBMDILIB` as described above. You can run the Sprite from the shell to probe for devices to verify that your setup is correct:

    > mips-sde-elf-sprite -i

Then, from GDB, use a command similar to:

    (gdb) target remote | mips-sde-elf-sprite \
    'mdi:/23/2?cfg=24KE.cfg&rst=-1' mipssim

Fill in your target and device numbers as reported by the probe output, and the full pathname to your configuration file. The `rst=-1` option is required, as MIPSsim does not support reset.

This section describes only the basic MDI usage; refer to the documentation for your MDI simulator or debug device for details specific to that target. Note, in particular, that some MDI targets may require you to set up a license in addition to the steps given here.

Prev | Up | Next
6.4. Sourcery G++ Debug Sprite Options | Home | 6.6. Debugging a Remote Board