xSCOPE target library#

The xSCOPE target library is used for communication between the host and the target over the fast xSCOPE transport. It can be used for data logging and targeted profiling.

The xSCOPE target library is automatically linked if your application is built with xSCOPE (see xcc options), so just include the header:

#include <xscope.h>

Including this also makes the probes which were specified in the xSCOPE config file available to the program.

This library is not accessible if a program is not built with xSCOPE support.

Example#

This file contains functions to access xSCOPE. Example:

#include <platform.h>
#include <xscope.h>
#include <xccompat.h>

void xscope_user_init(void) {
  xscope_register(1, XSCOPE_CONTINUOUS, "Continuous Value 1", XSCOPE_UINT, "Value");
}

int main (void) {
  par {
    on tile[0]: {
      for (int i = 0; i < 100; i++) {
        xscope_int(0, i*i);
      }
    }
  }
  return 0;
}

This example defines a probe “Continuous Value 1”, then sends 100 numbers as records over that probe.

Configuration API#

The configuration API is an alternative mechanism of configuring xSCOPE to xSCOPE config file.

For most purposes, the xSCOPE config file should be preferred over using this, as it is a richer, less error-prone mechanism. They can also be used in combination, such as defining the probes with a config file, but using this interface for the more advanced functionality.

Enums

enum xscope_EventType#

Kind of event that an xSCOPE probe can receive.

Values:

enumerator XSCOPE_STARTSTOP#: Start/Stop - Event gets a start and stop value representing a block of execution.

enumerator XSCOPE_CONTINUOUS#: Continuous - Only gets an event start, single timestamped “ping”.

enumerator XSCOPE_DISCRETE#: Discrete - Event generates a discrete block following on from the previous event.

enumerator XSCOPE_STATEMACHINE#: State Machine - Create a new event state for every new data value.

enumerator XSCOPE_HISTOGRAM#

enumerator XSCOPE_STARTSTOP: Start/Stop - Event gets a start and stop value representing a block of execution.

enumerator XSCOPE_CONTINUOUS: Continuous - Only gets an event start, single timestamped “ping”.

enumerator XSCOPE_DISCRETE: Discrete - Event generates a discrete block following on from the previous event.

enumerator XSCOPE_STATEMACHINE: State Machine - Create a new event state for every new data value.

enumerator XSCOPE_HISTOGRAM

enumerator XSCOPE_STARTSTOP: Start/Stop - Event gets a start and stop value representing a block of execution.

enumerator XSCOPE_CONTINUOUS: Continuous - Only gets an event start, single timestamped “ping”.

enumerator XSCOPE_DISCRETE: Discrete - Event generates a discrete block following on from the previous event.

enumerator XSCOPE_STATEMACHINE: State Machine - Create a new event state for every new data value.

enumerator XSCOPE_HISTOGRAM

enum xscope_UserDataType#

C data types an xSCOPE probe can receive.

Values:

enumerator XSCOPE_NONE#: No user data.

enumerator XSCOPE_UINT#: Unsigned int user data.

enumerator XSCOPE_INT#: Signed int user data.

enumerator XSCOPE_FLOAT#: Floating point user data.

enumerator XSCOPE_NONE: No user data.

enumerator XSCOPE_UINT: Unsigned int user data.

enumerator XSCOPE_INT: Signed int user data.

enumerator XSCOPE_FLOAT: Floating point user data.

enumerator XSCOPE_NONE: No user data.

enumerator XSCOPE_UINT: Unsigned int user data.

enumerator XSCOPE_INT: Signed int user data.

enumerator XSCOPE_FLOAT: Floating point user data.

enum xscope_IORedirectionMode#

Methods of I/O redirection over the xSCOPE connection.

This applies to all write syscalls.

Values:

enumerator XSCOPE_IO_NONE#: Output is not redirected.

enumerator XSCOPE_IO_BASIC#: Output is redirected over xSCOPE.

enumerator XSCOPE_IO_TIMED#: Output is redirected over xSCOPE, with prepended timestamp.

enumerator XSCOPE_IO_NONE: I/O is not redirected.

enumerator XSCOPE_IO_BASIC: Basic I/O redirection.

enumerator XSCOPE_IO_TIMED: Timed I/O redirection.

Functions

void xscope_user_init()#

User-implemented function to allow xSCOPE event registration.

This allows the code on the device to synchronize with the host. This may be defined anywhere in the application code and (if present) will be called before main(). It can be used to register probes which can then be used later in the application with the other functions defined in this header.

Note

A weak stub version of this function is defined, but it is intended to be overridden by a user implementation.

void xscope_register(int num_probes, ...)#

Registers the trace probes with the host system.

First parameter is the number of probes that will be registered. Further parameters are in groups of four.

event type (xscope_EventType)
probe name
user data type (xscope_UserDataType)
user data name.

This must be called from inside the xscope_user_init() function.

Examples:

xscope_register(1, XSCOPE_DISCRETE, "A probe", XSCOPE_UINT, "value"); ``
xscope_register(2, XSCOPE_CONTINUOUS, "Probe", XSCOPE_FLOAT, "Level",
                   XSCOPE_STATEMACHINE, "State machine", XSCOPE_NONE, "no name");

Note that the ‘id’ of each of these probes is implicit, starting from 0 and incrementing by 1 for each additional probe registered. In the above example:

“A probe” would have id 0.
”Probe” would have id 1.
”State machine” would have id 2.

If an xSCOPE config file file is specified on the compile line, that takes priority, so this call will be ignored.

For these reasons, it is recommended to not use this function, and instead use the xSCOPE config file on the command line to allocate probes. xSCOPE config file probe IDs are available as preprocessor constants in the compiled program.

Parameters:

num_probes – Number of probes that will be specified.

void xscope_enable()#

Enable the xSCOPE event capture on the local xCORE tile.

This is not necessary if an xSCOPE config file is used to enable xSCOPE.

void xscope_disable()#: Disable the xSCOPE event capture on the local xCORE tile.

void xscope_config_io(unsigned int mode)#

Configures xSCOPE I/O redirection.

This is not necessary if an xSCOPE config file is used to enable xSCOPE io.

Parameters:

mode – I/O redirection mode. See xscope_IORedirectionMode

void xscope_ping()#: Generate an xSCOPE ping system timestamp event.

void xscope_char(unsigned char id, unsigned char data)#

Send a trace event for the specified xSCOPE probe of type char.

Parameters:

id – xSCOPE probe id.
data – User data value (char).

void xscope_short(unsigned char id, unsigned short data)#

Send a trace event for the specified xSCOPE probe of type short.

Parameters:

id – xSCOPE probe id.
data – User data value (short).

void xscope_int(unsigned char id, unsigned int data)#

Send a trace event for the specified xSCOPE probe of type int.

Parameters:

id – xSCOPE probe id.
data – User data value (int).

void xscope_longlong(unsigned char id, unsigned long long data)#

Send a trace event for the specified xSCOPE probe of type long long.

Parameters:

id – xSCOPE probe id.
data – User data value (long long).

void xscope_float(unsigned char id, float data)#

Send a trace event for the specified xSCOPE probe of type float.

Parameters:

id – xSCOPE probe id.
data – User data value (float).

void xscope_double(unsigned char id, double data)#

Send a trace event for the specified xSCOPE probe of type double.

Parameters:

id – xSCOPE probe id.
data – User data value (double).

void xscope_bytes(unsigned char id, unsigned int size, const unsigned char data[])#

Send a trace event for the specified xSCOPE probe with a byte array.

Parameters:

id – xSCOPE probe id.
size – User data size.
data – User data bytes (char[]).

void xscope_start(unsigned char id)#

Start a trace block for the specified xSCOPE probe.

For use with XSCOPE_STARTSTOP probes.

Parameters:

id – xSCOPE probe id.

void xscope_stop(unsigned char id)#

Stop a trace block for the specified xSCOPE probe.

For use with XSCOPE_STARTSTOP probes.

Parameters:

id – xSCOPE probe id.

void xscope_start_int(unsigned char id, unsigned int data)#

Start a trace block for the specified xSCOPE probe and capture a value of type int.

For use with XSCOPE_STARTSTOP probes.

Parameters:

id – xSCOPE probe id.
data – User data value (int).

void xscope_stop_int(unsigned char id, unsigned int data)#

Stop a trace block for the specified xSCOPE probe and capture a value of type int.

For use with XSCOPE_STARTSTOP probes.

Parameters:

id – xSCOPE probe id.
data – User data value (int).

void xscope_core_char(unsigned char id, unsigned char data)#

Send a trace event for the specified xSCOPE probe of type char with logical core info.

Parameters:

id – xSCOPE probe id.
data – User data value (char).

void xscope_core_short(unsigned char id, unsigned short data)#

Send a trace event for the specified xSCOPE probe of type short with logical core info.

Parameters:

id – xSCOPE probe id.
data – User data value (short).

void xscope_core_int(unsigned char id, unsigned int data)#

Send a trace event for the specified xSCOPE probe of type int with logical core info.

Parameters:

id – xSCOPE probe id.
data – User data value (int).

void xscope_core_longlong(unsigned char id, unsigned long long data)#

Send a trace event for the specified xSCOPE probe of type long long with logical core info.

Parameters:

id – xSCOPE probe id.
data – User data value (long long).

void xscope_core_float(unsigned char id, float data)#

Send a trace event for the specified xSCOPE probe of type float with logical core info.

Parameters:

id – xSCOPE probe id.
data – User data value (float).

void xscope_core_double(unsigned char id, double data)#

Send a trace event for the specified xSCOPE probe of type double with logical core info.

Parameters:

id – xSCOPE probe id.
data – User data value (double).

void xscope_core_bytes(unsigned char id, unsigned int size, const unsigned char data[])#

Send a trace event for the specified xSCOPE probe with a byte array with logical core info.

Parameters:

id – xSCOPE probe id.
size – User data size.
data – User data bytes (char[]).

void xscope_core_start(unsigned char id)#

Start a trace block for the specified xSCOPE probe with logical core info.

For use with XSCOPE_STARTSTOP probes.

Parameters:

id – xSCOPE probe id.

void xscope_core_stop(unsigned char id)#

Stop a trace block for the specified xSCOPE probe with logical core info.

For use with XSCOPE_STARTSTOP probes.

Parameters:

id – xSCOPE probe id.

void xscope_core_start_int(unsigned char id, unsigned int data)#

Start a trace block for the specified xSCOPE probe with logical core info and capture a value of type int For use with XSCOPE_STARTSTOP probes.

Parameters:

id – xSCOPE probe id.
data – User data value (int).

void xscope_core_stop_int(unsigned char id, unsigned int data)#

Stop a trace block for the specified xSCOPE probe with logical core info and capture a value of type int For use with XSCOPE_STARTSTOP probes.

Parameters:

id – xSCOPE probe id.
data – User data value (int).

void xscope_mode_lossless()#

Put xSCOPE into a lossless mode where timing is no longer guaranteed.

If the logical core tries to send an xSCOPE packet which the xTAG does not have buffers for, then the logical core will wait until the xTAG does have buffers, stalling for a non-deterministic amount of time.

See also

xscope_mode_lossy

void xscope_mode_lossy()#

Put xSCOPE into a lossy mode where timing is not impacted, but data is lossy.

This is the default xSCOPE mode. If the logical core tries to send an xSCOPE packet which the xTAG does not have buffers for, then the entire packet will be dropped.

See also

xscope_mode_lossless

void xscope_data_from_host(unsigned int c, char buf[256], int *n)#

Receive data from the host over xSCOPE.

This function receives an xSCOPE packet from the host and puts the data contained within it into the supplied buffer. See Example host program and target programs for an example.

See also

xscope_connect_data_from_host

Parameters:

c – The xSCOPE chanend which has been configured with xscope_connect_data_from_host
buf – The user-supplied buffer to fill with data from the host
n – A pointer(c) or reference(xc) to an int which will be filled with the number of bytes put into the buffer

void xscope_connect_data_from_host(unsigned int from_host)#

Connect to the xSCOPE chanend to receive data packets from the host.

Note that it is only possible to use this function once in the system, as there is only a single xSCOPE chanend available to receive from the host. i.e. it can only be called on a single tile. See Example host program and target programs for an example.

See also

xscope_data_from_host

Parameters:

from_host – The chanend to receive on, obtained using the xscope_host_data() call from a multi-tile main.

__attribute__((deprecated)) static inline void xscope_probe(unsigned char id)#

Tracing API#

The tracing API is the mechanism to actually send event data to the host for a particular probe. It uses the high-speed xSCOPE link.

The ‘id’ for each of these functions is the id of the probe that the data is being sent on, which is either:

A preprocessor definition for config file probes, as explained in Auto-generated header file
Implicit for dynamically defined probes, as explained in xscope_register()

group xscope_trace_functions

Functions

void xscope_char(unsigned char id, unsigned char data)

Send a trace event for the specified xSCOPE probe of type char.

Parameters:

id – xSCOPE probe id.
data – User data value (char).

void xscope_short(unsigned char id, unsigned short data)

Send a trace event for the specified xSCOPE probe of type short.

Parameters:

id – xSCOPE probe id.
data – User data value (short).

void xscope_int(unsigned char id, unsigned int data)

Send a trace event for the specified xSCOPE probe of type int.

Parameters:

id – xSCOPE probe id.
data – User data value (int).

void xscope_longlong(unsigned char id, unsigned long long data)

Send a trace event for the specified xSCOPE probe of type long long.

Parameters:

id – xSCOPE probe id.
data – User data value (long long).

void xscope_float(unsigned char id, float data)

Send a trace event for the specified xSCOPE probe of type float.

Parameters:

id – xSCOPE probe id.
data – User data value (float).

void xscope_double(unsigned char id, double data)

Send a trace event for the specified xSCOPE probe of type double.

Parameters:

id – xSCOPE probe id.
data – User data value (double).

void xscope_bytes(unsigned char id, unsigned int size, const unsigned char data[])

Send a trace event for the specified xSCOPE probe with a byte array.

Parameters:

id – xSCOPE probe id.
size – User data size.
data – User data bytes (char[]).

void xscope_start(unsigned char id)

Start a trace block for the specified xSCOPE probe.

For use with XSCOPE_STARTSTOP probes.

Parameters:

id – xSCOPE probe id.

void xscope_stop(unsigned char id)

Stop a trace block for the specified xSCOPE probe.

For use with XSCOPE_STARTSTOP probes.

Parameters:

id – xSCOPE probe id.

void xscope_start_int(unsigned char id, unsigned int data)

Start a trace block for the specified xSCOPE probe and capture a value of type int.

For use with XSCOPE_STARTSTOP probes.

Parameters:

id – xSCOPE probe id.
data – User data value (int).

void xscope_stop_int(unsigned char id, unsigned int data)

Stop a trace block for the specified xSCOPE probe and capture a value of type int.

For use with XSCOPE_STARTSTOP probes.

Parameters:

id – xSCOPE probe id.
data – User data value (int).

void xscope_core_char(unsigned char id, unsigned char data)

Send a trace event for the specified xSCOPE probe of type char with logical core info.

Parameters:

id – xSCOPE probe id.
data – User data value (char).

void xscope_core_short(unsigned char id, unsigned short data)

Send a trace event for the specified xSCOPE probe of type short with logical core info.

Parameters:

id – xSCOPE probe id.
data – User data value (short).

void xscope_core_int(unsigned char id, unsigned int data)

Send a trace event for the specified xSCOPE probe of type int with logical core info.

Parameters:

id – xSCOPE probe id.
data – User data value (int).

void xscope_core_longlong(unsigned char id, unsigned long long data)

Send a trace event for the specified xSCOPE probe of type long long with logical core info.

Parameters:

id – xSCOPE probe id.
data – User data value (long long).

void xscope_core_float(unsigned char id, float data)

Send a trace event for the specified xSCOPE probe of type float with logical core info.

Parameters:

id – xSCOPE probe id.
data – User data value (float).

void xscope_core_double(unsigned char id, double data)

Send a trace event for the specified xSCOPE probe of type double with logical core info.

Parameters:

id – xSCOPE probe id.
data – User data value (double).

void xscope_core_bytes(unsigned char id, unsigned int size, const unsigned char data[])

Send a trace event for the specified xSCOPE probe with a byte array with logical core info.

Parameters:

id – xSCOPE probe id.
size – User data size.
data – User data bytes (char[]).

void xscope_core_start(unsigned char id)

Start a trace block for the specified xSCOPE probe with logical core info.

For use with XSCOPE_STARTSTOP probes.

Parameters:

id – xSCOPE probe id.

void xscope_core_stop(unsigned char id)

Stop a trace block for the specified xSCOPE probe with logical core info.

For use with XSCOPE_STARTSTOP probes.

Parameters:

id – xSCOPE probe id.

void xscope_core_start_int(unsigned char id, unsigned int data)

Start a trace block for the specified xSCOPE probe with logical core info and capture a value of type int For use with XSCOPE_STARTSTOP probes.

Parameters:

id – xSCOPE probe id.
data – User data value (int).

void xscope_core_stop_int(unsigned char id, unsigned int data)

Stop a trace block for the specified xSCOPE probe with logical core info and capture a value of type int For use with XSCOPE_STARTSTOP probes.

Parameters:

id – xSCOPE probe id.
data – User data value (int).