Network Data Notation (NDN)

Overview

Declarations of API for TAPI NDN. More…

// typedefs

typedef struct send_transform send_transform;
typedef struct receive_transform receive_transform;
typedef enum tapi_ndn_level_e tapi_ndn_level_t;

// enums

enum tapi_ndn_level_e;

// structs

struct receive_transform;
struct send_transform;
struct tapi_ndn_gso_conf;

// global functions

te_errno tapi_tad_init_asn_value(asn_value** value, const asn_type* type);
te_errno tapi_tad_csap_add_layer(asn_value** csap_spec, const asn_type* layer_type, const char* layer_choice, asn_value** layer_spec);
te_errno tapi_tad_tmpl_ptrn_add_layer(asn_value** obj_spec, bool is_pattern, const asn_type* pdu_type, const char* pdu_choice, asn_value** pdu_spec);
te_errno tapi_tad_new_ptrn_unit(asn_value** obj_spec, asn_value** unit_spec);
te_errno tapi_tad_tmpl_ptrn_set_payload_plain(asn_value** obj_spec, bool is_pattern, const void* payload, size_t length);
te_errno tapi_pdus_free_fields_by_du_tag(asn_value* pdus, asn_tag_value du_tag);
te_errno tapi_tad_pdus_relist_outer_inner(asn_value* pdu_seq, unsigned int* nb_pdus_o_out, asn_value*** pdus_o_out, unsigned int* nb_pdus_i_out, asn_value*** pdus_i_out);
te_errno tapi_tad_tmpl_relist_outer_inner_pdus(asn_value* tmpl, unsigned int* nb_pdus_o_out, asn_value*** pdus_o_out, unsigned int* nb_pdus_i_out, asn_value*** pdus_i_out);
asn_value* tapi_tad_mk_pattern_from_template(asn_value* template);
te_errno tapi_tad_packets_to_pattern(asn_value** packets, unsigned int n_packets, send_transform* transform, asn_value** pattern_out);
te_errno tapi_tad_concat_patterns(asn_value* dst, asn_value* src);
te_errno tapi_tad_aggregate_patterns(asn_value** patterns, unsigned int nb_patterns, asn_value** pattern_out);
te_errno tapi_ndn_subst_env(asn_value* value, te_kvpair_h* params, struct tapi_env* env);
te_errno tapi_ndn_tmpl_classify(const asn_value* tmpl, te_tad_protocols_t hdrs[TAPI_NDN_NLEVELS]);
te_errno tapi_ndn_tmpl_set_ip_cksum(asn_value* tmpl, uint16_t cksum, tapi_ndn_level_t level);
te_errno tapi_ndn_tmpl_set_udp_cksum(asn_value* tmpl, uint16_t cksum, tapi_ndn_level_t level);
te_errno tapi_ndn_tmpl_set_tcp_cksum(asn_value* tmpl, uint16_t cksum);
te_errno tapi_ndn_tmpl_set_tcp_flags(asn_value* tmpl, uint8_t flags);
te_errno tapi_ndn_tmpl_set_payload_len(asn_value* tmpl, unsigned int payload_len);
te_errno tapi_ndn_pkt_inject_vlan_tag(asn_value* pkt, uint16_t vlan_tci);
te_errno tapi_ndn_pdus_inject_vlan_tags(asn_value* pdus, const uint16_t* vid, const uint16_t* prio, const uint16_t* cfi, size_t n_tags);
te_errno tapi_ndn_pdus_remove_vlan_tags(asn_value* pdus, size_t n_tags);
te_errno tapi_ndn_eth_read_vlan_tci(const asn_value* eth, size_t* n_tags, uint16_t* vid, uint16_t* prio, uint16_t* cfi);
te_errno tapi_ndn_pkt_demand_correct_ip_cksum(asn_value* pkt, tapi_ndn_level_t level);
te_errno tapi_ndn_pkt_demand_correct_udp_cksum(asn_value* pkt, bool can_be_zero, tapi_ndn_level_t level);
te_errno tapi_ndn_pkt_demand_correct_tcp_cksum(asn_value* pkt);
te_errno tapi_ndn_superframe_gso(asn_value* superframe, size_t seg_payload_len, const struct tapi_ndn_gso_conf* gso_conf, asn_value*** pkts_out, unsigned int* nb_pkts_out);
te_errno tapi_ndn_tso_pkts_edit(asn_value** pkts, unsigned int nb_pkts);
te_errno tapi_ndn_gso_pkts_ip_len_edit(asn_value** pkts, unsigned int nb_pkts, te_tad_protocols_t ip_te_proto, tapi_ndn_level_t level);
te_errno tapi_ndn_gso_pkts_ip_id_edit(asn_value** pkts, unsigned int nb_pkts, tapi_ndn_level_t level);
te_errno tapi_ndn_gso_pkts_udp_len_edit(asn_value** pkts, unsigned int nb_pkts, tapi_ndn_level_t level);
te_errno tapi_ndn_pkts_to_ptrn(asn_value** pkts, unsigned int nb_pkts, asn_value** ptrn_out);
te_errno tapi_eth_transform_ptrn_on_rx(receive_transform* rx_transform, asn_value** ptrn);

// macros

#define RX_XFRM_EFFECT_OUTER_VLAN_TCI
#define RX_XFRM_EFFECT_VLAN_TCI
#define RX_XFRM_HW_OFFL_QINQ_STRIP
#define RX_XFRM_HW_OFFL_VLAN_STRIP
#define SEND_COND_HW_OFFL_IP_CKSUM
#define SEND_COND_HW_OFFL_L4_CKSUM
#define SEND_COND_HW_OFFL_OUTER_IP_CKSUM
#define SEND_COND_HW_OFFL_TSO
#define SEND_COND_HW_OFFL_VLAN
#define TEST_GET_NDN_TRAFFIC_TEMPLATE(_var_name)

Detailed Documentation

Declarations of API for TAPI NDN.

Global Functions

te_errno tapi_tad_init_asn_value(asn_value** value, const asn_type* type)

Check ASN.1 value pointer. If it is NULL, initialize a new value of specified type. All errors are logged inside the function. There is no necessity to log them after call.

Todo Check that ASN.1 value belongs to type

Parameters:

value	Location of ASN.1 value pointer
type	ASN.1 type to which value should belong

Returns:

Status code.

te_errno tapi_tad_csap_add_layer(asn_value** csap_spec, const asn_type* layer_type, const char* layer_choice, asn_value** layer_spec)

Add a new CSAP specification layer.

Parameters:

csap_spec	Location of ASN.1 value with CSAP specification (if NULL pointer is stored in location, a new CSAP specification is initialized)
layer_type	ASN.1 type of a new layer
layer_choice	String name of a new layer as ASN.1 choice (including ‘#’, e.g. “#eth”)
layer_spec	Location for a new ASN.1 value with layer specification (may be NULL)

Returns:

Status code.

te_errno tapi_tad_tmpl_ptrn_add_layer(asn_value** obj_spec, bool is_pattern, const asn_type* pdu_type, const char* pdu_choice, asn_value** pdu_spec)

Add a new layer specification in traffic template/pattern.

Parameters:

obj_spec	Location of ASN.1 value with Template of pattern spec (if NULL pointer is stored in location, a new CSAP specification is initialized)
is_pattern	Flag wheather required NDN is traffic pattern
pdu_type	ASN.1 type of a new PDU
pdu_choice	String name of a new PDU as ASN.1 choice (including ‘#’, e.g. “#eth”)
pdu_spec	Location for a new ASN.1 value with PDU specification (may be NULL)

Returns:

Status code.

te_errno tapi_tad_new_ptrn_unit(asn_value** obj_spec, asn_value** unit_spec)

Add a new unit in the traffic pattern specification.

Parameters:

obj_spec	Location of ASN.1 value with Template of pattern spec (if NULL pointer is stored in location, a new CSAP specification is initialized)
unit_spec	Location for a pointer to a new pattern unit or NULL

Returns:

Status code.

te_errno tapi_tad_tmpl_ptrn_set_payload_plain(asn_value** obj_spec, bool is_pattern, const void* payload, size_t length)

Set payload of the last unit in the traffic template or pattern specification.

If payload is NULL and length is not 0, random payload contents is generated on sending and any payload of specified length is matched.

Parameters:

obj_spec	Location of ASN.1 value with Template of Pattern specification (if NULL pointer is stored in location, a new one is initialized)
is_pattern	Flag whether required NDN is traffic pattern or template
payload	Pointer to payload data
length	Payload length

Returns:

Status code.

te_errno tapi_pdus_free_fields_by_du_tag(asn_value* pdus, asn_tag_value du_tag)

Free all the PDU fields of a choice denoted by a given DU tag (eg. NDN_DU_SCRIPT) from all the PDUs in a given PDU sequence

Parameters:

pdus	ASN.1 value contining a PDU sequence
du_tag	DU tag value to designate a DU choice

Returns:

Status code

te_errno tapi_tad_pdus_relist_outer_inner(asn_value* pdu_seq, unsigned int* nb_pdus_o_out, asn_value*** pdus_o_out, unsigned int* nb_pdus_i_out, asn_value*** pdus_i_out)

Find outer and inner PDUs in a given PDU sequence ASN.1 value and provide them back to the caller in the form of two arrays. This function does not copy the PDU ASN.1 values it discovers.

Parameters:

pdu_seq	PDU sequence ASN.1 value to process
nb_pdus_o_out	Location for the number of outer PDU ASN.1 values
pdus_o_out	Location for outer PDU ASN.1 values
nb_pdus_i_out	Location for the number of inner PDU ASN.1 values
pdus_i_out	Location for inner PDU ASN.1 values

Returns:

Status code

te_errno tapi_tad_tmpl_relist_outer_inner_pdus(asn_value* tmpl, unsigned int* nb_pdus_o_out, asn_value*** pdus_o_out, unsigned int* nb_pdus_i_out, asn_value*** pdus_i_out)

Convenient tapi_tad_pdus_relist_outer_inner() wrapper which assumes template ASN.1 value as its first argument.

Parameters:

tmpl	Traffic template
nb_pdus_o_out	Location for the number of outer PDU ASN.1 values
pdus_o_out	Location for outer PDU ASN.1 values
nb_pdus_i_out	Location for the number of inner PDU ASN.1 values
pdus_i_out	Location for inner PDU ASN.1 values

asn_value* tapi_tad_mk_pattern_from_template(asn_value* template)

Convert an ASN.1 template to a pattern containing the same set of PDUs as ones in the template

Parameters:

template

ASN.1 template to be converted into a pattern

Returns:

ASN.1 value containing a pattern or NULL

te_errno tapi_tad_packets_to_pattern(asn_value** packets, unsigned int n_packets, send_transform* transform, asn_value** pattern_out)

Convert an array of ASN.1 ‘ndn_raw_packet’-s to a unified ASN.1 ‘ndn_traffic_pattern’ carrying an exact sequence of ‘ndn_traffic_pattern_unit’-s applicable to match definite packets which are to be received by the peer side in case if the initial ‘ndn_raw_packet’-s are sent and (possibly) undergo some transformations (eg, HW offloads are active)

Deprecated This API is not well-thought, and the implementation is mind-boggling.

Please consider using better, granular helpers to do varios editing, namely:

tapi_ndn_pkt_demand_correct_ip_cksum()
tapi_ndn_pkt_demand_correct_udp_cksum()
tapi_ndn_pkt_demand_correct_tcp_cksum()
tapi_ndn_superframe_gso()
tapi_ndn_tso_pkts_edit()
tapi_ndn_gso_pkts_ip_len_edit()
tapi_ndn_gso_pkts_ip_id_edit()
tapi_ndn_gso_pkts_udp_len_edit().

Please use tapi_ndn_pkts_to_ptrn() for the actual conversion.

Consider removing this API and all connected helpers.

The given set of possible transformations is only considered with respect to all ‘ndn_raw_packet’-s in the array, i.e., some individual peculiarities of the items cannot be taken into account, hence, if one needs to process any of individual packets independently, separate calls should be performed (eg, if SEND_COND_HW_OFFL_TSO flag is present, it means that TSO shall be done for all the packets)

Parameters:

packets	An ASN.1 ‘ndn_raw_packet’-s to be processed
n_packets	The number of items available within `packets`
transform	A set of parameters describing some trasformations which are expected to affect the outgoing packets
pattern_out	Location for the pattern which is to be produced

Returns:

Status code

te_errno tapi_tad_concat_patterns(asn_value* dst, asn_value* src)

Concatenate two traffic patterns

src will be freed internally after successful concatenation only

Parameters:

dst	The first pattern to which `src` is to be appended
src	The second pattern which is to be appended to `dst`

Returns:

Status code

te_errno tapi_tad_aggregate_patterns(asn_value** patterns, unsigned int nb_patterns, asn_value** pattern_out)

Aggregate the copies of pattern units from all the patterns within a given array to make a single pattern suitable for matching heterogeneous packets

The function doesn’t change or free the initial patterns; tapi_tad_concat_patterns() is fed by copies internally

Parameters:

patterns	An array containing initial patterns to be aggregated
nb_patterns	The number of patterns available in `patterns` array
pattern_out	Location for the new pattern which is to be produced

Returns:

Status code

te_errno tapi_ndn_subst_env(asn_value* value, te_kvpair_h* params, struct tapi_env* env)

The function iterates through ASN.1 value, find all data units with “#env” value choice and substitute it in accordance with params and env

Parameters:

value	ASN value, which content should be substituted
params	Key-value pairs with test parameters or `NULL`
env	Environment or `NULL`

Returns:

Status code

te_errno tapi_ndn_tmpl_classify(const asn_value* tmpl, te_tad_protocols_t hdrs[TAPI_NDN_NLEVELS])

Given a traffic template, inspect its PDUs and fill out the output array of header types to provide the caller with details about protocols in use.

The API will indicate missing PDUs by TE_PROTO_INVALID.

Parameters:

tmpl	The traffic template
hdrs	Array of size `TAPI_NDN_NLEVELS` to store the results in

Returns:

Status code.

te_errno tapi_ndn_tmpl_set_ip_cksum(asn_value* tmpl, uint16_t cksum, tapi_ndn_level_t level)

Given a traffic template, set its IPv4 checksum plain value.

Parameters:

tmpl	The traffic template
cksum	The checksum value to be set (host byte order)
level	`TAPI_NDN_OUTER_L3` or `TAPI_NDN_INNER_L3`

Returns:

Status code.

te_errno tapi_ndn_tmpl_set_udp_cksum(asn_value* tmpl, uint16_t cksum, tapi_ndn_level_t level)

Given a traffic template, set its UDP checksum plain value.

Parameters:

tmpl	The traffic template
cksum	The checksum value to be set (host byte order)
level	`TAPI_NDN_OUTER_L4` or `TAPI_NDN_INNER_L4`

Returns:

Status code.

te_errno tapi_ndn_tmpl_set_tcp_cksum(asn_value* tmpl, uint16_t cksum)

Given a traffic template, set its TCP checksum plain value.

Parameters:

tmpl	The traffic template
cksum	The checksum value to be set (host byte order)

Returns:

Status code.

te_errno tapi_ndn_tmpl_set_tcp_flags(asn_value* tmpl, uint8_t flags)

Given a traffic template, set its TCP flags plain value.

Parameters:

tmpl	The traffic template
flags	The flags value to be set

Returns:

Status code.

te_errno tapi_ndn_tmpl_set_payload_len(asn_value* tmpl, unsigned int payload_len)

Given a traffic template, set its payload length. This function doesn’t set the payload data since random payload will be provided later by Tx CSAP.

Parameters:

tmpl	The traffic template
payload_len	Payload length value

Returns:

Status code.

te_errno tapi_ndn_pkt_inject_vlan_tag(asn_value* pkt, uint16_t vlan_tci)

Given an ASN.1 raw packet and VLAN TCI, inject a VLAN tag to the outer Ethernet PDU thus simulating a VLAN tag HW offload.

Parameters:

pkt	The ASN.1 raw packet to be edited
vlan_tci	VLAN TCI (host byte order) to be injected

Returns:

Status code.

te_errno tapi_ndn_pdus_inject_vlan_tags(asn_value* pdus, const uint16_t* vid, const uint16_t* prio, const uint16_t* cfi, size_t n_tags)

Inject VLAN tags to outer Ethernet PDU in a PDU sequence.

The API works only with exactly specified or not set vlan headers. Ranged fields are not supported.

UINT16_MAX for vid, prio or cfi means that this value is not specified in the PDU

Parameters:

pdus	PDU sequence
vid	VLAN IDs
prio	VLAN priority fields
cfi	VLAN CFI fields
n_tags	Number of tags to be pushed, specifies size of `vid`, `prio`, `cfi`

Returns:

Status code

te_errno tapi_ndn_pdus_remove_vlan_tags(asn_value* pdus, size_t n_tags)

Remove VLAN tags from outer Ethernet PDU in a PDU sequence.

The API works only with exactly specified or not set VLAN headers. Ranged fields are not supported.

Parameters:

pdus	PDU sequence
n_tags	Number of tags to remove

Returns:

Status code

te_errno tapi_ndn_eth_read_vlan_tci(const asn_value* eth, size_t* n_tags, uint16_t* vid, uint16_t* prio, uint16_t* cfi)

Read TCI value of VLAN tags of a Ethernet PDU.

The API works only with exactly specified or not set vlan headers. Ranged fields are not supported.

UINT16_MAX for vid, prio or cfi means that this value is not specified in the PDU

Parameters:

eth	ASN.1 value of ethernet PDU
n_tags	Size of the `vid`, `prio` and `cfi` arrays, on success contains the number of tags that were read (may be `0` if `eth` does not have any VLAN tags)
vid	VLAN IDs
prio	VLAN priority fields
cfi	VLAN CFI fields

Returns:

Status code

te_errno tapi_ndn_pkt_demand_correct_ip_cksum(asn_value* pkt, tapi_ndn_level_t level)

Take an ASN.1 raw packet which is going to be transformed to a pattern and override IPv4 checksum field to require correct checksum in the packet which is about to be received on peer.

Parameters:

pkt	The ASN.1 raw packet to be edited
level	`TAPI_NDN_OUTER_L3` or `TAPI_NDN_INNER_L3`

Returns:

Status code.

te_errno tapi_ndn_pkt_demand_correct_udp_cksum(asn_value* pkt, bool can_be_zero, tapi_ndn_level_t level)

Take an ASN.1 raw packet which is going to be transformed to a pattern and override UDP checksum field to require correct checksum in the packet which is about to be received on peer.

Parameters:

pkt	The ASN.1 raw packet to be edited
can_be_zero	If `true`, allow for zero checksum value
level	`TAPI_NDN_OUTER_L4` or `TAPI_NDN_INNER_L4`

Returns:

Status code.

te_errno tapi_ndn_pkt_demand_correct_tcp_cksum(asn_value* pkt)

Take an ASN.1 raw packet which is going to be transformed to a pattern and override TCP checksum field to require correct checksum in the packet which is about to be received on peer.

Parameters:

pkt	The ASN.1 raw packet to be edited

Returns:

Status code.

te_errno tapi_ndn_superframe_gso(asn_value* superframe, size_t seg_payload_len, const struct tapi_ndn_gso_conf* gso_conf, asn_value*** pkts_out, unsigned int* nb_pkts_out)

Take an ASN.1 raw packet containing a superframe and conduct GSO slicing to produce a burst of ASN.1 raw packets each one containing unchanged PDUs from the original superframe and a properly sized chunk of payload read out from the same frame.

Parameters:

superframe	The superframe to undergo GSO slicing
seg_payload_len	The desired length of a payload chunk
gso_conf	Segmentation fine-tuning configuration
pkts_out	Location for the resulting packets
nb_pkts_out	Location for the number of the packets

Returns:

Status code.

te_errno tapi_ndn_tso_pkts_edit(asn_value** pkts, unsigned int nb_pkts)

Given a bunch of ASN.1 raw packets originating from some GSO transaction, conduct a very minimal TSO edit across TCP PDUs. Line up TCP sequence numbers as per GSO segment payload size and amend TCP flags so that all the packets but the last one have FIN and PSH bits cleared whilst CWR bit (if present) is retained intact solely in the very first packet of the array.

Parameters:

pkts	The array of ASN.1 raw packets
nb_pkts	The number of ASN.1 raw packets

Returns:

Status code.

te_errno tapi_ndn_gso_pkts_ip_len_edit(asn_value** pkts, unsigned int nb_pkts, te_tad_protocols_t ip_te_proto, tapi_ndn_level_t level)

Given a bunch of ASN.1 raw packets originating from some GSO transaction, fix IP inner / outer length field in each frame.

Parameters:

pkts	The array of ASN.1 raw packets
nb_pkts	The number of ASN.1 raw packets
ip_te_proto	`TE_PROTO_IP4` or `TE_PROTO_IP6`
level	`TAPI_NDN_OUTER_L3` or `TAPI_NDN_INNER_L3`

Returns:

Status code.

te_errno tapi_ndn_gso_pkts_ip_id_edit(asn_value** pkts, unsigned int nb_pkts, tapi_ndn_level_t level)

Given a bunch of ASN.1 raw packets originating from some GSO transaction, line up IPv4 ID field values across the packets.

Parameters:

pkts	The array of ASN.1 raw packets
nb_pkts	The number of ASN.1 raw packets
level	`TAPI_NDN_OUTER_L3` or `TAPI_NDN_INNER_L3`

Returns:

Status code.

te_errno tapi_ndn_gso_pkts_udp_len_edit(asn_value** pkts, unsigned int nb_pkts, tapi_ndn_level_t level)

Given a bunch of ASN.1 raw packets originating from some GSO transaction, fix UDP inner / outer length field in each frame.

Parameters:

pkts	The array of ASN.1 raw packets
nb_pkts	The number of ASN.1 raw packets
level	`TAPI_NDN_OUTER_L4` or `TAPI_NDN_INNER_L4`

Returns:

Status code.

te_errno tapi_ndn_pkts_to_ptrn(asn_value** pkts, unsigned int nb_pkts, asn_value** ptrn_out)

Convert ASN.1 raw packets to a multi-unit traffic pattern.

Parameters:

pkts	The array of ASN.1 raw packets
nb_pkts	The number of ASN.1 raw packets
ptrn_out	Location for the resulting pattern

Returns:

Status code.

te_errno tapi_eth_transform_ptrn_on_rx(receive_transform* rx_transform, asn_value** ptrn)

Transform a pattern of coming packets in accordance with receive effects

Parameters:

rx_transform	A set of parameters describing some trasformations which are expected to affect the packets on receive
ptrn	Location of a pattern to be transformed

Returns:

Status code.

Macros

#define SEND_COND_HW_OFFL_IP_CKSUM

Flags used to designate transformations which take place in hardware

#define TEST_GET_NDN_TRAFFIC_TEMPLATE(_var_name)

Get ndn_traffic_template ASN.1 type test parameter.

Parameters:

_var_name

Variable whose name is the same as the name of parameter we get the value