System Data Structures

Defines

TRF_INTERFACE_LOCAL: Return local interfaces, e.g. the loopback interface.

TRF_INTERFACE_EXT: Return externally facing interfaces, e.g. the Ethernet port.

TRF_INTERFACE_SPD: Only return interfaces with known link rates.

TRF_INTERFACE_IP4: Return interfaces with IPv4 addresses attached.

TRF_INTERFACE_IP6: Return interfaces with IPv6 addresses attached. Note that LibTRF does not currently support IPv6.

TRF_INTERFACE_POLICY_IP: Use the interface IP address to determine whether an interface is local or external.

TRF_INTERFACE_POLICY_DB: Use a platform specific database to determine whether an interface is local or external.

TRFSock

trfSockValid(x)

TRFInvalidSock

trfLastSockError

PTRFDisplay

PTRFXFabric

PTRFAddrV

PTRFInterface

PTRFSession

PTRFContext

PTRFContextOpts

PTRFCursor

TRF_SA_LEN(x)

trf_perror(retval)

PTRFTCQFabric

PTRFMem

TRFI_VALID

TRFX_MAX_STR

Maximum serialized TRF address string size.

Currently, the longest TRF address string is: trfx_sockaddr_in6://[ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff]:65535 at 67 characters, plus the terminating null byte.

Typedefs

typedef enum TRFMemType TRFMemType: TRF memory region type.

Enums

enum TRFMemType

TRF memory region type.

Values:

enumerator TRF_MEM_TYPE_INVALID

enumerator TRF_MEM_TYPE_RAW

enumerator TRF_MEM_TYPE_LF_MR

enumerator TRF_MEM_TYPE_MAX

enum TRFEPType

TRF endpoint types.

This endpoint type determines the behaviour of connection functions, as well as how to decode data stored within a TRFContext struct.

Values:

enumerator TRF_EP_INVALID

enumerator TRF_EP_FREE

enumerator TRF_EP_SINK

enumerator TRF_EP_SOURCE

enumerator TRF_EP_CONN_ID

enumerator TRF_EP_MAX

enum TRFXType

TRF connection types.

May be used to determine the type of transport in use. Currently, only Libfabric is supported.

Values:

enumerator TRFX_TYPE_INVALID: Invalid.

enumerator TRFX_TYPE_LIBFABRIC: Libfabric Auto-Selection.

enumerator TRFX_TYPE_RDMACM: RDMA-CM.

enumerator TRFX_TYPE_MAX: Sentinel value.

enum TRFXAddr

TRF serialized address formats.

Values:

enumerator TRFX_ADDR_INVALID: Invalid.

enumerator TRFX_ADDR_FI_STR: Libfabric FI_ADDR_STR.

enumerator TRFX_ADDR_SOCKADDR: struct sockaddr

enumerator TRFX_ADDR_SOCKADDR_IN: struct sockaddr_in

enumerator TRFX_ADDR_SOCKADDR_IN6: struct sockaddr_in6

enumerator TRFX_ADDR_IB_GID: InfiniBand GID (currently unused)

enumerator TRFX_ADDR_IB_UD: InfiniBand UD GID.

enumerator TRFX_ADDR_PSMX: Intel Performance Scaled Messaging 1 (True Scale Fabric)

enumerator TRFX_ADDR_PSMX2: Intel Performance Scaled Messaging 2 (Omni-Path)

enumerator TRFX_ADDR_PSMX3: Intel Performance Scaled Messaging 3 (RoCE v2)

enumerator TRFX_ADDR_MAX: Sentinel value.

enum TRFTexFormat

Values:

enumerator TRF_TEX_INVALID: Invalid.

enumerator TRF_TEX_RGBA_8888: RGBA packed pixels, 8 bits per channel.

enumerator TRF_TEX_RGB_888: RGB packed pixels, 8 bits per channel.

enumerator TRF_TEX_BGRA_8888: BGRA packed pixels, 8 bits per channel.

enumerator TRF_TEX_BGR_888: BGR packed pixels, 8 bits per channel.

enumerator TRF_TEX_BGR_32: 24-in-32 format for compatibility with Looking Glass

enumerator TRF_TEX_RGBA_16161616F: RGBA, 16 bits per channel HDR float.

enumerator TRF_TEX_RGBA_16161616: RGBA, 16 bits per channel.

enumerator TRF_TEX_BGRA_16161616F: BGRA, 16 bits per channel HDR float.

enumerator TRF_TEX_BGRA_16161616: BGRA, 16 bits per channel.

enumerator TRF_TEX_RGBA_1010102: RGBA, 10 bpc RGB, 2 bit alpha.

enumerator TRF_TEX_MONO_8: Monochrome, 8 bits per pixel.

enumerator TRF_TEX_MAX: Sentinel Value.

enum TRFMAType

TRF Memory Access Type.

Values:

enumerator TRF_MA_INVALID

enumerator TRF_MA_VADDR: The address refers to an actual address in virtual memory.

enumerator TRF_MA_OFFSET: The address is an offset relative to the start of the registered memory region.

enumerator TRF_MA_TAG: The address is a tag, used to identify a receive memory region.

enumerator TRF_MA_64B_KEY: The remote key fits within 64 bits.

enumerator TRF_MA_RAW_KEY: The remote key size exceeds 64 bits.

Functions

static inline void *trfMemPtr(PTRFMem mem)

static inline size_t trfMemSize(PTRFMem mem)

static inline TRFMemType trfMemType(PTRFMem mem)

static inline struct fid_mr *trfMemFabricMR(PTRFMem mem)

static inline uint64_t trfMemFabricKey(PTRFMem mem)

static inline void *trfMemFabricDesc(PTRFMem mem)

static inline size_t trf__GetPageSize()

Get the system page size.

Returns:: System page size

static inline void trfSetDefaultOpts(PTRFContextOpts opts)

static inline void trfDuplicateOpts(PTRFContextOpts in, PTRFContextOpts out)

PTRFAddrV trfDuplicateAddrV(PTRFAddrV av)

static inline int trfTimespecToMs(struct timespec *ts)

Convert a timespec into an absolute delay in milliseconds.

Parameters:: ts –
Returns:: int

static inline struct timespec trfMsToTimespec(int ms)

Convert a delay in milliseconds to a timespec representation.

Parameters:: ms – Delay in milliseconds
Returns:: struct timespec

static inline struct timespec trfSumTimespec(struct timespec *ts, struct timespec *ts2)

Sum two timespecs and return the result.

Parameters:

ts – First timespec
ts2 – Second timespec

Returns:

Result timespec

struct TRFTCQFabric

#include <trf_def.h>

Tracked CQ (Libfabric)

This structure is used to track the number of in-flight operations, in order to prevent CQ overruns.

Public Members

struct fid_cq *cq

atomic_int_fast64_t entries

struct TRFMem

#include <trf_def.h>

Memory region object.

Public Members

void *ptr

size_t size

TRFMemType type

struct fid_mr *fabric_mr

union TRFMem::[anonymous] [anonymous]

struct TRFRKey

#include <trf_def.h>

Remote access key object.

Remote keys (rkeys) are required for access to data in remote memory, both read and write. Most fabric providers are able to encode their keys within a 64-bit region, though some providers like the multi-rail Libfabric provider require keysizes that exceed 64-bits. Additionally, this allows custom API implementations to use key sizes which exceed 64 bits.

Public Members

uint64_t rkey: Remote access key.

uint8_t *raw_key

Raw remote access key.

If the fabric provider supports regular sized rkeys it is recommended that this field be set to NULL.

ssize_t raw_key_len

Raw remote access key length.

If the fabric provider supports regular sized rkeys it is necessary to set this field to a negative number to indicate this.

int8_t raw_key_mapped

Whether the raw key mapping has been cached.

0: Raw key mapping exists but is not cached 1: Raw key mapping exists and is cached -1: Raw key does not exist, or mapping it is not supported

Once a raw key has been mapped, it may be reused in the future. This value should be set to 1 to indicate that the raw key has already been mapped. Then the rkey field should be set to indicate the mapped value.

struct TRFInterface

#include <trf_def.h>

Struct for Storing Interface & Address Data for transmission.

Public Members

struct sockaddr *addr: sockaddr struct containing sa_family and IP Address

uint8_t netmask: Netmask of address.

int32_t speed: Interface speed.

int32_t port: Port.

int32_t flags: Flags set if the port and ip address are valid interfaces.

struct TRFInterface *next: Next item in linked list.

struct TRFAddrV

#include <trf_def.h>

Address vector for storing source-destination address pairs, as well as their connection speeds.

Public Members

struct sockaddr *src_addr: struct sockaddr containing source address

struct sockaddr *dst_addr: struct sockaddr containing destination address

int32_t pair_speed: pair speed between the interface

struct TRFAddrV *next: next item in linked list

struct TRFXFabric

#include <trf_def.h>

Libfabric specific context objects.

Public Members

fi_addr_t src_addr: Source address identifier.

fi_addr_t peer_addr: Destination address identifier.

uint32_t addr_fmt: Address format, from fi->addr_format.

struct fi_info *fi: Fabric attributes.

struct fid_ep *ep: Endpoint.

struct fid_fabric *fabric: Fabric interface identifier.

struct fid_domain *domain

Domain identifier.

A domain is the root object to which connection objects should be bound.

struct fid_eq *eq

Event queue.

An event queue is a mechanism for managing asynchronous events, such as address insertion. Currently, as all TRF operations are synchronous, it is not used.

struct TRFTCQFabric *tx_cq

Transmission Completion queue.

Transmit events are used to track the progress of send and RMA operations, including RMA read and write operations.

struct TRFTCQFabric *rx_cq

Receive Completion queue.

Receive events are used to track the progress of message receive operations only.

struct fid_av *av

Address Vector.

An address vector contains translations of Libfabric addresses into fabric-specific addresses.

struct TRFMem msg_mem: Message memory region.

uint32_t intrv

Interrupt vector.

The interrupt vector determines the CPU thread on which events are delivered. This is a “best effort” option - not all fabric types support this option.

struct TRFDisplay

Public Members

int32_t id

Display ID.

The display ID, unique within a context. This display is the actual value used in the TRF API to identify which display should be used.

char *name

Display name.

The display name is a user-facing string that identifies the display via a human-readable name, which could be the monitor name or the name of the server the display is connected to.

uint32_t width

Width.

Display width in pixels

uint32_t height

Height.

Display height in pixels

uint32_t rate

Refresh rate.

Display refresh rate, in Hz.

uint32_t format

Texture format.

`

Currently, only one texture format is supported simultaneously.

uint32_t dgid

Display Group.

A server acting as a multiplexer for multiple sources may set logical display groups to allow users to select only sources from a particular machine.

uint32_t x_offset

X Offset.

Horizontal offset of the display, relative to the display group only.

uint32_t y_offset

Y Offset.

Vertical offset of the display, relative to the display group only.

struct TRFMem mem: Memory region containing the framebuffer data.

size_t fb_offset: Offset from the start of the framebuffer address to the start of the actual frame data, excluding any header information.

uint32_t frame_cntr: Frames since the start of the capture session.

struct TRFDisplay *next: Next display in the list.

struct TRFContextOpts

#include <trf_def.h>

Context options.

Default context options may be set in this struct, which modifies the behaviour of Telescope functions.

Public Members

int32_t nc_snd_timeo: Negotiation channel send timeout in milliseconds.

int32_t nc_rcv_timeo: Negotiation channel receive timeout in milliseconds.

size_t nc_snd_bufsize: Negotiation channel send buffer size in bytes.

size_t nc_rcv_bufsize: Negotiation channel receive buffer size in bytes.

int32_t fab_snd_timeo: Fabric send timeout in milliseconds.

int32_t fab_rcv_timeo: Fabric receive timeout in milliseconds.

size_t fab_snd_bufsize

Fabric send buffer max size in bytes.

Note: If set to a positive value, this must be less than or equal to the length of the fabric message buffer region.

size_t fab_rcv_bufsize

Fabric receive buffer max size in bytes.

Note: If set to a positive value, this must be less than or equal to the length of the fabric message buffer region.

int64_t fab_poll_rate

Fabric polling rate limit (sleep time in nanoseconds)

Note: For latency sensitive applications, this should be set to 0, to use busy waiting.

uint8_t fab_cq_sync: Synchronous CQ polling mode.

uint32_t fab_api_ver: Libfabric API/ABI version for this session.

uint64_t iface_flags: Flags for determining if linklocal or external addresses should be used.

uint32_t max_clients: Maximum number of clients (server side only).

uint32_t max_subchannels: Maximum number of subchannels.

struct TRFContext

#include <trf_def.h>

The Telescope Remote Framebuffer Library Context.

This is the main context for most TRF operations. It contains all of the resources necessary to establish main and side channel communications between endpoints. Additionally, the TRFContext may be chained with other related contexts to allow for group operations, e.g. disconnecting all clients or broadcasting frames simultaneously to all clients.

Public Members

enum TRFEPType type

Endpoint type.

Servers and clients both use the same struct to store connection information. This field determines the type of endpoint contained within the context.