API Documentation

version 2018.1 (other versions)

Documentation Parts

Message passing library

group libmp

This is the message passing library for inter-tile communication in OpTiMSoC. It abstracts from the hardware and serves as a generic API. The implementation choses the best available hardware.

Each communication is between two endpoints, which are a tuple: (tile, node, port). The application has to manage nodes and port by itself and tiles are denoted by rank of the compute tile.

There are two types of communication: Connection-less communication with messages is best suited for adhoc communication between multiple communication partners. The protocol for connection-oriented channel is more efficient if the communication relations are fixed, such as in streaming applications. Here channels establish a fixed communication relation and flow control can be implemented more efficient.

Defines

OPTIMSOC_MP_CONF_DOMAINS
OPTIMSOC_MP_ERROR_NOT_INITIALIZED
OPTIMSOC_MP_ERROR_DOMAINS_NOT_SUPPORTED
OPTIMSOC_MP_ERROR_BUFFEROVERFLOW

Typedefs

typedef uint32_t optimsoc_mp_endpoint_handle

This is the handle for an endpoint

The endpoint is an opaque type to hide the implementaiton details.

Enums

enum optimsoc_endpoint_type

The endpoint types

Each endpoint is of a certain type and can only be used in a subset of functions.

Values:

enumerator OPTIMSOC_MP_EP_CONNECTIONLESS

Connection-less communication

enumerator OPTIMSOC_MP_EP_CHANNEL

Connection-oriented communication

Functions

int optimsoc_mp_initialize(struct optimsoc_mp_attributes *attr)

Initialize the message passing subsystem

Return

0 on success, an error code otherwise

Parameters

  • attr: Configuration attributes (currently ignored)

int optimsoc_mp_endpoint_create(optimsoc_mp_endpoint_handle *endpoint, uint32_t node, uint32_t port, optimsoc_endpoint_type type, uint32_t buffer_size, int overwrite_max_size)

Create an endpoint

Creates a message passing endpoint in this tile for a specific node on a port. Other endpoints can send messages or connect to the endpoint via the <tile, node, port> tuple.

The buffer can either be connection-less or connection-oriented. When connection-oriented you need to connect two endpoints to a channel first using optimsoc_mp_channel_connect().

The buffer_size is the number of messages or packets that can be used. If messages or packets are larger than the default size, the maximum element size can be overwritten for this endpoint.

Return

0 if success, error code otherwise

Parameters

  • endpoint: Pointer to the handle to initialize

  • node: Local node number

  • port: Local port number

  • type: Type of the endpoint

  • buffer_size: Number of messages the endpoint accepts

  • overwrite_max_size: Set the maximum message size or 0 for the default

int optimsoc_mp_endpoint_get(optimsoc_mp_endpoint_handle *endpoint, uint32_t tile, uint32_t node, uint32_t port)

Retrieve a remote endpoint

Before communicating with a remote endpoint, an endpoint handle must be configured. This function initializes the endpoint for the remote endpoint.

The remote tile is the compute tile rank.

This function blocks until the remote endpoint is available.

Return

Return 0 on success, an error code otherwise

Parameters

  • endpoint: Handle to initialize

  • tile: Remote compute tile rank

  • node: Node of the remote endpoint

  • port: Port of the remote endpoint

int optimsoc_mp_msg_send(optimsoc_mp_endpoint_handle from, optimsoc_mp_endpoint_handle to, uint8_t *data, uint32_t size)

Send a message to a remote endpoint

A local endpoint is used to store the data locally for an asynchronous transfer if supported. The local endpoint must be created by optimsoc_mp_endpoint_create() with type OPTIMSOC_MP_EP_CONNECTIONLESS. The remote endpoint must be retrieved with optimsoc_mp_endpoint_get().

The function blocks until the data is stored in another data structure or successfully transfer, i.e., the input buffer can be safely reused.

Return

0 on success, an error code otherwise

Parameters

  • from: Local endpoint

  • to: Remote endpoint

  • data: Data to transfer

  • size: Size of the data to transfer

int optimsoc_mp_msg_recv(optimsoc_mp_endpoint_handle ep, uint8_t *buffer, uint32_t buffer_size, uint32_t *received_size)

Receive a message from a local endpoint

Receive a message from the local endpoint. The endpoint must be configured by optimsoc_mp_endpoint_create() with type OPTIMSOC_MP_EP_CONNECTIONLESS.

The function blocks until a message was received.

Return

0 on success, an error code otherwise

Parameters

  • ep: Local endpoint to receive from

  • buffer: Output data buffer

  • buffer_size: Size of the buffer

  • received_size: The actual written data size

int optimsoc_mp_channel_connect(optimsoc_mp_endpoint_handle from, optimsoc_mp_endpoint_handle to)
int optimsoc_mp_channel_send(optimsoc_mp_endpoint_handle from, optimsoc_mp_endpoint_handle to, uint8_t *buffer, uint32_t size)
int optimsoc_mp_channel_recv(optimsoc_mp_endpoint_handle ep, uint8_t *buffer, uint32_t buffer_size, uint32_t *received_size)
int optimsoc_mp_channel_pause(optimsoc_mp_endpoint_handle ep)
int optimsoc_mp_channel_continue(optimsoc_mp_endpoint_handle ep)
char *optimsoc_mp_error_string(int errno)
struct optimsoc_mp_attributes
#include <optimsoc-mp.h>

Configuration attributes

Currently not used.