Shell commands to test a CongURE implementation. More...

Detailed Description

Shell commands to test a CongURE implementation.

This module requires an application defined congure_impl.h which defines the congure_snd_t extension of the CongURE implementation as congure_test_snd_t and provides a function declaration congure_test_snd_setup() setup said type. E.g.

typedef congure_reno_snd_t congure_test_snd_t;
 
void congure_test_snd_setup(congure_test_snd_t *c, int id);

All constants and initial values can then be set within the application specific definition of congure_test_snd_setup().

Files
file	test.h
	Definitions for the CongURE test framework.

Macros
#define	CONFIG_CONGURE_TEST_LOST_MSG_POOL_SIZE (4U)
	Pool size for the message list elements for a lost message report.

Typedefs
typedef congure_snd_t	congure_test_snd_t
	Application-defined type for the CongURE state object under test.

Functions
int	congure_test_snd_setup (void congure_test_snd_t *c, unsigned id)
	Setup the application-defined CongURE state object under test.

congure_test_snd_t *	congure_test_get_state (void)
	Get the application-defined CongURE state object.

int	congure_test_clear_state (int argc, char **argv)
	Clears the CongURE state object.

int	congure_test_call_setup (int argc, char **argv)
	Setup the CongURE state object.

int	congure_test_call_init (int argc, char **argv)
	Calls `init()` method for CongURE state object.

int	congure_test_call_inter_msg_interval (int argc, char **argv)
	Calls `inter_msg_interval()` method for CongURE state object.

int	congure_test_add_msg (int argc, char **argv)
	Adds a message from the message pool to the list for `cong_report msgs_lost` and `cong_report msgs_timeout`.

int	congure_test_msgs_reset (int argc, char **argv)
	Resets the the message pool and messages list for `cong_report msgs_lost` and `cong_report msgs_timeout`.

int	congure_test_call_report (int argc, char **argv)
	Calls one of the `report_*()` methods for CongURE state object.

Macro Definition Documentation

◆ CONFIG_CONGURE_TEST_LOST_MSG_POOL_SIZE

#define CONFIG_CONGURE_TEST_LOST_MSG_POOL_SIZE (4U)

Pool size for the message list elements for a lost message report.

See also: congure_snd_driver_t::report_msg_lost

This defines the maximum number of 3-tuples you can use with congure_test_call_report() when argv[1] = "msg_lost".

Definition at line 84 of file test.h.

Typedef Documentation

◆ congure_test_snd_t

typedef congure_snd_t congure_test_snd_t

Application-defined type for the CongURE state object under test.

Note: Needs to be set within an application-provided congure_impl.h to the state object of the CongURE implementation you want to test.

Definition at line 54 of file test.h.

Function Documentation

◆ congure_test_add_msg()

int congure_test_add_msg	(	int	argc,
		char **	argv
	)

Adds a message from the message pool to the list for cong_report msgs_lost and cong_report msgs_timeout.

Parameters

[in]	argc	Number of `argv`. Needs to be at least 4
[in]	argv	Three arguments are expected. Each call of the command represents an element of the `msgs` list parameter of congure_snd_driver_t::report_msgs_lost() and congure_snd_msg_t::report_msgs_timeout(): `argv[1]` (`msg_send_time`) is expected to be an integer for the `send_time` member of congure_snd_msg_t, `argv[2]` (`msg_size`) is expected to be an integer for the `size` member of congure_snd_msg_t, and `argv[3]` (`msg_resends`) is expected to be a an integer integer for the `resends` member of congure_snd_msg_t.

This function will generate the following JSON objects in STDOUT:

{"success":null}

On success
{"error":"At least 3 arguments `msg_send_time`, `msg_size`,

`msg_resends` expected"}

When argc < 4.
{"error":"`<arg_name>` expected to be integer"}

When argv[i] = "<arg_name>" is expected to be an integer but is not parseable
{"error":"List element pool depleted"}

When called moret than > CONFIG_CONGURE_TEST_LOST_MSG_POOL_SIZE) times without calling cong_msgs_reset in between.

Return values

0	on success.
1	on error.

◆ congure_test_call_init()

int congure_test_call_init	(	int	argc,
		char **	argv
	)

Calls init() method for CongURE state object.

See also: congure_snd_driver_t::init()

Parameters

[in]	argc	Number of `argv`. Needs to be at least 2.
[in]	argv	Command line arguments. `argv[0]` needs to be the command name and `argv[1]` needs to be a hexadecimal integer of format 0xXXXX, representing a pointer to the object used as the `ctx` parameter for `init()`.

This function will generate the following JSON objects in STDOUT on error:

{"error":"State object not set up"}

When congure_test_snd_setup() was not called before calling this command (i.e. the driver member of the state object is NULL).
{"error":"`ctx` argument expected"}

When argc < 2.
{"error":"`ctx` expected to be hex"}

When argv[1] is not parseable as a hexadecimal integer.

Always generates the following JSON object in STDOUT:

{"success": null}

Return values

0	on success.
1	on error.

◆ congure_test_call_inter_msg_interval()

int congure_test_call_inter_msg_interval	(	int	argc,
		char **	argv
	)

Calls inter_msg_interval() method for CongURE state object.

See also: congure_snd_driver_t::inter_msg_interval()

Parameters

[in]	argc	Number of `argv`. Needs to be at least 1.
[in]	argv	Command line arguments. No extra arguments are required except for the command name in `argv[0]`.

This function will generate the following JSON objects in STDOUT:

{"success":X}

On success, with X being replaced with the return value of congure_snd_driver_t::inter_msg_interval().
{"error":"State object not set up"}

When congure_test_snd_setup() was not called before calling this command (i.e. the driver member of the state object is NULL).

Return values

0	on success.
1	on error.

◆ congure_test_call_report()

int congure_test_call_report	(	int	argc,
		char **	argv
	)

Calls one of the report_*() methods for CongURE state object.

See also: congure_snd_driver_t::report_msg_sent(); congure_snd_driver_t::report_msg_discarded(); congure_snd_driver_t::report_msg_timeout(); congure_snd_driver_t::report_msg_lost(); congure_snd_driver_t::report_msg_acked(); congure_snd_driver_t::report_ecn_ce()

Parameters

[in]	argc	Number of `argv`. Needs to be at least 2.
[in]	argv	Command line arguments. `argv[0]` needs to be the command name and `argv[1]` needs to one of the following sub-commands that may require at least one extra arguments: `msg_sent`: `argv[2]` is expected to be an integer for the `msg_size` parameter of congure_snd_driver_t::report_msg_sent() `msg_sent`: `argv[2]` is expected to be an integer for the `msg_size` parameter of congure_snd_driver_t::report_msg_discarded() `msg_timeout`: no arguments are expected, but congure_test_add_msg() should be called a number of times beforehand to add messages that are to be reported timed out. The list of messages is reset after the call. `msg_lost`: no arguments are expected, but congure_test_add_msg() should be called a number of times beforehand to add messages that are to be reported lost. The list of messages is reset after the call. `msg_acked`: congure_test_add_msg() must have been called to add a message for the `msg` parameter of congure_snd_driver_t::report_msg_acked(). `argc` must be 8. The 6 arguments after the sub-command represent members of the `ack` parameter of congure_snd_driver_t::report_msg_acked(): `argv[2]` (`ack_recv_time`) is expected to be a an integer for the `recv_time` member of congure_snd_ack_t, `argv[3]` (`ack_id`) is expected to be a an integer for the `ack_id` member of congure_snd_ack_t, and `argv[4]` (`ack_size`) is expected to be a an integer integer for the `size` member of congure_snd_ack_t. `argv[5]` (`ack_clean`) is expected to be a an integer for the `clean` member of congure_snd_ack_t. If `argv[5]` is `"0"`, `clean` will be set to `false` and to `true` otherwise. `argv[6]` (`ack_wnd`) is expected to be a 16-bit integer for the `wnd` member of congure_snd_ack_t. `argv[7]` (`ack_delay`) is expected to be a 16-bit integer for the `delay` member of congure_snd_ack_t. `ecn_ce`: `argv[2]` is expected to be an integer for the `time` parameter of congure_snd_driver_t::report_ecn_ce()

This function will generate the following JSON objects in STDOUT:

{"success":null}

On success
{"error":"State object not set up"}

When congure_test_snd_setup() was not called before calling this command (i.e. the driver member of the state object is NULL).
{"error":"No report command provided"}

When argc < 2.
{"error":"Unknown command `<command>`"}

When argv[1] = "<command>" is not a known sub-command.
{"error":"`<arg_name>` argument expected"}

When argv[i] = "<arg_name>" is expected but argc <= i.
{"error":"`<arg_name>` expected to be integer"}

When argv[i] = "<arg_name>" is expected to be an integer but is not parseable
{"error":"`<arg_name>` expected not 16 bit wide"}

When argv[i] = "<arg_name>" is expected to be an 16-bit unsigned integer but is is greater than or equal to $2^{16}$
{"error":"At least `<arg_num>` arguments <arglist> expecdted"}

When argc is smaller than expected. <arg_num> provides the number of arguments beyond the sub-command (i.e. argc needs at least to be <arg_num> + 2), with the names of the arguments expected provided in <arg_list> as a comma-seperated list of <arg_name>.
{"error":"Message not initialized"}

When argv[0] in {msg_acked, msgs_lost, msgs_timout} was not called, but no messages where added using congure_test_add_msg().

Return values

0	on success.
1	on error.

◆ congure_test_call_setup()

int congure_test_call_setup	(	int	argc,
		char **	argv
	)

Setup the CongURE state object.

Calls application-defined congure_test_snd_setup()

Parameters

[in]	argc	Number of `argv`. Needs to be at least 1.
[in]	argv	Command line arguments. The command name is expected in `argv[0]`. If `argc` > 1, a integer is expected in `argv[1]` for the `id` parameter of congure_test_snd_setup().

This function will generate the following JSON objects in STDOUT:

{"success": "0x12345678"}

On success, with 0x12345678 being replaced with the memory address of the state object.
{"error":"`id` expected to be integer"}

On error, when argv[1] is not parsable to an unsigned integer.
{"error":"`id` is invalid"}

On error, when argv[1] is a valid unsigned integer but is an unknown value to the application.

Return values

0	on success.
1	on error. Only can happen if `argv[1]` is provided and an invalid or unexpected value.

◆ congure_test_clear_state()

int congure_test_clear_state	(	int	argc,
		char **	argv
	)

Clears the CongURE state object.

Every byte in the state object is set to 0.

Parameters

[in]	argc	Number of `argv`. Needs to be at least 1.
[in]	argv	Command line arguments. No extra arguments are required except for the command name in `argv[0]`.

Always generates the following JSON object in STDOUT:

{"success": null}

Returns: Always 0.

◆ congure_test_get_state()

congure_test_snd_t * congure_test_get_state ( void )

Get the application-defined CongURE state object.

Note: Needs to be defined by the application

Returns: The CongURE state object.

◆ congure_test_msgs_reset()

int congure_test_msgs_reset	(	int	argc,
		char **	argv
	)

Resets the the message pool and messages list for cong_report msgs_lost and cong_report msgs_timeout.

Parameters

[in]	argc	Number of `argv`. Needs to be at least 1.
[in]	argv	Command line arguments. No extra arguments are required except for the command name in `argv[0]`.

Always generates the following JSON object in STDOUT:

{"success": null}

Returns: Always 0.

◆ congure_test_snd_setup()

int congure_test_snd_setup	(	void congure_test_snd_t *	c,
		unsigned	id
	)

Setup the application-defined CongURE state object under test.

Note: Needs to be defined by the application and declare it within an application-provided congure_impl.h

Parameters

[in,out]	c	The CongURE state object under test. May not be NULL.
[in]	id	And application-specific ID that may identify different setup parameters, e.g. a set of different constants to use when setting up `c`. If not applicable to your application just ignore `id`.

Return values

0	on success
-1	when `id` is not ignored and is an unknown value to the application.

Detailed Description

Files

Macros

Typedefs

Functions

Macro Definition Documentation

◆ CONFIG_CONGURE_TEST_LOST_MSG_POOL_SIZE

Typedef Documentation

◆ congure_test_snd_t

Function Documentation

◆ congure_test_add_msg()

◆ congure_test_call_init()

◆ congure_test_call_inter_msg_interval()

◆ congure_test_call_report()

◆ congure_test_call_setup()

◆ congure_test_clear_state()

◆ congure_test_get_state()

◆ congure_test_msgs_reset()

◆ congure_test_snd_setup()