Network environment

Overview

Optional library which can help to simplify test iteration and description of the tested network environment schema. More…

// typedefs

typedef struct cfg_handle_tqe cfg_handle_tqe;
typedef struct tapi_env_net tapi_env_net;
typedef struct tapi_env_host tapi_env_host;
typedef struct tapi_env_if tapi_env_if;
typedef struct tapi_env_ps_if tapi_env_ps_if;
typedef struct tapi_env_process tapi_env_process;
typedef struct tapi_env_pco tapi_env_pco;
typedef struct tapi_env_addr tapi_env_addr;
typedef struct tapi_env_alias tapi_env_alias;
typedef struct tapi_env tapi_env;

typedef void tapi_env_foreach_if_fn(
    tapi_env_if *iface,
    void *opaque
    );

// enums

enum tapi_env_addr_type;
enum tapi_env_type;

// structs

struct cfg_handle_tqe;
struct tapi_env;
struct tapi_env_addr;
struct tapi_env_alias;
struct tapi_env_host;
struct tapi_env_if;
struct tapi_env_net;
struct tapi_env_pco;
struct tapi_env_process;
struct tapi_env_ps_if;

// global functions

static const char* tapi_env_type_str(tapi_env_type type);
typedef STAILQ_HEAD(cfg_handle_tqh, cfg_handle_tqe);
typedef SLIST_HEAD(tapi_env_nets, tapi_env_net);
typedef SLIST_HEAD(tapi_env_processes, tapi_env_process);
typedef SLIST_HEAD(tapi_env_hosts, tapi_env_host);
typedef CIRCLEQ_HEAD(tapi_env_ifs, tapi_env_if);
typedef STAILQ_HEAD(tapi_env_ps_ifs, tapi_env_ps_if);
typedef STAILQ_HEAD(tapi_env_pcos, tapi_env_pco);
typedef CIRCLEQ_HEAD(tapi_env_addrs, tapi_env_addr);
typedef SLIST_HEAD(tapi_env_aliases, tapi_env_alias);
te_errno tapi_env_init(tapi_env* env);
te_errno tapi_env_get(const char* cfg, tapi_env* env);
te_errno tapi_env_get_rpcs_only(const char* cfg, tapi_env* env);
te_errno tapi_env_allocate_addr(tapi_env_net* net, int af, struct sockaddr** addr, socklen_t* addrlen);
te_errno tapi_env_free(tapi_env* env);
tapi_env_net* tapi_env_get_net(tapi_env* env, const char* name);
tapi_env_host* tapi_env_get_host(tapi_env* env, const char* name);
rcf_rpc_server* tapi_env_get_pco(tapi_env* env, const char* name);
const struct sockaddr* tapi_env_get_addr(tapi_env* env, const char* name, socklen_t* addrlen);
tapi_env_addr_type tapi_get_addr_type(tapi_env* env, const char* name);
const struct if_nameindex* tapi_env_get_if(tapi_env* env, const char* name);
const tapi_env_if* tapi_env_get_env_if(tapi_env* env, const char* name);
const struct if_nameindex* tapi_env_get_br(tapi_env* env, const char* name);
const struct if_nameindex* tapi_env_get_ph(tapi_env* env, const char* name);
te_errno tapi_env_get_net_host_addr(const tapi_env* env, const tapi_env_net* net, const tapi_env_host* host, sa_family_t af, tapi_cfg_net_assigned* assigned, struct sockaddr** addr, socklen_t* addrlen);
const tapi_env_pco* tapi_env_rpcs2pco(const tapi_env* env, const rcf_rpc_server* rpcs);
struct sockaddr** tapi_env_add_addresses(rcf_rpc_server* rpcs, tapi_env_net* net, int af, const struct if_nameindex* iface, int addr_num);
void tapi_env_foreach_if(tapi_env* env, tapi_env_foreach_if_fn* fn, void* opaque);
unsigned tapi_env_nets_count(tapi_env* env);
const cfg_net_node_t* tapi_env_get_if_net_node(const tapi_env_if* iface);

// macros

#define CHECK_ADDR_FAKE(addr_, fake_)
#define TEST_END_ENV
#define TEST_GET_ADDR(pco_, addr_)
#define TEST_GET_ADDR_NO_PORT(addr_)
#define TEST_GET_ADDR_REUSE_PORT(pco_, src_, addr_)
#define TEST_GET_BR(if_, br_)
#define TEST_GET_ENV_IF(env_if_)
#define TEST_GET_HOST(host_)
#define TEST_GET_IF(if_)
#define TEST_GET_LINK_ADDR(addr_)
#define TEST_GET_NET(net_)
#define TEST_GET_PCO(rpcs_)
#define TEST_GET_PH(if_, ph_)
#define TEST_START_ENV
#define TEST_START_ENV_VARS

Detailed Documentation

Optional library which can help to simplify test iteration and description of the tested network environment schema. If the library is used then every test in the test suite has to have argument env written in YACC which describes location of IUT and Tester RPC servers, nets, interfaces and addresses.

Copyright (C) 2004-2022 OKTET Labs Ltd. All rights reserved.

Typedefs

typedef struct cfg_handle_tqe cfg_handle_tqe

Tail queue of Cfgr handles

typedef struct tapi_env_net tapi_env_net

Network entry

typedef struct tapi_env_host tapi_env_host

Host entry in environment

typedef struct tapi_env_if tapi_env_if

Host/interface entry in environment

typedef struct tapi_env_ps_if tapi_env_ps_if

Process interfaces

typedef struct tapi_env_process tapi_env_process

Process entry on a host

typedef struct tapi_env_pco tapi_env_pco

Entry of PCO name to RPC server mapping

typedef struct tapi_env_addr tapi_env_addr

Entry of address name to real address mapping

typedef struct tapi_env_alias tapi_env_alias

Alias in Socket API testing environment

typedef struct tapi_env tapi_env

Environment for the test

Global Functions

typedef STAILQ_HEAD(cfg_handle_tqh, cfg_handle_tqe)

Head of the tail queue with Cfgr handles

typedef SLIST_HEAD(tapi_env_nets, tapi_env_net)

List of required networks in environment

typedef SLIST_HEAD(tapi_env_processes, tapi_env_process)

List of processes on a host

typedef SLIST_HEAD(tapi_env_hosts, tapi_env_host)

List of required hosts in environment

typedef CIRCLEQ_HEAD(tapi_env_ifs, tapi_env_if)

List of host interfaces required in environment

typedef STAILQ_HEAD(tapi_env_ps_ifs, tapi_env_ps_if)

List of process interfaces

typedef STAILQ_HEAD(tapi_env_pcos, tapi_env_pco)

List of PCOs

typedef CIRCLEQ_HEAD(tapi_env_addrs, tapi_env_addr)

List of addresses in environment

typedef SLIST_HEAD(tapi_env_aliases, tapi_env_alias)

List of aliases in environment

te_errno tapi_env_init(tapi_env* env)

Initialize environment variable.

Parameters:

env	Location for environment

Returns:

Status code.

te_errno tapi_env_get(const char* cfg, tapi_env* env)

Get Socket API test suite environment for the test.

Parameters:

cfg	Environment configuration string
env	Location for environment

Returns:

Status code.

te_errno tapi_env_get_rpcs_only(const char* cfg, tapi_env* env)

Get only RPC servers for the test suite environment. Unlike the tapi_env_get(), the function does not bind interfaces, addresses and sniffers.

Parameters:

cfg	Environment configuration string
env	Location for environment

Returns:

Status code.

te_errno tapi_env_allocate_addr(tapi_env_net* net, int af, struct sockaddr** addr, socklen_t* addrlen)

Allocate new address from specified net.

Parameters:

net	Net
af	Family of the address to be allocated
addr	Location for address pointer (allocated from heap)
addrlen	Location for address length of NULL

Returns:

Status code.

te_errno tapi_env_free(tapi_env* env)

Free Socket API test suite environment.

Parameters:

env	Environment

Returns:

Status code.

tapi_env_net* tapi_env_get_net(tapi_env* env, const char* name)

Get handle of the net from environment by name.

Parameters:

env	Environment
name	Name of the net

Returns:

Handle of the net.

tapi_env_host* tapi_env_get_host(tapi_env* env, const char* name)

Get handle of the host from environment by name.

Parameters:

env	Environment
name	Name of the host

Returns:

Handle of the host.

rcf_rpc_server* tapi_env_get_pco(tapi_env* env, const char* name)

Get handle of PCO (RPC server) from environment by name.

RPC server is automatically closed and handle becomes not valid when environment is freed.

Parameters:

env	Environment
name	Name of the PCO

Returns:

Handle of the RPC server.

const struct sockaddr* tapi_env_get_addr(tapi_env* env, const char* name, socklen_t* addrlen)

Get address from environment by name.

Valid port is set in the structure as well. The structure should be copied, if user wants to modify its content. Pointer becomes not valid when environment is freed.

Parameters:

env	Environment
name	Name of the address in configuration string
addrlen	Address length

Returns:

Pointer to address structure.

tapi_env_addr_type tapi_get_addr_type(tapi_env* env, const char* name)

Get type address from environment by name.

Parameters:

env	Environment
name	Name of the address in configuration string

Returns:

Type of address.

const struct if_nameindex* tapi_env_get_if(tapi_env* env, const char* name)

Get system name of the interface named in configuration string as ‘name’ argument.

Pointer becomes not valid when environment is freed.

Parameters:

env	Environment handle
name	Name of the interface in environment

Returns:

Pointer to the structure with interface name and index.

const tapi_env_if* tapi_env_get_env_if(tapi_env* env, const char* name)

Get environment entity of the interface named in configuration string as ‘name’ argument.

Pointer becomes not valid when environment is freed.

Parameters:

env	Environment handle
name	Name of the interface in environment

Returns:

Pointer to the environment interface entity.

const struct if_nameindex* tapi_env_get_br(tapi_env* env, const char* name)

Get system name of the bridge named in configuration string as ‘name’ argument.

Pointer becomes not valid when environment is freed.

Parameters:

env	Environment handle
name	Name of the bridge in environment

Returns:

Pointer to the structure with bridge name and index.

const struct if_nameindex* tapi_env_get_ph(tapi_env* env, const char* name)

Get system name of the physical interface named in configuration string as ‘name’ argument.

Pointer becomes not valid when environment is freed.

Parameters:

env	Environment handle
name	Name of the physical interface in environment

Returns:

Pointer to the structure with bridge name and index.

te_errno tapi_env_get_net_host_addr(const tapi_env* env, const tapi_env_net* net, const tapi_env_host* host, sa_family_t af, tapi_cfg_net_assigned* assigned, struct sockaddr** addr, socklen_t* addrlen)

Get address assigned to the host in specified HW net and address space.

Parameters:

env	Environment
net	Environment net
host	Environment host
af	Address family of requested address
assigned	Information about assigned addresses
addr	Location for address pointer (OUT)
addrlen	Address length (OUT)

Returns:

Status code.

const tapi_env_pco* tapi_env_rpcs2pco(const tapi_env* env, const rcf_rpc_server* rpcs)

Find PCO by RPC server handle.

struct sockaddr** tapi_env_add_addresses(rcf_rpc_server* rpcs, tapi_env_net* net, int af, const struct if_nameindex* iface, int addr_num)

Allocate and add a number of addresses to the specified interface.

The function does not roll back configuration changes in case of fail - the test execution should be aborted.

Parameters:

rpcs	RPC server handle.
net	Network addresses pool.
af	Address family.
iface	Interface handle.
addr_num	Addresses number to be added.

Returns:

Address pointers array or NULL in case of fail.

void tapi_env_foreach_if(tapi_env* env, tapi_env_foreach_if_fn* fn, void* opaque)

Run over all interfaces mentioned in the environment and run a given function for each one.

Hook can call TEST_FAIL() if things go wrong.

Parameters:

env	Environment
fn	Hook pointer
opaque	Hook-defined opaque

unsigned tapi_env_nets_count(tapi_env* env)

Return total number of nets in the environment

Parameters:

env	Environment

Returns:

Number of nets

const cfg_net_node_t* tapi_env_get_if_net_node(const tapi_env_if* iface)

Return network node of an interface.

Parameters:

iface

Network interface

Returns:

Network node configuration

Macros

#define CHECK_ADDR_FAKE(addr_, fake_)

Check that the address is fake. Name of the variable must match name of the address in environment configuration string.

Parameters:

addr_	address
fake_	Whether the address has FAKE type (OUT)

#define TEST_END_ENV

Test suite specific part of the last action with ‘env’ support.

#define TEST_GET_ADDR(pco_, addr_)

Get address and assign a free port. Name of the variable must match name of the address in environment configuration string.

Parameters:

pco_	RPC server to use when checking the port (IN)
addr_	address (const struct sockaddr *) (OUT)

#define TEST_GET_ADDR_NO_PORT(addr_)

Get address. Name of the variable must match name of the address in environment configuration string.

Parameters:

addr_

address (const struct sockaddr *) (OUT)

#define TEST_GET_ADDR_REUSE_PORT(pco_, src_, addr_)

Get address and assign port from another address. Names of the variables must match name of the addresses in environment configuration string. Source address must already be initialized.

Parameters:

pco_	RPC server to use when checking the port.
src_	Address whose port to use (const struct sockaddr *).
addr_	Address (const struct sockaddr *).

#define TEST_GET_BR(if_, br_)

Get XEN bridge. Name of the variable must match name of the XEN bridge in environment configuration string.

Parameters:

br_	XEN bridge (const struct if_nameindex *) (OUT)

#define TEST_GET_ENV_IF(env_if_)

Get environment interface entity. Name of the variable must match name of the interface in environment configuration string.

Parameters:

env_if_

interface (const tapi_env_if *) (OUT)

#define TEST_GET_HOST(host_)

Get named host from environment. Name of the variable must match name of the host in environment configuration string.

Parameters:

host_

Pointer to tapi_env_host (OUT)

#define TEST_GET_IF(if_)

Get interface. Name of the variable must match name of the interface in environment configuration string.

Parameters:

if_	interface (const struct if_nameindex *) (OUT)

#define TEST_GET_LINK_ADDR(addr_)

Get the value of link-layer address parameter. Name of the variable must match name of the address in environment configuration string.

Parameters:

addr_

address (const unsigned char *) (OUT)

#define TEST_GET_NET(net_)

Get network. Name of the variable must match name of the network in environment configuration string.

Parameters:

net_	Pointer to tapi_env_net (OUT)

#define TEST_GET_PCO(rpcs_)

Get PCO (RPC server) handle. Name of the variable must match name of the PCO in environment configuration string.

Parameters:

rpcs_

RPC server handle (OUT)

#define TEST_GET_PH(if_, ph_)

Get XEN physical interface. Name of the variable must match name of the XEN physical interface in environment configuration string.

Parameters:

ph_	XEN physical interface (const struct if_nameindex *) (OUT)

#define TEST_START_ENV

Test suite specific the first actions of the test with ‘env’ support.

#define TEST_START_ENV_VARS

Test suite specific variables with ‘env’ support.