osd_gateway class

This class implements a gateway between two debug subnets, typically between the subnet on the host and the one on a “target device”, an OSD enabled chip (as an ASIC, on an FPGA or running in simulation). On the host side, the gateway registers with the host controller for a given subnet. It then receives all traffic going to this subnet. On the device side, the OSD packets are transformed into Data Transport Datagrams (length-value encoded OSD packets). Standard read()/write() callback function can then be implemented to perform the actual data transfer to the device, possibly using another suitable library (such as GLIP).

Behavior on connection loss

The connected device can drop the connection at any time. That is signaled by the device by returning OSD_ERROR_NOT_CONNECTED from its packet_read() and packet_write() callback functions. When osd_gateway detects this kind of loss in connectivity, it disconnects the gateway from the host controller.

Usage

#include <osd/osd.h>
#include <osd/gateway.h>

Public Interface

Typedefs

typedef osd_result(* packet_read_fn)(struct osd_packet **pkg, void *cb_arg)

Read a osd_packet from the device

Return
OSD_ERROR_NOT_CONNECTED if the not connected to the device
Return
OSD_OK if successful
Parameters
  • pkg: the packet to read to (allocated by the called function)
  • cb_arg: an user-defined callback argument

typedef osd_result(* packet_write_fn)(const struct osd_packet *pkg, void *cb_arg)

Write a osd_packet to the device

Return
OSD_ERROR_NOT_CONNECTED if the not connected to the device
Return
OSD_OK if successful
Parameters
  • pkg: the packet to write
  • cb_arg: an user-defined callback argument

Functions

osd_result osd_gateway_new(struct osd_gateway_ctx ** ctx, struct osd_log_ctx * log_ctx, const char * host_controller_address, uint16_t device_subnet_addr, packet_read_fn packet_read, packet_write_fn packet_write, void * cb_arg)

Create new osd_gateway instance

Return
OSD_OK on success, any other value indicates an error
See
osd_gateway_free()
Parameters
  • [out] ctx: the osd_gateway_ctx context to be created
  • [in] log_ctx: the log context to be used. Set to NULL to disable logging
  • [in] host_controller_address: ZeroMQ endpoint of the host controller
  • [in] device_subnet_addr: Subnet address of the device
  • [in] packet_read: callback function to perform a read from the device
  • [in] packet_write: callback function to perform a write to the device
  • [in] cb_arg: an user-defined pointer passed to all callback functions, such as packet_read and packet_write. Can be used to pass context objects to the callbacks. Set to NULL if unused. Note: the callbacks are called from different threads, make sure all uses of cb_arg inside the callbacks are thread safe.

void osd_gateway_free(struct osd_gateway_ctx ** ctx)

Free and NULL a communication API context object

Call osd_gateway_disconnect() before calling this function.

Parameters
  • ctx: the osd_com context object

osd_result osd_gateway_connect(struct osd_gateway_ctx * ctx)

Connect to the device and to the host controller

Return
OSD_OK on success, any other value indicates an error
See
osd_gateway_disconnect()
Parameters
  • ctx: the osd_gateway_ctx context object

osd_result osd_gateway_disconnect(struct osd_gateway_ctx * ctx)

Shut down all communication with the device and the host controller

Return
OSD_OK on success, any other value indicates an error
See
osd_gateway_run()
Parameters
  • ctx: the osd_hostmod context object

bool osd_gateway_is_connected(struct osd_gateway_ctx * ctx)

Is the connection to the device and to the host controller active?

Return
1 if connected, 0 if not connected
See
osd_gateway_connect()
See
osd_gateway_disconnect()
Parameters
  • ctx: the context object

struct osd_gateway_transfer_stats* osd_gateway_get_transfer_stats(struct osd_gateway_ctx * ctx)

Get statistics about the data transferred through the gateway

struct osd_gateway_transfer_stats
#include <gateway.h>

Data transfer statistics

See
osd_gateway_get_transfer_stats()

Public Members

struct timespec connect_time
uint64_t bytes_from_device
uint64_t bytes_to_device