4.5.1. Base#

4.5.1.1. Interface#

Enums

enum SimbricksBaseIfSyncMode#

Values:

enumerator kSimbricksBaseIfSyncDisabled#: No synchronization enabled.

enumerator kSimbricksBaseIfSyncOptional#: Synchronization enabled if both peers request it.

enumerator kSimbricksBaseIfSyncRequired#: Enable synchronization and error if not both support it.

Functions

int SimbricksBaseIfSHMPoolCreate(struct SimbricksBaseIfSHMPool *pool, const char *path, size_t pool_size)#: Create and map a new shared memory pool with the specified path and size.

int SimbricksBaseIfSHMPoolMapFd(struct SimbricksBaseIfSHMPool *pool, int fd)#: Map existing shared memory pool by file descriptor.

int SimbricksBaseIfSHMPoolMap(struct SimbricksBaseIfSHMPool *pool, const char *path)#: Map existing shared memory pool by path.

int SimbricksBaseIfSHMPoolUnmap(struct SimbricksBaseIfSHMPool *pool)#: Unmap shared memory pool, without unlinking it.

int SimbricksBaseIfSHMPoolUnlink(struct SimbricksBaseIfSHMPool *pool)#: Delete but don’t unmap shared memory pool.

void SimbricksBaseIfDefaultParams(struct SimbricksBaseIfParams *params)#: Initialize params struct with default values

size_t SimbricksBaseIfSHMSize(struct SimbricksBaseIfParams *params)#: Required SHM size for these parameters

int SimbricksBaseIfInit(struct SimbricksBaseIf *base_if, struct SimbricksBaseIfParams *params)#

int SimbricksBaseIfListen(struct SimbricksBaseIf *base_if, struct SimbricksBaseIfSHMPool *pool)#: Create listening base interface. Note this does not wait for a connector.

int SimbricksBaseIfConnect(struct SimbricksBaseIf *base_if)#: Initiate connection for base interface. Note this is asynchronous.

int SimbricksBaseIfConnected(struct SimbricksBaseIf *base_if)#: Check if incoming/outgoing connection is established . (non-blocking)

int SimbricksBaseIfConnFd(struct SimbricksBaseIf *base_if)#: FD to wait on for listen or connect event.

int SimbricksBaseIfConnsWait(struct SimbricksBaseIf **base_ifs, unsigned n)#: Block till base_if is connected or failed

int SimbricksBaseIfIntroSend(struct SimbricksBaseIf *base_if, const void *payload, size_t payload_len)#: Send intro.

int SimbricksBaseIfIntroRecv(struct SimbricksBaseIf *base_if, void *payload, size_t *payload_len)#: Receive intro.

int SimbricksBaseIfIntroFd(struct SimbricksBaseIf *base_if)#: FD to wait on for intro events.

int SimBricksBaseIfEstablish(struct SimBricksBaseIfEstablishData *ifs, size_t n)#

Completely establish multiple base-ifs in parallel. This handles the parallel connecting and handshake transmission and reception. Expects all base ifs to be in non-blocking mode.

Parameters:

ifs – Array of structs with info about each baseif including pointers and lengths for intro messages.
n – Number of ifs to establish.

Returns:

0 on success, != 0 otherwise.

void SimbricksBaseIfClose(struct SimbricksBaseIf *base_if)#

void SimbricksBaseIfUnlink(struct SimbricksBaseIf *base_if)#

static inline uint8_t SimbricksBaseIfInType(struct SimbricksBaseIf *base_if, volatile union SimbricksProtoBaseMsg *msg)#

Read message type from received message.

Parameters:

base_if – Base interface handle (connected).
msg – Pointer to the previously received message.

static union SimbricksProtoBaseMsg *SimbricksBaseIfInPeek(struct SimbricksBaseIf *base_if, uint64_t timestamp)#

Poll for an incoming message without advancing the position if one is found. Message must be retrieved again with a call to SimbricksBaseIfInPoll

Parameters:

base_if – Base interface handle (connected).
timestamp – Current timestamp (in picoseconds).

Returns:

Pointer to the message struct if successful, NULL otherwise.

static union SimbricksProtoBaseMsg *SimbricksBaseIfInPoll(struct SimbricksBaseIf *base_if, uint64_t timestamp)#

Poll for an incoming message. After processing the message must be freed by calling SimbricksBaseIfInDone.

Parameters:

base_if – Base interface handle (connected).
timestamp – Current timestamp (in picoseconds).

Returns:

Pointer to the message struct if successful, NULL otherwise.

static inline void SimbricksBaseIfInDone(struct SimbricksBaseIf *base_if, volatile union SimbricksProtoBaseMsg *msg)#

Mark received message as processed and pass ownership of the slot back to the sender.

Parameters:

base_if – Base interface handle (connected).
msg – Pointer to the previously received message.

static inline uint64_t SimbricksBaseIfInTimestamp(struct SimbricksBaseIf *base_if)#

Message timestamp of the next. Valid only after a poll failed because of a future timestamp.

Parameters:: base_if – Base interface handle (connected).
Returns:: Input timestamp.

static inline int SimbricksBaseIfInTerminated(struct SimbricksBaseIf *base_if)#

Check if incoming channel has been terminated by peer.

Parameters:: base_if – Base interface handle (connected).

static union SimbricksProtoBaseMsg *SimbricksBaseIfOutAlloc(struct SimbricksBaseIf *base_if, uint64_t timestamp)#

Allocate a new message in the queue. Must be followed by a call to SimbricksBaseIfOutSend.

Parameters:

base_if – Base interface handle (connected).
timestamp – Current timestamp (in picoseconds).

Returns:

Pointer to the message struct if successful, NULL otherwise.

static inline void SimbricksBaseIfOutSend(struct SimbricksBaseIf *base_if, volatile union SimbricksProtoBaseMsg *msg, uint8_t msg_type)#

Send out a fully filled message. Sets the message type and ownership flag. Also acts as a compiler barrier to avoid other writes to the message being reordered after this.

Parameters:

base_if – Base interface handle (connected).
msg – Pointer to the previously allocated and fully initialized message (other than the type.).
msg_type – Message type to set (without ownership flag).

static inline int SimbricksBaseIfOutSync(struct SimbricksBaseIf *base_if, uint64_t timestamp)#

Send a synchronization dummy message if necessary.

Parameters:

base_if – Base interface handle (connected).
timestamp – Current timestamp (in picoseconds).

Returns:

0 if sync successfully sent or sync was unnecessary, -1 if a necessary sync message could not be sent because the queue is full.

static inline uint64_t SimbricksBaseIfOutNextSync(struct SimbricksBaseIf *base_if)#

Timestamp when the next sync or data packet must be sent.

Parameters:: base_if – Base interface handle (connected).
Returns:: Timestamp. Undefined if synchronization is disabled.

static inline size_t SimbricksBaseIfOutMsgLen(struct SimbricksBaseIf *base_if)#

Retrieve maximal total message length for outgoing messages.

Parameters:: base_if – Base interface handle (connected).
Returns:: Maximal message length in bytes.

static inline bool SimbricksBaseIfSyncEnabled(struct SimbricksBaseIf *base_if)#

Check if synchronization is enabled for this connection.

Parameters:: base_if – Base interface handle (connected).
Returns:: true if synchronized, false otherwise.

struct SimbricksBaseIfSHMPool#

#include <if.h>

Handle for a SHM pool. Treat as opaque.

Public Members

const char *path#

int fd#

void *base#

size_t size#

size_t pos#

struct SimbricksBaseIfParams#

#include <if.h>

Parameters for a SimBricks interface

Public Members

uint64_t link_latency#: Link latency/propagation delay [picoseconds]

uint64_t sync_interval#: Maximum gap between sync messages [picoseconds]

const char *sock_path#: Unix socket path to listen on/connect to

enum SimbricksBaseIfSyncMode sync_mode#: Synchronization mode: disabled, optional, required

bool blocking_conn#: for connecters and listeners choose blocking vs. non-blocking.

size_t in_num_entries#: For listeners: Number of entries in incoming queue

size_t in_entries_size#: For listeners: Size of individual entries in incoming queue

size_t out_num_entries#: For listeners: Number of entries in outgoing queue

size_t out_entries_size#: For listeners: Size of individual entries in outgoing queue

uint64_t upper_layer_proto#

struct SimbricksBaseIf#

#include <if.h>

Handle for a SimBricks base interface. Treat as opaque.

Public Members

void *in_queue#

size_t in_pos#

size_t in_elen#

size_t in_enum#

uint64_t in_timestamp#

void *out_queue#

size_t out_pos#

size_t out_elen#

size_t out_enum#

uint64_t out_timestamp#

bool in_terminated#

int conn_state#

int sync#

struct SimbricksBaseIfParams params#

struct SimbricksBaseIfSHMPool *shm#

int listen_fd#

int conn_fd#

bool listener#

struct SimBricksBaseIfEstablishData#

Public Members

struct SimbricksBaseIf *base_if#

const void *tx_intro#

size_t tx_intro_len#

void *rx_intro#

size_t rx_intro_len#

4.5.1.2. Generic Interface#

Defines

SIMBRICKS_BASEIF_GENERIC(prefix, msg_union, if_struct)#

Generates static inline functions specialized for message types of a specific SimBricks protocol. These are thin wrappers around the baseif functions but insert appropriate casts.

Generates the following function with the specified prefix:

In: prefixInPeek (wraps SimbricksBaseIfInPeek)
In: prefixInPoll (wraps SimbricksBaseIfInPoll)
In: prefixInType (wraps SimbricksBaseIfInType)
In: prefixInDone (wraps SimbricksBaseIfInDone)
In: prefixInTimestamp (wraps SimbricksBaseIfInTimestamp)
Out: prefixOutAlloc (wraps SimbricksBaseIfOutAlloc)
Out: prefixOutSend (wraps SimbricksBaseIfOutSend)
Out: prefixOutSync (wraps SimbricksBaseIfOutSync)
Out: prefixOutNextSync (wraps SimbricksBaseIfOutNextSync)
Out: prefixOutMsgLen (wraps SimBricksBaseIfOutMsgLen)

Parameters:

prefix – Name prefix for all the functions
msg_union – Union name for the message type of the protocol. (not including the “union” keyword).
if_struct – Interfacing struct, (member base must be struct SimBricksBaseIf).

4.5.1.3. Protocol#

Defines

SIMBRICKS_PROTO_MSG_SZCHECK(s)#

SIMBRICKS_PROTO_VERSION#

SIMBRICKS_PROTO_ID_BASE#

SIMBRICKS_PROTO_ID_NET#

SIMBRICKS_PROTO_ID_PCIE#

SIMBRICKS_PROTO_ID_MEM#

SIMBRICKS_PROTO_FLAGS_LI_SYNC#: Listener requests synchronization

SIMBRICKS_PROTO_FLAGS_LI_SYNC_FORCE#: Listener forces synchronization

SIMBRICKS_PROTO_FLAGS_CO_SYNC#: Connecter has synchronization enabled

SIMBRICKS_PROTO_FLAGS_CO_SYNC_FORCE#: Connecter forces synchronization

SIMBRICKS_PROTO_MSG_OWN_MASK#: Mask for ownership bit in own_type field

SIMBRICKS_PROTO_MSG_OWN_PRO#: Message is owned by producer

SIMBRICKS_PROTO_MSG_OWN_CON#: Message is owned by consumer

SIMBRICKS_PROTO_MSG_TYPE_MASK#: Mask for messsage type in own_type field

SIMBRICKS_PROTO_MSG_TYPE_SYNC#: Pure Sync Message, no upper layer data

SIMBRICKS_PROTO_MSG_TYPE_TERMINATE#: Peer Termination Message, no upper layer data

SIMBRICKS_PROTO_MSG_TYPE_UPPER_START#: first message type reserved for upper layer protocols

SIMBRICKS_PROTO_SYNC_SIMBRICKS#

SIMBRICKS_PROTO_SYNC_BARRIER#

Functions

struct SimbricksProtoListenerIntro __attribute__ ((packed))

SIMBRICKS_PROTO_MSG_SZCHECK(struct SimbricksProtoBaseMsgHeader)#

SIMBRICKS_PROTO_MSG_SZCHECK(union SimbricksProtoBaseMsg)#

Variables

uint64_t version#: simbricks protocol version

uint64_t flags#

flags: see SIMBRICKS_PROTO_FLAGS_LI_*

flags: see SIMBRICKS_PROTO_FLAGS_CO_*

flags (see SIMBRICKS_PROTO_PCIE_BAR_*)

uint64_t l2c_offset#: offset of the listener-to-connecter queue in shared memory region

uint64_t l2c_elen#: size of an entry in the listener-to-connecter queue in bytes

uint64_t l2c_nentries#: total listener-to-connecter queue length in #entries

uint64_t c2l_offset#: offset of the connecter-to-listener queue in shared memory region

uint64_t c2l_elen#: size of an entry in the host-to-device queue in bytes

uint64_t c2l_nentries#: total host-to-device queue length in #entries

uint64_t upper_layer_proto#: upper layer protocol identifier: see SIMBRICKS_PROTO_ID_*

uint64_t upper_layer_intro_off#: offset of upper layer intro from beginning of this message

uint8_t pad[48]#

uint64_t timestamp#

uint8_t pad_[7]#

uint8_t own_type#

struct SimbricksProtoBaseMsgHeader header#

struct SimbricksProtoBaseMsgHeader sync#

struct SimbricksProtoBaseMsgHeader terminate#

struct SimbricksProtoListenerIntro#

#include <proto.h>

Welcome message that the listener sends to the connector on the unix socket. The message specifies if and what synchronization is enabled, the shared memory queues information, and information on the upper layer protocol. The message on the Unix socket also includes the shared memory file descriptor with this message. Finally the intro also contains the upper-layer intro.

Public Members

uint64_t version#: simbricks protocol version

uint64_t flags#: flags: see SIMBRICKS_PROTO_FLAGS_LI_*

uint64_t l2c_offset#: offset of the listener-to-connecter queue in shared memory region

uint64_t l2c_elen#: size of an entry in the listener-to-connecter queue in bytes

uint64_t l2c_nentries#: total listener-to-connecter queue length in #entries

uint64_t c2l_offset#: offset of the connecter-to-listener queue in shared memory region

uint64_t c2l_elen#: size of an entry in the host-to-device queue in bytes

uint64_t c2l_nentries#: total host-to-device queue length in #entries

uint64_t upper_layer_proto#: upper layer protocol identifier: see SIMBRICKS_PROTO_ID_*

uint64_t upper_layer_intro_off#: offset of upper layer intro from beginning of this message

struct SimbricksProtoConnecterIntro#

Public Members

uint64_t version#: simbricks protocol version

uint64_t flags#: flags: see SIMBRICKS_PROTO_FLAGS_CO_*

uint64_t upper_layer_proto#: upper layer protocol identifier: see SIMBRICKS_PROTO_ID_*

uint64_t upper_layer_intro_off#: offset of upper layer intro from beginning of this message

struct SimbricksProtoBaseMsgHeader#

Public Members

uint8_t pad[48]#

uint64_t timestamp#

uint8_t pad_[7]#

uint8_t own_type#

union SimbricksProtoBaseMsg#

Public Members

struct SimbricksProtoBaseMsgHeader header#

struct SimbricksProtoBaseMsgHeader sync#

struct SimbricksProtoBaseMsgHeader terminate#