stream_net.h

Reference Documentation

product_line_custom
Napatech SmartNIC
category
Reference Information

Go to the documentation of this file.

1/* 2 * %NT_SOFTWARE_LICENSE% 3 */ 4 5/** 6 * @file 7 * 8 * This is header file of the network stream interface 9 */ 10#ifndef __STREAM_NET_H__ 11#define __STREAM_NET_H__ 12 13#if !defined(__NT_H__) 14 #error: My interface file is 'nt.h'. Please include that via #include "nt.h" directly. 15#endif 16 17/** @addtogroup NetworkStream 18 * 19 * Network streams are used to receive and transmit data packets to 20 * and from the adapters. They are an extension build on top of the 21 * hardware-based host buffers. 22 * Three types of network streams exist: 23 * @li @ref StreamRx is used to receive data 24 * @li @ref StreamTx is used to transmit data 25 * @li @ref StreamFile is used to receive data to a file 26 * 27 * @note The streams are not thread safe so using the network stream API 28 * must be performed without concurrent access to the stream. 29 */ 30 31/** @addtogroup StreamRx 32 * The RX network stream is used for both capture and in-line 33 * scenarios. The capture scenarios can deliver packets either 34 * packet-by-packet or as segments. The segment delivery is used for 35 * store to disk scenarios followed by offline analysis via the 36 * file-based network stream. 37 * 38 * @section PacketInterface Packet Interface 39 * 40 * The main interface is the packet interface. The packet interface is 41 * an interface for applications to do packet-by-packet 42 * processing. Please note that this approach will move some CPU load 43 * from the application to the driver compared to the segment 44 * interface. To open an RX network stream using the packet interface, 45 * call the @ref NT_NetRxOpen function with the interface type set to 46 * @ref NtNetInterface_e::NT_NET_INTERFACE_PACKET 47 * "NT_NET_INTERFACE_PACKET". To receive a packet, call @ref NT_NetRxGet 48 * and use the @ref PacketMacros "packet macros" to access the 49 * data. When finished with the packet, call @ref NT_NetRxRelease to release 50 * it again. When finished with the stream, call @ref NT_NetRxClose to close 51 * it. 52 * 53 * For an example on how to use the packet interface see @ref 54 * net/analysis/analysis_example.c "net/analysis/analysis_example.c". 55 * 56 * @section SegmentInterface Segment Interface 57 * 58 * The segment interface is only intended to be used for writing data 59 * to the disc and to do this the application will have to add a file 60 * header, provided by the system, to the beginning of the file. To read 61 * back data from the file, the application will have to use the 62 * @ref StreamFile to open the file and process the saved data packet 63 * by packet. To open an RX network stream using the segment interface, 64 * call the @ref NT_NetRxOpen function with the interface type set to 65 * @ref NtNetInterface_e::NT_NET_INTERFACE_SEGMENT 66 * "NT_NET_INTERFACE_SEGMENT". To receive a segment, call @ref NT_NetRxGet 67 * and use the @ref SegmentMacros "segment macros" to access the 68 * data. When finished with the segment, call @ref NT_NetRxRelease to release 69 * it again. When finished with the stream, call @ref NT_NetRxClose to 70 * close it. 71 * 72 * For an example on how to use the segment interface see @ref 73 * net/capture/capture_example.c "net/capture/capture_example.c". 74 * 75 * @section DataSharing Data Sharing 76 * 77 * Data sharing is a feature that will allow multiple applications to 78 * access the same shared host buffer. 79 * 80 * Data sharing is supported at the host buffer level. This allows 81 * multiple applications to access the same host buffer, at the 82 * same time, and individually decide if they want to use the packet 83 * interface or the segment interface. Data sharing is zero copy but 84 * will take up some extra CPU power to handle the synchronization of 85 * the host buffers. The service daemon is responsible for handling the 86 * host buffer exchange with the hardware and the data sharing is 87 * transparent to the application. 88 * 89 * @note Be aware that the slowest application sets the speed. This 90 * means that a packet/segment will not be returned to the hardware 91 * before all applications that share the host buffer have 92 * processed it. To avoid this use @ref MainDocMainFeaturesTraffic_ReceiveHb_HostBufferAllowance 93 * 94 * @section DataMerging Data Merging 95 * 96 * Data merging is used for merging data packets received from 97 * multiple host buffers into one stream. This feature is used to merge 98 * data from multiple ports on multiple adapters, or multiple host buffers from one 99 * in-line adapter. The Napatech Software Suite supports 100 * merging of data from up to 42 host buffers, making it possible to 101 * merge data from 42 NT adapters. See the @ref NtplOverview "NTPL" for a 102 * description on how to configure data merging. 103 * 104 * @note Data merging is only possible for packet streams. 105 * @par 106 * @note Timesynchronisation is required when merging from different adapters (see @ref MainDocMainFeaturesVirtPort_AdapterMerge). 107 */ 108 109/** @addtogroup StreamTx 110 * The TX network stream is used for transmitting data. Packets sent 111 * via this stream will be interleaved with traffic from in-line 112 * streams or other transmit streams. 113 * 114 * To open a TX network stream, call the @ref NT_NetTxOpen function. To 115 * get an empty packet, call the @ref NT_NetTxGet function with the 116 * desired length of the packet. The length includes the 4 bytes for 117 * the Ethernet CRC. Now fill data into the buffer and use the 118 * @ref TxMacros "TX Macros" for setting the desired time stamp, force CRC 119 * generation, etc. When finished with the packet, call @ref NT_NetTxRelease 120 * to release and transmit it. When finished with the stream, call @ref 121 * NT_NetTxClose to close it. 122 * 123 * For an example on how to use the packet interface, see @ref 124 * net/transmit/transmit_example.c "net/transmit/transmit_example.c". 125 * 126 */ 127 128/** @addtogroup StreamFile 129 * The File network stream is used for packet-by-packet offline 130 * analysis of the packets captured with the segment RX interface. See 131 * @ref SegmentInterface "Segment interface" for a description of how 132 * to accomplish this. 133 * 134 * To open a file network stream, call the @ref NT_NetFileOpen with the 135 * name of the captured file as argument. To get the next packet from 136 * the file network stream, call the @ref NT_NetFileGet. Use the 137 * @ref PacketMacros "packet macros" to access the packet data. When 138 * finished with the packet, call @ref NT_NetFileRelease to release it 139 * again. When finished with the stream, call @ref NT_NetFileClose to close 140 * it. 141 * 142 * Supported files are native NT captured files, pcap and pcap-ng files. 143 * When using pcap or pcap-ng files, the received port information is always 144 * set to 0. 145 * 146 * For an example on how to use the file network stream interface, see 147 * @ref net/replay/replay_example.c "net/replay/replay_example.c". 148 * 149 */ 150 151/** 152 * The network interface types. 153 * Used to select PACKET or NETWORK interface. 154 */ 155enum NtNetInterface_e { 156 NT_NET_INTERFACE_UNKNOWN=0, //!< Unknown interface 157 NT_NET_INTERFACE_PACKET, //!< Packet interface 158 NT_NET_INTERFACE_SEGMENT //!< Segment interface 159}; 160 161#ifndef DOXYGEN_INTERNAL_ONLY 162/** 163 * Internal structures used in @ref NtNetBuf_s 164 */ 165typedef struct NtNetBufData_s* NtNetBufData_t; //!< Confidential data 166typedef struct NtNetBufPkt_s* NtNetBufPkt_t; //!< Packet data 167typedef struct NtNetBufHdr_s* NtNetBufHdr_t; //!< Header data 168#endif 169 170 171/** 172 * This structure is used by the @ref NetworkStream Get/Release functions and provides a handle to the returned data. 173 * The layout of the structure is confidential and must only be accessed via @ref DataMacros. 174 * The layout of the structure might change between major releases of NTAPI. 175 */ 176typedef struct NtNetBuf_s { 177#ifndef DOXYGEN_INTERNAL_ONLY 178 int version; //!< The version of the NetworkData header 179 NtNetBufData_t hData; //!< A handle to confidential data 180 NtNetBufPkt_t hPkt; //!< A handle to packet data 181 NtNetBufHdr_t hHdr; //!< A handle to header data 182 uint64_t length; //!< Data field length 183 enum NtNetInterface_e netIf; //!< The network interface 184 enum NtTimestampType_e tsType; //!< The time stamp type 185 uint8_t portOffset; //!< The port offset - used to identify virtual ports 186 uint8_t Reserved1[3]; 187 uint8_t adapterNo; //!< The adapter from which the data originated 188 uint8_t Reserved2[3]; 189 int8_t egressPort; //!< The destination port (in-line) 190 uint8_t Reserved3[3]; 191 uint8_t* colorMap; //!< The filter color map table 192#define _FEED2STREAM_SHL_ 3 193 int* streamInfo; //!< A pointer to indexed stream IDs - used by macros 194 uint32_t pkts; 195#endif 196 uintptr_t arg0; //!< User specific meta data container 0 197 uintptr_t arg1; //!< User specific meta data container 1 198 uintptr_t arg2; //!< User specific meta data container 2 199} *NtNetBuf_t; 200 201/** @addtogroup StreamRx 202 *@{ 203 */ 204 205/** 206 * Possible NetRx stream commands 207 */ 208enum NtNetRxCmd_e { 209 NT_NETRX_READ_CMD_UNKNOWN=0, //!< Unknown read command 210 NT_NETRX_READ_CMD_GET_FILE_HEADER, //!< Gets the file header for the stream 211 NT_NETRX_READ_CMD_STREAM_DROP, //!< Returns the drop counters for each stream - the counters increment when packets are dropped because of the host buffer allowance (hysteresis) being activated 212 NT_NETRX_READ_CMD_STREAM_TIME, //!< Returns the current stream time 213 NT_NETRX_READ_CMD_PCAP_FCS, //!< Returns whether packets with pcap descriptors include ethernet FCS 214 NT_NETRX_READ_CMD_GET_RING_CONTROL, //!< Return control of the host buffer ring of a stream Dangerous!! (Napatech internal use only - may change without further notice) 215 NT_NETRX_READ_CMD_GET_HB_INFO //!< Gets the info on the host buffers used by the stream 216}; 217 218/** 219 * File header return structure. 220 * Note: This header can only be read when all NTPL assignments have completed. 221 */ 222struct NtNetRxFileHeader_s { 223 uint8_t data[128]; //!< The actual file header 224 int32_t size; //!< The size of the file header 225}; 226 227/** 228 * Stream drop counter return structure 229 */ 230struct NtNetRxStreamDrop_s { 231 uint64_t pktsDropped; //!< Packets dropped because the application is affected by the host buffer allowance (hysteresis) 232 uint64_t octetsDropped; //!< Bytes dropped because the application is affected by the host buffer allowance (hysteresis) 233}; 234 235/** 236 * Stream time 237 */ 238struct NtNetRxStreamTime_s { 239 uint64_t ts; //!< Current stream time. Can be used when NT_NetRxGet() returns timeout to get the time of the stream. 240}; 241 242/** 243 * PCAP information 244 */ 245struct NtNetRxPcapInfo_s { 246 uint32_t fcs; //!< Returns non-zero if FCS is included in packets with PCAP descriptors. 247}; 248 249/** 250 * Expose buffer info to the user (Napatech internal use only - may change without further notice) 251 */ 252struct NtNetRxHbRing_s { 253 volatile uint64_t* pRead; 254 volatile uint64_t* pWrite; 255 uint8_t* ring; 256 uint64_t size; 257 uint64_t mask; 258}; 259 260/** 261 * RX Host buffer info 262 */ 263struct NtNetRxHbInfo_s { 264 unsigned int numAddedHostBuffers; //!< The number of host buffers added by the driver 265 unsigned int numAssignedHostBuffers; //!< The number of host buffers assigned and also the depth of the array 266 struct NtNetRxHb_s { 267 uint64_t timestamp; //!< The current host buffer time 268 size_t size; //!< The size of the host buffer (4GA only) 269 size_t available; //!< Amount of the host buffer available to the adapter (4GA only) 270 size_t dequeued; //!< Reserved for future use 271 size_t pending; //!< Amount of the host buffer pending for the application to read (4GA only) 272 size_t inlinePending; //!< Reserved for future use 273 enum NtNetHostBufferLayout_e layout; //!< The host buffer layout 274 int index; //!< The host buffer index. Unique throughout the system 275 } aHostBuffer[128]; 276}; 277 278/** 279 * NetRx structure. Network RX data is read via this structure via @ref NT_NetRxRead(). 280 */ 281typedef struct NtNetRx_s { 282 enum NtNetRxCmd_e cmd; //!< The read command - specified what to read from NetRx 283 /** 284 * Union of all possible return structures from NetRxRead() 285 */ 286 union NtNetRx_u { 287 struct NtNetRxFileHeader_s fileheader; //!< The structure to use for @ref NtNetRx_s::cmd==NT_NETRX_READ_CMD_GET_FILE_HEADER 288 struct NtNetRxStreamDrop_s streamDrop; //!< The structure to use for @ref NtNetRx_s::cmd==NT_NETRX_READ_CMD_STREAM_DROP 289 struct NtNetRxStreamTime_s streamTime; //!< The structure to use for @ref NtNetRx_s::cmd==NT_NETRX_READ_CMD_STREAM_TIME 290 struct NtNetRxPcapInfo_s pcap; //!< The structure to use for @ref NtNetRx_s::cmd==NT_NETRX_READ_CMD_PCAP_INFO 291 struct NtNetRxHbRing_s ringControl; //!< The structure to use for @ref NtNetRx_s::cmd==NT_NETRX_READ_CMD_GET_RING_CONTROL 292 struct NtNetRxHbInfo_s hbInfo; //!< The structure to use for @ref NtNetRx_s::cmd==NT_NETRX_READ_CMD_GET_HB_INFO 293 } u ; 294} NtNetRx_t; 295 296/** 297 * Possible NetTx stream commands 298 */ 299enum NtNetTxCmd_e { 300 NT_NETTX_READ_CMD_UNKNOWN=0, //!< Unknown read command 301 NT_NETTX_READ_CMD_GET_HB_INFO, //!< Gets the info on the host buffers used by the stream 302 NT_NETTX_READ_CMD_GET_RING_CONTROL, //!< Get the control of the host buffer ring. Dangerous!! (Napatech internal use only - may change without further notice) 303}; 304 305/** 306 * TX Host buffer info 307 */ 308struct NtNetTxHbInfo_s { 309 unsigned int numHostBuffers; //!< The number of host buffers used by the stream and also the depth of the array 310 struct NtNetTxHb_s { 311 size_t size; //!< The size of the host buffer 312 size_t available; //!< Amount of the host buffer available to the application 313 size_t dequeued; //!< Amount of the host buffer dequeued by the application 314 size_t released; //!< Amount of the host buffer released waiting to be transmitted 315 enum NtNetHostBufferLayout_e layout; //!< The host buffer layout 316 int index; //!< The host buffer index. Unique throughout the system. 317 uint64_t portMask; //!< The port-mask the host buffer can utilize 318 } aHostBuffer[128]; 319}; 320 321/** 322 * Expose host buffer info (Napatech internal use only - may change without further notice) 323 */ 324struct NtNetTxHbRing_s { 325 volatile uint64_t* pRead; 326 volatile uint64_t* pWrite; 327 uint8_t* ring; 328 uint64_t size; 329 uint16_t minTxPktSize; //!< The min transmit packet size of this port 330 uint16_t maxTxPktSize; //!< The max transmit packet size of this port 331 uint8_t port; //!< The port this ring is attached to 332 //TODO: Maybe expose what descriptors can be used? 333}; 334 335/** 336 * NetTx structure. Network TX data is read via this structure via @ref NT_NetTxRead(). 337 */ 338typedef struct NtNetTx_s { 339 enum NtNetTxCmd_e cmd; //!< The read command - specified what to read from NetTx 340 /** 341 * Union of all possible return structures from NetTxRead() 342 */ 343 union NtNetTx_u { 344 struct NtNetTxHbInfo_s hbInfo; //!< Information about the host buffers used 345 struct NtNetTxHbRing_s ringControl; //!< Control of the host buffer ring (Napatech internal use only - may change without further notice) 346 } u ; 347} NtNetTx_t; 348 349 350/** 351 * NtNetTxFragment structure. A TX packet may be scattered in a list of fragments, 352 * which is put together and added to the TX hostbuffer via @ref NT_NetTxAddPacket(). 353 */ 354typedef struct NtNetTxFragment_s 355{ 356 uint8_t* data; 357 uint16_t size; 358} NtNetTxFragment_t; 359 360/** 361 * Possible NetFileRead commands 362 */ 363enum NtNetFileReadCmd_e { 364 NT_NETFILE_READ_INFO_UNKNOWN_CMD=0, //!< Unknown read command 365 NT_NETFILE_READ_COMPAT_0, //!< Read information about the NetFile stream 366 NT_NETFILE_READ_FILETYPE_CMD, //!< Read information about the opened file type 367 NT_NETFILE_READ_DESCRIPTOR_CMD, //!< Read information about the descriptor and timestamp format used 368 NT_NETFILE_READ_INFO_CMD_V1, //!< Read information about the NetFile stream 369}; 370 371/** 372 * NetFile stream Info return structure 373 */ 374 375typedef struct NtNetFileReadInfo_v1_s { 376 uint64_t lastTimestamp; //!< The time stamp in the last packet in last segment read using the function @ref NT_NetFileGet 377 uint64_t numberOfOctets; //!< Number of octets read from Netfile so far 378 uint32_t numberOfPackets; //!< Number of packets read from Netfile so far 379 uint64_t firstTimestamp; //!< The time stamp in the first packet in first segment read using the function @ref NT_NetFileGet 380} NtNetFileInfo_v1_t; 381 382typedef enum { 383 NT_NETFILE_TYPE_UNKNOWN, //!< The opened file is a unknown 384 NT_NETFILE_TYPE_NT, //!< The opened file is a Napatech capture file 385 NT_NETFILE_TYPE_PCAP, //!< The opened file is a PCAP capture file 386 NT_NETFILE_TYPE_PCAP_NG, //!< The opened file is a PCAP NG capture file 387} NtNetFileType_e; 388 389typedef struct NtNetFileReadDesc_s 390{ 391 enum NtTimestampType_e tsType; //!< Timestamp format used in packet data 392 enum NtPacketDescriptorType_e desc; //!< Descriptor used in packet data 393} NtNetFileReadDesc_t; 394 395/* Include commands for backward compatibility */ 396#if !defined(_NT_NTAPI_NO_COMPAT) 397#include "stream_net_compat.h" 398#endif 399 400/** 401 * NetFileRead stream structure - network File data is read via this structure via @ref NT_NetFileRead() 402 */ 403typedef struct NtNetFileRead_s { 404 enum NtNetFileReadCmd_e cmd; //!< The read command - specified what to read from NetFile 405 /** 406 * Union of all possible return structures from NT_NetFileRead() 407 */ 408 union NtNetFileRead_u { 409 struct NtNetFileReadInfo_v1_s info_v1; //!< Information about the NetFile. Used by NT_NETFILE_READ_INFO_CMD 410 struct NtNetFileReadDesc_s desc; //!< Information about the descriptor and timestamp format used. Used by NT_NETFILE_READ_DESCRIPTOR_CMD 411 NtNetFileType_e fileType; //!< Information about the type of the opened file 412#if !defined(_NT_NTAPI_NO_COMPAT) 413 /* Commands for backward compatibility */ 414 struct NtNetFileReadInfo_s info; //!< Information about the NetFile. Used by NT_NETFILE_READ_INFO_CMD 415#endif 416 } u ; 417} NtNetFileRead_t; 418 419/** 420 * The Network RX stream handle - used for both in-line and capture streams 421 */ 422typedef struct NtNetStreamRx_s* NtNetStreamRx_t; 423 424/** 425 * Flags for NT_NetRxOpen_v2/NT_NetRxOpenMulti_v2 426 */ 427#define NT_NETRX_NONE 0 428#define NT_NETRX_READONLY_STREAM (1<<0) 429 430/** 431 * @brief Opens in-line or capture host buffer(s) and returns a NtNetStreamRx_t handle 432 * 433 * This function is called to retrieve a handle to an in-line or capture network stream. 434 * @note It is important to start calling NT_NetRxGet() and NT_NetRxRelease() soon 435 * after this call to avoid packet drop. Host buffers are assigned/released to the streamid within 436 * NT_NetRxGet() and NT_NetRxRelease(). 437 * 438 * @param[out] hStream Reference to a NtNetStreamRx_t stream pointer 439 * @param[in] name Stream friendly name - used in, for example, logging statements 440 * @param[in] netIntf Interface type - segment or packet 441 * @param[in] streamId The network stream ID to open - can be opened a number of times which will cause sharing of the host buffers in the streamId 442 * @param[in] hostBufferAllowance Drop level for the host buffer allowance (hysteresis), -1 means disabled 443 * 444 * @retval NT_SUCCESS Success 445 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 446 */ 447int NT_NetRxOpen(NtNetStreamRx_t* hStream, const char* name, enum NtNetInterface_e netIntf, uint32_t streamId, int hostBufferAllowance); 448 449/** 450 * @brief Opens in-line or capture host buffer(s) and returns a NtNetStreamRx_t handle 451 * 452 * This function is called to retrieve a handle to an in-line or capture network stream with flags. 453 * @note It is important to start calling NT_NetRxGet() and NT_NetRxRelease() soon 454 * after this call to avoid packet drop. Host buffers are assigned/released to the streamid within 455 * NT_NetRxGet() and NT_NetRxRelease(). 456 * 457 * The flags shall be either NT_NETRX_NONE or the bitwise-inclusive OR of one or more of the other 458 * flags in the following table: 459 * 460 * Flag | Description 461 * -------------------------|------------- 462 * NT_NETRX_NONE | No flags set, equivalent to passing '0' as flag. 463 * NT_NETRX_READONLY_STREAM | Using this option will cause a write to data returned by NT_NetRxGet to fail with a segmentation fault. 464 * 465 * @param[out] hStream Reference to a NtNetStreamRx_t stream pointer 466 * @param[in] name Stream friendly name - used in, for example, logging statements 467 * @param[in] netIntf Interface type - segment or packet 468 * @param[in] streamId The network stream ID to open - can be opened a number of times which will cause sharing of the host buffers in the streamId 469 * @param[in] hostBufferAllowance Drop level for the host buffer allowance (hysteresis), -1 means disabled 470 * @param[in] flags Flags for the stream OR'd together, or zero for no flags. 471 * 472 * @retval NT_SUCCESS Success 473 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 474 */ 475int NT_NetRxOpen_v2(NtNetStreamRx_t* hStream, const char* name, enum NtNetInterface_e netIntf, uint32_t streamId, int hostBufferAllowance, int flags); 476 477/** 478 * @brief Opens in-line or capture host buffer(s) and returns a NtNetStreamRx_t handle 479 * 480 * This function is called to retrieve a handle to an in-line or capture network streams. If 481 * multiple stream-ids are opened the data from them will be time stamp merged. Note multiple 482 * stream-ids can only be used with the packet interface. 483 * @note It is important to start calling NT_NetRxGet() and NT_NetRxRelease() soon 484 * after this call to avoid packet drop. Host buffers are assigned/released to the streamid within 485 * NT_NetRxGet() and NT_NetRxRelease(). 486 * 487 * @param[out] hStream Reference to a NtNetStreamRx_t stream pointer 488 * @param[in] name Stream friendly name - used in, for example, logging statements 489 * @param[in] netIntf Interface type - Can only be packet if multiple are opened 490 * @param[in] paStreamId Array containing the network stream IDs to open. A maximum of 8 streams can be specified. 491 * @param[in] numStreamIds The number of stream-ids in the paStreamId array 492 * @param[in] hostBufferAllowance Drop level for the host buffer allowance (hysteresis), -1 means disabled 493 * 494 * @retval NT_SUCCESS Success 495 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 496 */ 497int NT_NetRxOpenMulti(NtNetStreamRx_t* hStream, const char* name, enum NtNetInterface_e netIntf, uint32_t* paStreamId, unsigned int numStreamIds, int hostBufferAllowance); 498 499/** 500 * @brief Opens in-line or capture host buffer(s) and returns a NtNetStreamRx_t handle 501 * 502 * This function is called to retrieve a handle to an in-line or capture network streams with flags. 503 * If multiple stream-ids are opened the data from them will be time stamp merged. Note multiple 504 * stream-ids can only be used with the packet interface. 505 * @note It is important to start calling NT_NetRxGet() and NT_NetRxRelease() soon 506 * after this call to avoid packet drop. Host buffers are assigned/released to the streamid within 507 * NT_NetRxGet() and NT_NetRxRelease(). 508 * 509 * The flags shall be either NT_NETRX_NONE or the bitwise-inclusive OR of one or more of the other 510 * flags in the following table: 511 * 512 * Flag | Description 513 * -------------------------|------------- 514 * NT_NETRX_NONE | No flags set, equivalent to passing '0' as flag. 515 * NT_NETRX_READONLY_STREAM | Using this option will cause a write to data returned by NT_NetRxGet to fail with a segmentation fault. 516 * 517 * @param[out] hStream Reference to a NtNetStreamRx_t stream pointer 518 * @param[in] name Stream friendly name - used in, for example, logging statements 519 * @param[in] netIntf Interface type - Can only be packet if multiple are opened 520 * @param[in] paStreamId Array containing the network stream IDs to open. A maximum of 8 streams can be specified. 521 * @param[in] numStreamIds The number of stream-ids in the paStreamId array 522 * @param[in] hostBufferAllowance Drop level for the host buffer allowancei (hysteresis), -1 means disabled 523 * @param[in] flags Flags for the stream OR'd together, or zero for no flags. 524 * 525 * @retval NT_SUCCESS Success 526 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 527 */ 528int NT_NetRxOpenMulti_v2(NtNetStreamRx_t* hStream, const char* name, enum NtNetInterface_e netIntf, uint32_t* paStreamId, unsigned int numStreamIds, int hostBufferAllowance, int flags); 529 530/** 531 * @brief Gets data from an in-line or capture stream 532 * 533 * This function is called to retrieve packets/segments from a in-line or capture stream. 534 * 535 * The calling process is suspended when no data is immediately available. 536 * The suspension is done in one of two ways, depending on the system clock resolution: 537 538 * 1) If the system clock resolution is <= 1 uSec, sleep calls are used. The timeout value 539 * is divided into sleep intervals (with intervals approximating the segment timeout on the adapter). 540 * It then periodically polls for data. 541 542 * 2) using events. If the system cannot do uSec sleeps, then the suspension mechanism used is event 543 * based. It puts the calling process to sleep waiting for an event. On data receival an event is sent 544 * and the process is woken up. 545 * 546 * @param[in] hStream Network RX stream handle 547 * @param[out] netBuf Segment/packet container reference, is set to NULL if return value is not NT_SUCCESS 548 * @param[in] timeout The timeout in milliseconds. The call will return when this timeout is reached unless data is available. A timeout of -1 will wait indefinitely for a new buffer. 549 * 550 * @note This function has no mutex protection, therefore the same hStream cannot be used by multiple threads 551 * @note When the segment interface is used this function can return empty segments only containing a time stamp update, hence if NT_NET_GET_SEGMENT_LENGTH() return 0 only NT_NET_GET_SEGMENT_TIMESTAMP() can be used. 552 * The time stamp update will make it possible for users to merge packets in segments from different stream ids. 553 * 554 * @retval NT_SUCCESS Data has been returned and must be released again via NT_NetRxRelease() 555 * @retval NT_STATUS_TIMEOUT No data has been returned and a timeout has occured 556 * @retval NT_STATUS_TRYAGAIN The resource is temporarily unavailable because of reconfiguration - call NT_NetRxGet() again 557 * @retval Error Use @ref NT_ExplainError for an error description 558 */ 559int NT_NetRxGet(NtNetStreamRx_t hStream, NtNetBuf_t* netBuf, int timeout); 560 561/** 562 * @brief Gets data from an in-line or capture stream 563 * 564 * This function is called to retrieve packets from a in-line or capture stream. The function will 565 * automatically release the previous packet when called, hence it is not possible to keep packets and if necessary 566 * the packets must be copied to a safe buffer before calling the function to get the next packet. 567 * 568 * @param[in] hStream Network RX stream handle 569 * @param[out] netBuf Segment/packet container reference, is set to NULL if return value is not NT_SUCCESS 570 * @param[in] timeout The timeout in milliseconds. The call will return when this timeout is reached unless data is available. A timeout of -1 will wait indefinitely for a new buffer. 571 * 572 * @note This function has no mutex protection, therefore the same hStream cannot be used by multiple threads 573 * 574 * @retval NT_SUCCESS Data has been returned and will be valid until the next @ref NT_NetRxGetNextPacket() call 575 * @retval NT_STATUS_TIMEOUT No data has been returned and a timeout has occured 576 * @retval NT_STATUS_TRYAGAIN The resource is temporarily unavailable because of reconfiguration - call NT_NetRxGetNextPacket() again 577 * @retval Error Use @ref NT_ExplainError for an error description 578 */ 579int NT_NetRxGetNextPacket(NtNetStreamRx_t hStream, NtNetBuf_t* netBuf, int timeout); 580 581/** 582 * @brief Reads data from the stream 583 * 584 * This function will read on-line generated data from the stream, for example, a file header 585 * 586 * @param[in] hStream NetRx stream handle 587 * @param[in] cmd NetRx read structure 588 * 589 * @retval NT_SUCCESS Success 590 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 591 */ 592int NT_NetRxRead(NtNetStreamRx_t hStream, NtNetRx_t* cmd); 593 594 595/** 596 * @brief Releases network buffer 597 * 598 * This function will release the netBuf data obtained via NT_NetRxGet(). The data within 599 * netBuf will on an in-line profile be sent to the adapter upon release even in the case where 600 * the NTPL assignment has been terminated. 601 * 602 * @note This function has no mutex protection, therefore the same hStream cannot be used by multiple threads 603 * 604 * @param[in] hStream NetRx stream handle 605 * @param[in] netBuf Net buffer received via NT_NetRxGet() 606 * 607 * @retval NT_SUCCESS Success 608 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 609 */ 610int NT_NetRxRelease(NtNetStreamRx_t hStream, NtNetBuf_t netBuf); 611 612/** 613 * @brief Closes an in-line or capture stream 614 * 615 * This function is called to close an in-line or capture stream 616 * 617 * @param[in] hStream In-line or capture stream handle to close 618 * 619 * @retval NT_SUCCESS Success 620 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 621 */ 622int NT_NetRxClose(NtNetStreamRx_t hStream); 623 624/** @} */ 625 626 627/** @addtogroup StreamTx 628 *@{ 629 */ 630/** 631 * Network TX stream handle - used for TX streams 632 */ 633typedef struct NtNetStreamTx_s* NtNetStreamTx_t; 634 635/** 636 * Network TX packet options 637 */ 638enum NtNetTxPacketOption_e { 639 NT_NETTX_PACKET_OPTION_UNKNOWN=0, //!< Unknown option 640 NT_NETTX_PACKET_OPTION_DEFAULT, //!< Gets a TX buffer with a pre-configured packet descriptor. Use this option to transmit L2 data. This option uses packetSize as wire length. 641 NT_NETTX_PACKET_OPTION_L2=NT_NETTX_PACKET_OPTION_DEFAULT, //!< Same as default 642 NT_NETTX_PACKET_OPTION_RAW, //!< Gets a raw TX packet buffer without packet descriptor. Care needs to be taken when using this option. Use this option in replay scenarios where packets already have a correct descriptor, e.g. data recorded using @ref StreamFile. Uses packetSize as the stored length. With this option packetSize must be a multiple of 8 (NT3GA only). 643 NT_NETTX_SEGMENT_OPTION_RAW, //!< Gets a raw TX segment buffer. Care needs to be taken when using this option. Use this option in replay scenarios where the segment length is known prior to calling @ref NT_NetTxGet. Use packetSize as the segment length. The port parameter in @ref NT_NetTxGet is used to control that the segment returned belongs to the adapter on which the port resides. It is required that the txPort in the packet descriptors within the segment are set before releasing the segment. If the host buffer layout is NT_NET_HOSTBUFFER_LAYOUT_SLABS, the slabs are automatically terminated when this option is used. 644}; 645 646/** 647 * Network TX NUMA HB options for NUMA-parameter in NT_NetTxOpen() 648 */ 649enum NtNetTxOpenNumaOption_e { 650 NT_NETTX_NUMA_ANY_HB=0xFFFFFFFE, //!< (=-2) Allocate TX host buffer from any TX host buffer pool 651 NT_NETTX_NUMA_ADAPTER_HB=0xFFFFFFFF, //!< (=-1) Allocate TX host buffer from TX-host buffer pool on that NUMA node where the adapter of the TX-port is located 652}; 653 654/** 655 * @brief Opens a TX host buffer and returns a NtNetStreamTx_t handle 656 * 657 * This function is called to retrieve a TX stream handle. 658 * Note that the TX stream on capture-only adapters (NT4E Capture, NT4E_STD Capture and NT20E Capture) 659 * will have very limited transmit capabilities. They will not be able to transmit at line rate 660 * and their transmit sizes and statistics will also be limited. Packets larger than 2000 bytes 661 * will sliced to the size of 2000 bytes. 662 * 663 * @param[out] hStream Reference to a NtNetStreamTx_t stream pointer 664 * @param[in] name Stream friendly name - used in, for example, logging statements 665 * @param[in] portMask Bitmask for ports this stream will use for transmitting 666 * @param[in] NUMA NUMA node on which the host buffer is be located (NOTE: Special options in NtNetTxOpenNumaOption_e) 667 * @param[in] minHostBufferSize Minimum size of host buffer needed. Must be in MBytes. The smallest host buffer found that is larger or equal to minHostBufferSize is used and the size of the host buffer is set to minHostBufferSize. If set to 0, the first host buffer found is used regardsless of the size. 668 * 669 * @retval NT_SUCCESS Success 670 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 671 */ 672int NT_NetTxOpen(NtNetStreamTx_t* hStream, const char* name, uint64_t portMask, uint32_t NUMA, uint32_t minHostBufferSize); 673 674/** 675 * @brief Opens a TX host buffer and returns a NtNetStreamTx_t handle (extended version) 676 * 677 * This function is called to retrieve a TX stream handle. 678 * This function will only work with 4GA adapters. 679 * 680 * @param[out] hStream Reference to a NtNetStreamTx_t stream pointer 681 * @param[in] name Stream friendly name - used in, for example, logging statements 682 * @param[in] portMask Bitmask for ports this stream will use for transmitting 683 * @param[in] NUMA NUMA node on which the host buffer is be located (NOTE: Special options in NtNetTxOpenNumaOption_e) 684 * @param[in] minHostBufferSize Minimum size of host buffer needed. Must be in MBytes. The smallest host buffer found that is larger or equal to minHostBufferSize is used and the size of the host buffer is set to minHostBufferSize. If set to 0, the first host buffer found is used regardsless of the size. 685 * @param[in] descriptor Descriptor type to use when transmitting. 686 * @param[in] ts Timestamp format to use when transmitting. 687 * 688 * @retval NT_SUCCESS Success 689 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 690 */ 691int NT_NetTxOpen_v2(NtNetStreamTx_t* hStream, const char* name, uint64_t portMask, uint32_t NUMA, uint32_t minHostBufferSize, enum NtPacketDescriptorType_e descriptor, enum NtTimestampType_e ts); 692 693/** 694 * @brief Opens a TX host buffer and returns a NtNetStreamTx_t handle (extended version) 695 * 696 * This function is called to retrieve a TX stream handle. 697 * This function will only work with 4GA adapters. 698 * 699 * @param[out] hStream Reference to a NtNetStreamTx_t stream pointer 700 * @param[in] name Stream friendly name - used in, for example, logging statements 701 * @param[in] portMask Bitmask for ports this stream will use for transmitting 702 * @param[in] NUMA NUMA node on which the host buffer is be located (NOTE: Special options in NtNetTxOpenNumaOption_e) 703 * @param[in] minHostBufferSize Minimum size of host buffer needed in bytes. The smallest host buffer found that is larger or equal to minHostBufferSize is used and the size of the host buffer is set to minHostBufferSize. If set to 0, the first host buffer found is used regardsless of the size. 704 * @param[in] descriptor Descriptor type to use when transmitting. 705 * @param[in] ts Timestamp format to use when transmitting. 706 * 707 * @retval NT_SUCCESS Success 708 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 709 */ 710int NT_NetTxOpen_v3(NtNetStreamTx_t* hStream, const char* name, uint64_t portMask, uint32_t NUMA, uint64_t minHostBufferSize, enum NtPacketDescriptorType_e descriptor, enum NtTimestampType_e ts); 711 712/** 713 * @brief Gets a TX port buffer 714 * 715 * This function is called to acquire a TX buffer 716 * 717 * @note This function has no mutex protection, therefore the same hStream cannot be used by multiple threads 718 * 719 * @param[in] hStream Network TX stream handle 720 * @param[out] netBuf Segment/packet container reference 721 * @param[in] port Port to receive a TX buffer from 722 * @param[in] packetSize Size of the packet to transmit including 4-byte CRC. 723 * @param[in] packetOption Option to control the properties of the buffer, see @ref NtNetTxPacketOption_e for details 724 * @param[in] timeout Time in milliseconds to wait for a new buffer - a timeout of -1 will wait indefinitely for a new buffer 725 * 726 * @retval NT_SUCCESS Success 727 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 728 */ 729int NT_NetTxGet(NtNetStreamTx_t hStream, NtNetBuf_t* netBuf, uint32_t port, size_t packetSize, enum NtNetTxPacketOption_e packetOption, int timeout); 730 731/** 732 * @brief Releases the network buffer 733 * 734 * This function releases the netBuf data obtained via NT_TxGet 735 * 736 * @note This function has no mutex protection and can therefore the same hStream cannot be used by multiple threads 737 * 738 * @param[in] hStream Network TX stream handle 739 * @param[in] netBuf Net buffer is received via NT_TxGet 740 * 741 * @retval NT_SUCCESS Success 742 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 743 */ 744int NT_NetTxRelease(NtNetStreamTx_t hStream, NtNetBuf_t netBuf); 745 746/** 747 * @brief Reads data from the stream 748 * 749 * This function will read Tx related info 750 * 751 * @param[in] hStream NetTx stream handle 752 * @param[in] cmd NetTx read structure 753 * 754 * @retval NT_SUCCESS Success 755 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 756 */ 757int NT_NetTxRead(NtNetStreamTx_t hStream, NtNetTx_t* cmd); 758 759/** 760 * @brief Closes a TX stream 761 * 762 * This function is called to close a TX stream 763 * 764 * @param[in] hStream The TX stream handle to close 765 * 766 * @retval NT_SUCCESS Success 767 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 768 */ 769int NT_NetTxClose(NtNetStreamTx_t hStream); 770 771/** 772 * @brief AddPacket to a TX stream 773 * 774 * This function is called to put together scattered fragments of a packet and add it to a TX stream 775 * 776 * @note This function has no mutex protection and cannot be used by multiple threads on the same stream, hStream. 777 * 778 * @param[in] hStream Network TX stream handle 779 * @param[in] port Port to add packet into host buffer 780 * @param[in] fragments The scattered list of packet fragments 781 * @param[in] fragmentCount The number of scattered fragments in the list 782 * @param[in] timeout Time in milliseconds to wait for a packet buffer - a timeout of -1 will wait indefinitely for a packet buffer 783 * 784 * @retval NT_SUCCESS Success 785 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 786 */ 787int NT_NetTxAddPacket(NtNetStreamTx_t hStream, uint32_t port, NtNetTxFragment_t* fragments, uint32_t fragmentCount, int timeout ); 788 789//@G-- 790 791#ifndef DOXYGEN_INTERNAL_ONLY 792 793/** 794 * The Network TX Ring buffer handle - used for NFV NIC xmit 795 */ 796typedef struct NtNetTxRing_s* NtNetTxRing_t; 797 798/** 799 * @brief Initializes a Tx ring buffer in the Tx stream 800 * 801 * @param[in] hStream The TX stream handle 802 * 803 * @retval NT_SUCCESS Success 804 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 805 */ 806int NT_NetTxRingbufferInit(NtNetStreamTx_t hStream, uint32_t port); 807 808/** 809 * @brief Xmits a packet using a newly initialized Tx ring buffer 810 * 811 * @param[in] hStream The TX stream handle 812 * @param[in] pkt pointer to a L2 packet 813 * @param[in] wirelen The the L2 packet length including FCS 814 * 815 * @retval NT_SUCCESS Success 816 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 817 */ 818int NT_NetTxRingbufferTransmitPacket(NtNetStreamTx_t hStream, uint8_t* pkt, uint16_t wirelen, int src_id); 819 820/** 821 * @brief Closes the Tx ring buffer in the Tx stream 822 * 823 * @param[in] hStream The TX stream handle 824 * 825 * @retval NT_SUCCESS Success 826 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 827 */ 828void NT_NetTxRingbufferDone(NtNetStreamTx_t hStream); 829 830#endif 831 832//@G++ 833 834/** @page HwL3L4Checksum HW IP/UDP/TCP checksum 835 * @{ 836 * The NT40E2-4, NT20E2, NT4E2 adapters and NT4E in-line adapters support IPv4, UDP and TCP 837 * calculations in hardware on transmit.\n 838 * In order to use the feature, the packet descriptor must be configured prior to calling 839 * @ref NT_NetTxRelease().\n 840 * <b>Note:</b> The feature only works on non-fragmented packets.\n\n 841 * Here is an example on the configuration required before transmitting a packet. 842 * 843 @verbatim 844 845 struct IPv4Header_s { 846 uint16_t ip_hl: 4; 847 uint16_t ip_v: 4; 848 uint16_t ip_tos: 8; 849 uint16_t ip_len; 850 851 uint32_t ip_id:16; 852 uint32_t ip_frag_off:16; 853#define IP_DONT_FRAGMENT 0x4000 854#define IP_MORE_FRAGMENTS 0x2000 855 856 uint32_t ip_ttl:8; 857 uint32_t ip_prot:8; 858 uint32_t ip_crc:16; 859 860 uint32_t ip_src; 861 uint32_t ip_dest; 862}; //20 bytes 863 864struct UDPHeader_s { 865 uint32_t udp_src:16; 866 uint32_t udp_dest:16; 867 868 uint32_t udp_len:16; 869 uint32_t udp_crc:16; 870}; // 8 bytes 871 872 873 NT_NET_SET_PKT_IS_IP(hNetBuf, 1); 874 NT_NET_SET_PKT_IS_UDP(hNetBuf, 1); 875 NT_NET_SET_PKT_IP_CSUM_OK(hNetBuf, 1); 876 NT_NET_SET_PKT_UDP_CSUM_OK(hNetBuf, 1); 877 if(NT_NET_GET_PKT_DESCRIPTOR_TYPE(hNetBuf) == NT_PACKET_DESCRIPTOR_TYPE_NT_EXTENDED) { 878 NT_NET_SET_PKT_ISL(hNetBuf, 0); 879 NT_NET_SET_PKT_VLAN_COUNT(hNetBuf, 0); 880 NT_NET_SET_PKT_MPLS_COUNT(hNetBuf, 0); 881 NT_NET_SET_PKT_L2_FRAME_TYPE(hNetBuf, NT_L2_FRAME_TYPE_ETHER_II); 882 NT_NET_SET_PKT_L3_FRAME_TYPE(hNetBuf, NT_L3_FRAME_TYPE_IPv4); 883 NT_NET_SET_PKT_L4_FRAME_TYPE(hNetBuf, NT_L4_FRAME_TYPE_UDP); 884 NT_NET_SET_PKT_L3_LENGTH(hNetBuf, sizeof(struct IPv4Header_s)>>2); 885 NT_NET_SET_PKT_L4_LENGTH(hNetBuf, sizeof(struct UDPHeader_s)>>2); 886 NT_NET_SET_PKT_CALC_L3_CHECKSUM(hNetBuf, 1); 887 NT_NET_SET_PKT_CALC_L4_CHECKSUM(hNetBuf, 1); 888 } 889 @endverbatim 890 891 @} */ 892 893/** @page PacketBasedTransmit Packet based transmit 894 * @{ 895 * 896 * For packet based transmit see the example @ref transmit_example.c "net/transmit/transmit_example.c" 897 @} */ 898 899/** @page SegmentBasedTransmit Segment based transmit 900 * @{ 901 * 902 * For segment based transmit see the example @ref transmitSegment_example.c "net/transmitSegment/transmitSegment_example.c" 903 @} */ 904 905/** @} */ 906 907 908/** @addtogroup StreamFile 909 *@{ 910 */ 911/** 912 * Network file stream handle - used for file streams 913 */ 914typedef struct NtNetStreamFile_s* NtNetStreamFile_t; 915 916/** 917 * @brief Opens a capture file 918 * 919 * This function is called to open a capture file, captured with a segment-based stream. 920 * The capture file must have an NT, PCAP or PCAP-NG file header otherwise it will fail 921 * when opening the capture file. 922 * 923 * @param[out] hStream Reference to a NetFile_t stream pointer 924 * @param[in] name A stream friendly name - used in, for example, logging statements 925 * @param[in] netIntf Deliver packets or segments 926 * @param[in] file The capture file to open 927 * 928 * @retval NT_SUCCESS Success 929 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 930 */ 931int NT_NetFileOpen(NtNetStreamFile_t* hStream, const char* name, enum NtNetInterface_e netIntf, const char* file); 932 933/** 934* @brief Opens a capture file (extended version) 935* 936* This function is called to open a capture file, captured with a segment-based stream. 937* The capture file must have an NT, PCAP or PCAP-NG file header otherwise it will fail 938* when opening the capture file. 939* 940* @param[out] hStream Reference to a NetFile_t stream pointer 941* @param[in] name A stream friendly name - used in, for example, logging statements 942* @param[in] netIntf Deliver packets or segments 943* @param[in] file The capture file to open 944* @param[in] noConvert Do not convert PCAP files (Native PCAP tx for 4GA) 945* 946* @retval NT_SUCCESS Success 947* @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 948*/ 949int NT_NetFileOpen_v2(NtNetStreamFile_t* hStream, const char* name, enum NtNetInterface_e netIntf, const char* file, bool noConvert); 950 951/** 952 * @brief Gets packets/segments from a file stream 953 * 954 * This function is called to retrieve packets or segments from a capture file 955 * 956 * @note This function has no mutex protection, therefore the same hStream cannot be used by multiple threads 957 * 958 * @param[in] hStream NetFile stream handle 959 * @param[out] netBuf Packet/segment container reference 960 * 961 * @retval NT_SUCCESS (0) Success 962 * @retval NT_STATUS_END_OF_FILE EOF indicator - See note 963 * @retval otherwise Error - use @ref NT_ExplainError for an error description 964 * @note When NT_STATUS_END_OF_FILE is returned the internal file offset that been reset making it possible to 965 * call NT_NetFileGet() again without having to close and open the file, which improves performance when 966 * replaying a file continuously. 967 */ 968int NT_NetFileGet(NtNetStreamFile_t hStream, NtNetBuf_t* netBuf); 969 970/** 971 * @brief Releases the network buffer 972 * 973 * This function will release the netBuf data obtained via NT_FileGet 974 * 975 * @note This function has no mutex protection, therefore the same hStream cannot be used by multiple threads 976 * 977 * @param[in] hStream NetStreamFile stream handle 978 * @param[in] netBuf The network buffer is received via NT_FileGet 979 * 980 * @retval NT_SUCCESS Success 981 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 982 */ 983int NT_NetFileRelease(NtNetStreamFile_t hStream, NtNetBuf_t netBuf); 984 985/** 986 * @brief Closes a file stream 987 * 988 * This function is called to close a file stream 989 * 990 * @param[in] hStream The file stream handle to close 991 * 992 * @retval NT_SUCCESS Success 993 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 994 */ 995int NT_NetFileClose(NtNetStreamFile_t hStream); 996 997/** 998 * @brief Read information about a file stream 999 * 1000 * This function is called to read information about a file stream 1001 * 1002 * @param[in] hStream The file stream handle 1003 * @param[in,out] data Structure containing command and returned data 1004 * 1005 * @retval NT_SUCCESS Success 1006 * @retval !=NT_SUCCESS Error - use @ref NT_ExplainError for an error description 1007 */ 1008int NT_NetFileRead(NtNetStreamFile_t hStream, NtNetFileRead_t* data); 1009 1010 1011/** @} */ 1012 1013/** 1014 * MACROs to access network data 1015 */ 1016 1017/** 1018 * Layer 2 types 1019 */ 1020enum NtL2FrameType_e { 1021 NT_L2_FRAME_TYPE_ETHER_II=0, //!< Ether type II frame 1022 NT_L2_FRAME_TYPE_LLC, //!< LLC frame 1023 NT_L2_FRAME_TYPE_SNAP, //!< SNAP frame 1024 NT_L2_FRAME_TYPE_NOVELL_RAW //!< Novell Raw frame 1025}; 1026 1027/** 1028 * Layer 3 types 1029 */ 1030enum NtL3FrameType_e { 1031 NT_L3_FRAME_TYPE_IPv4=0, //!< IPv4 frame 1032 NT_L3_FRAME_TYPE_IPv6, //!< IPV6 frame 1033 NT_L3_FRAME_TYPE_IPX, //!< IPX frame 1034 NT_L3_FRAME_TYPE_OTHER, //!< Other frame 1035}; 1036 1037/** 1038 * Layer 4 frame types 1039 */ 1040enum NtL4FrameType_e { 1041 NT_L4_FRAME_TYPE_TCP=0, //!< TCP frame 1042 NT_L4_FRAME_TYPE_UDP, //!< UDP frame 1043 NT_L4_FRAME_TYPE_ICMP, //!< ICMP frame 1044 NT_L4_FRAME_TYPE_OTHER, //!< Other frame 1045 NT_L4_FRAME_TYPE_GRE, //!< GRE frame 1046 NT_L4_FRAME_TYPE_SCTP, //!< SCTP frame 1047 NT_L4_FRAME_TYPE_IPV4, //!< IPV4 in IP frame 1048 NT_L4_FRAME_TYPE_IPV6, //!< IPV6 in IP frame 1049}; 1050 1051/** 1052 * Layer 4 port types 1053 */ 1054enum NtL4PortType_e { 1055 NT_L4_PORT_OTHER=0, //!< Other port 1056 NT_L4_PORT_GTPV0_U, //!< GTPV0_U port 1057 NT_L4_PORT_GTPV1V2_C, //!< GTPV1V2_C port 1058 NT_L4_PORT_GTPV1_U //!< GTPV1_U port 1059}; 1060 1061/** 1062 * Frame tunnel types 1063 */ 1064enum NtTunnelType_e { 1065 NT_TUNNELTYPE_OTHER=0, //!< Other data type 1066 NT_TUNNELTYPE_GTPV0_U, //!< GTPV0_U data type 1067 NT_TUNNELTYPE_GTPV1V2_C, //!< GTPV1V2_C data type 1068 NT_TUNNELTYPE_GTPV1_U_SIGNAL, //!< GTPV1_U_SIGNAL type 1069 NT_TUNNELTYPE_GTPV1_U_GPDU, //!< GTPV1_U_GPDU data type 1070 NT_TUNNELTYPE_IPINIP, //!< IPINIP data type 1071}; 1072 1073/** 1074 * L3 fragmentation 1075 */ 1076enum NtL3FragmentType_e { 1077 NT_L3_FRAGMENT_TYPE_NONE, //!< L3 not fragmented 1078 NT_L3_FRAGMENT_TYPE_FIRST, //!< L3 first fragment 1079 NT_L3_FRAGMENT_TYPE_MIDDLE, //!< L3 middle fragment 1080 NT_L3_FRAGMENT_TYPE_LAST, //!< L3 last fragment 1081}; 1082 1083/** @addtogroup NetworkStream 1084 *@{ 1085 */ 1086 1087/** 1088 * @defgroup MetaDataMacros User meta data container 1089 * @{ 1090 * The following macros get and set user defined meta data. 1091 * Use these fields as house-keeping storage. No NTAPI function use these meta containers for anything. 1092 * 1093 */ 1094 1095/** @def NT_NET_GET_USER_META_ARG0 1096 * @brief Returns the meta data arg0 uintptr_t value 1097 * @param[in] "_hNetBuf_" NetBuf pointer 1098 * @hideinitializer 1099 */ 1100#define NT_NET_GET_USER_META_ARG0(_hNetBuf_) ((_hNetBuf_)->arg0) 1101 1102/** @def NT_NET_GET_USER_META_ARG1 1103 * @brief Returns the meta data arg1 uintptr_t value 1104 * @param[in] "_hNetBuf_" NetBuf pointer 1105 * @hideinitializer 1106 */ 1107#define NT_NET_GET_USER_META_ARG1(_hNetBuf_) ((_hNetBuf_)->arg1) 1108 1109/** @def NT_NET_GET_USER_META_ARG2 1110 * @brief Returns the meta data arg2 uintptr_t value 1111 * @param[in] "_hNetBuf_" NetBuf pointer 1112 * @hideinitializer 1113 */ 1114#define NT_NET_GET_USER_META_ARG2(_hNetBuf_) ((_hNetBuf_)->arg2) 1115 1116/** @def NT_NET_SET_USER_META_ARG0 1117 * @brief Set the meta data arg0 uintptr_t value 1118 * @param[in] "_hNetBuf_" NetBuf pointer 1119 * @param[in] value An uintptr_t sized value 1120 * @hideinitializer 1121 */ 1122#define NT_NET_SET_USER_META_ARG0(_hNetBuf_, value) ((_hNetBuf_)->arg0 = (value)) 1123 1124/** @def NT_NET_SET_USER_META_ARG1 1125 * @brief Set the meta data arg1 uintptr_t value 1126 * @param[in] "_hNetBuf_" NetBuf pointer 1127 * @param[in] value An uintptr_t sized value 1128 * @hideinitializer 1129 */ 1130#define NT_NET_SET_USER_META_ARG1(_hNetBuf_, value) ((_hNetBuf_)->arg1 = (value)) 1131 1132/** @def NT_NET_SET_USER_META_ARG2 1133 * @brief Set the meta data arg2 uintptr_t value 1134 * @param[in] "_hNetBuf_" NetBuf pointer 1135 * @param[in] value An uintptr_t sized value 1136 * @hideinitializer 1137 */ 1138#define NT_NET_SET_USER_META_ARG2(_hNetBuf_, value) ((_hNetBuf_)->arg2 = (value)) 1139 1140/** @} */ 1141 1142/** @defgroup DataMacros Network macros 1143 * @{ 1144 * The network stream delivers data to the application. In order to access data 1145 * content, such as packet length or packet receive time stamp, a set of macros is 1146 * provided. These macros are divided into 2 major groups: 1147 * - @ref SegmentMacros 1148 * - @ref PacketMacros 1149 * 1150 * The @ref SegmentMacros are used with the segment-based interface 1151 * The @ref PacketMacros are used with the packet-based interface 1152 */ 1153 1154/** @defgroup SegmentMacros Segment macros 1155 * @{ 1156 * The following is only possible on segment-based streams 1157 */ 1158 1159/** @def NT_NET_GET_SEGMENT_PTR 1160 * @brief Returns the segment pointer 1161 * @param[in] "_hNetBuf_" Segment container reference 1162 * @hideinitializer 1163 */ 1164#define NT_NET_GET_SEGMENT_PTR(_hNetBuf_) ((_hNetBuf_)->hHdr) 1165 1166/** @def NT_NET_GET_SEGMENT_LENGTH 1167 * @brief Returns the segment length 1168 * @param[in] "_hNetBuf_" Segment container reference 1169 * @hideinitializer 1170 */ 1171#define NT_NET_GET_SEGMENT_LENGTH(_hNetBuf_) ((size_t)(_hNetBuf_)->length) 1172 1173/** @def NT_NET_GET_SEGMENT_PKTS 1174 * @brief Returns the number of packets in a segment 1175 * 1176 * This macro is only supported on NT4GA adapters configured to static segment 1177 * size emulation mode. On NT4GA adapters configured to dynamic segment size 1178 * this macro will always return 0. 1179 * @param[in] "_hNetBuf_" Segment container reference 1180 * @hideinitializer 1181 */ 1182#define NT_NET_GET_SEGMENT_PKTS(_hNetBuf_) ((size_t)(_hNetBuf_)->pkts) 1183 1184/** @def NT_NET_GET_SEGMENT_TIMESTAMP 1185 * @brief The time stamp of the first packet in the segment 1186 * @param[in] "_hNetBuf_" Segment container reference 1187 * @hideinitializer 1188 */ 1189#define NT_NET_GET_SEGMENT_TIMESTAMP(_hNetBuf_) NT_NetGetSegmentTimestamp((_hNetBuf_)->hHdr) 1190uint64_t NT_NetGetSegmentTimestamp(void* pDescr); 1191 1192/** @def NT_NET_GET_SEGMENT_TIMESTAMP_TYPE 1193 * @brief The time stamp type 1194 * @param[in] "_hNetBuf_" Segment container reference 1195 * @hideinitializer 1196 */ 1197#define NT_NET_GET_SEGMENT_TIMESTAMP_TYPE(_hNetBuf_) ((_hNetBuf_)->tsType) 1198 1199/** @def NT_NET_SET_SEGMENT_LENGTH 1200 * @brief Sets the segment length 1201 * 1202 * This is used when generating a TX segment and should be used with care. 1203 * @param[in,out] "_hNetBuf_" Segment container reference 1204 * @param[in] "_length_" Length of the segment 1205 * @hideinitializer 1206 */ 1207#define NT_NET_SET_SEGMENT_LENGTH(_hNetBuf_, _length_) do {(_hNetBuf_)->length=_length_;} while(0) 1208 1209 1210/** @defgroup SegmentFunctions Functions to handle segment data 1211 * @{ 1212 * These inline C functions are only valid when "PacketDescriptor" in ntservice.ini file has been set to any value than PCAP 1213 * and @ref NT_NET_GET_PKT_DESCRIPTOR_TYPE returns @ref NT_PACKET_DESCRIPTOR_TYPE_NT_EXTENDED or @ref NT_PACKET_DESCRIPTOR_TYPE_NT 1214 */ 1215/** 1216 * @brief Inline C function to create a segment NtNetBuf_t 1217 * 1218 * This function is used when creating segments in application memory, e.g. 1219 * when constructing a transmit segment 1220 * 1221 * @param[in] size Size of the memory provided by the "mem" pointer 1222 * @param[in] mem Pointer to the segment memory allocated 1223 * @param[in] portOffset Segments are per adapter and ports are relative to the port offset. The port offset can be found in @ref NtInfoAdapter_v6_s::portOffset. If 0 is provided then the possible values in @ref NT_NET_SET_PKT_TXPORT can only be from 0 to 3. 1224 * @param[out] segNetBuf Destination segment NtNetBuf_t structure 1225 * 1226 */ 1227static NT_INLINE void _nt_net_create_segment_netbuf(uint64_t size, void* mem, uint8_t portOffset, struct NtNetBuf_s* segNetBuf) 1228{ 1229 memset(segNetBuf, 0, sizeof(struct NtNetBuf_s)); 1230 segNetBuf->length=size; 1231 segNetBuf->portOffset=portOffset; 1232 segNetBuf->hHdr=(NtNetBufHdr_t)(mem); 1233 segNetBuf->hPkt=(NtNetBufPkt_t)(mem); 1234 *((uint64_t*)mem+0)=0; 1235 *((uint64_t*)mem+1)=0; 1236 *((uint64_t*)mem+2)=0; 1237 *((uint64_t*)mem+3)=0; 1238} 1239 1240/** 1241 * @brief Inline C function to use when traversing segments. The 1242 * function will update the NetBuf to the next packet 1243 * in the segment. 1244 * 1245 * @param[in] segNetBuf Segment NtNetBuf_s * structure 1246 * @param[in] segLength Length of the segment - used to know when there is no more data 1247 * @param[out] pktNetBuf Packet NtNetBuf_s * structure 1248 * 1249 * @retval Returns the amount of data left in the segment 1250 */ 1251static NT_INLINE uint64_t _nt_net_get_next_packet(struct NtNetBuf_s* segNetBuf, uint64_t segLength, struct NtNetBuf_s* pktNetBuf) 1252{ 1253 if(segLength) { 1254 uint8_t* nextPacket = (uint8_t*)pktNetBuf->hHdr + NT_NET_GET_PKT_CAP_LENGTH(pktNetBuf); 1255 uint8_t* endSegm = (uint8_t*)segNetBuf->hHdr + segLength; 1256 // If this was the last packet then do not traverse any further 1257 if (nextPacket >= endSegm) { 1258 return 0; 1259 } 1260 pktNetBuf->hHdr=(NtNetBufHdr_t)nextPacket; 1261 pktNetBuf->hPkt=(NtNetBufPkt_t)(nextPacket + NT_NET_GET_PKT_DESCR_LENGTH(pktNetBuf)); 1262 return (endSegm - nextPacket); 1263 } else { 1264 return 0; 1265 } 1266} 1267 1268/** 1269 * @brief Inline C function to build a packet based NtNetBuf_t 1270 * from a segment based NtNetBuf_t 1271 * 1272 * @param[in] segNetBuf Segment NtNetBuf_t structure 1273 * @param[out] pktNetBuf Destination packet NtNetBuf_t structure 1274 * 1275 */ 1276static NT_INLINE void _nt_net_build_pkt_netbuf(struct NtNetBuf_s* segNetBuf, struct NtNetBuf_s* pktNetBuf) 1277{ 1278 memcpy((void*)pktNetBuf, (void*)segNetBuf, sizeof(struct NtNetBuf_s)); 1279 pktNetBuf->hHdr=(NtNetBufHdr_t)(segNetBuf->hHdr); 1280 pktNetBuf->hPkt=(NtNetBufPkt_t)((uint8_t*)segNetBuf->hHdr+NT_NET_GET_PKT_DESCR_LENGTH(segNetBuf)); 1281} 1282 1283/** 1284 * @brief Inline C function to initialize a segment NtNetBuf_t structure 1285 * using any received segment buffer. 1286 * 1287 * This function is used when a new NtNetBuf_t handle is needed for a provided segment 1288 * buffer, e.g. when copying segments 1289 * 1290 * @param[in] size Size of the segment pointed to by the "segment" pointer 1291 * @param[in] segment Pointer to the segment 1292 * @param[in] portOffset Segments are per adapter and ports are relative to the port offset. The port offset of the adapter of which the segment originates from most be copied/stored in parallel, or known by some other means, and specified here. If 0 is used here local ports will be seen as virtual ports. 1293 * @param[out] segNetBuf Segment NtNetBuf_t structure to initialize 1294 * 1295 */ 1296static NT_INLINE void _nt_net_initialize_segment_netbuf(uint64_t size, void* segment, uint8_t portOffset, struct NtNetBuf_s* segNetBuf) 1297{ 1298 memset(segNetBuf, 0, sizeof(struct NtNetBuf_s)); 1299 segNetBuf->length=size; 1300 segNetBuf->portOffset=portOffset; 1301 segNetBuf->hHdr=(NtNetBufHdr_t)(segment); 1302 segNetBuf->hPkt=(NtNetBufPkt_t)(segment); 1303} 1304 1305 1306/** @} */ 1307 1308/** @} */ 1309 1310/** @} */ 1311/** @} */ 1312/** @} */ 1313 1314 1315#ifndef DOXYGEN_INTERNAL_ONLY 1316#define NT_MAKE_STRUCTURE_ID( __structureType, __structureName ) \ 1317 ((uint32_t)((__structureType << 16) | sizeof(__structureName))) 1318 1319/** 1320 * File header. This data must be placed in the beginning of a 1321 * file when storing data to disk. 1322 */ 1323#define NT_FILE_HEADER0_COOKIE 0xDEADBEAF 1324// Ensure that the following is packed equally on 32 and 64bit 1325#pragma pack(push, 1) 1326typedef struct NtFileHeader0_s { 1327 /** 1328 * StructureID is used to identify the header structure type 1329 */ 1330 uint32_t structid; //!< The segment descriptor version 1331 uint64_t align; //!< Alignment to ensure the cookie is located at offset 12 1332 /** 1333 * Cookie to validate the header 1334 */ 1335 uint32_t cookie; //!< Cookie = 0xDEADBEAF. Must be located at offset 12 to be able to detect if the file starts with a packet. The cookie will be located where storedLength is found in a packet. 1336 /** 1337 * The time stamp type used to time stamp the segments - very useful in offline mode 1338 */ 1339 uint8_t tsType; //!< Timestamp type that is supplied with 'TimeValidAt' 1340 /** 1341 * Port offset. All packets in the segment have a per adapter specific port index 1342 * and by adding this portOffset, the system-wide port is retrieved. 1343 */ 1344 uint8_t portOffset; //!< Port offset - use to calculate the virtual port number 1345 /** 1346 * Color lookup. 1347 * Contains the customer color ID mapping to HW IDs. 1348 */ 1349 uint8_t colorMap[64]; //!< Filter color map table 1350 uint8_t reserved[46]; //!< Reserved. Total structure size must be 128 bytes. 1351} NtFileHeader0_t; 1352 1353// Disable packing 1354#pragma pack(pop) 1355#define NT_STID_FILE_HEADER0 NT_MAKE_STRUCTURE_ID(1, NtFileHeader0_t) 1356#endif 1357#endif /* __STREAM_NET_H__ */ 1358 1359// 1360// EOF 1361//