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.