Class UDPFormat

Nested Relationships

Nested Types

Inheritance Relationships

Base Type

Derived Types

Class Documentation

class UDPFormat : public ska::pst::common::PacketLayout

Abstract base class for UDPFormats of the CBF/PSR data format.

Subclassed by ska::pst::recv::LowPST, ska::pst::recv::LowTestVector, ska::pst::recv::MidPST

Public Types

enum PacketState

Enumeration of the different types of received packet state Ok Packet received in good order Malformed Packet header is invalid and does not conform to the ICD definition Misdirected Packet header is valid but belongs to a different beam or sub-band Misordered Packet sequence number is wildly out of order Ignored Packet is valid but precedes the start_psn, so it is simply ignored whilst waiting for the start of the stream.

Values:

enumerator Ok
enumerator Malformed
enumerator Misdirected
enumerator Misordered
enumerator Ignored
typedef struct ska::pst::recv::UDPFormat::data_and_weights data_and_weights_t

Convenience structure for data and weights used for offsets and sizes.

Public Functions

UDPFormat()

Construct a new UDPFormat object.

~UDPFormat()

Destroy the UDPFormat object.

void validate_configure_beam(const ska::pst::common::AsciiHeader &beam_config, ska::pst::common::ValidationContext *context)

validate the configure beam configuration.

This method should be used to validate a configuration for the configure_beam method to ensure that before any resources are allocated that the configuration is valid.

Parameters

  • beam_config – the configuration to validate.

  • context – a validation context that any validation errors will be added to.

virtual void configure_beam(const ska::pst::common::AsciiHeader &beam_config)

Configure the UDPFormat from the fixed configuration.

Parameters

beam_config –

void configure_scan(const ska::pst::common::AsciiHeader &scan_config)

Prepare the UDPFormat once the complete header has been provided. Includes the fixed and dynamic configuration parameters.

Parameters

scan_config – complete set of meta-data for the observation

void deconfigure_beam()

Reset the beam configuration on the format.

Resets the beam_id and clears the weights_beam_config

void deconfigure_scan()

Reset the scan configuration on the format.

Clears the weights_scan_config.

void start_scan(const ska::pst::common::AsciiHeader &startscan_config)

Prepare the UDPFormat for a scan.

The startscan_config is expected to have a SCAN_ID and an optional START_TIME.

Parameters

startscan_config – the start scan configuration.

void stop_scan()

Reset the start scan configuration on the format.

Resets the scan_id and start_psn attribtues.

void reset()

Force reset the internal state to initial values.

uint64_t get_samples_for_bytes(uint64_t nbytes)

Return the number of samples that correspond to the specified number of bytes.

Parameters

nbytes – Number of bytes to use in calculation

Returns

uint64_t Number of samples that match the specified bytes

uint64_t get_resolution()

Return the resolution of the UDPFormat which corresponds to the minimum block size.

Returns

uint64_t data minimum resolution in bytes

uint64_t get_weights_resolution()

Return the minimum resolution of the weights in UDPFormat. Corresponds to the minimum block size for the weights.

Returns

uint64_t weights minimum resolution in bytes

void encode_header(char *buf)

Encode the contents of the.

Parameters

buf –

PacketState process_stream_start(char *buffer, uint32_t psn_offset = 0)

check whether the data stream has started by virtue of the first packet being received

Parameters

  • buffer – pointer to buffer container received UDP packet payload

  • psn_offset – number of packet sequence numbers to offset the start of acquisition from the first packet received

Returns

PacketState return value indicating status: OK, IGNORE or MALFORMED

inline ska::pst::common::Time get_start_timestamp()

Get the start timestamp for the packet stream.

Returns

ska::pst::common::Time timestamp of the start of the packet stream

void clear_monitor_psn(uint32_t psn_offset)

Reset the monitor_psn to a default value (max uint64), such that the psn of the next inspected packet will used to set the monitor_psn.

Parameters

psn_offset – offset to apply the monitor psn

PacketState inspect_packet(char *buffer, uint64_t *relative_psn)

Inspect the received UDP packet and determine its PSN relative to the PSN of the first packet that is not ignored.

Parameters

  • buffer – pointer to buffer containing received UDP packet payload

  • relative_psn – packet sequence number of the inspected packet

Returns

PacketState status of the received packet (e.g. OK, IGNORE, MALFORMED)

virtual PacketState decode_packet(char *buffer, data_and_weights_t *offsets, data_and_weights_t *received)

Decode the received UDP packet and determine its location within the data stream.

Parameters

  • buffer – pointer to buffer containing received UDP packet payload

  • offsets – offsets of the data and weights in their respective data streams

  • received – size of the data and weights portions of the payload

Returns

PacketState status of the received packet (e.g. OK, IGNORE, MALFORMED)

virtual void insert_last_packet(char *data, char *weights)

copy the most recently received packet data and weights to the provided buffers

Parameters

  • data – pointer to buffer to which packet data will be copied

  • weights – pointer to buffer to which packet scales and weights will be copied

void clear_scales_buffer(char *buffer, uint64_t bufsz)

Reset all of the scales values in the weights buffer to NAN.

Parameters

  • buffer – pointer to the weights buffer

  • bufsz – size of the weights buffer in bytes

void print_packet_header()

Print a brief description of the UDP packet header.

inline unsigned get_os_numerator() const

Get the oversampling numerator of the UDP format.

Returns

unsigned numerator of the oversampling ratio

inline unsigned get_os_denominator() const

Get the os denominator of the UDP format.

Returns

unsigned denominator of the oversampling ratio

inline uint16_t get_sample_period_numerator() const

Get the numerator of the sample period ratio, in microseconds.

Returns

uint16_t numerator of the sample period

inline uint16_t get_sample_period_denominator() const

Get the denominator of the sample period ratio, in microseconds.

Returns

uint16_t denominator of the sample period

inline double get_expected_tsamp() const

Get the expected sample period (TSAMP), in microseconds.

This is calculated from the fraction of sample_period_numerator / sample_period_denominator.

Returns

the expected sample period (TSAMP), in microseconds.

inline unsigned get_destination() const

Get the CBF/PSR destination for the UDP format.

Returns

unsigned value of the CBF/PSR destination field

inline bool get_increment_psn_every_packet() const

Get the increment psn every packet value.

Returns

true UDP format expects PSN to increment every packet

Returns

false UDP format does not expect PSN to increment every packet

const ska::pst::common::AsciiHeader &get_weights_scan_config()

return the scan configuration for the weights

inline bool is_misdirected()

Return true if the packet is valid, but not meant to be received by this format.

Reasons for being misdirected are:

  • The Beam Number in the CBF/PSR packet does not match the BEAM_ID in the beam configuration

  • The Scan ID in the CBF/PSR packet is greater than zero and does not match the SCAN_ID in the start scan configuration

  • The channel numbers in the CBF/PSR packet are not within the START_CHANNEL and END_CHANNEL in the scan configuration

Returns

true packet is misdirected

Returns

false packet is not misdirected

inline bool is_ignored()

Return true if the packet is valid, but should be ignored by this format.

Reasons for being ignored are:

  • The Sequence Number in the CBF/PSR packet is less than the start_psn. The start_psn is not set until either Scan ID in the CBF/PSR is non-zero or that the packet’s samples since SKA epoch is greater or equal that of the an equivalent time of the start_timestamp.

  • The samples since SKA epoch is less than the start_samples_since_ska_epoch, this is relevant if the start_timestamp from the START_TIME of a scan.

  • The Scan ID in the CBF/PSR packet is zero, indicating it should be ignored. This check only happens if neither of the above two conditions are met.

Returns

true packet is ignored

Returns

false packet is not ignored

inline void set_validity_flags_policy(PacketValidityFlagsPolicy policy)

Set the new validity flags policy for the UDPFormat.

Parameters

policy – new validity flags policy to use when interpreting packet validity flags

inline PacketValidityFlagsPolicy get_validity_flags_policy() const

Get the validity flags policy for the UDPFormat.

Returns

PacketValidityFlagsPolicy current validity flags policy that is used when interpreting packet validity flags

virtual void update_statistics(UDPStats &stats) = 0

Update UDP Stats based on current packet information.

Parameters

stats – the UDP stats to be updated.

virtual unsigned get_expected_nbit() = 0

Get the expected NBIT value for UDPFormat.

Returns

the expected NBIT value for the format.

inline int64_t get_start_samples_since_ska_epoch() const

Get the starting samples since SKA epoch, will return -1 if the start_timestamp was not.

Public Members

uint64_t monitor_psn = std::numeric_limits<uint64_t>::max()

Packet sequence number on which monitoring starts.

uint32_t monitor_psn_offset = {0}

Offset to apply to the monitor psn.

Protected Functions

void reset_scan_state()

resets the internal scan state.

This is used at the beginning of start_scan, stop_scan and reset methods to ensure the internal scan state is in a known state.

This resets the scan_id, start_psn, and the start_timestamp

void set_start_timestamp(ska::pst::common::Time start_timestamp)

Set the start timestamp.

Setting the start timestamp via this method will ensure that the process_stream_start will ignore all packets until a packet’s samples_since_ska_epoch is equal to or greater than the appropriate timestamp. This method will ensure that the start_timestamp is adjusted to the nearest sample

The UDP format may start slightly after this given timestamp if the process_stream_start method is given a non-zero psn_offset.

See also

Time.adjust_to_nearest_sample.

Parameters

start_timestamp – the timestamp instructed to start at.

virtual std::pair<unsigned, unsigned> get_expected_os_factor() = 0

Get the expected OS_FACTOR for the UDPFormat.

Returns

a pair of unsigned values. The first is the numerator and the second is the denominator.

inline void check_beam_configured(bool expected)

Check that the beam_configured attribute matches the expected value.

Throws

std::runtime_error – if the beam_configured attribute does not match the expected value

Parameters

expected – expected value of the beam_configured attribute

inline void check_scan_configured(bool expected)

Check that the scan_configured attribute matches the expected value.

Throws

std::runtime_error – if the scan_configured attribute does not match the expected value

Parameters

expected – expected value of the scan_configured attribute

void check_scan_started(bool expected)

Check that the scan_started attribute matches the expected value.

Throws

std::runtime_error – if the scan_started attribute does not match the expected value

Parameters

expected – expected value of the scan_started attribute

Protected Attributes

cbf_psr_packet_t packet = {nullptr, nullptr, nullptr}

struct of pointers to the header, weights and data of the current UDP packet.

unsigned beam_id = {0}

the beam number or beam identifier

uint64_t scan_id = {0}

the scan identifier

unsigned nant = {0}

number of antennae

unsigned nbeam = {0}

number of beams

unsigned ndim = {0}

number of dimensions

unsigned npol = {0}

number of polarisations

unsigned nbit = {0}

number of bits per dimension

unsigned os_numerator = {0}

oversampling numerator

unsigned os_denominator = {0}

oversampling denominator

uint16_t sample_period_numerator = {0}

sample period (TSAMP) numerator

uint16_t sample_period_denominator = {0}

sample period (TSAMP) denominator

unsigned start_channel = {0}

first channel

unsigned end_channel = {0}

last channel

unsigned nchan = {0}

number of channels

double tsamp = {0}

the sampling interval in microseconds

unsigned tsamp_numerator = {0}

numerator of the sampling interval in microseconds

unsigned tsamp_denominator = {0}

denominator of the sampling interval

double bw = {0}

the bandwidth in MHz

double freq = {0}

the centre frequency in MHz

bool beam_configured = {false}

flag for format configuration, fixed time parameters received

bool scan_configured = {false}

flag for format preparation, fixed and runtime parameters received

bool scan_started = {false}

flag for the starting of the scan, specifically once a packet has been received and the start_psn attribute is set

unsigned data_channel_stride = {0}

Number of bytes per channel in UDPFormat data.

unsigned data_psn_stride = {0}

Number of bytes that span the data time samples associated with all packets of the sample Packet Sequence Number (PSN)

unsigned weights_channel_stride = {0}

Number of bytes per channel in UDPFormat weights.

unsigned weights_psn_stride = {0}

Number of bytes that span the weights time samples associated with all packets of the sample Packet Sequence Number (PSN)

uint32_t destination = {5}

Number indicating the destination product for the packet (Low.PST, Mid.PSt, Low.PSS, Mid.PSS)

int64_t start_psn = {-1}

The Packet Sequence Number (PSN) that is associated with the start of data.

int64_t start_samples_since_ska_epoch = {-1}

The starting samples since SKAO Epoch.

ska::pst::common::Time start_timestamp = {}

The timestamp that corresponds to the start_psn.

ska::pst::common::AsciiHeader weights_beam_config

beam configuration for the weights stream of this format

ska::pst::common::AsciiHeader weights_scan_config

scan configuration for the weights stream of this format

uint64_t attoseconds_per_packet = {0}

number of attoseconds per packet

bool increment_psn_every_packet = {false}

increment the PSN on every single packet, only true in LowTestVector

struct data_and_weights

Convenience structure for data and weights used for offsets and sizes.

Public Members

int64_t data

the value for the data component of the data_and_weights structure

int64_t weights

the value for the weights component of the data_and_weights structure