xSCOPE config file

An xSCOPE config file is an XML file, with a suffix of .xscope.

It is used for the configuration of xSCOPE, such as to enable printing over xSCOPE, or to configure probes to send data to the host. Config files are the preferred mechanism to configure xSCOPE, however it is also possible to use the xSCOPE target library.

Here is an example:

<xSCOPEconfig ioMode="basic" enabled="true">
  <Probe name="Tile0 Result" type="CONTINUOUS" datatype="UINT" units="mV" enabled="true"/>
  <Probe name="Tile1 i" type="CONTINUOUS" datatype="UINT" units="mV" enabled="true"/>
  <Probe name="Tile1 Accumulation" type="CONTINUOUS" datatype="UINT" units="mV" enabled="true"/>
</xSCOPEconfig>

Here is a more complex example:

<xSCOPEconfig ioDest="link" ioMode="basic" enabled="true">
  <Probe name="Probe 1" type="DISCRETE" datatype="UINT" units="Bytes" enabled="true"/>
  <Probe name="Probe 2" type="DISCRETE" datatype="UINT" units="Bytes" enabled="false"/>
  <Probe name="Really Interesting Probe 3" shortname="PROBE3" type="DISCRETE" datatype="UINT" units="Bytes" enabled="true"/>
  <Module name="Ethernet" id="ETH">
    <Probe name="Packet Count" type="DISCRETE" datatype="UINT" units="Bytes" enabled="true"/>
  </Module>
</xSCOPEconfig>

If compiling and linking separately, the xSCOPE config files must be provided to XCC at every stage, since they are used both to autogenerate definitions at compile time, and provide functionality at link time.

Multiple xSCOPE config files can be provided to xcc, but they must be provided in the same order for every xcc command, and care must be taken: later files can override information specified in earlier files. As good practice, avoid specifying the same probe or module more than once, and only specify the root node’s attributes in a single file.

xscopeconfig element

The xscopeconfig element is required. It specifies the top level configuration for xSCOPE.

Attributes are:

iomode

Configure write syscalls (such as printf or fwrite) to be sent over the much faster xSCOPE transport rather than over JTAG. Can be set to:

Value	Description
none	Use JTAG for write syscalls (slow)
basic	Use xSCOPE for write syscalls.
timed	Use xSCOPE for write syscalls, and prepend each write with a timestamp. Note while this is a useful shortcut to get timestamps while printf debugging, it causes all writes, including writes to files to be prepended with a timestamp. This may not be desirable.

Note that if xSCOPE is configured for io, then xrun --xscope must be specified when using xrun/xgdb or the output will not be shown. It is not possible to attach to an already running program and see the xSCOPE output: it must be freshly loaded for the session with xrun/xgdb.

enabled

May be set to true to enable or false to disable xSCOPE. If a .xscope file is not provided, or this attribute is not specified, then xSCOPE is disabled by default.

probe elements

The probe elements are optional, depending on the desired number of named xSCOPE “probes”. Each probe element represents a single probe channel which can be used to send reports to the host.

Attributes are:

name

Set to a string representing the name of the probe. This can consist of alphanumeric characters, spaces and underscores.

type

May be set to:

Value	Description
STARTSTOP	Event which gets a ‘start’ and a ‘stop’ representing a block of execution (e.g a function call).
CONTINUOUS	A probe which will receive continuous data which can be interpolated.
DISCRETE	A probe which will receive data which should not be interpolated.
STATEMACHINE	Similar to DISCRETE - a probe which represents different states of a state machine, and each report represents moving to a new state.

datatype

May be set to:

Value	Description
NONE	No data. The event will be reported but there is no associated data.
UINT	Unsigned bit integer (1, 2, 4 or 8 bytes)
INT	Signed 32 bit integer (1, 2, 4 or 8 bytes)
FLOAT	Floating point number (4 or 8 bytes)

units

Set to a string representing the units of measurement for the probe

enabled

May be set to true to enable the probe or false to disable it. Defaults to false.

shortname

The name of the define which will be used for the auto-generated define name. See Auto-generated header file for more detail. This defaults to a fully capitalised, underscored version of name. This can consist of alphanumeric characters and underscores, as it becomes a macro name available in the C program.

module

Name of the module to add this probe to, which will affect the name of the define visible in C code. It is preferred to not use this attribute, and instead group module probes together in <Module> elements.

module element

The module element can be used to group several related probes together. Probe elements can be children of the module element.

The auto-generated probe defines will be prefixed with MODULE_ID_ where MODULE_ID is the contents of the id attribute.

name

Set to a string representing the name of the probe.

id

Set to a string to prefix the autogenerated probe define names in the C header. See Auto-generated header file for more detail.

Auto-generated header file

The xSCOPE config file is used to automatically generate some preprocessor definitions for the purpose of referencing the probes from code.

These definitions can be used with the xSCOPE target library.

These preprocessor definitions are accessible by #include <xscope.h>.

The definition name is of the form SHORTNAME or MODULE_ID_SHORTNAME where SHORTNAME is the value of the shortname attribute of the probe element, and MODULE_ID is the contents of the id attribute of the module element if the probe is part of a module.

The probe definition values are equal to the unique ID of the probe, or -1 if the probe is disabled.

To see the autogenerated file, xcc -save-temps can be used. The auto-generated file will be dumped to the current directory as xscope_probes.h.

For example, the earlier example autogenerates the following output:

// This file is autogenerated.
#ifndef __XSCOPE_PROBES_H__
#define __XSCOPE_PROBES_H__
#define PROBE_1 (0)
#define PROBE_2 (-1)
#define PROBE3 (1)
#define ETH_PACKET_COUNT (2)
#endif // __XSCOPE_PROBES_H__