xSCOPE host library#

The xSCOPE host library is used for communication between the host and the target over the fast xSCOPE transport using a custom user host program. It connects to the “xSCOPE server”, and communicates while the program is running. For a full example, see User-supplied host program.

The communication takes place using “probes”, which can be defined using xSCOPE config file or using the xSCOPE target library.

The host program can be written in either the C or C++ programming language. The header xscope_endpoint.h provides the API for the host program. It must be linked against the shared library libxscope_endpoint.so on Linux and Mac hosts and xscope_endpoint.dll on Windows hosts, using C linkage. These libraries are provided by the XTC Tools in the lib sub-directory of the installation root.

Example#

For an example, see Host program.

API#

xSCOPE host API

This file contains functions to communicate with an xSCOPE server.

Defines

XSCOPE_EP_SUCCESS#

Status code: Function was successful.

XSCOPE_EP_FAILURE#

Status code: Function failed.

Typedefs

typedef void (*xscope_ep_register_fptr)(unsigned int id, unsigned int type, unsigned int r, unsigned int g, unsigned int b, unsigned char *name, unsigned char *unit, unsigned int data_type, unsigned char *data_name)#

Function pointer which will be called when the target registers new probes.

Probes registered using an xSCOPE config file will trigger this callback upon initial connection. Probes registered via calls to xscope_register() will trigger this callback when they are called.

Most of these parameters are configured directly by the target code/config file. The RGB color is currently chosen arbitrarily by the server.

Param id:

The unique ID of the probe, which has been allocated by the server.

Param type:

The type of the probe. See xscope_EventType

Param r:

Red color value from 0-255 to visually represent the probe

Param g:

Green color value from 0-255 to visually represent the probe

Param b:

Blue color value from 0-255 to visually represent the probe

Param name:

String representing the name of the probe

Param unit:

String representing the unit of time being used (e.g. ‘ps’)

Param data_type:

Type of the data (signed, unsigned or float). See xscope_UserDataType

Param data_name:

String representing the unit of measurement of the probe (e.g. ‘mV’)

typedef void (*xscope_ep_record_fptr)(unsigned int id, unsigned long long timestamp, unsigned int length, unsigned long long dataval, unsigned char *databytes)#

Function pointer which will be called when a record for a probe is received from the target.

Param id:

ID value which has previously been registered with a xscope_ep_register_fptr call

Param timestmp:

Timestamp of the received record, in the units given in the xscope_ep_register_fptr call

Param length:

0 if the value received is in dataval, otherwise it is the length of the data in databytes

Param dataval:

The value received for the record. Only valid if the length is zero. The value should be cast based on the data_type argument provided by the xscope_ep_register_fptr call

Param databytes:

The data buffer received for the record. Only valid if length is nonzero. The target can send this kind of message using xscope_bytes()

typedef void (*xscope_ep_stats_fptr)(int id, unsigned long long average)#

Function pointer which will be called with stats when requested using xscope_ep_request_stats.

Warning

The server does not implement this request.

Param id:

Not implemented: always zero

Param average:

Not implemented: value of ‘data’ from the server. Always 0xdeadbeef.

typedef void (*xscope_ep_print_fptr)(unsigned long long timestamp, unsigned int length, unsigned char *data)#

Function pointer which will be called when the target executes a write syscall (such as a print)

Warning

This function gets called for all write syscalls, not just prints to stdout.

Param timestamp:

The timestamp of the print record that has been received

Param length:

The number of characters in the data buffer

Param data:

Data buffer containing the data the target is writing.

typedef void (*xscope_ep_exit_fptr)()#

Function pointer which will be called when xscope_ep_disconnect is called.

Warning

This does not automatically get called by anything internally. Only xscope_ep_disconnect calls this when it is called manually.

Functions

int xscope_ep_set_register_cb(xscope_ep_register_fptr registration)#

Register a callback for receiving probe registration information.

Parameters:

  • registration – Callback

Return values:

  • XSCOPE_EP_SUCCESS – Success

  • XSCOPE_EP_FAILURE – Failure, such as endpoint is already connected.

int xscope_ep_set_record_cb(xscope_ep_record_fptr record)#

Register a callback for receiving probe record data.

Parameters:

  • record – Callback

Return values:

  • XSCOPE_EP_SUCCESS – Success

  • XSCOPE_EP_FAILURE – Failure, such as endpoint is already connected.

int xscope_ep_set_stats_cb(xscope_ep_stats_fptr stats)#

Register a callback for getting statistics.

Warning

This system is not implemented.

Parameters:

  • stats – Callback

Return values:

  • XSCOPE_EP_SUCCESS – Success

  • XSCOPE_EP_FAILURE – Failure, such as endpoint is already connected.

int xscope_ep_set_print_cb(xscope_ep_print_fptr print)#

Register a callback for receiving data to print to the user.

Warning

This callback is not implemented.

Parameters:

  • print – Callback

Return values:

  • XSCOPE_EP_SUCCESS – Success

  • XSCOPE_EP_FAILURE – Failure, such as endpoint is already connected.

int xscope_ep_set_exit_cb(xscope_ep_exit_fptr exit)#

Register a callback which will be called when xscope_ep_disconnect is called.

Parameters:

  • exit – Callback

Return values:

  • XSCOPE_EP_SUCCESS – Success

  • XSCOPE_EP_FAILURE – Failure, such as endpoint is already connected.

int xscope_ep_connect(const char *ipaddr, const char *port)#

Connect to an xSCOPE server which is running and waiting for a client to connect.

Parameters:

  • ipaddr – IPv4 address of the xSCOPE server or a host name which will be resolved to one

  • port – Port of the xSCOPE server

Return values:

  • XSCOPE_EP_SUCCESS – Success

  • XSCOPE_EP_FAILURE – Failure, such as endpoint is already connected, or failed to connect.

int xscope_ep_disconnect(void)#

Disconnect from the connected xSCOPE server, and clean up.

Return values:

  • XSCOPE_EP_SUCCESS – Success

  • XSCOPE_EP_FAILURE – Failure

int xscope_ep_request_registered(void)#

No-op, unimplemented.

This is not required. The xscope_ep_register_fptr callback will be called as probe registrations are made, regardless of whether this function is called.

Warning

This is not implemented

Returns:

Status value

int xscope_ep_request_stats(void)#

Request stats from the xSCOPE server, and trigger any registered xscope_ep_stats_fptr callback.

Warning

This is not implemented

Returns:

Status value

int xscope_ep_request_upload(unsigned int length, const unsigned char *data)#

Send data to the target.

This will be received by xscope_data_from_host() on the target.

Parameters:

  • length – Length of the data buffer, in bytes. Must be 256 bytes or fewer

  • data – The data buffer to send to the target

Return values:

  • XSCOPE_EP_SUCCESS – Success

  • XSCOPE_EP_FAILURE – Failure, such as data too long, or endpoint not connected.