stream_net.h
Go to the documentation of this file.
136 * @note Timesynchronisation is required when merging from different adapters (see @ref MainDocMainFeaturesVirtPort_AdapterMerge).
156 * With NT3GA FPGAs Tx mode selection is an adapter global configuration - controlled by the actual FPGA image functionality and the profile ini-option.\n
157 * With NT4GA FPGAs the configuration granularity has changed - Tx mode selection can be set up/configured dynamically on individual streams.\n
160 * Tx streams are normally "per port Tx mode" - meaning that one host buffer is allocated per (Tx) port set in the (Tx) portMask specfied to NT_NetTxOpen.
161 * Each allocated host buffer will be paired to a specific Tx port and the txPort field in the standard packet descriptor will have no meaning/effect.
163 * Adapter-based multi-port transmit buffer mode (named after its option/flag) will allocate one host buffer per adapter that has (Tx) ports set in the (Tx) portMask specified to NetTxOpen.
164 * Each host buffer allocated will be paired to a specific adapter - and that host buffer will be able to transmit on all the ports mentioned in the portMask on the adapter it is paired with.
167 * Adapter-based multi-port transmit buffer mode is selected by a new option (called flags) that is introduced to the attributes used by NTAPI function NT_NetTxOpen_Attr().
168 * The new NT_NETTX_OPEN_FLAGS_ADAPTER_MULTI_PORT_BUFFER flag/attribute is set up using NT_NetTxOpenAttrSetFlags().
170 * With NT4GA Test & Measurement FPGAs the following can be controlled per transmitted packet: timestamp injection, FCS calculation, Layer 3 checksum calculation and Layer 4 checksum calculation.
171 * See @ref test_and_measurement_4ga_introduction "4GA Test and Measurement features" for a detailed description.
219 * This structure is used by the @ref NetworkStream Get/Release functions and provides a handle to the returned data.
260 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
262 NT_NETRX_READ_CMD_PCAP_FCS, //!< Returns whether packets with pcap descriptors include ethernet FCS
263 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)
292 uint64_t pktsDropped; //!< Packets dropped because the application is affected by the host buffer allowance (hysteresis)
293 uint64_t octetsDropped; //!< Bytes dropped because the application is affected by the host buffer allowance (hysteresis)
300 uint64_t ts; //!< Current stream time. Can be used when NT_NetRxGet() returns timeout to get the time of the stream.
311 * Expose buffer info to the user (Napatech internal use only - may change without further notice)
326 uint32_t numAssignedHostBuffers; //!< The number of host buffers assigned and also the depth of the array
348 struct NtNetRxFileHeader_s fileheader; //!< The structure to use for @ref NtNetRx_s::cmd==NT_NETRX_READ_CMD_GET_FILE_HEADER
349 struct NtNetRxStreamDrop_s streamDrop; //!< The structure to use for @ref NtNetRx_s::cmd==NT_NETRX_READ_CMD_STREAM_DROP
350 struct NtNetRxStreamTime_s streamTime; //!< The structure to use for @ref NtNetRx_s::cmd==NT_NETRX_READ_CMD_STREAM_TIME
351 struct NtNetRxPcapInfo_s pcap; //!< The structure to use for @ref NtNetRx_s::cmd==NT_NETRX_READ_CMD_PCAP_INFO
352 struct NtNetRxHbRing_s ringControl; //!< The structure to use for @ref NtNetRx_s::cmd==NT_NETRX_READ_CMD_GET_RING_CONTROL
353 struct NtNetRxHbInfo_s hbInfo; //!< The structure to use for @ref NtNetRx_s::cmd==NT_NETRX_READ_CMD_GET_HB_INFO
363 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)
370 unsigned int numHostBuffers; //!< The number of host buffers used by the stream and also the depth of the array
406 struct NtNetTxHbRing_s ringControl; //!< Control of the host buffer ring (Napatech internal use only - may change without further notice)
428 NT_NETFILE_READ_DESCRIPTOR_CMD, //!< Read information about the descriptor and timestamp format used
437 uint64_t lastTimestamp; //!< The time stamp in the last packet in last segment read using the function @ref NT_NetFileGet
440 uint64_t firstTimestamp; //!< The time stamp in the first packet in first segment read using the function @ref NT_NetFileGet
462 * NetFileRead stream structure - network File data is read via this structure via @ref NT_NetFileRead()
470 struct NtNetFileReadInfo_v1_s info_v1; //!< Information about the NetFile. Used by NT_NETFILE_READ_INFO_CMD
471 struct NtNetFileReadDesc_s desc; //!< Information about the descriptor and timestamp format used. Used by NT_NETFILE_READ_DESCRIPTOR_CMD
475 struct NtNetFileReadInfo_s info; //!< Information about the NetFile. Used by NT_NETFILE_READ_INFO_CMD
540 * In-line network streams cannot be shared and any attempt to open an existing in-line stream fails with an error return value.
543 * after this call to avoid packet drop. Host buffers are assigned/released to the streamid within
549 * @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
550 * @param[in] hostBufferAllowance Drop level for the host buffer allowance (hysteresis), -1 means disabled
555 int NT_NetRxOpen(NtNetStreamRx_t* hStream, const char* name, enum NtNetInterface_e netIntf, uint32_t streamId, int hostBufferAllowance);
560 * This function is called to retrieve a handle to an in-line or capture network stream with flags.
562 * In-line network streams cannot be shared and any attempt to open an existing in-line stream fails with an error return value.
565 * after this call to avoid packet drop. Host buffers are assigned/released to the streamid within
568 * The flags shall be either NT_NETRX_OPEN_FLAGS_NONE or the bitwise-inclusive OR of one or more of the other
574 * NT_NETRX_OPEN_FLAGS_READONLY_STREAM | Using this option will cause a write to data returned by NT_NetRxGet to fail with a segmentation fault.
579 * @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
580 * @param[in] hostBufferAllowance Drop level for the host buffer allowance (hysteresis), -1 means disabled
586 int NT_NetRxOpen_v2(NtNetStreamRx_t* hStream, const char* name, enum NtNetInterface_e netIntf, uint32_t streamId, int hostBufferAllowance, int flags);
633 * @param[in] hostBufferAllowance Drop level for the host buffer allowance (hysteresis), -1 means disabled
646 * The flags shall be either NT_NETRX_NONE or the bitwise-inclusive OR of one or more of the other
652 * NT_NETRX_READONLY_STREAM | Using this option will cause a write to data returned by NT_NetRxGet to fail with a segmentation fault.
668 * This function is called to retrieve a handle to an in-line or capture network stream with flags.
670 * after this call to avoid packet drop. Host buffers are assigned/released to the streamid within
674 * @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
689 * after this call to avoid packet drop. Host buffers are assigned/released to the streamid within
695 * @param[in] paStreamId Array containing the network stream IDs to open. A maximum of 8 streams can be specified.
697 * @param[in] hostBufferAllowance Drop level for the host buffer allowance (hysteresis), -1 means disabled
702 int NT_NetRxOpenMulti(NtNetStreamRx_t* hStream, const char* name, enum NtNetInterface_e netIntf, uint32_t* paStreamId, unsigned int numStreamIds, int hostBufferAllowance);
707 * This function is called to retrieve a handle to an in-line or capture network streams with flags.
711 * after this call to avoid packet drop. Host buffers are assigned/released to the streamid within
714 * The flags shall be either NT_NETRX_NONE or the bitwise-inclusive OR of one or more of the other
720 * NT_NETRX_READONLY_STREAM | Using this option will cause a write to data returned by NT_NetRxGet to fail with a segmentation fault.
725 * @param[in] paStreamId Array containing the network stream IDs to open. A maximum of 8 streams can be specified.
727 * @param[in] hostBufferAllowance Drop level for the host buffer allowancei (hysteresis), -1 means disabled
733 int NT_NetRxOpenMulti_v2(NtNetStreamRx_t* hStream, const char* name, enum NtNetInterface_e netIntf, uint32_t* paStreamId, unsigned int numStreamIds, int hostBufferAllowance, int flags);
738 * This function is called to retrieve a handle to an in-line or capture network streams with flags.
742 * after this call to avoid packet drop. Host buffers are assigned/released to the streamid within
746 * @param[in] paStreamId Array containing the network stream IDs to open. A maximum of 8 streams can be specified.
753 int NT_NetRxOpenMulti_Attr(NtNetStreamRx_t* hStream, uint32_t* paStreamId, unsigned int numStreamIds, const NtNetRxAttr_t* attr);
764 * is divided into sleep intervals (with intervals approximating the segment timeout on the adapter).
767 * 2) using events. If the system cannot do uSec sleeps, then the suspension mechanism used is event
768 * based. It puts the calling process to sleep waiting for an event. On data receival an event is sent
772 * @param[out] netBuf Segment/packet container reference, is set to NULL if return value is not NT_SUCCESS
773 * @param[in] timeout The timeout in milliseconds. The call will return when any data is available, or when the timeout is reached.
774 * A timeout of -1 will wait indefinitely if using the packet mode. In segment mode the waiting is always capped
775 * to the next HostBufferPollInterval (ntservice.ini), which is 100 usecs by default, at which point an empty
776 * segment is returned, if no data arrived. So in segment mode, any timeout larger than HostBufferPollInterval
779 * @note This function has no mutex protection, therefore the same hStream cannot be used by multiple threads
780 * @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.
781 * The time stamp update will make it possible for users to merge packets in segments from different stream ids.
785 * @retval NT_STATUS_TRYAGAIN The resource is temporarily unavailable because of reconfiguration - call NT_NetRxGet() again
793 * This function is called to retrieve packets from a in-line or capture stream. The function will
794 * automatically release the previous packet when called, hence it is not possible to keep packets and if necessary
795 * the packets must be copied to a safe buffer before calling the function to get the next packet.
798 * @param[out] netBuf Segment/packet container reference, is set to NULL if return value is not NT_SUCCESS
799 * @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.
801 * @note This function has no mutex protection, therefore the same hStream cannot be used by multiple threads
803 * @retval NT_SUCCESS Data has been returned and will be valid until the next @ref NT_NetRxGetNextPacket() call
805 * @retval NT_STATUS_TRYAGAIN The resource is temporarily unavailable because of reconfiguration - call NT_NetRxGetNextPacket() again
831 * @note This function has no mutex protection, therefore the same hStream cannot be used by multiple threads
869 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.
871 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).
872 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.
873 NT_NETTX_PACKET_OPTION_DYN, //!< Gets a TX buffer with a pre-configured dynamic packet descriptor. Use this option to transmit L2 data. This option uses packetSize as wire length. Set DescriptorMode before using this option.
880 NT_NETTX_NUMA_ANY_HB=0xFFFFFFFE, //!< (=-2) Allocate TX host buffer from any TX host buffer pool
881 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
890 NT_NETTX_OPEN_FLAGS_ADAPTER_MULTI_PORT_BUFFER=(1LL<<0), //!< Allocate one TX host buffer per adapter that has ports set in NT_NetTXOpen portmask - if unset allocate one TX host buffer per port that is set in NT_NetTXOpen portmask
899 * Note that the TX stream on capture-only adapters (NT4E Capture, NT4E_STD Capture and NT20E Capture)
907 * @param[in] NUMA NUMA node on which the host buffer is be located (NOTE: Special options in NtNetTxOpenNumaOption_e)
916 int NT_NetTxOpen(NtNetStreamTx_t* hStream, const char* name, uint64_t portMask, uint32_t NUMA, uint32_t minHostBufferSize);
931 * @param[in] NUMA NUMA node on which the host buffer is be located (NOTE: Special options in NtNetTxOpenNumaOption_e)
932 * @param[in] minHostBufferSize Minimum size of host buffer needed in <em>MBytes</em>. The smallest host
942 int 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);
956 * @param[in] NUMA NUMA node on which the host buffer is be located (NOTE: Special options in NtNetTxOpenNumaOption_e)
957 * @param[in] minHostBufferSize Minimum size of host buffer needed in <em>bytes</em>. The smallest host
968 * When using NT_NetTxOpen() >= 3: ntservice ini-option System.NtapiNetTxSegmentRawAlignMode can be used to control NT_NetTxGet()/NT_NetTxRelease() behaviour for NT_NETTX_SEGMENT_OPTION_RAW mode.
969 * System.NtapiNetTxSegmentRawAlignMode = 1 will retain previous NTAPI default behaviour where RAW segment mode always operates on a whole (aligned) underlying slab (segment) typically (1,2,4 MB - dictated by FPGA)
970 * System.NtapiNetTxSegmentRawAlignMode = 0 will enable NT4GA to operate on arbitrary raw segment sizes that will be placed back to back
971 * System.NtapiNetTxSegmentRawAlignMode = -1 will apply the decided default value for the current driver release. This default value (applied with -1) can change across driver releases.
973 int 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);
1013 int NT_NetTxOpenAttrSetDescriptorMode(NtNetTxAttr_t* attr, enum NtNetTxDescriptorMode_e descriptorMode);
1039 * @param[in] NUMA NUMA node on which the host buffer is be located (NOTE: Special options in enum ::NtNetTxOpenNumaOption_e)
1055 * flags shall be either NT_NETTX_OPEN_FLAGS_NONE (0) or the bitwise-inclusive OR of one or more of the other flags in enum ::NtNetTxOpenFlags_e
1069 * @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.
1085 void NT_NetTxOpenAttrSetDescriptor(NtNetTxAttr_t* attr, enum NtPacketDescriptorType_e descriptor);
1104 int NT_NetTxOpenAttrSetTxtDescriptorPosTimestampInject(NtNetTxAttr_t* attr, bool enable, uint32_t pos);
1113 void NT_NetTxOpenAttrGetTxtDescriptorPosTimestampInject(NtNetTxAttr_t* attr, bool* enable, uint32_t* pos);
1148 void NT_NetTxOpenAttrSetTimestampType(NtNetTxAttr_t* attr, enum NtTimestampType_e timestampType);
1166 int NT_NetTxOpenAttrSetDescriptorPosLayer3Offset(NtNetTxAttr_t* attr, bool enable, uint32_t pos);
1175 void NT_NetTxOpenAttrGetDescriptorPosLayer3Offset(const NtNetTxAttr_t* attr, bool* enable, uint32_t* pos);
1187 int NT_NetTxOpenAttrSetDescriptorPosLayer4Offset(NtNetTxAttr_t* attr, bool enable, uint32_t pos);
1196 void NT_NetTxOpenAttrGetDescriptorPosLayer4Offset(const NtNetTxAttr_t* attr, bool* enable, uint32_t* pos);
1217 void NT_NetTxOpenAttrGetDescriptorPosFrameType(const NtNetTxAttr_t* attr, bool* enable, uint32_t* pos);
1229 int NT_NetTxOpenAttrSetDescriptorPosChecksumCmd(NtNetTxAttr_t* attr, bool enable, uint32_t pos);
1238 void NT_NetTxOpenAttrGetDescriptorPosChecksumCmd(const NtNetTxAttr_t* attr, bool* enable, uint32_t* pos);
1261 void NT_NetTxOpenAttrGetDescriptorPosIgnoreBit(const NtNetTxAttr_t* attr, bool* enable, uint32_t* pos);
1284 void NT_NetTxOpenAttrGetDescriptorPosTxNowBit(const NtNetTxAttr_t* attr, bool* enable, uint32_t* pos);
1307 void NT_NetTxOpenAttrGetDescriptorPosClockBit(const NtNetTxAttr_t* attr, bool* enable, uint32_t* pos);
1344 * @note This function has no mutex protection, therefore the same hStream cannot be used by multiple threads
1350 * @param[in] packetOption Option to control the properties of the buffer, see @ref NtNetTxPacketOption_e for details
1351 * @param[in] timeout Time in milliseconds to wait for a new buffer - a timeout of -1 will wait indefinitely for a new buffer
1356 int NT_NetTxGet(NtNetStreamTx_t hStream, NtNetBuf_t* netBuf, uint32_t port, size_t packetSize, enum NtNetTxPacketOption_e packetOption, int timeout);
1363 * @note This function has no mutex protection and can therefore the same hStream cannot be used by multiple threads
1401 * This function is called to put together scattered fragments of a packet and add it to a TX stream
1403 * @note This function has no mutex protection and cannot be used by multiple threads on the same stream, hStream.
1409 * @param[in] timeout Time in milliseconds to wait for a packet buffer - a timeout of -1 will wait indefinitely for a packet buffer
1414 int NT_NetTxAddPacket(NtNetStreamTx_t hStream, uint32_t port, NtNetTxFragment_t* fragments, uint32_t fragmentCount, int timeout );
1481 * For packet based transmit see the example @ref transmit_packet_example.c "net/transmit/transmit_packet_example.c"
1487 * For segment based transmit see the example @ref transmit_segment_example.c "net/transmit_segment/transmit_segment_example.c"
1516 int NT_NetFileOpen(NtNetStreamFile_t* hStream, const char* name, enum NtNetInterface_e netIntf, const char* file);
1534 int NT_NetFileOpen_v2(NtNetStreamFile_t* hStream, const char* name, enum NtNetInterface_e netIntf, const char* file, bool noConvert);
1541 * @note This function has no mutex protection, therefore the same hStream cannot be used by multiple threads
1549 * @note When NT_STATUS_END_OF_FILE is returned the internal file offset that been reset making it possible to
1550 * call NT_NetFileGet() again without having to close and open the file, which improves performance when
1560 * @note This function has no mutex protection, therefore the same hStream cannot be used by multiple threads
1609 int NT_NetFileOpen_Attr(NtNetStreamFile_t* hStream, const char* file, const NtNetFileAttr_t* attr);
1694 int NT_NetFileOpenAttrSetConvertedTsType(NtNetFileAttr_t* attr, enum NtTimestampType_e convertedTsType);
1785 * Use these fields as house-keeping storage. No NTAPI function use these meta containers for anything.
1901 #define NT_NET_SET_SEGMENT_LENGTH(_hNetBuf_, _length_) do {(_hNetBuf_)->length=_length_;} while(0)
1906 * These inline C functions are only valid when "PacketDescriptor" in ntservice.ini file has been set to any value than PCAP
1907 * and @ref NT_NET_GET_PKT_DESCRIPTOR_TYPE returns @ref NT_PACKET_DESCRIPTOR_TYPE_NT_EXTENDED or @ref NT_PACKET_DESCRIPTOR_TYPE_NT
1917 * @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.
1921 static NT_INLINE void _nt_net_create_segment_netbuf(uint64_t size, void* mem, uint8_t portOffset, struct NtNetBuf_s* segNetBuf)
1945 static NT_INLINE uint64_t _nt_net_get_next_packet(struct NtNetBuf_s* segNetBuf, uint64_t segLength, struct NtNetBuf_s* pktNetBuf)
1970 static NT_INLINE void _nt_net_build_pkt_netbuf(struct NtNetBuf_s* segNetBuf, struct NtNetBuf_s* pktNetBuf)
1974 pktNetBuf->hPkt=(NtNetBufPkt_t)((uint8_t*)segNetBuf->hHdr+NT_NET_GET_PKT_DESCR_LENGTH(segNetBuf));
1986 * @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 logical ports.
1990 static NT_INLINE void _nt_net_initialize_segment_netbuf(uint64_t size, void* segment, uint8_t portOffset, struct NtNetBuf_s* segNetBuf)