cdi_core_api.h

Go to the documentation of this file.

// -------------------------------------------------------------------------------------------
// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
// This file is part of the AWS CDI-SDK, licensed under the BSD 2-Clause "Simplified" License.
// License details at: https://github.com/aws/aws-cdi-sdk/blob/mainline/LICENSE
// -------------------------------------------------------------------------------------------
 
#ifndef CDI_CORE_API_H__
#define CDI_CORE_API_H__
 
// Doxygen for CDI-CORE
/*
 * With older distros (Ubuntu 16.04 in particular), "struct timespec" often is undefined prior to references to it.
 * C source files likely include time.h indirectly and sometimes directly prior to its inclusion below and if
 * _POSIX_C_SOURCE is undefined or defined to be less than 200112L, it does not get defined through the inclusion here.
 * The only solution is to ensure that it is defined with the required value early in each compilation unit.
 *
 * The block below ensures that _POSIX_C_SOURCE is defined with a value of 200112L or greater, erring out if not.
 */
#if !defined(_POSIX_C_SOURCE)
#define _POSIX_C_SOURCE 200112L
#else
#if _POSIX_C_SOURCE < 200112L
/*
 * If the compiler hits this #error, define _POSIX_C_SOURCE to the value 200112L or a newer supported value in the
 * definitions passed in from the command line.
 */
#error _POSIX_C_SOURCE must be >= 200112L
#endif  // _POSIX_C_SOURCE < 200112L
#endif  // !defined(_POSIX_C_SOURCE)
 
#include <stdbool.h>
#include <stdint.h>
#include <time.h>
 
#include "cdi_log_enums.h"
#include "cdi_utility_api.h"
 
//*********************************************************************************************************************
//***************************************** START OF DEFINITIONS AND TYPES ********************************************
//*********************************************************************************************************************
 
// NOTE: Do not change the ordering of the three defines below. They are used internally by the CDI SDK makefile or
// scripts to extract version information.
 
#define CDI_SDK_VERSION             3
 
#define CDI_SDK_MAJOR_VERSION       0
 
#define CDI_SDK_MINOR_VERSION       2
 
#define CDI_PROTOCOL_VERSION             2
 
#define CDI_PROTOCOL_MAJOR_VERSION       3
 
#define CDI_PROBE_VERSION                5
 
#define CDI_MAX_SIMULTANEOUS_CONNECTIONS                (30)
 
#define CDI_MAX_ENDPOINTS_PER_CONNECTION                (5)
 
#define CDI_MAX_SIMULTANEOUS_TX_PAYLOADS_PER_CONNECTION  (8)
 
#define CDI_MAX_SIMULTANEOUS_TX_PAYLOAD_SGL_ENTRIES_PER_CONNECTION   (CDI_MAX_SIMULTANEOUS_TX_PAYLOADS_PER_CONNECTION*3500)
 
#define CDI_MAX_SIMULTANEOUS_RX_PAYLOADS_PER_CONNECTION  (32)
 
#define CDI_MAX_RX_PAYLOAD_OUT_OF_ORDER_BUFFER          (8192)
 
#define CDI_MAX_RX_PACKET_OUT_OF_ORDER_WINDOW           (5000)
 
#define CDI_MAX_CONNECTION_NAME_STRING_LENGTH           (128)
 
#define CDI_MAX_STREAM_NAME_STRING_LENGTH               (CDI_MAX_CONNECTION_NAME_STRING_LENGTH+10)
 
#define CDI_MAX_LOG_FILENAME_LENGTH                     (1024)
 
#define CDI_ENABLED_RX_BUFFER_DELAY_DEFAULT_MS          (67)
 
#define CDI_MAXIMUM_RX_BUFFER_DELAY_MS                  (100)
 
#define CDI_RX_BUFFER_DELAY_BUFFER_MS_DIVISOR           (10)
 
// Declare forward references for internal structures that are not directly available through the API.
struct CdiAdapterState;
struct CdiConnectionState;
struct CdiMemoryState;
typedef struct CdiLogMethodData CdiLogMethodData;
 
typedef struct CdiAdapterState* CdiAdapterHandle;
 
typedef struct CdiConnectionState* CdiConnectionHandle;
 
typedef struct CdiEndpointState* CdiEndpointHandle;
 
typedef struct CdiMemoryState* CdiMemoryHandle;
 
typedef void* CdiUserCbParameter;
 
typedef enum {
    kCdiStatusOk                    = 0,
 
    kCdiStatusFatal                 = 1,
 
    kCdiStatusNotEnoughMemory       = 2,
 
    kCdiStatusNotInitialized        = 3,
 
    kCdiStatusMaxLatencyExceeded    = 4,
 
    kCdiStatusInvalidHandle         = 5,
 
    kCdiStatusInvalidParameter      = 6,
 
    kCdiStatusNotConnected          = 7,
 
    kCdiStatusQueueFull             = 8,
 
    kCdiStatusInvalidConnectionType = 9,
 
    kCdiStatusRxPayloadError        = 10,
 
    kCdiStatusRxWrongProtocolType   = 11,
 
    kCdiStatusCreateLogFailed       = 12,
 
    kCdiStatusCreateThreadFailed    = 13,
 
    kCdiStatusShuttingDown          = 14,
 
    kCdiStatusWrongDirection        = 15,
 
    kCdiStatusGetPortFailed         = 16,
 
    kCdiStatusNotReady              = 17,
 
    kCdiStatusSendFailed            = 18,
 
    kCdiStatusAllocationFailed      = 19,
 
    kCdiStatusOpenFailed            = 20,
 
    kCdiStatusDuplicateConnection   = 21,
 
    kCdiStatusInvalidSgl            = 22,
 
    kCdiStatusEndpointManagerState  = 23,
 
    kCdiStatusBufferOverflow        = 24,
 
    kCdiStatusRxPayloadMissing      = 25,
 
    kCdiStatusArraySizeExceeded     = 26,
 
    kCdiStatusNonFatal              = 27,
 
    kCdiStatusCloudWatchNotEnabled  = 28,
 
    kCdiStatusCloudWatchThrottling  = 29,
 
    kCdiStatusCloudWatchInvalidCredentials = 30,
 
    kCdiStatusInternalIdle          = 31,
 
    kCdiStatusAdapterDuplicateEntry = 32,
 
    kCdiStatusProfileNotSupported   = 33,
 
    kCdiStatusProbePacketCrcError   = 34,
 
    kCdiStatusProbePacketInvalidSize = 35,
 
    kCdiStatusRxPayloadBackPressure  = 36,
 
    kCdiStatusDuplicateBaselineVersion = 37,
 
    kCdiStatusInvalidPayload        = 38,
 
    kCdiStatusLibraryLoadFailed     = 39,
 
    kCdiStatusLibrarySymbolNotFound = 40,
 
    kCdiStatusLibraryWrongVersion   = 41,
 
    kCdiStatusRetry                 = 42,
} CdiReturnStatus;
 
//typedef struct CdiPtpTimestamp CdiPtpTimestamp;
typedef struct CdiPtpTimestamp {
    uint32_t seconds;
    uint32_t nanoseconds;
} CdiPtpTimestamp;
 
typedef struct {
    CdiPtpTimestamp origination_ptp_timestamp;
 
    uint64_t payload_user_data;
} CdiCoreExtraData;
 
typedef struct {
    CdiCoreExtraData core_extra_data;
 
    CdiUserCbParameter user_cb_param;
 
    int unit_size;
} CdiCoreTxPayloadConfig;
 
typedef enum {
    kCdiConnectionStatusDisconnected, 
    kCdiConnectionStatusConnected,    
} CdiConnectionStatus;
 
typedef struct {
    CdiConnectionStatus status_code;
 
    const char* err_msg_str;
 
    CdiEndpointHandle tx_stream_endpoint_handle;
 
    const char* remote_ip_str; 
    int remote_dest_port; 
 
    CdiUserCbParameter connection_user_cb_param;
 
    uint8_t negotiated_version_num;
    uint8_t negotiated_major_version_num; 
    uint8_t negotiated_probe_version_num; 
} CdiCoreConnectionCbData;
 
typedef void (*CdiCoreConnectionCallback)(const CdiCoreConnectionCbData* data_ptr);
 
typedef struct {
    CdiReturnStatus status_code;
 
    const char* err_msg_str;
 
    CdiConnectionHandle connection_handle;
 
    CdiCoreExtraData core_extra_data;
 
    CdiUserCbParameter user_cb_param;
} CdiCoreCbData;
 
typedef enum {
    kCdiAdapterTypeEfa,
    kCdiAdapterTypeSocket,
 
    kCdiAdapterTypeSocketLibfabric
} CdiAdapterTypeSelection;
 
typedef struct {
    const char* adapter_ip_addr_str;
 
    uint64_t tx_buffer_size_bytes;
 
    void* ret_tx_buffer_ptr;
 
    CdiAdapterTypeSelection adapter_type;
} CdiAdapterData;
 
typedef struct {
    uint64_t num_payloads_transferred;
 
    uint64_t num_payloads_dropped;
 
    uint64_t num_payloads_late;
 
    uint64_t num_bytes_transferred;
} CdiPayloadCounterStats;
 
typedef struct {
    uint32_t transfer_time_min;
 
    uint32_t transfer_time_max;
 
    int transfer_count;
 
    uint64_t transfer_time_sum;
 
    uint32_t transfer_time_P50;
 
    uint32_t transfer_time_P90;
 
    uint32_t transfer_time_P99;
} CdiPayloadTimeIntervalStats;
 
typedef struct {
    uint32_t dropped_connection_count;
 
    uint32_t probe_command_retry_count;
 
    int poll_thread_load;
 
    bool connected; 
} CdiAdapterEndpointStats;
 
typedef struct {
    uint64_t timestamp_in_ms_since_epoch;
 
    char stream_name_str[CDI_MAX_STREAM_NAME_STRING_LENGTH];
 
    CdiPayloadCounterStats payload_counter_stats; 
    CdiPayloadTimeIntervalStats payload_time_interval_stats; 
    CdiAdapterEndpointStats endpoint_stats; 
} CdiTransferStats;
 
typedef struct {
    int stats_count; 
    CdiTransferStats* transfer_stats_array; 
 
    CdiUserCbParameter stats_user_cb_param;
} CdiCoreStatsCbData;
 
typedef void (*CdiCoreStatsCallback)(const CdiCoreStatsCbData* data_ptr);
 
typedef struct {
    uint32_t stats_period_seconds;
 
    bool disable_cloudwatch_stats;
} CdiStatsConfigData;
 
typedef struct {
    CdiAdapterHandle adapter_handle;
 
    const char* dest_ip_addr_str;
 
    int dest_port;
 
    const char* bind_ip_addr_str;
 
    int shared_thread_id;
 
    int thread_core_num;
 
    int max_simultaneous_tx_payloads;
 
    int max_simultaneous_tx_payload_sgl_entries;
 
    const char* connection_name_str;
 
    CdiLogMethodData* connection_log_method_data_ptr;
 
    CdiCoreConnectionCallback connection_cb_ptr;
 
    CdiUserCbParameter connection_user_cb_param;
 
    CdiCoreStatsCallback stats_cb_ptr;
 
    CdiUserCbParameter stats_user_cb_param;
 
    CdiStatsConfigData stats_config;
} CdiTxConfigData;
 
typedef struct CdiSglEntry CdiSglEntry;
struct CdiSglEntry {
    void* address_ptr;
 
    int size_in_bytes;
 
    void* internal_data_ptr;
 
    CdiSglEntry* next_ptr;
};
 
typedef struct {
    int total_data_size;
 
    CdiSglEntry* sgl_head_ptr;
 
    CdiSglEntry* sgl_tail_ptr;
 
    void* internal_data_ptr;
} CdiSgList;
 
typedef enum {
    kCdiLinearBuffer       = 0,
 
    kCdiSgl                = 1,
} CdiBufferType;
 
typedef struct {
    CdiAdapterHandle adapter_handle;
 
    int dest_port;
 
    const char* bind_ip_addr_str;
 
    int shared_thread_id;
 
    int thread_core_num;
 
    CdiBufferType rx_buffer_type;
 
    int buffer_delay_ms;
 
    uint64_t linear_buffer_size;
 
    int max_simultaneous_rx_payloads_per_connection;
 
    CdiUserCbParameter user_cb_param;
 
    const char* connection_name_str;
 
    CdiLogMethodData* connection_log_method_data_ptr;
 
    CdiCoreConnectionCallback connection_cb_ptr;
 
    CdiUserCbParameter connection_user_cb_param;
 
    CdiCoreStatsCallback stats_cb_ptr;
 
    CdiUserCbParameter stats_user_cb_param;
 
    CdiStatsConfigData stats_config;
} CdiRxConfigData;
 
typedef struct {
    const char* namespace_str;
 
    const char* region_str;
 
    const char* dimension_domain_str;
} CdiCloudWatchConfigData;
 
typedef struct {
    CdiLogLevel default_log_level;
 
    const CdiLogMethodData* global_log_method_data_ptr;
 
    const CdiCloudWatchConfigData* cloudwatch_config_ptr;
} CdiCoreConfigData;
 
typedef struct {
    uint64_t tx_retry_timeout_ms;
 
    uint64_t rx_wait_timeout_ms;
} CdiCoreReadOnlySettings;
 
//*********************************************************************************************************************
//******************************************* START OF PUBLIC FUNCTIONS ***********************************************
//*********************************************************************************************************************
 
CDI_INTERFACE CdiReturnStatus CdiCoreInitialize(const CdiCoreConfigData* core_config_ptr);
 
CDI_INTERFACE CdiReturnStatus CdiCoreNetworkAdapterInitialize(CdiAdapterData* adapter_data_ptr,
                                                              CdiAdapterHandle* ret_handle_ptr);
 
CDI_INTERFACE CdiReturnStatus CdiCoreNetworkAdapterDestroy(CdiAdapterHandle handle);
 
CDI_INTERFACE CdiReturnStatus CdiCoreRxFreeBuffer(const CdiSgList* sgl_ptr);
 
CDI_INTERFACE int CdiCoreGather(const CdiSgList* sgl_ptr, int offset, void* dest_data_ptr, int byte_count);
 
CDI_INTERFACE CdiReturnStatus CdiCoreStatsReconfigure(CdiConnectionHandle handle, const CdiStatsConfigData* config_ptr);
 
CDI_INTERFACE CdiReturnStatus CdiCoreConnectionDestroy(CdiConnectionHandle handle);
 
CDI_INTERFACE CdiReturnStatus CdiCoreShutdown(void);
 
CDI_INTERFACE void CdiCoreGetUtcTime(struct timespec* ret_time_ptr);
 
CDI_INTERFACE CdiPtpTimestamp CdiCoreGetPtpTimestamp(CdiPtpTimestamp* ret_ptp_time_ptr);
 
CDI_INTERFACE uint64_t CdiCoreGetUtcTimeMicroseconds(void);
 
CDI_INTERFACE uint64_t CdiCoreGetTaiTimeMicroseconds();
 
CDI_INTERFACE const char* CdiCoreStatusToString(CdiReturnStatus status);
 
CDI_INTERFACE const CdiCoreReadOnlySettings* CdiCoreGetSettings();
 
#endif // CDI_CORE_API_H__