Types and functions for operating with bRAWcap timestamps. More...

Macros
#define	BRAWCAP_TIMESTAMP_MODE_SYSL_AVAILABLE(_capabilities) (_capabilities & 0x01)
	Checks if timestamp mode system low precision is supported.

#define	BRAWCAP_TIMESTAMP_MODE_SYSH_AVAILABLE(_capabilities) (_capabilities & 0x02)
	Checks if timestamp mode system high precision is supported.

#define	BRAWCAP_TIMESTAMP_MODE_SW_AVAILABLE(_capabilities) (_capabilities & 0x04)
	Checks if timestamp mode software is supported.

#define	BRAWCAP_TIMESTAMP_MODE_ADAPTER_SYS_AVAILABLE(_capabilities) (_capabilities & 0x08)
	Checks if timestamp mode adapter system is supported.

#define	BRAWCAP_TIMESTAMP_MODE_ADAPTER_SW_AVAILABLE(_capabilities) (_capabilities & 0x10)
	Checks if timestamp mode adapter software is supported.

#define	BRAWCAP_TIMESTAMP_MODE_ADAPTER_HW_AVAILABLE(_capabilities) (_capabilities & 0x20)
	Checks if timestamp mode adapter hardware is supported.

#define	BRAWCAP_TIMESTAMP_RESOLUTION_UNKNOWN 0
	If a timestamp resolution is set to this value, it´s resolution is unknown - could not be resolved.

#define	BRAWCAP_TIMESTAMP_NS_PER_SEC 1000000000
	Number of nanoseconds per second.

#define	BRAWCAP_TIMESTAMP_US_PER_SEC 1000000
	Number of microseconds per second.

#define	BRAWCAP_TIMESTAMP_MS_PER_SEC 1000
	Number of milliseconds per second.

#define	BRAWCAP_TIMESTAMP_NS_PER_US 1000
	Number of nanoseconds per microsecond.

#define	BRAWCAP_TIMESTAMP_NS_PER_MS 1000000
	Number of nanoseconds per millisecond.

Typedefs
typedef UINT32	brawcap_timestamp_capabilities_t
	Type used for indicating the supported timestamp modes.

typedef UINT32	brawcap_timestamp_resolution_ns_t
	Represents the timestamp resolution in nanoseconds.

typedef struct _brawcap_timestamp	brawcap_timestamp_t
	bRAWcap timestamp object.

Enumerations
enum	brawcap_timestamp_mode_t { BRAWCAP_TIMESTAMP_MODE_NO_TIMESTAMP = 0x00 , BRAWCAP_TIMESTAMP_MODE_SYSTEM_LOWPREC = 0x01 , BRAWCAP_TIMESTAMP_MODE_SYSTEM_HIGHPREC = 0x02 , BRAWCAP_TIMESTAMP_MODE_SOFTWARE = 0x04 , BRAWCAP_TIMESTAMP_MODE_ADAPTER_SYSTEM = 0x08 , BRAWCAP_TIMESTAMP_MODE_ADAPTER_SOFTWARE = 0x10 , BRAWCAP_TIMESTAMP_MODE_ADAPTER_HARDWARE = 0x20 }
	List of different timestamp modes. More...

Functions
brawcap_status_t	brawcap_timestamp_mode_get (brawcap_timestamp_t const pTimestamp, brawcap_timestamp_mode_t const pMode)
	Reads out the mode of the specified timestamp.

brawcap_status_t	brawcap_timestamp_resolution_ns_get (brawcap_timestamp_t const pTimestamp, brawcap_timestamp_resolution_ns_t const pResolution_ns)
	Reads out the timestamp resolution of the specified timestamp.

brawcap_status_t	brawcap_timestamp_value_ns_get (brawcap_timestamp_t const pTimestamp, UINT64 const pSeconds, UINT32 *const pNanoseconds)
	Reads out the timestamp value in seconds and nanoseconds.

brawcap_status_t	brawcap_timestamp_value_ns_set (brawcap_timestamp_t *const pTimestamp, const UINT64 seconds, const UINT32 nanoseconds)
	Sets the timestamp value in seconds and nanoseconds.

brawcap_status_t	brawcap_timestamp_value_us_get (brawcap_timestamp_t const pTimestamp, UINT64 const pSeconds, UINT32 *const pMicroseconds)
	Reads out the timestamp value in seconds and microseconds.

brawcap_status_t	brawcap_timestamp_value_us_set (brawcap_timestamp_t *const pTimestamp, const UINT64 seconds, const UINT32 microseconds)
	Sets the timestamp value in seconds and microseconds.

brawcap_status_t	brawcap_timestamp_value_ms_get (brawcap_timestamp_t const pTimestamp, UINT64 const pSeconds, UINT32 *const pMilliseconds)
	Reads out the timestamp value in seconds and milliseconds.

brawcap_status_t	brawcap_timestamp_value_ms_set (brawcap_timestamp_t *const pTimestamp, const UINT64 seconds, const UINT32 milliseconds)
	Sets the timestamp value in seconds and milliseconds.

Detailed Description

Types and functions for operating with bRAWcap timestamps.

At the moment it is not possible to create a standalone timestamp object. Instead a timestamp is always part of a packet. To get the timestamp object use brawcap_packet_timestamp_get on a specific packet. This object can be used than for all functions in this module.

Attention: The user application shall never store a timestamp, instead it should always request it from a packet and only use it as long as the packet itself is valid.

List of examples:

Macro Definition Documentation

◆ BRAWCAP_TIMESTAMP_RESOLUTION_UNKNOWN

#define BRAWCAP_TIMESTAMP_RESOLUTION_UNKNOWN 0

#include <brawcap_types_shared.h>

If a timestamp resolution is set to this value, it´s resolution is unknown - could not be resolved.

For example this can be the case for adapter hardware timestamps, if the adapter does not report it´s clock frequency.

Examples: 08_receive_timestamp_inspector.c.

Typedef Documentation

◆ brawcap_timestamp_capabilities_t

typedef UINT32 brawcap_timestamp_capabilities_t

#include <brawcap_types_shared.h>

Type used for indicating the supported timestamp modes.

It has to be interpreted as bitfield.

◆ brawcap_timestamp_resolution_ns_t

typedef UINT32 brawcap_timestamp_resolution_ns_t

#include <brawcap_types_shared.h>

Represents the timestamp resolution in nanoseconds.

The resolution can be used to check how accurate a timestamp is. For example if it is set to 1.000.000 ns the timestamp has a accuracy of "only" one millisecond. If it is set to 1 ns instead, it would indicate a very precise timestamp with a resolution of one nanosecond.

◆ brawcap_timestamp_t

typedef struct _brawcap_timestamp brawcap_timestamp_t

#include <brawcap_types_shared.h>

bRAWcap timestamp object.

The timestamp object is part of each packet and has to be used for each timestamp module function. To get a timestamp object from a packet use brawcap_packet_timestamp_get.

Enumeration Type Documentation

◆ brawcap_timestamp_mode_t

enum brawcap_timestamp_mode_t

#include <brawcap_types_shared.h>

List of different timestamp modes.

The mode of a timestamp can be used to check when the timestamp is generated (time of trigger). It can also indicate how accurate a timestamp is.

Description for the different timestamp types:

System timestamps:
- Less accurate
- Jumps if the system time itself is jumping.
- Source is the system time
Software timestamps:
- Good accuracy
- Guaranteed to not jump.
- Source is almost ever the local TSC (if the CPU supports it). If not Windows will take the next accurate source for it. For more information on QPC, please see the official Microsoft documentation .
- They will always start from zero and increase with system up time.
Hardware timestamps:
- Highest accuracy because they are not influenced by the system.
- Only jumps if the adapter hardware clock jumps.
- Source is the adapter hardware clock.

Note

Adapter timestamps are features provided by the underlying adapter and not part of bRAWcap. bRAWcap only provides those timestamps if the underlying adapter supports it. To check if the underlying adapter supports them use

brawcap_rx_timestamp_capabilities for receive timestamps
brawcap_tx_timestamp_capabilities for transmit timestamps

More accurate system or software timestamps can increase the overall CPU load a bit. These differences can be neglected in most cases, but if the user is not interested in high-precision timestamps, always timestamps that require less effort should be preferred.

Trigger position for timestamps created by bRAWcap driver:

Receive: When the packet is recognized by the bRAWcap driver (forwarded from the underlying driver)
Transmit: When the transmission complete event is recognized by the bRAWcap driver

Enumerator
BRAWCAP_TIMESTAMP_MODE_NO_TIMESTAMP	No timestamp.
BRAWCAP_TIMESTAMP_MODE_SYSTEM_LOWPREC	A low precision system timestamp created by bRAWcap driver.
BRAWCAP_TIMESTAMP_MODE_SYSTEM_HIGHPREC	A high precision system timestamp created by bRAWcap driver.
BRAWCAP_TIMESTAMP_MODE_SOFTWARE	A software timestamp created by bRAWcap driver.
BRAWCAP_TIMESTAMP_MODE_ADAPTER_SYSTEM	A system timestamp created by the network adapter driver.
BRAWCAP_TIMESTAMP_MODE_ADAPTER_SOFTWARE	A software timestamp created by the network adapter driver.
BRAWCAP_TIMESTAMP_MODE_ADAPTER_HARDWARE	A hardware timestamp created by the network adapter hardware/firmware.

Function Documentation

◆ brawcap_timestamp_mode_get()

brawcap_status_t brawcap_timestamp_mode_get	(	brawcap_timestamp_t *const	pTimestamp,
		brawcap_timestamp_mode_t *const	pMode
	)

#include <brawcap.h>

Reads out the mode of the specified timestamp.

Parameters

[in]	pTimestamp	The timestamp to read from.
[out]	pMode	Will contain the timestamp mode, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

Examples: 08_receive_timestamp_inspector.c.

◆ brawcap_timestamp_resolution_ns_get()

brawcap_status_t brawcap_timestamp_resolution_ns_get	(	brawcap_timestamp_t *const	pTimestamp,
		brawcap_timestamp_resolution_ns_t *const	pResolution_ns
	)

#include <brawcap.h>

Reads out the timestamp resolution of the specified timestamp.

Note: If the resolution is unknown it will be set to zero (BRAWCAP_TIMESTAMP_RESOLUTION_UNKNOWN)

Parameters

[in]	pTimestamp	The timestamp to read from.
[out]	pResolution_ns	Will contain the timestamp resolution in nanoseconds, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

Examples: 08_receive_timestamp_inspector.c.

◆ brawcap_timestamp_value_ns_get()

brawcap_status_t brawcap_timestamp_value_ns_get	(	brawcap_timestamp_t *const	pTimestamp,
		UINT64 *const	pSeconds,
		UINT32 *const	pNanoseconds
	)

#include <brawcap.h>

Reads out the timestamp value in seconds and nanoseconds.

The values are based on 00:00 01.01.1970.

The seconds part contains only whole seconds of the timestamp, while the nanoseconds part contains only the fractional part.

Parameters

[in]	pTimestamp	The timestamp to read from.
[out]	pSeconds	Will contain the whole seconds of the timestamp, afterwards.
[out]	pNanoseconds	Will contain the fractional part in nanoseconds, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

Examples: 05_receive_simple_packet_receiver.c, and 08_receive_timestamp_inspector.c.

◆ brawcap_timestamp_value_ns_set()

brawcap_status_t brawcap_timestamp_value_ns_set	(	brawcap_timestamp_t *const	pTimestamp,
		const UINT64	seconds,
		const UINT32	nanoseconds
	)

#include <brawcap.h>

Sets the timestamp value in seconds and nanoseconds.

The values has to be based on 00:00 01.01.1970.

Parameters

[in]	pTimestamp	The timestamp to be modified.
[in]	seconds	Whole seconds since 00:00 01.01.1970.
[in]	nanoseconds	The fractional part in nanoseconds. This parameter should only contain the fractional timestamp part. That means that it can never exceed 999.999.999 nanoseconds.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE	Nanosecond value to high (only fraction of second).

◆ brawcap_timestamp_value_us_get()

brawcap_status_t brawcap_timestamp_value_us_get	(	brawcap_timestamp_t *const	pTimestamp,
		UINT64 *const	pSeconds,
		UINT32 *const	pMicroseconds
	)

#include <brawcap.h>

Reads out the timestamp value in seconds and microseconds.

The values are based on 00:00 01.01.1970.

The seconds part contains only whole seconds of the timestamp, while the microseconds contains only the fractional part.

Parameters

[in]	pTimestamp	The timestamp to read from.
[out]	pSeconds	Will contain the whole seconds of the timestamp, afterwards.
[out]	pMicroseconds	Will contain the fractional part in microseconds, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

Examples: 08_receive_timestamp_inspector.c.

◆ brawcap_timestamp_value_us_set()

brawcap_status_t brawcap_timestamp_value_us_set	(	brawcap_timestamp_t *const	pTimestamp,
		const UINT64	seconds,
		const UINT32	microseconds
	)

#include <brawcap.h>

Sets the timestamp value in seconds and microseconds.

The values has to be based on 00:00 01.01.1970.

Parameters

[in]	pTimestamp	The timestamp to be modified.
[in]	seconds	Whole seconds since 00:00 01.01.1970.
[in]	microseconds	The fractional part in microseconds. This parameter should only contain the fractional timestamp part. That means that it can never exceed 999.999 microseconds.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE	Nanosecond value to high (only fraction of second).

◆ brawcap_timestamp_value_ms_get()

brawcap_status_t brawcap_timestamp_value_ms_get	(	brawcap_timestamp_t *const	pTimestamp,
		UINT64 *const	pSeconds,
		UINT32 *const	pMilliseconds
	)

#include <brawcap.h>

Reads out the timestamp value in seconds and milliseconds.

The values are based on 00:00 01.01.1970.

The seconds part contains only whole seconds of the timestamp, while the milliseconds part contains only the fractional part.

Parameters

[in]	pTimestamp	The timestamp to read from.
[out]	pSeconds	Will contain the whole seconds of the timestamp, afterwards.
[out]	pMilliseconds	Will contain the fractional part in milliseconds, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

Examples: 08_receive_timestamp_inspector.c.

◆ brawcap_timestamp_value_ms_set()

brawcap_status_t brawcap_timestamp_value_ms_set	(	brawcap_timestamp_t *const	pTimestamp,
		const UINT64	seconds,
		const UINT32	milliseconds
	)

#include <brawcap.h>

Sets the timestamp value in seconds and milliseconds.

The values has to be based on 00:00 01.01.1970.

Parameters

[in]	pTimestamp	The timestamp to be modified.
[in]	seconds	Whole seconds since 00:00 01.01.1970.
[in]	milliseconds	The fractional part in milliseconds. This parameter should only contain the fractional timestamp part. That means that it can never exceed 999 milliseconds.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE	Nanosecond value to high (only fraction of second).

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ BRAWCAP_TIMESTAMP_RESOLUTION_UNKNOWN

Typedef Documentation

◆ brawcap_timestamp_capabilities_t

◆ brawcap_timestamp_resolution_ns_t

◆ brawcap_timestamp_t

Enumeration Type Documentation

◆ brawcap_timestamp_mode_t

Function Documentation

◆ brawcap_timestamp_mode_get()

◆ brawcap_timestamp_resolution_ns_get()

◆ brawcap_timestamp_value_ns_get()

◆ brawcap_timestamp_value_ns_set()

◆ brawcap_timestamp_value_us_get()

◆ brawcap_timestamp_value_us_set()

◆ brawcap_timestamp_value_ms_get()

◆ brawcap_timestamp_value_ms_set()