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.