doca_comch.h

Go to the documentation of this file.

/*
 * Copyright (c) 2023 NVIDIA CORPORATION & AFFILIATES, ALL RIGHTS RESERVED.
 *
 * This software product is a proprietary product of NVIDIA CORPORATION &
 * AFFILIATES (the "Company") and all right, title, and interest in and to the
 * software product, including all associated intellectual property rights, are
 * and shall remain exclusively with the Company.
 *
 * This software product is governed by the End User License Agreement
 * provided with the software product.
 *
 */
 
#ifndef DOCA_COMCH_H_
#define DOCA_COMCH_H_
 
#include <stddef.h>
#include <stdint.h>
 
#include <doca_compat.h>
#include <doca_error.h>
#include <doca_types.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct doca_dev;
struct doca_dev_rep;
struct doca_devinfo;
 
/*********************************************************************************************************************
 * DOCA Comch Connection
 *********************************************************************************************************************/
 
/* Representantion of a comms channel point to point connection */
struct doca_comch_connection;
 
DOCA_STABLE
doca_error_t doca_comch_connection_set_user_data(struct doca_comch_connection *connection, union doca_data user_data);
 
DOCA_STABLE
union doca_data doca_comch_connection_get_user_data(const struct doca_comch_connection *connection);
 
DOCA_STABLE
struct doca_comch_server *doca_comch_server_get_server_ctx(const struct doca_comch_connection *connection);
 
DOCA_STABLE
struct doca_comch_client *doca_comch_client_get_client_ctx(const struct doca_comch_connection *connection);
 
/*********************************************************************************************************************
 * DOCA Comch General Capabilities
 *********************************************************************************************************************/
 
DOCA_STABLE
doca_error_t doca_comch_cap_get_max_name_len(const struct doca_devinfo *devinfo, uint32_t *max_name_len);
 
DOCA_STABLE
doca_error_t doca_comch_cap_get_max_msg_size(const struct doca_devinfo *devinfo, uint32_t *size);
 
DOCA_STABLE
doca_error_t doca_comch_cap_get_max_recv_queue_size(const struct doca_devinfo *devinfo, uint32_t *size);
 
DOCA_STABLE
doca_error_t doca_comch_cap_get_max_clients(const struct doca_devinfo *devinfo, uint32_t *num_clients);
 
/*********************************************************************************************************************
 * DOCA Comch server Context
 *********************************************************************************************************************/
 
/* DOCA Comch server end point instance */
struct doca_comch_server;
 
DOCA_STABLE
doca_error_t doca_comch_server_create(struct doca_dev *dev,
                      struct doca_dev_rep *repr,
                      const char *name,
                      struct doca_comch_server **comch_server);
 
DOCA_STABLE
doca_error_t doca_comch_server_destroy(struct doca_comch_server *comch_server);
 
DOCA_STABLE
doca_error_t doca_comch_cap_server_is_supported(const struct doca_devinfo *devinfo);
 
DOCA_STABLE
doca_error_t doca_comch_server_set_max_msg_size(struct doca_comch_server *comch_server, uint32_t size);
 
DOCA_STABLE
doca_error_t doca_comch_server_get_max_msg_size(const struct doca_comch_server *comch_server, uint32_t *size);
 
DOCA_STABLE
doca_error_t doca_comch_server_set_recv_queue_size(struct doca_comch_server *comch_server, uint32_t size);
 
DOCA_STABLE
doca_error_t doca_comch_server_get_recv_queue_size(const struct doca_comch_server *comch_server, uint32_t *size);
 
DOCA_STABLE
doca_error_t doca_comch_server_get_device(const struct doca_comch_server *comch_server, struct doca_dev **dev);
 
DOCA_STABLE
doca_error_t doca_comch_server_get_device_rep(const struct doca_comch_server *comch_server, struct doca_dev_rep **rep);
 
DOCA_STABLE
struct doca_ctx *doca_comch_server_as_ctx(struct doca_comch_server *comch_server);
 
DOCA_STABLE
doca_error_t doca_comch_server_disconnect(struct doca_comch_server *comch_server,
                      struct doca_comch_connection *connection);
 
/*********************************************************************************************************************
 * DOCA Comch Client Context
 *********************************************************************************************************************/
 
/* DOCA Comch Client end point instance */
struct doca_comch_client;
 
DOCA_STABLE
doca_error_t doca_comch_client_create(struct doca_dev *dev, const char *name, struct doca_comch_client **comch_client);
 
DOCA_STABLE
doca_error_t doca_comch_client_destroy(struct doca_comch_client *comch_client);
 
DOCA_STABLE
doca_error_t doca_comch_cap_client_is_supported(const struct doca_devinfo *devinfo);
 
DOCA_STABLE
doca_error_t doca_comch_client_set_max_msg_size(struct doca_comch_client *comch_client, uint32_t size);
 
DOCA_STABLE
doca_error_t doca_comch_client_get_max_msg_size(const struct doca_comch_client *comch_client, uint32_t *size);
 
DOCA_STABLE
doca_error_t doca_comch_client_set_recv_queue_size(struct doca_comch_client *comch_client, uint32_t size);
 
DOCA_STABLE
doca_error_t doca_comch_client_get_recv_queue_size(const struct doca_comch_client *comch_client, uint32_t *size);
 
DOCA_STABLE
doca_error_t doca_comch_client_get_device(const struct doca_comch_client *comch_client, struct doca_dev **dev);
 
DOCA_STABLE
struct doca_ctx *doca_comch_client_as_ctx(struct doca_comch_client *comch_client);
 
DOCA_STABLE
doca_error_t doca_comch_client_get_connection(const struct doca_comch_client *comch_client,
                          struct doca_comch_connection **connection);
 
/*********************************************************************************************************************
 * DOCA Comch - Send Task
 *********************************************************************************************************************/
 
/* Task instance to send a message on the control channel */
struct doca_comch_task_send;
 
typedef void (*doca_comch_task_send_completion_cb_t)(struct doca_comch_task_send *task,
                             union doca_data task_user_data,
                             union doca_data ctx_user_data);
 
DOCA_STABLE
doca_error_t doca_comch_cap_get_max_send_tasks(const struct doca_devinfo *devinfo, uint32_t *max_send_tasks);
 
DOCA_STABLE
doca_error_t doca_comch_server_task_send_set_conf(struct doca_comch_server *comch_server,
                          doca_comch_task_send_completion_cb_t task_completion_cb,
                          doca_comch_task_send_completion_cb_t task_error_cb,
                          uint32_t num_send_tasks);
 
DOCA_STABLE
doca_error_t doca_comch_client_task_send_set_conf(struct doca_comch_client *comch_client,
                          doca_comch_task_send_completion_cb_t task_completion_cb,
                          doca_comch_task_send_completion_cb_t task_error_cb,
                          uint32_t num_send_tasks);
 
DOCA_STABLE
doca_error_t doca_comch_server_task_send_alloc_init(struct doca_comch_server *comch_server,
                            struct doca_comch_connection *peer,
                            const void *msg,
                            uint32_t len,
                            struct doca_comch_task_send **task);
 
DOCA_STABLE
doca_error_t doca_comch_client_task_send_alloc_init(struct doca_comch_client *comch_client,
                            struct doca_comch_connection *peer,
                            const void *msg,
                            uint32_t len,
                            struct doca_comch_task_send **task);
 
DOCA_STABLE
struct doca_task *doca_comch_task_send_as_task(struct doca_comch_task_send *task);
 
/*********************************************************************************************************************
 * DOCA Comch - Receive Message Event Registration
 *********************************************************************************************************************/
 
/* Async event instance for receiving a message from a connected endpoint */
struct doca_comch_event_msg_recv;
 
typedef void (*doca_comch_event_msg_recv_cb_t)(struct doca_comch_event_msg_recv *event,
                           uint8_t *recv_buffer,
                           uint32_t msg_len,
                           struct doca_comch_connection *comch_connection);
 
DOCA_STABLE
doca_error_t doca_comch_server_event_msg_recv_register(struct doca_comch_server *comch_server,
                               doca_comch_event_msg_recv_cb_t recv_event_cb);
 
DOCA_STABLE
doca_error_t doca_comch_client_event_msg_recv_register(struct doca_comch_client *comch_client,
                               doca_comch_event_msg_recv_cb_t recv_event_cb);
 
/*********************************************************************************************************************
 * DOCA Comch - Connection Event Registration
 *********************************************************************************************************************/
 
/* Async event instance for a connection status change */
struct doca_comch_event_connection_status_changed;
 
typedef void (*doca_comch_event_connection_status_changed_cb_t)(struct doca_comch_event_connection_status_changed *event,
                                struct doca_comch_connection *comch_connection,
                                uint8_t change_successful);
 
DOCA_STABLE
doca_error_t doca_comch_server_event_connection_status_changed_register(
    struct doca_comch_server *comch_server,
    doca_comch_event_connection_status_changed_cb_t connect_event_cb,
    doca_comch_event_connection_status_changed_cb_t disconnect_event_cb);
 
/*********************************************************************************************************************
 * DOCA Comch - Connection Statistics
 *********************************************************************************************************************/
 
enum doca_comch_counter {
    DOCA_COMCH_COUNTER_SENT_MESSAGES = 1, /* total messages sent over a given comch_connection from local side. */
    DOCA_COMCH_COUNTER_SENT_BYTES = 2,    /* total bytes sent over a given comch_connection from local side. */
    DOCA_COMCH_COUNTER_RECV_MESSAGES = 3, /* total messages received on local side over a given comch_connection. */
    DOCA_COMCH_COUNTER_RECV_BYTES = 4,    /* total bytes received on local side over a given comch_connection. */
};
 
DOCA_STABLE
doca_error_t doca_comch_connection_update_info(struct doca_comch_connection *comch_connection);
 
DOCA_STABLE
doca_error_t doca_comch_connection_get_counter(const struct doca_comch_connection *comch_connection,
                           enum doca_comch_counter counter_type,
                           uint64_t *counter_value);
 
/*********************************************************************************************************************
 * DOCA Comch - Consumer Event Registration
 *********************************************************************************************************************/
 
/* Async event instance for a consumer change*/
struct doca_comch_event_consumer;
 
typedef void (*doca_comch_event_consumer_cb_t)(struct doca_comch_event_consumer *event,
                           struct doca_comch_connection *comch_connection,
                           uint32_t id);
 
DOCA_STABLE
doca_error_t doca_comch_server_event_consumer_register(struct doca_comch_server *comch_server,
                               doca_comch_event_consumer_cb_t new_consumer_event_cb,
                               doca_comch_event_consumer_cb_t expired_consumer_event_cb);
 
DOCA_STABLE
doca_error_t doca_comch_client_event_consumer_register(struct doca_comch_client *comch_client,
                               doca_comch_event_consumer_cb_t new_consumer_event_cb,
                               doca_comch_event_consumer_cb_t expired_consumer_event_cb);
 
#ifdef __cplusplus
}
#endif
 
#endif /* DOCA_COMCH_H_ */