|
CDI SDK
SDK for transporting chunks of data reliably and with low latency using a polled mode network driver.
|
This file declares the public API data types, structures and functions that comprise the CDI low-level transport SDK API. More...
#include <stdbool.h>#include <stdint.h>#include <time.h>#include "cdi_log_enums.h"#include "cdi_utility_api.h"Go to the source code of this file.
Data Structures | |
| struct | CdiPtpTimestamp |
| A structure for holding a PTP timestamp defined in seconds and nanoseconds. This PTP time as defined by SMPTE ST 2059-2 and IEEE 1588-2008 with the exception that the seconds field is an unsigned 32 bit integer instead of the specified 48 bit integer. More... | |
| struct | CdiCoreExtraData |
| Extra data that is sent along with payloads to the receiver. It will be provided to the receiver through registered user receive data callback functions. More... | |
| struct | CdiCoreTxPayloadConfig |
| A structure used to configure a transmit payload. More... | |
| struct | CdiCoreConnectionCbData |
| A structure of this type is passed as the parameter to CdiCoreConnectionCallback(). It contains data related to the status of a single connection. More... | |
| struct | CdiCoreCbData |
| A structure of this type is passed as part of the data to the TX/RX registered user callback functions. It contains data related to the transmission of a single payload. More... | |
| struct | CdiAdapterData |
| Configuration data used by the CdiCoreNetworkAdapterInitialize() API function. More... | |
| struct | CdiPayloadCounterStats |
| Transfer statistics data specific to payloads that contain counters that increment for the duration of the connection. They are never reset. More... | |
| struct | CdiPayloadTimeIntervalStats |
| Transfer statistics data specific to payloads that are reset at the start of each time interval as specified using CdiStatsConfigData.stats_period_seconds. A snapshot of the current values is made and provided through the user-registered callback function CdiCoreStatsCallback(). More... | |
| struct | CdiAdapterEndpointStats |
| Transfer statistics data specific to an adapter endpoint. Used in the CdiTransferStats structure as a parameter of the user-registered CdiCoreStatsCallback() API function. More... | |
| struct | CdiTransferStats |
| Transfer statistics data. Used as a parameter of the user-registered CdiCoreStatsCallback() API function. More... | |
| struct | CdiCoreStatsCbData |
| A structure of this type is passed as the parameter to CdiCoreStatsCallback(). It contains data related to the statistics of a single connection. More... | |
| struct | CdiStatsConfigData |
| A structure that is used to hold statistics gathering configuration data. More... | |
| struct | CdiTxConfigData |
| Configuration data used by one of the Cdi...TxCreate() API functions. More... | |
| struct | CdiSglEntry |
| This structure represents a single, contiguous region of memory as part of a scatter-gather list. More... | |
| struct | CdiSgList |
| This structure defines a scatter-gather list (SGL) which is used to represent an array of data comprising one or more contiguous regions of memory. More... | |
| struct | CdiRxConfigData |
| Configuration data used by one of the Cdi...RxCreate() API functions. More... | |
| struct | CdiCloudWatchConfigData |
| A structure that is used to hold statistics gathering configuration data that is specific to CloudWatch. More... | |
| struct | CdiCoreConfigData |
| SDK configuration data used by the CdiCoreInitialize() API function. More... | |
| struct | CdiCoreReadOnlySettings |
| SDK read-only settings used internally by SDK. More... | |
Macros | |
| #define | _POSIX_C_SOURCE 200112L |
| This define ensures that "struct timespec" is defined prior to using it. | |
| #define | CDI_SDK_VERSION 3 |
| CDI version. | |
| #define | CDI_SDK_MAJOR_VERSION 0 |
| CDI major version. | |
| #define | CDI_SDK_MINOR_VERSION 2 |
| CDI minor version. | |
| #define | CDI_PROTOCOL_VERSION 2 |
| CDI protocol version. | |
| #define | CDI_PROTOCOL_MAJOR_VERSION 3 |
| CDI protocol major version. | |
| #define | CDI_PROBE_VERSION 5 |
| CDI probe command version. Possible value are: For Protocol version 2.0 (CDI_PROTOCOL_VERSION.CDI_PROTOCOL_MAJOR_VERSION): 0: SDK 1.x.x. Only supports protocol version 1.0. 1: not used 2: SDK 2.0.x, Only supports protocol version 1.0 3: SDK 2.1.x. Supports the new protocol version command. See kProbeCommandProtocolVersion. Supports protocols version 1.0 and 2.0. | |
| #define | CDI_MAX_SIMULTANEOUS_CONNECTIONS (30) |
| Define to limit the max number of allowable Tx or Rx connections that can be created in the SDK. | |
| #define | CDI_MAX_ENDPOINTS_PER_CONNECTION (5) |
| Define to limit the max number of allowable Tx or Rx endpoints for a single connection that can be created in the SDK. | |
| #define | CDI_MAX_SIMULTANEOUS_TX_PAYLOADS_PER_CONNECTION (8) |
| Define to limit the max number of allowable payloads that can be simultaneously sent on a single connection in the SDK. NOTE: This value is used to mask the MSBs of array indices so this value must be a power of two. | |
| #define | CDI_MAX_SIMULTANEOUS_TX_PAYLOAD_SGL_ENTRIES_PER_CONNECTION (CDI_MAX_SIMULTANEOUS_TX_PAYLOADS_PER_CONNECTION*3500) |
| Define to limit the max number of allowable payload SGL entries that can be simultaneously sent on a single connection in the SDK. 3500 SGL entries supports 4K at 10-bits packed using 2110-20. | |
| #define | CDI_MAX_SIMULTANEOUS_RX_PAYLOADS_PER_CONNECTION (32) |
| Define to limit the max number of allowable payloads that can be simultaneously received on a single connection in the SDK. This number should be larger than the respective Tx limit since more payloads can potentially be in flight in the receive logic. This is because Tx packets can get acknowledged to the transmitter before being fully processed by the receiver, allowing the transmitter to send more. This number must also be as large or larger than the maximum SRD packet ordering window so that we can be sure we make enough room in our state arrays for tracking all possible payloads that could be in flight at the same time. NOTE: This value must be a power of two because it is used to mask the MSBs of array indices. | |
| #define | CDI_MAX_RX_PAYLOAD_OUT_OF_ORDER_BUFFER (8192) |
| Define the size of the Rx payload buffer used to hold out of order payloads. Value must be a power of 2. Sized to allow receive of 4K RGB 4:4:4 12 bit. | |
| #define | CDI_MAX_RX_PACKET_OUT_OF_ORDER_WINDOW (5000) |
| Define to limit the max number packets of that can arrive out of order and be put back in order. Sized to allow receive of 4K RGB 4:4:4 12 bit. | |
| #define | CDI_MAX_CONNECTION_NAME_STRING_LENGTH (128) |
| Maximum connection name string length. | |
| #define | CDI_MAX_STREAM_NAME_STRING_LENGTH (CDI_MAX_CONNECTION_NAME_STRING_LENGTH+10) |
| Maximum stream name string length. | |
| #define | CDI_MAX_LOG_FILENAME_LENGTH (1024) |
| Maximum log filename string length. | |
| #define | CDI_ENABLED_RX_BUFFER_DELAY_DEFAULT_MS (67) |
| When Rx Buffer delay is enabled using "-1", this is the delay used in milliseconds. This is 4 video frames at 60FPS (4*16.6ms= 66.4ms). This value is the recommended buffer size for transport between instances that are not in a cluster placement group. | |
| #define | CDI_MAXIMUM_RX_BUFFER_DELAY_MS (100) |
| Maximum Rx buffer delay in milliseconds. This is approximately 6 video frames at 60FPS (6*16.6ms= ~100ms). | |
| #define | CDI_RX_BUFFER_DELAY_BUFFER_MS_DIVISOR (10) |
| The millisecond divisor used to calculate how many additional packet buffers to allocate for the Rx buffer. A value of 10 here corresponds to 100FPS (10ms). | |
Typedefs | |
| typedef struct CdiLogMethodData | CdiLogMethodData |
| Forward structure declaration to create pointer to log data when used. | |
| typedef struct CdiAdapterState * | CdiAdapterHandle |
| Type used as the handle (pointer to an opaque structure) for a network adapter. Each handle represents an instance of a network adapter. | |
| typedef struct CdiConnectionState * | CdiConnectionHandle |
| Type used as the handle (pointer to an opaque structure) for a transmitter or receiver connection. Each handle represents a single data flow. | |
| typedef struct CdiEndpointState * | CdiEndpointHandle |
| Type used as the handle (pointer to an opaque structure) for a transmitter or receiver endpoint. Each handle represents a single data flow. | |
| typedef struct CdiMemoryState * | CdiMemoryHandle |
| Type used as the handle (pointer to an opaque structure) for holding private SDK data that relates to memory. | |
| typedef void * | CdiUserCbParameter |
| Type used as user defined data that is passed to the registered user RX/TX callback functions. | |
| typedef struct CdiPtpTimestamp | CdiPtpTimestamp |
| A structure for holding a PTP timestamp defined in seconds and nanoseconds. This PTP time as defined by SMPTE ST 2059-2 and IEEE 1588-2008 with the exception that the seconds field is an unsigned 32 bit integer instead of the specified 48 bit integer. | |
| typedef void(* | CdiCoreConnectionCallback) (const CdiCoreConnectionCbData *data_ptr) |
| Prototype of connection callback function. The user code must implement a function with this prototype and provide it in CdiTxConfigData or CdiRxConfigData structure when using one of the Cdi...Create() API functions. | |
| typedef void(* | CdiCoreStatsCallback) (const CdiCoreStatsCbData *data_ptr) |
| Prototype of statistics callback function. The user code must implement a function with this prototype and provide it as a parameter to the CdiCoreStatsRegisterCallback() API function. | |
| typedef struct CdiSglEntry | CdiSglEntry |
| This typedef is declared here so we can use it as a pointer element within the structure. | |
This file declares the public API data types, structures and functions that comprise the CDI low-level transport SDK API.
| #define CDI_MAX_SIMULTANEOUS_RX_PAYLOADS_PER_CONNECTION (32) |
Define to limit the max number of allowable payloads that can be simultaneously received on a single connection in the SDK. This number should be larger than the respective Tx limit since more payloads can potentially be in flight in the receive logic. This is because Tx packets can get acknowledged to the transmitter before being fully processed by the receiver, allowing the transmitter to send more. This number must also be as large or larger than the maximum SRD packet ordering window so that we can be sure we make enough room in our state arrays for tracking all possible payloads that could be in flight at the same time. NOTE: This value must be a power of two because it is used to mask the MSBs of array indices.
| #define CDI_PROBE_VERSION 5 |
CDI probe command version. Possible value are: For Protocol version 2.0 (CDI_PROTOCOL_VERSION.CDI_PROTOCOL_MAJOR_VERSION): 0: SDK 1.x.x. Only supports protocol version 1.0. 1: not used 2: SDK 2.0.x, Only supports protocol version 1.0 3: SDK 2.1.x. Supports the new protocol version command. See kProbeCommandProtocolVersion. Supports protocols version 1.0 and 2.0.
For Protocol version 2.1 (CDI_PROTOCOL_VERSION.CDI_PROTOCOL_MAJOR_VERSION): 4: SDK 2.2.x. Supports bidirectional sockets for probe control interface. Logic added to maintain compatibility with previous probe version that used unidirectional sockets.
| typedef void(* CdiCoreConnectionCallback) (const CdiCoreConnectionCbData *data_ptr) |
Prototype of connection callback function. The user code must implement a function with this prototype and provide it in CdiTxConfigData or CdiRxConfigData structure when using one of the Cdi...Create() API functions.
This callback function is invoked whenever the connection status changes.
| data_ptr | A pointer to an CdiCoreConnectionCbData structure. |
| typedef void(* CdiCoreStatsCallback) (const CdiCoreStatsCbData *data_ptr) |
Prototype of statistics callback function. The user code must implement a function with this prototype and provide it as a parameter to the CdiCoreStatsRegisterCallback() API function.
This callback function is invoked whenever statistics gathering interval has expired.
| data_ptr | A pointer to an CdiCoreStatsCbData structure. |
This selector determines the type of network adapter in the API function. NOTE: Any changes made here MUST also be made to "adapter_type_key_array" in cdi_avm_api.c.
| enum CdiBufferType |
Values used to determine type of receive buffer to configure for a receiver connection. NOTE: Any changes made here MUST also be made to "buffer_type_key_array" in cdi_utility_api.c.
| enum CdiConnectionStatus |
This enumeration is used to indicate the current state of a connection. NOTE: Any changes made here MUST also be made to "connection_status_key_array" in cdi_utility_api.c.
| Enumerator | |
|---|---|
| kCdiConnectionStatusDisconnected | Disconnected. The SDK is trying to establish the connection. |
| kCdiConnectionStatusConnected | Connected and ready for use. |
| enum CdiReturnStatus |
Values used for API function return codes.
NOTE: Additions to and removals from this enumeration need to be reflected in CdiCoreStatusToString().
| CDI_INTERFACE CdiReturnStatus CdiCoreConnectionDestroy | ( | CdiConnectionHandle | handle | ) |
Destroy a specific TX or RX connection and free resources that were created for it.
| handle | Connection handle returned by Cdi...TxCreate() API functions. |
| CDI_INTERFACE int CdiCoreGather | ( | const CdiSgList * | sgl_ptr, |
| int | offset, | ||
| void * | dest_data_ptr, | ||
| int | byte_count ) |
Gather received data represented by a scatter-gather list into a contiguous buffer. The caller is responsible for ensuring that the destination buffer is large enough to hold the data.
A subset of the entire payload of the SGL can be extracted by using a non-zero value for offset and/or a smaller number for byte_count than sgl->total_data_size. The number of bytes copied is the smaller of (sgl->total_data_size - offset) or byte_count.
| sgl_ptr | The scatter-gather list containing the data to be gathered. |
| offset | Number of bytes to skip in SGL before starting the copy. |
| dest_data_ptr | Where to write the gathered data in linear format. |
| byte_count | The number of bytes to copy. |
| CDI_INTERFACE CdiPtpTimestamp CdiCoreGetPtpTimestamp | ( | CdiPtpTimestamp * | ret_ptp_time_ptr | ) |
Get the current TAI time as a PTP timestamp.
There seems to be no trivial solutions for automatically getting the current leap second adjustment. All leap second adjustments occur on either December 31st or June 30th. The next possible leap second introduction is June 30th 2021. This function applies a fixed 37 second adjustment to UTC time to get TAI time.
| ret_ptp_time_ptr | Pointer to CdiPtpTimestamp to return the current PtpTimestamp to. This may be NULL. |
| CDI_INTERFACE const CdiCoreReadOnlySettings * CdiCoreGetSettings | ( | ) |
Returns the core configuration read-only settings.
| CDI_INTERFACE uint64_t CdiCoreGetTaiTimeMicroseconds | ( | ) |
Get the current TAI time in microseconds.
| CDI_INTERFACE void CdiCoreGetUtcTime | ( | struct timespec * | ret_time_ptr | ) |
Get the current synced AWS network UTC time in a timespec structure. This function will be kept up to date with the best practices for getting high accuracy time from Amazon Time Sync Service as improved accuracy time is available. All EC2 instances that call this function should be using the Amazon Time Sync Service. Amazon Time Sync Service setup directions for Linux can be found at: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/set-time.html#configure-amazon-time-service. For Windows follow the directions at: https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/windows-set-time.html
| ret_time_ptr | Address where to write the UTC timestamp in a timespec structure as defined by time.h. |
| CDI_INTERFACE uint64_t CdiCoreGetUtcTimeMicroseconds | ( | void | ) |
Get the current synced AWS network UTC time in microseconds. It uses CdiCoreGetUtcTime().
| CDI_INTERFACE CdiReturnStatus CdiCoreInitialize | ( | const CdiCoreConfigData * | core_config_ptr | ) |
Initialize the SDK. Must be called once before using any other SDK APIs. When done, must call CdiCoreShutdown() once.
NOTE: Newly created data structures that are passed in to this function should be properly initialized before being programmed with user values. Use memset or a zero structure initializer (= {0}) to set the whole structure to zero before setting the desired members to the actual values required.
| core_config_ptr | Pointer to core configuration data that is used to initialize the SDK. Value is required and cannot be NULL. Copies of the data in the configuration data structure are made as needed. A local variable can be used for composing the structure since its contents are not needed after this function returns. |
| CDI_INTERFACE CdiReturnStatus CdiCoreNetworkAdapterDestroy | ( | CdiAdapterHandle | handle | ) |
Free resources associated with the specified network adapter that was previously created using CdiCoreNetworkAdapterInitialize(). NOTE: Before calling this function, all connections that use the adapter should be closed using CdiCoreConnectionDestroy().
| handle | Handle of network adapter to destroy. |
| CDI_INTERFACE CdiReturnStatus CdiCoreNetworkAdapterInitialize | ( | CdiAdapterData * | adapter_data_ptr, |
| CdiAdapterHandle * | ret_handle_ptr ) |
Create an instance of a network adapter. CdiCoreNetworkAdapterDestroy() must be called before CdiCoreShutdown() but after all connections using the adapter are closed using CdiCoreConnectionDestroy().
NOTE: Currently if the shared memory provider is enabled in the EFA Adapter (see FI_EFA_ENABLE_SHM_TRANSFER in CDI), libfabric uses fork() to determine capability (see rxr_check_cma_capability() in the EFA provider). This causes a double flush of cached write data of any open files. By default, the shared memory provider is disabled. If enabled, all open files must have used fflush() prior to using this API function. The CDI SDK always flushes all open log files that were created using the CDI logger API functions.
NOTE: Newly created data structures that are passed in to this function should be properly initialized before being programmed with user values. Use memset or a zero structure initializer (= {0}) to set the whole structure to zero before setting the desired members to the actual values required.
| adapter_data_ptr | Pointer to network adapter configuration data. Copies of the data in the configuration data structure are made as needed. A local variable can be used for composing the structure since its contents are not needed after this function returns. |
| ret_handle_ptr | Pointer to returned instance handle (used as parameter for other API functions). |
| CDI_INTERFACE CdiReturnStatus CdiCoreRxFreeBuffer | ( | const CdiSgList * | sgl_ptr | ) |
Free the receive buffer that was used in one of the Cdi...RxCallback() API functions.
| sgl_ptr | The scatter-gather list containing the memory to be freed. |
| CDI_INTERFACE CdiReturnStatus CdiCoreShutdown | ( | void | ) |
Application is shutting down. Stop open connections and free-up all resources being used by the SDK.
| CDI_INTERFACE CdiReturnStatus CdiCoreStatsReconfigure | ( | CdiConnectionHandle | handle, |
| const CdiStatsConfigData * | config_ptr ) |
Configure transfer statistics.
| handle | Connection handle returned by Cdi...TxCreate() API functions. |
| config_ptr | Pointer to statistics configuration data. Copies of the data in the configuration data structure are made as needed. A local variable can be used for composing the structure since its contents are not needed after this function returns. |
| CDI_INTERFACE const char * CdiCoreStatusToString | ( | CdiReturnStatus | status | ) |
Returns a short string that briefly describes the meaning of an CDI status code.
| status | The value to be converted to a string. |