metadata.h File Reference

#include <uhd/config.h>
#include <uhd/error.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include <time.h>

Go to the source code of this file.

Typedefs
typedef struct uhd_rx_metadata_t *	uhd_rx_metadata_handle
	RX metadata interface for describing sent IF data. More...
typedef struct uhd_tx_metadata_t *	uhd_tx_metadata_handle
	TX metadata interface for describing received IF data. More...
typedef struct uhd_async_metadata_t *	uhd_async_metadata_handle
	Interface for describing transmit-related events. More...

Enumerations
enum	uhd_rx_metadata_error_code_t {   UHD_RX_METADATA_ERROR_CODE_NONE = 0x0, UHD_RX_METADATA_ERROR_CODE_TIMEOUT = 0x1, UHD_RX_METADATA_ERROR_CODE_LATE_COMMAND = 0x2, UHD_RX_METADATA_ERROR_CODE_BROKEN_CHAIN = 0x4,   UHD_RX_METADATA_ERROR_CODE_OVERFLOW = 0x8, UHD_RX_METADATA_ERROR_CODE_ALIGNMENT = 0xC, UHD_RX_METADATA_ERROR_CODE_BAD_PACKET = 0xF }
	Error condition on a receive call. More...
enum	uhd_async_metadata_event_code_t {   UHD_ASYNC_METADATA_EVENT_CODE_BURST_ACK = 0x1, UHD_ASYNC_METADATA_EVENT_CODE_UNDERFLOW = 0x2, UHD_ASYNC_METADATA_EVENT_CODE_SEQ_ERROR = 0x4, UHD_ASYNC_METADATA_EVENT_CODE_TIME_ERROR = 0x8,   UHD_ASYNC_METADATA_EVENT_CODE_UNDERFLOW_IN_PACKET = 0x10, UHD_ASYNC_METADATA_EVENT_CODE_SEQ_ERROR_IN_BURST = 0x20, UHD_ASYNC_METADATA_EVENT_CODE_USER_PAYLOAD = 0x40 }
	The type of event for a receive async message call. More...

Functions
UHD_API uhd_error	uhd_rx_metadata_make (uhd_rx_metadata_handle *handle)
	Create a new RX metadata handle. More...
UHD_API uhd_error	uhd_rx_metadata_free (uhd_rx_metadata_handle *handle)
	Free an RX metadata handle. More...
UHD_API uhd_error	uhd_rx_metadata_has_time_spec (uhd_rx_metadata_handle h, bool *result_out)
	Has time specification? More...
UHD_API uhd_error	uhd_rx_metadata_time_spec (uhd_rx_metadata_handle h, time_t *full_secs_out, double *frac_secs_out)
	Time of first sample. More...
UHD_API uhd_error	uhd_rx_metadata_more_fragments (uhd_rx_metadata_handle h, bool *result_out)
	Fragmentation flag. More...
UHD_API uhd_error	uhd_rx_metadata_fragment_offset (uhd_rx_metadata_handle h, size_t *fragment_offset_out)
	Fragmentation offset. More...
UHD_API uhd_error	uhd_rx_metadata_start_of_burst (uhd_rx_metadata_handle h, bool *result_out)
	Start of burst? More...
UHD_API uhd_error	uhd_rx_metadata_end_of_burst (uhd_rx_metadata_handle h, bool *result_out)
	End of burst? More...
UHD_API uhd_error	uhd_rx_metadata_out_of_sequence (uhd_rx_metadata_handle h, bool *result_out)
	Result out of sequence? More...
UHD_API uhd_error	uhd_rx_metadata_to_pp_string (uhd_rx_metadata_handle h, char *pp_string_out, size_t strbuffer_len)
	Return a pretty-print representation of this metadata. More...
UHD_API uhd_error	uhd_rx_metadata_error_code (uhd_rx_metadata_handle h, uhd_rx_metadata_error_code_t *error_code_out)
	Get the last error state of the RX metadata object. More...
UHD_API uhd_error	uhd_rx_metadata_strerror (uhd_rx_metadata_handle h, char *strerror_out, size_t strbuffer_len)
	Get a string representation of the last error state of the RX metadata object. More...
UHD_API uhd_error	uhd_rx_metadata_last_error (uhd_rx_metadata_handle h, char *error_out, size_t strbuffer_len)
	Get the last error logged by the RX metadata object. More...
UHD_API uhd_error	uhd_tx_metadata_make (uhd_tx_metadata_handle *handle, bool has_time_spec, time_t full_secs, double frac_secs, bool start_of_burst, bool end_of_burst)
	Create a new TX metadata handle. More...
UHD_API uhd_error	uhd_tx_metadata_free (uhd_tx_metadata_handle *handle)
	Free an TX metadata handle. More...
UHD_API uhd_error	uhd_tx_metadata_has_time_spec (uhd_tx_metadata_handle h, bool *result_out)
	Has time specification? More...
UHD_API uhd_error	uhd_tx_metadata_time_spec (uhd_tx_metadata_handle h, time_t *full_secs_out, double *frac_secs_out)
	Get time specification. More...
UHD_API uhd_error	uhd_tx_metadata_start_of_burst (uhd_tx_metadata_handle h, bool *result_out)
	Start of burst? More...
UHD_API uhd_error	uhd_tx_metadata_end_of_burst (uhd_tx_metadata_handle h, bool *result_out)
	End of burst? More...
UHD_API uhd_error	uhd_tx_metadata_last_error (uhd_tx_metadata_handle h, char *error_out, size_t strbuffer_len)
	Get the last error logged by the TX metadata object. More...
UHD_API uhd_error	uhd_async_metadata_make (uhd_async_metadata_handle *handle)
	Create a new async metadata handle. More...
UHD_API uhd_error	uhd_async_metadata_free (uhd_async_metadata_handle *handle)
	Free an async metadata handle. More...
UHD_API uhd_error	uhd_async_metadata_channel (uhd_async_metadata_handle h, size_t *channel_out)
	Channel number in a MIMO configuration. More...
UHD_API uhd_error	uhd_async_metadata_has_time_spec (uhd_async_metadata_handle h, bool *result_out)
	Has time specification? More...
UHD_API uhd_error	uhd_async_metadata_time_spec (uhd_async_metadata_handle h, time_t *full_secs_out, double *frac_secs_out)
	Get time specification. More...
UHD_API uhd_error	uhd_async_metadata_event_code (uhd_async_metadata_handle h, uhd_async_metadata_event_code_t *event_code_out)
	Get last event code. More...
UHD_API uhd_error	uhd_async_metadata_user_payload (uhd_async_metadata_handle h, uint32_t user_payload_out[4])
	Get payload from custom FPGA fabric. More...
UHD_API uhd_error	uhd_async_metadata_last_error (uhd_async_metadata_handle h, char *error_out, size_t strbuffer_len)
	Get the last error logged by the async metadata object. More...

Typedef Documentation

uhd_async_metadata_handle

typedef struct uhd_async_metadata_t* uhd_async_metadata_handle

Interface for describing transmit-related events.

See uhd::async_metadata_t for details.

NOTE: Using this handle before calling uhd_async_metadata_make() will result in undefined behavior.

uhd_rx_metadata_handle

typedef struct uhd_rx_metadata_t* uhd_rx_metadata_handle

RX metadata interface for describing sent IF data.

See uhd::rx_metadata_t for details.

NOTE: Using this handle before calling uhd_rx_metadata_make() will result in undefined behavior.

uhd_tx_metadata_handle

typedef struct uhd_tx_metadata_t* uhd_tx_metadata_handle

TX metadata interface for describing received IF data.

See uhd::tx_metadata_t for details.

NOTE: Using this handle before calling uhd_tx_metadata_make() will result in undefined behavior.

Enumeration Type Documentation

uhd_async_metadata_event_code_t

enum uhd_async_metadata_event_code_t

The type of event for a receive async message call.

See uhd::async_metadata_t::event_code_t for more details.

Enumerator
UHD_ASYNC_METADATA_EVENT_CODE_BURST_ACK	A burst was successfully transmitted.
UHD_ASYNC_METADATA_EVENT_CODE_UNDERFLOW	An internal send buffer has emptied.
UHD_ASYNC_METADATA_EVENT_CODE_SEQ_ERROR	Packet loss error between host and device.
UHD_ASYNC_METADATA_EVENT_CODE_TIME_ERROR	Packet had time that was late.
UHD_ASYNC_METADATA_EVENT_CODE_UNDERFLOW_IN_PACKET	Underflow occurred inside a packet.
UHD_ASYNC_METADATA_EVENT_CODE_SEQ_ERROR_IN_BURST	Packet loss within a burst.
UHD_ASYNC_METADATA_EVENT_CODE_USER_PAYLOAD	Some kind of custom user payload.

uhd_rx_metadata_error_code_t

enum uhd_rx_metadata_error_code_t

Error condition on a receive call.

See uhd::rx_metadata_t::error_code_t for more details.

Enumerator
UHD_RX_METADATA_ERROR_CODE_NONE	No error code associated with this metadata.
UHD_RX_METADATA_ERROR_CODE_TIMEOUT	No packet received, implementation timed out.
UHD_RX_METADATA_ERROR_CODE_LATE_COMMAND	A stream command was issued in the past.
UHD_RX_METADATA_ERROR_CODE_BROKEN_CHAIN	Expected another stream command.
UHD_RX_METADATA_ERROR_CODE_OVERFLOW	Overflow or sequence error.
UHD_RX_METADATA_ERROR_CODE_ALIGNMENT	Multi-channel alignment failed.
UHD_RX_METADATA_ERROR_CODE_BAD_PACKET	The packet could not be parsed.

Function Documentation

uhd_async_metadata_channel()

UHD_API uhd_error uhd_async_metadata_channel	(	uhd_async_metadata_handle	h,
		size_t *	channel_out
	)

Channel number in a MIMO configuration.

uhd_async_metadata_event_code()

UHD_API uhd_error uhd_async_metadata_event_code	(	uhd_async_metadata_handle	h,
		uhd_async_metadata_event_code_t *	event_code_out
	)

Get last event code.

uhd_async_metadata_free()

UHD_API uhd_error uhd_async_metadata_free

(

uhd_async_metadata_handle *

handle

)

Free an async metadata handle.

Using a handle after freeing it will result in a segmentation fault.

uhd_async_metadata_has_time_spec()

UHD_API uhd_error uhd_async_metadata_has_time_spec	(	uhd_async_metadata_handle	h,
		bool *	result_out
	)

Has time specification?

uhd_async_metadata_last_error()

UHD_API uhd_error uhd_async_metadata_last_error	(	uhd_async_metadata_handle	h,
		char *	error_out,
		size_t	strbuffer_len
	)

Get the last error logged by the async metadata object.

NOTE: This function will overwrite any string in the given buffer before inserting the error string.

Parameters

h	metadata handle
error_out	string buffer for error
buffer	length

uhd_async_metadata_make()

UHD_API uhd_error uhd_async_metadata_make

(

uhd_async_metadata_handle *

handle

)

Create a new async metadata handle.

uhd_async_metadata_time_spec()

UHD_API uhd_error uhd_async_metadata_time_spec	(	uhd_async_metadata_handle	h,
		time_t *	full_secs_out,
		double *	frac_secs_out
	)

Get time specification.

uhd_async_metadata_user_payload()

UHD_API uhd_error uhd_async_metadata_user_payload	(	uhd_async_metadata_handle	h,
		uint32_t	user_payload_out[4]
	)

Get payload from custom FPGA fabric.

uhd_rx_metadata_end_of_burst()

UHD_API uhd_error uhd_rx_metadata_end_of_burst	(	uhd_rx_metadata_handle	h,
		bool *	result_out
	)

End of burst?

uhd_rx_metadata_error_code()

UHD_API uhd_error uhd_rx_metadata_error_code	(	uhd_rx_metadata_handle	h,
		uhd_rx_metadata_error_code_t *	error_code_out
	)

Get the last error state of the RX metadata object.

uhd_rx_metadata_fragment_offset()

UHD_API uhd_error uhd_rx_metadata_fragment_offset	(	uhd_rx_metadata_handle	h,
		size_t *	fragment_offset_out
	)

Fragmentation offset.

uhd_rx_metadata_free()

UHD_API uhd_error uhd_rx_metadata_free

(

uhd_rx_metadata_handle *

handle

)

Free an RX metadata handle.

Using a handle after freeing it here will result in a segmentation fault.

uhd_rx_metadata_has_time_spec()

UHD_API uhd_error uhd_rx_metadata_has_time_spec	(	uhd_rx_metadata_handle	h,
		bool *	result_out
	)

Has time specification?

uhd_rx_metadata_last_error()

UHD_API uhd_error uhd_rx_metadata_last_error	(	uhd_rx_metadata_handle	h,
		char *	error_out,
		size_t	strbuffer_len
	)

Get the last error logged by the RX metadata object.

NOTES:

• This is different from the error that can be retrieved with uhd_rx_metadata_strerror(). See <uhd/error.h> for details.
• This function will overwrite any string in the given buffer before inserting the error string.

Parameters

h	metadata handle
error_out	string buffer for error
buffer	length

uhd_rx_metadata_make()

UHD_API uhd_error uhd_rx_metadata_make

(

uhd_rx_metadata_handle *

handle

)

Create a new RX metadata handle.

uhd_rx_metadata_more_fragments()

UHD_API uhd_error uhd_rx_metadata_more_fragments	(	uhd_rx_metadata_handle	h,
		bool *	result_out
	)

Fragmentation flag.

uhd_rx_metadata_out_of_sequence()

UHD_API uhd_error uhd_rx_metadata_out_of_sequence	(	uhd_rx_metadata_handle	h,
		bool *	result_out
	)

Result out of sequence?

uhd_rx_metadata_start_of_burst()

UHD_API uhd_error uhd_rx_metadata_start_of_burst	(	uhd_rx_metadata_handle	h,
		bool *	result_out
	)

Start of burst?

uhd_rx_metadata_strerror()

UHD_API uhd_error uhd_rx_metadata_strerror	(	uhd_rx_metadata_handle	h,
		char *	strerror_out,
		size_t	strbuffer_len
	)

Get a string representation of the last error state of the RX metadata object.

NOTES:

• This is different from the error that can be retrieved with uhd_rx_metadata_last_error. See uhd::rx_metadata_t::strerror() for details.
• This function will overwrite any string in the given buffer before inserting the error string.

Parameters

h	metadata handle
strerror_out	string buffer for strerror
buffer	length

uhd_rx_metadata_time_spec()

UHD_API uhd_error uhd_rx_metadata_time_spec	(	uhd_rx_metadata_handle	h,
		time_t *	full_secs_out,
		double *	frac_secs_out
	)

Time of first sample.

uhd_rx_metadata_to_pp_string()

UHD_API uhd_error uhd_rx_metadata_to_pp_string	(	uhd_rx_metadata_handle	h,
		char *	pp_string_out,
		size_t	strbuffer_len
	)

Return a pretty-print representation of this metadata.

NOTE: This function will overwrite any string in the given buffer before inserting the pp_string.

Parameters

h	metadata handle
pp_string_out	string buffer for pp_string
buffer	length

uhd_tx_metadata_end_of_burst()

UHD_API uhd_error uhd_tx_metadata_end_of_burst	(	uhd_tx_metadata_handle	h,
		bool *	result_out
	)

End of burst?

uhd_tx_metadata_free()

UHD_API uhd_error uhd_tx_metadata_free

(

uhd_tx_metadata_handle *

handle

)

Free an TX metadata handle.

Using a handle after freeing it here will result in a segmentation fault.

uhd_tx_metadata_has_time_spec()

UHD_API uhd_error uhd_tx_metadata_has_time_spec	(	uhd_tx_metadata_handle	h,
		bool *	result_out
	)

Has time specification?

uhd_tx_metadata_last_error()

UHD_API uhd_error uhd_tx_metadata_last_error	(	uhd_tx_metadata_handle	h,
		char *	error_out,
		size_t	strbuffer_len
	)

Get the last error logged by the TX metadata object.

NOTE: This function will overwrite any string in the given buffer before inserting the error string.

Parameters

h	metadata handle
error_out	string buffer for error
buffer	length

uhd_tx_metadata_make()

UHD_API uhd_error uhd_tx_metadata_make	(	uhd_tx_metadata_handle *	handle,
		bool	has_time_spec,
		time_t	full_secs,
		double	frac_secs,
		bool	start_of_burst,
		bool	end_of_burst
	)

Create a new TX metadata handle.

uhd_tx_metadata_start_of_burst()

UHD_API uhd_error uhd_tx_metadata_start_of_burst	(	uhd_tx_metadata_handle	h,
		bool *	result_out
	)

Start of burst?

uhd_tx_metadata_time_spec()

UHD_API uhd_error uhd_tx_metadata_time_spec	(	uhd_tx_metadata_handle	h,
		time_t *	full_secs_out,
		double *	frac_secs_out
	)

Get time specification.