TAPI definitions for testing TCP states

Overview

TCP states API library - public declarations of API used to achieve a requested TCP socket state following specified sequence of TCP states. More…

// typedefs

typedef enum tsa_tst_type tsa_tst_type;
typedef enum tsa_flags tsa_flags;
typedef struct tsa_config tsa_config;
typedef struct tsa_state_sock tsa_state_sock;
typedef struct tsa_state_csap tsa_state_csap;
typedef te_errno (*tsa_handler)(struct tsa_session *ss);
typedef struct tsa_handlers tsa_handlers;
typedef struct tsa_state tsa_state;
typedef struct tsa_session tsa_session;
typedef struct tcp_move_action tcp_move_action;
typedef struct tsa_packets_counter tsa_packets_counter;

// enums

enum tsa_flags;
enum tsa_tst_type;

// structs

struct tcp_move_action;
struct tsa_config;
struct tsa_handlers;
struct tsa_packets_counter;
struct tsa_session;
struct tsa_state;
struct tsa_state_csap;
struct tsa_state_sock;

// global functions

static int tsa_iut_sock(tsa_session* ss);
static int tsa_tst_sock(tsa_session* ss);
static rpc_tcp_state tsa_state_cur(tsa_session* ss);
static void tsa_state_cur_set(tsa_session* ss, rpc_tcp_state state);
static rpc_tcp_state tsa_state_to(tsa_session* ss);
static rpc_tcp_state tsa_state_from(tsa_session* ss);
static const char* tsa_rem_path(tsa_session* ss);
static bool tsa_timeout_used(tsa_session* ss);
static int tsa_elapsed_time(tsa_session* ss);
te_errno tsa_state_init(tsa_session* ss, tsa_tst_type tst_type);
te_errno tsa_iut_set(tsa_session* ss, rcf_rpc_server* pco_iut, const struct if_nameindex* iut_if, const struct sockaddr* iut_addr);
te_errno tsa_tst_set(tsa_session* ss, rcf_rpc_server* pco_tst, const struct if_nameindex* tst_if, const struct sockaddr* tst_addr, const void* fake_link_addr);
te_errno tsa_gw_set(tsa_session* ss, rcf_rpc_server* pco_gw, const struct sockaddr* gw_iut_addr, const struct sockaddr* gw_tst_addr, const struct if_nameindex* gw_iut_if, const struct if_nameindex* gw_tst_if, const void* alien_link_addr);
void tsa_gw_preconf(tsa_session* ss, bool preconfigured);
te_errno tsa_break_tst_iut_conn(tsa_session* ss);
te_errno tsa_break_iut_tst_conn(tsa_session* ss);
te_errno tsa_repair_tst_iut_conn(tsa_session* ss);
te_errno tsa_repair_iut_tst_conn(tsa_session* ss);
te_errno tsa_do_tcp_move(tsa_session* ss, rpc_tcp_state state_from, rpc_tcp_state state_to, uint32_t flags);
te_errno tsa_do_moves(tsa_session* ss, rpc_tcp_state stop_state, uint32_t flags, ...);
te_errno tsa_do_moves_str(tsa_session* ss, rpc_tcp_state init_state, rpc_tcp_state stop_state, uint32_t flags, const char* s);
te_errno tsa_create_session(tsa_session* ss, uint32_t flags);
te_errno tsa_destroy_session(tsa_session* ss);
te_errno tsa_set_start_tcp_state(tsa_session* ss, rpc_tcp_state state, rpc_tcp_state stop_state, uint32_t flags);
te_errno tsa_update_cur_state(tsa_session* ss);
te_errno tsa_tst_send_rst(tsa_session* ss);
void tsa_packet_handler(const char* packet, void* user_param);
void tsa_print_packet_stats(tsa_packets_counter* ctx);

// macros

#define TEST_GET_TSA_TST_TYPE_PARAM(var_)
#define TSA_ESTOP
#define TSA_SESSION_INITIALIZER

Detailed Documentation

TCP states API library - public declarations of API used to achieve a requested TCP socket state following specified sequence of TCP states.

Typedefs

typedef enum tsa_tst_type tsa_tst_type

What should be used on tester side:

typedef enum tsa_flags tsa_flags

Flags used by various functions in library

typedef struct tsa_config tsa_config

Environment configuration for current working session with TSA

typedef struct tsa_state_sock tsa_state_sock

Structure describing variables used in TSA_TST_SOCKET mode

typedef struct tsa_state_csap tsa_state_csap

Structure describing variables used in TSA_TST_CSAP mode

typedef te_errno (*tsa_handler)(struct tsa_session *ss)

Type for handler to be called when moving from one TCP state to another one.

typedef struct tsa_handlers tsa_handlers

Structure containing handlers to be used for moving between TCP states. TSA session state structure

typedef struct tsa_state tsa_state

TSA session variables

typedef struct tcp_move_action tcp_move_action

Actions must be performed to move from one TCP state to another

typedef struct tsa_packets_counter tsa_packets_counter

Context to count packets in processing in the packet handler function.

Global Functions

static int tsa_iut_sock(tsa_session* ss)

Accessor for IUT socket.

Parameters:

ss	Pointer to TSA session structure of current working session

Returns:

IUT socket ID

static int tsa_tst_sock(tsa_session* ss)

Accessor for TESTER TCP socket (or its CSAP emulator handler if TSA_TST_CSAP mode is used).

Parameters:

ss	Pointer to TSA session structure of current working session

Returns:

Socket (CSAP handler) or -1

static rpc_tcp_state tsa_state_cur(tsa_session* ss)

Accessor for current TCP state of IUT socket.

Parameters:

ss	Pointer to TSA session structure of current working session

Returns:

Current TCP state of IUT socket

static void tsa_state_cur_set(tsa_session* ss, rpc_tcp_state state)

Setter for current TCP state of IUT socket.

Parameters:

ss	Pointer to TSA session structure of current working session

static rpc_tcp_state tsa_state_to(tsa_session* ss)

Accessor for state_to field of tsa_state structure.

Parameters:

ss	Pointer to TSA session structure of current working session

Returns:

Value of state_to field of tsa_state stucture

static rpc_tcp_state tsa_state_from(tsa_session* ss)

Accessor for state_from field of tsa_state structure.

Parameters:

ss	Pointer to TSA session structure of current working session

Returns:

Value of state_from field of tsa_state structure.

static const char* tsa_rem_path(tsa_session* ss)

Accessor for rem_path field of tsa_state structure.

Parameters:

ss	Pointer to TSA session structure of current working session

Returns:

Value of rem_path field of tsa_state structure

static bool tsa_timeout_used(tsa_session* ss)

Accessor for timeout_used field of tsa_state structure.

Parameters:

ss	Pointer to TSA session structure of current working session

Returns:

Value of timeout_used field of tsa_state structure

static int tsa_elapsed_time(tsa_session* ss)

Accessor for elapsed_time field of tsa_state structure.

Parameters:

ss	Pointer to TSA session structure of current working session

Returns:

Value of elapsed_time field of tsa_state structure

te_errno tsa_state_init(tsa_session* ss, tsa_tst_type tst_type)

Initialize tsa_session structure.

Parameters:

ss	Pointer to TSA session structure to be initialized
tst_type	What should be used on the tester (socket, CSAP)

Returns:

Status code.

te_errno tsa_iut_set(tsa_session* ss, rcf_rpc_server* pco_iut, const struct if_nameindex* iut_if, const struct sockaddr* iut_addr)

Set tsa_session structure fields related to RPC server on the IUT side.

Parameters:

ss	Pointer to TSA session structure
pco_iut	RPC server on the IUT side
iut_if	Network interface on the IUT side
iut_addr	Network address on the IUT side

Returns:

Status code.

te_errno tsa_tst_set(tsa_session* ss, rcf_rpc_server* pco_tst, const struct if_nameindex* tst_if, const struct sockaddr* tst_addr, const void* fake_link_addr)

Set tsa_session structure fields related to RPC server on the TST side. Add entries in ARP and routing tables for fake addresses if we use CSAP emulation on the TESTER (CFG_WAIT_CHANGES should be used after call of this function in such a case).

Parameters:

ss	Pointer to TSA session structure
pco_tst	RPC server on the TST side
tst_if	Network interface on the TST side
tst_addr	Network address on the TST side
fake_link_addr	Fake ethernet address to be used by CSAP (if we use CSAP implementation of TCP socket)

Returns:

Status code.

te_errno tsa_gw_set(tsa_session* ss, rcf_rpc_server* pco_gw, const struct sockaddr* gw_iut_addr, const struct sockaddr* gw_tst_addr, const struct if_nameindex* gw_iut_if, const struct if_nameindex* gw_tst_if, const void* alien_link_addr)

Set tsa_session structure fields related to gateway; configure routes via gateway. CFG_WAIT_CHANGES should be used after calling this function.

Parameters:

ss	Pointer to TSA session structure
pco_gw	RPC server on a gateway
gw_iut_addr	Gateway IUT address
gw_tst_addr	Gateway TST address
gw_iut_if	Gateway IUT interface.
gw_tst_if	Gateway TST interface.
alien_link_addr	Invalid ethernet address

Returns:

Status code.

void tsa_gw_preconf(tsa_session* ss, bool preconfigured)

Specify whether gateway is already configured. It makes sense to call this function only before tsa_gw_set().

Parameters:

ss	Pointer to TSA session structure
preconfigured	If `true`, gateway is already configured, tsa_gw_set() should not try to configure routes or forwarding.

te_errno tsa_break_tst_iut_conn(tsa_session* ss)

Break network connection from pco_tst to pco_iut by adding ARP table entry associating IUT IP address with alien MAC address. CFG_WAIT_CHANGES should be used after calling this function.

Parameters:

ss	Pointer to TSA session structure

Returns:

Status code.

te_errno tsa_break_iut_tst_conn(tsa_session* ss)

Break network connection from pco_iut to pco_tst by adding ARP table entry associating Tester IP address with alien MAC address. CFG_WAIT_CHANGES should be used after calling this function.

Parameters:

ss	Pointer to TSA session structure

Returns:

Status code.

te_errno tsa_repair_tst_iut_conn(tsa_session* ss)

Repair network connection from pco_tst to pco_iut by removing ARP table entry for alien MAC address. CFG_WAIT_CHANGES should be used after calling this function.

Parameters:

ss	Pointer to TSA session structure

Returns:

Status code.

te_errno tsa_repair_iut_tst_conn(tsa_session* ss)

Repair network connection from pco_iut to pco_tst by removing ARP table entry for alien MAC address. CFG_WAIT_CHANGES should be used after calling this function.

Parameters:

ss	Pointer to TSA session structure

Returns:

Status code.

te_errno tsa_do_tcp_move(tsa_session* ss, rpc_tcp_state state_from, rpc_tcp_state state_to, uint32_t flags)

Move from one TCP state to another one.

Parameters:

ss	Pointer to TSA session structure
state_from	Initial TCP state
state_to	TCP state to move to
flags	Flags defined in tsa_flags enum

Returns:

Status code.

te_errno tsa_do_moves(tsa_session* ss, rpc_tcp_state stop_state, uint32_t flags, ...)

Perform a given sequence of TCP state transitions.

Parameters:

ss	Pointer to TSA session structure
stop_state	TCP state where to stop (it’s useful when we want to perform some actions in some interjacent state and then resume transition)
flags	Flags defined in tsa_flags enum
…	List of TCP states in transition sequence (it should be terminated by RPC_TCP_UNKNOWN)

Returns:

Non-negative status code or TSA_ESTOP if function stopped in specificed state.

te_errno tsa_do_moves_str(tsa_session* ss, rpc_tcp_state init_state, rpc_tcp_state stop_state, uint32_t flags, const char* s)

Perform a given sequence of TCP state transitions (like tsa_do_moves but the sequence is given as a string).

Parameters:

ss	Pointer to TSA session structure
init_state	TCP state to be considered as initial in search for the first transition actions (it is useful when we work with TCP_LISTEN -> TCP_SYN_RECV -> TCP_ESTABLISHED because TCP_SYN_RECV is not observable in this case)
stop_state	TCP state where to stop (it’s useful when we want to perform some actions in some interjacent state and then resume transition)
flags	Flags defined in tsa_flags enum
s	String containing the sequence of TCP states. For example, “TCP_CLOSE -> TCP_SYN_SENT -> timeout -> TCP_CLOSE”. TCP states can be separated by spaces, ‘-’, ‘>’, ‘;’, ‘:’, ‘,’ (including any combinations of these symbols).

Returns:

Non-negative status code or TSA_ESTOP if function stopped in specificed state.

te_errno tsa_create_session(tsa_session* ss, uint32_t flags)

Create IUT socket and TESTER socket or CSAP emulation (according to working mode determined by tst_type during initialization), set socket options if needed, bind() socket(s). Cleanup should be done by tsa_destroy_session() call.

Parameters:

ss	Pointer to TSA session structure
flags	Flags (described above in tsa_flags enum)

Returns:

Status code.

te_errno tsa_destroy_session(tsa_session* ss)

Perform cleanup on TSA library context.

Parameters:

ss	Pointer to TSA session structure

Returns:

Status code.

te_errno tsa_set_start_tcp_state(tsa_session* ss, rpc_tcp_state state, rpc_tcp_state stop_state, uint32_t flags)

Move from TCP_CLOSE state to another state using correspoding pre-defined path. Pre-defined path is just sequence of TCP states from TCP_CLOSE to a given state which is defined in tcp_state.c and is used by default. There is only two pre-defined paths for any TCP state - path using active opening of TCP connection and path using passive one (for some paths these make no sense and two paths are defined for simplicity of related functions).

Parameters:

ss	Pointer to TSA session structure
state	TCP state to be achieved
stop_state	TCP state where to stop (it’s useful when we want to perform some actions in some interjacent state and then resume transition)
flags	Flags defined in tsa_flags enum

Returns:

Status code.

te_errno tsa_update_cur_state(tsa_session* ss)

Update current TCP state of IUT socket.

Parameters:

ss	Pointer to TSA session structure

Returns:

Status code.

te_errno tsa_tst_send_rst(tsa_session* ss)

Send RST from TESTER to IUT.

Parameters:

ss	Pointer to TSA session structure

Returns:

Status code.

void tsa_packet_handler(const char* packet, void* user_param)

Packet handler callback function.

Parameters:

packet	Packet handler
user_param	Packet context as opaque argument

void tsa_print_packet_stats(tsa_packets_counter* ctx)

Print captured packets stats.

Parameters:

ctx	Packets stats struct

Macros

#define TEST_GET_TSA_TST_TYPE_PARAM(var_)

Get tsa_tst_type parameter determining whether we use socket or CSAP emulation of TCP socket on the TESTER.

#define TSA_ESTOP

Value returned when function stopped transition in specified state, before reaching end state in sequence.

#define TSA_SESSION_INITIALIZER

Initializer for tsa_session structure.