CongURE test framework shell commands

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.

congure_snd_t congure_test_snd_t
Application-defined type for the CongURE state object under test.
Definition: test.h:54
int congure_test_snd_setup(void congure_test_snd_t *c, unsigned id)
Setup the application-defined CongURE state object under test.
State object for CongURE Reno.
Definition: reno.h:172
Base state object for CongURE implementations.
Definition: congure.h:51

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. More...
 

Typedefs

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

Functions

int congure_test_snd_setup (void congure_test_snd_t *c, unsigned id)
 Setup the application-defined CongURE state object under test. More...
 
congure_test_snd_tcongure_test_get_state (void)
 Get the application-defined CongURE state object. More...
 
int congure_test_clear_state (int argc, char **argv)
 Clears the CongURE state object. More...
 
int congure_test_call_setup (int argc, char **argv)
 Setup the CongURE state object. More...
 
int congure_test_call_init (int argc, char **argv)
 Calls init() method for CongURE state object. More...
 
int congure_test_call_inter_msg_interval (int argc, char **argv)
 Calls inter_msg_interval() method for CongURE state object. More...
 
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. More...
 
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. More...
 
int congure_test_call_report (int argc, char **argv)
 Calls one of the report_*() methods for CongURE state object. More...
 

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

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]argcNumber of argv. Needs to be at least 4
[in]argvThree 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
0on success.
1on 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]argcNumber of argv. Needs to be at least 2.
[in]argvCommand 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
0on success.
1on 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]argcNumber of argv. Needs to be at least 1.
[in]argvCommand 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:

Return values
0on success.
1on 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]argcNumber of argv. Needs to be at least 2.
[in]argvCommand 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:

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
0on success.
1on 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]argcNumber of argv. Needs to be at least 1.
[in]argvCommand 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
0on success.
1on 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]argcNumber of argv. Needs to be at least 1.
[in]argvCommand 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]argcNumber of argv. Needs to be at least 1.
[in]argvCommand 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]cThe CongURE state object under test. May not be NULL.
[in]idAnd 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
0on success
-1when id is not ignored and is an unknown value to the application.