def dpdk_testpmd_stop(node):
"""Stop DPDK testpmd app on node.
:param node: Node to stop testpmd on.
:type node: dict
:returns: nothing
"""
ssh = SSH()
ssh.connect(node)
cmd = "/stop-testpmd.sh"
exec_cmd_no_error(node, cmd, sudo=True)
ssh.disconnect(node)
def dpdk_testpmd_start(node, **kwargs):
"""Start DPDK testpmd app on VM node.
:param node: VM Node to start testpmd on.
:param args: Key-value testpmd parameters.
:type node: dict
:type args: dict
:returns: nothing
"""
eal_options = DpdkUtil.get_eal_options(**kwargs)
pmd_options = DpdkUtil.get_pmd_options(**kwargs)
ssh = SSH()
ssh.connect(node)
cmd = "/start-testpmd.sh {0} {1}".format(eal_options, pmd_options)
exec_cmd_no_error(node, cmd, sudo=True)
ssh.disconnect(node)
def install_vpp_on_all_duts(nodes, vpp_pkg_dir, vpp_rpm_pkgs,
vpp_deb_pkgs):
"""Install VPP on all DUT nodes.
:param nodes: Nodes in the topology.
:param vpp_pkg_dir: Path to directory where VPP packages are stored.
:param vpp_rpm_pkgs: List of VPP rpm packages to be installed.
:param vpp_deb_pkgs: List of VPP deb packages to be installed.
:type nodes: dict
:type vpp_pkg_dir: str
:type vpp_rpm_pkgs: list
:type vpp_deb_pkgs: list
:raises RuntimeError: If failed to remove or install VPP.
"""
for node in nodes.values():
if node['type'] == NodeType.DUT:
logger.debug("Installing VPP on node {0}".format(node['host']))
ssh = SSH()
ssh.connect(node)
cmd = "[[ -f /etc/redhat-release ]]"
return_code, _, _ = ssh.exec_command(cmd)
if not int(return_code):
# workaroud - uninstall existing vpp installation until
# start-testcase script is updated on all virl servers
rpm_pkgs_remove = "vpp*"
cmd_u = 'yum -y remove "{0}"'.format(rpm_pkgs_remove)
r_rcode, _, r_err = ssh.exec_command_sudo(cmd_u,
timeout=90)
if int(r_rcode):
raise RuntimeError(
'Failed to remove previous VPP'
'installation on host {0}:\n{1}'.format(
node['host'], r_err))
rpm_pkgs = "*.rpm ".join(
str(vpp_pkg_dir + pkg)
for pkg in vpp_rpm_pkgs) + "*.rpm"
cmd_i = "rpm -ivh {0}".format(rpm_pkgs)
ret_code, _, err = ssh.exec_command_sudo(cmd_i, timeout=90)
if int(ret_code):
raise RuntimeError('Failed to install VPP on host {0}:'
'\n{1}'.format(node['host'], err))
else:
ssh.exec_command_sudo("rpm -qai vpp*")
logger.info("VPP installed on node {0}".format(
node['host']))
else:
# workaroud - uninstall existing vpp installation until
# start-testcase script is updated on all virl servers
deb_pkgs_remove = "vpp*"
cmd_u = 'apt-get purge -y "{0}"'.format(deb_pkgs_remove)
r_rcode, _, r_err = ssh.exec_command_sudo(cmd_u,
timeout=90)
if int(r_rcode):
raise RuntimeError(
'Failed to remove previous VPP'
'installation on host {0}:\n{1}'.format(
node['host'], r_err))
deb_pkgs = "*.deb ".join(
str(vpp_pkg_dir + pkg)
for pkg in vpp_deb_pkgs) + "*.deb"
cmd_i = "dpkg -i --force-all {0}".format(deb_pkgs)
ret_code, _, err = ssh.exec_command_sudo(cmd_i, timeout=90)
if int(ret_code):
raise RuntimeError('Failed to install VPP on host {0}:'
'\n{1}'.format(node['host'], err))
else:
ssh.exec_command_sudo("dpkg -l | grep vpp")
logger.info("VPP installed on node {0}".format(
node['host']))
ssh.disconnect(node)
class PapiExecutor:
"""Contains methods for executing VPP Python API commands on DUTs.
TODO: Remove .add step, make get_stats accept paths directly.
This class processes only one type of VPP PAPI methods: vpp-stats.
The recommended ways of use are (examples):
path = ['^/if', '/err/ip4-input', '/sys/node/ip4-input']
with PapiExecutor(node) as papi_exec:
stats = papi_exec.add(api_name='vpp-stats', path=path).get_stats()
print('RX interface core 0, sw_if_index 0:\n{0}'.\
format(stats[0]['/if/rx'][0][0]))
or
path_1 = ['^/if', ]
path_2 = ['^/if', '/err/ip4-input', '/sys/node/ip4-input']
with PapiExecutor(node) as papi_exec:
stats = papi_exec.add('vpp-stats', path=path_1).\
add('vpp-stats', path=path_2).get_stats()
print('RX interface core 0, sw_if_index 0:\n{0}'.\
format(stats[1]['/if/rx'][0][0]))
Note: In this case, when PapiExecutor method 'add' is used:
- its parameter 'csit_papi_command' is used only to keep information
that vpp-stats are requested. It is not further processed but it is
included in the PAPI history this way:
vpp-stats(path=['^/if', '/err/ip4-input', '/sys/node/ip4-input'])
Always use csit_papi_command="vpp-stats" if the VPP PAPI method
is "stats".
- the second parameter must be 'path' as it is used by PapiExecutor
method 'add'.
"""
def __init__(self, node):
"""Initialization.
:param node: Node to run command(s) on.
:type node: dict
"""
# Node to run command(s) on.
self._node = node
# The list of PAPI commands to be executed on the node.
self._api_command_list = list()
self._ssh = SSH()
def __enter__(self):
try:
self._ssh.connect(self._node)
except IOError:
raise RuntimeError(
f"Cannot open SSH connection to host {self._node[u'host']} "
f"to execute PAPI command(s)")
return self
def __exit__(self, exc_type, exc_val, exc_tb):
self._ssh.disconnect(self._node)
def add(self, csit_papi_command=u"vpp-stats", history=True, **kwargs):
"""Add next command to internal command list; return self.
The argument name 'csit_papi_command' must be unique enough as it cannot
be repeated in kwargs.
The kwargs dict is deep-copied, so it is safe to use the original
with partial modifications for subsequent commands.
:param csit_papi_command: VPP API command.
:param history: Enable/disable adding command to PAPI command history.
:param kwargs: Optional key-value arguments.
:type csit_papi_command: str
:type history: bool
:type kwargs: dict
:returns: self, so that method chaining is possible.
:rtype: PapiExecutor
"""
if history:
PapiHistory.add_to_papi_history(self._node, csit_papi_command,
**kwargs)
self._api_command_list.append(
dict(api_name=csit_papi_command, api_args=copy.deepcopy(kwargs)))
return self
def get_stats(self,
err_msg=u"Failed to get statistics.",
timeout=120,
socket=Constants.SOCKSTAT_PATH):
"""Get VPP Stats from VPP Python API.
:param err_msg: The message used if the PAPI command(s) execution fails.
:param timeout: Timeout in seconds.
:param socket: Path to Stats socket to tunnel to.
:type err_msg: str
:type timeout: int
:type socket: str
:returns: Requested VPP statistics.
:rtype: list of dict
"""
paths = [cmd[u"api_args"][u"path"] for cmd in self._api_command_list]
self._api_command_list = list()
stdout = self._execute_papi(paths,
method=u"stats",
err_msg=err_msg,
timeout=timeout,
socket=socket)
return json.loads(stdout)
@staticmethod
def _process_api_data(api_d):
"""Process API data for smooth converting to JSON string.
Apply binascii.hexlify() method for string values.
:param api_d: List of APIs with their arguments.
:type api_d: list
:returns: List of APIs with arguments pre-processed for JSON.
:rtype: list
"""
def process_value(val):
"""Process value.
:param val: Value to be processed.
:type val: object
:returns: Processed value.
:rtype: dict or str or int
"""
if isinstance(val, dict):
for val_k, val_v in val.items():
val[str(val_k)] = process_value(val_v)
retval = val
elif isinstance(val, list):
for idx, val_l in enumerate(val):
val[idx] = process_value(val_l)
retval = val
else:
retval = val.encode().hex() if isinstance(val, str) else val
return retval
api_data_processed = list()
for api in api_d:
api_args_processed = dict()
for a_k, a_v in api[u"api_args"].items():
api_args_processed[str(a_k)] = process_value(a_v)
api_data_processed.append(
dict(api_name=api[u"api_name"], api_args=api_args_processed))
return api_data_processed
def _execute_papi(self,
api_data,
method=u"request",
err_msg=u"",
timeout=120,
socket=None):
"""Execute PAPI command(s) on remote node and store the result.
:param api_data: List of APIs with their arguments.
:param method: VPP Python API method. Supported methods are: 'request',
'dump' and 'stats'.
:param err_msg: The message used if the PAPI command(s) execution fails.
:param timeout: Timeout in seconds.
:type api_data: list
:type method: str
:type err_msg: str
:type timeout: int
:returns: Stdout from remote python utility, to be parsed by caller.
:rtype: str
:raises SSHTimeout: If PAPI command(s) execution has timed out.
:raises RuntimeError: If PAPI executor failed due to another reason.
:raises AssertionError: If PAPI command(s) execution has failed.
"""
if not api_data:
raise RuntimeError(u"No API data provided.")
json_data = json.dumps(api_data) \
if method in (u"stats", u"stats_request") \
else json.dumps(self._process_api_data(api_data))
sock = f" --socket {socket}" if socket else u""
cmd = f"{Constants.REMOTE_FW_DIR}/{Constants.RESOURCES_PAPI_PROVIDER}" \
f" --method {method} --data '{json_data}'{sock}"
try:
ret_code, stdout, _ = self._ssh.exec_command_sudo(
cmd=cmd, timeout=timeout, log_stdout_err=False)
# TODO: Fail on non-empty stderr?
except SSHTimeout:
logger.error(f"PAPI command(s) execution timeout on host "
f"{self._node[u'host']}:\n{api_data}")
raise
except Exception as exc:
raise RuntimeError(
f"PAPI command(s) execution on host {self._node[u'host']} "
f"failed: {api_data}") from exc
if ret_code != 0:
raise AssertionError(err_msg)
return stdout
def dpdk_testpmd_start(node, **args):
"""Start DPDK testpmd app on VM node.
:param node: VM Node to start testpmd on.
:param args: List of testpmd parameters.
:type node: dict
:type args: dict
:return: nothing
"""
# Set the hexadecimal bitmask of the cores to run on.
eal_coremask = '-c {} '.format(args['eal_coremask'])\
if args.get('eal_coremask', '') else ''
# Set master core.
eal_master_core = '--master-lcore 0 '
# Set the number of memory channels to use.
eal_mem_channels = '-n {} '.format(args['eal_mem_channels'])\
if args.get('eal_mem_channels', '') else ''
# Set the memory to allocate on specific sockets (comma separated).
eal_socket_mem = '--socket-mem {} '.format(args['eal_socket_mem'])\
if args.get('eal_socket_mem', '') else ''
# Load an external driver. Multiple -d options are allowed.
eal_driver = '-d /usr/lib/librte_pmd_virtio.so '
# Set the forwarding mode: io, mac, mac_retry, mac_swap, flowgen,
# rxonly, txonly, csum, icmpecho, ieee1588
pmd_fwd_mode = '--forward-mode={} '.format(args['pmd_fwd_mode'])\
if args.get('pmd_fwd_mode', '') else ''
# Set the number of packets per burst to N.
pmd_burst = '--burst=64 '
# Set the number of descriptors in the TX rings to N.
pmd_txd = '--txd={} '.format(args.get('pmd_txd', '256')) \
if args.get('pmd_txd', '256') else ''
# Set the number of descriptors in the RX rings to N.
pmd_rxd = '--rxd={} '.format(args.get('pmd_rxd', '256')) \
if args.get('pmd_rxd', '256') else ''
# Set the number of queues in the TX to N.
pmd_txq = '--txq={} '.format(args.get('pmd_txq', '1')) \
if args.get('pmd_txq', '1') else ''
# Set the number of queues in the RX to N.
pmd_rxq = '--rxq={} '.format(args.get('pmd_rxq', '1')) \
if args.get('pmd_rxq', '1') else ''
# Set the hexadecimal bitmask of TX queue flags.
pmd_txqflags = '--txqflags=0xf00 '
# Set the number of mbufs to be allocated in the mbuf pools.
pmd_total_num_mbufs = '--total-num-mbufs={} '.format(\
args['pmd_num_mbufs']) if args.get('pmd_num_mbufs', '') else ''
# Set the hexadecimal bitmask of the ports for forwarding.
pmd_portmask = '--portmask={} '.format(args['pmd_portmask'])\
if args.get('pmd_portmask', '') else ''
# Disable hardware VLAN.
pmd_disable_hw_vlan = '--disable-hw-vlan '\
if args.get('pmd_disable_hw_vlan', '') else ''
# Disable RSS (Receive Side Scaling).
pmd_disable_rss = '--disable-rss '\
if args.get('pmd_disable_rss', '') else ''
# Set the MAC address XX:XX:XX:XX:XX:XX of the peer port N
pmd_eth_peer_0 = '--eth-peer={} '.format(args['pmd_eth_peer_0'])\
if args.get('pmd_eth_peer_0', '') else ''
pmd_eth_peer_1 = '--eth-peer={} '.format(args['pmd_eth_peer_1'])\
if args.get('pmd_eth_peer_1', '') else ''
# Set the number of forwarding cores based on coremask.
pmd_nb_cores = '--nb-cores={} '.format(\
bin(int(args['eal_coremask'], 0)).count('1')-1)\
if args.get('eal_coremask', '') else ''
eal_options = '-v '\
+ eal_coremask\
+ eal_master_core\
+ eal_mem_channels\
+ eal_socket_mem\
+ eal_driver
pmd_options = '-- '\
+ pmd_fwd_mode\
+ pmd_burst\
+ pmd_txd\
+ pmd_rxd\
+ pmd_txq\
+ pmd_rxq\
+ pmd_txqflags\
+ pmd_total_num_mbufs\
+ pmd_portmask\
+ pmd_disable_hw_vlan\
+ pmd_disable_rss\
+ pmd_eth_peer_0\
+ pmd_eth_peer_1\
+ pmd_nb_cores
ssh = SSH()
ssh.connect(node)
cmd = "/start-testpmd.sh {0} {1}".format(eal_options, pmd_options)
exec_cmd_no_error(node, cmd, sudo=True)
ssh.disconnect(node)
class PapiExecutor(object):
"""Contains methods for executing VPP Python API commands on DUTs.
Note: Use only with "with" statement, e.g.:
with PapiExecutor(node) as papi_exec:
replies = papi_exec.add('show_version').get_replies(err_msg)
This class processes three classes of VPP PAPI methods:
1. simple request / reply: method='request',
2. dump functions: method='dump',
3. vpp-stats: method='stats'.
The recommended ways of use are (examples):
1. Simple request / reply
a. One request with no arguments:
with PapiExecutor(node) as papi_exec:
reply = papi_exec.add('show_version').get_reply()
b. Three requests with arguments, the second and the third ones are the same
but with different arguments.
with PapiExecutor(node) as papi_exec:
replies = papi_exec.add(cmd1, **args1).add(cmd2, **args2).\
add(cmd2, **args3).get_replies(err_msg)
2. Dump functions
cmd = 'sw_interface_rx_placement_dump'
with PapiExecutor(node) as papi_exec:
details = papi_exec.add(cmd, sw_if_index=ifc['vpp_sw_index']).\
get_details(err_msg)
3. vpp-stats
path = ['^/if', '/err/ip4-input', '/sys/node/ip4-input']
with PapiExecutor(node) as papi_exec:
stats = papi_exec.add(api_name='vpp-stats', path=path).get_stats()
print('RX interface core 0, sw_if_index 0:\n{0}'.\
format(stats[0]['/if/rx'][0][0]))
or
path_1 = ['^/if', ]
path_2 = ['^/if', '/err/ip4-input', '/sys/node/ip4-input']
with PapiExecutor(node) as papi_exec:
stats = papi_exec.add('vpp-stats', path=path_1).\
add('vpp-stats', path=path_2).get_stats()
print('RX interface core 0, sw_if_index 0:\n{0}'.\
format(stats[1]['/if/rx'][0][0]))
Note: In this case, when PapiExecutor method 'add' is used:
- its parameter 'csit_papi_command' is used only to keep information
that vpp-stats are requested. It is not further processed but it is
included in the PAPI history this way:
vpp-stats(path=['^/if', '/err/ip4-input', '/sys/node/ip4-input'])
Always use csit_papi_command="vpp-stats" if the VPP PAPI method
is "stats".
- the second parameter must be 'path' as it is used by PapiExecutor
method 'add'.
"""
def __init__(self, node):
"""Initialization.
:param node: Node to run command(s) on.
:type node: dict
"""
# Node to run command(s) on.
self._node = node
# The list of PAPI commands to be executed on the node.
self._api_command_list = list()
self._ssh = SSH()
def __enter__(self):
try:
self._ssh.connect(self._node)
except IOError:
raise RuntimeError(
"Cannot open SSH connection to host {host} to "
"execute PAPI command(s)".format(host=self._node["host"]))
return self
def __exit__(self, exc_type, exc_val, exc_tb):
self._ssh.disconnect(self._node)
def add(self, csit_papi_command="vpp-stats", history=True, **kwargs):
"""Add next command to internal command list; return self.
The argument name 'csit_papi_command' must be unique enough as it cannot
be repeated in kwargs.
:param csit_papi_command: VPP API command.
:param history: Enable/disable adding command to PAPI command history.
:param kwargs: Optional key-value arguments.
:type csit_papi_command: str
:type history: bool
:type kwargs: dict
:returns: self, so that method chaining is possible.
:rtype: PapiExecutor
"""
if history:
PapiHistory.add_to_papi_history(self._node, csit_papi_command,
**kwargs)
self._api_command_list.append(
dict(api_name=csit_papi_command, api_args=kwargs))
return self
def get_stats(self, err_msg="Failed to get statistics.", timeout=120):
"""Get VPP Stats from VPP Python API.
:param err_msg: The message used if the PAPI command(s) execution fails.
:param timeout: Timeout in seconds.
:type err_msg: str
:type timeout: int
:returns: Requested VPP statistics.
:rtype: list of dict
"""
paths = [cmd['api_args']['path'] for cmd in self._api_command_list]
self._api_command_list = list()
stdout = self._execute_papi(paths,
method='stats',
err_msg=err_msg,
timeout=timeout)
return json.loads(stdout)
def get_replies(self, err_msg="Failed to get replies.", timeout=120):
"""Get replies from VPP Python API.
The replies are parsed into dict-like objects,
"retval" field is guaranteed to be zero on success.
:param err_msg: The message used if the PAPI command(s) execution fails.
:param timeout: Timeout in seconds.
:type err_msg: str
:type timeout: int
:returns: Responses, dict objects with fields due to API and "retval".
:rtype: list of dict
:raises RuntimeError: If retval is nonzero, parsing or ssh error.
"""
return self._execute(method='request',
err_msg=err_msg,
timeout=timeout)
def get_reply(self, err_msg="Failed to get reply.", timeout=120):
"""Get reply from VPP Python API.
The reply is parsed into dict-like object,
"retval" field is guaranteed to be zero on success.
TODO: Discuss exception types to raise, unify with inner methods.
:param err_msg: The message used if the PAPI command(s) execution fails.
:param timeout: Timeout in seconds.
:type err_msg: str
:type timeout: int
:returns: Response, dict object with fields due to API and "retval".
:rtype: dict
:raises AssertionError: If retval is nonzero, parsing or ssh error.
"""
replies = self.get_replies(err_msg=err_msg, timeout=timeout)
if len(replies) != 1:
raise RuntimeError("Expected single reply, got {replies!r}".format(
replies=replies))
return replies[0]
def get_sw_if_index(self, err_msg="Failed to get reply.", timeout=120):
"""Get sw_if_index from reply from VPP Python API.
Frequently, the caller is only interested in sw_if_index field
of the reply, this wrapper makes such call sites shorter.
TODO: Discuss exception types to raise, unify with inner methods.
:param err_msg: The message used if the PAPI command(s) execution fails.
:param timeout: Timeout in seconds.
:type err_msg: str
:type timeout: int
:returns: Response, sw_if_index value of the reply.
:rtype: int
:raises AssertionError: If retval is nonzero, parsing or ssh error.
"""
return self.get_reply(err_msg=err_msg, timeout=timeout)["sw_if_index"]
def get_details(self, err_msg="Failed to get dump details.", timeout=120):
"""Get dump details from VPP Python API.
The details are parsed into dict-like objects.
The number of details per single dump command can vary,
and all association between details and dumps is lost,
so if you care about the association (as opposed to
logging everything at once for debugging purposes),
it is recommended to call get_details for each dump (type) separately.
:param err_msg: The message used if the PAPI command(s) execution fails.
:param timeout: Timeout in seconds.
:type err_msg: str
:type timeout: int
:returns: Details, dict objects with fields due to API without "retval".
:rtype: list of dict
"""
return self._execute(method='dump', err_msg=err_msg, timeout=timeout)
@staticmethod
def dump_and_log(node, cmds):
"""Dump and log requested information, return None.
:param node: DUT node.
:param cmds: Dump commands to be executed.
:type node: dict
:type cmds: list of str
"""
with PapiExecutor(node) as papi_exec:
for cmd in cmds:
details = papi_exec.add(cmd).get_details()
logger.debug("{cmd}:\n{details}".format(
cmd=cmd, details=pformat(details)))
@staticmethod
def run_cli_cmd(node, cmd, log=True):
"""Run a CLI command as cli_inband, return the "reply" field of reply.
Optionally, log the field value.
:param node: Node to run command on.
:param cmd: The CLI command to be run on the node.
:param log: If True, the response is logged.
:type node: dict
:type cmd: str
:type log: bool
:returns: CLI output.
:rtype: str
"""
cli = 'cli_inband'
args = dict(cmd=cmd)
err_msg = "Failed to run 'cli_inband {cmd}' PAPI command on host " \
"{host}".format(host=node['host'], cmd=cmd)
with PapiExecutor(node) as papi_exec:
reply = papi_exec.add(cli, **args).get_reply(err_msg)["reply"]
if log:
logger.info("{cmd}:\n{reply}".format(cmd=cmd, reply=reply))
return reply
@staticmethod
def _process_api_data(api_d):
"""Process API data for smooth converting to JSON string.
Apply binascii.hexlify() method for string values.
:param api_d: List of APIs with their arguments.
:type api_d: list
:returns: List of APIs with arguments pre-processed for JSON.
:rtype: list
"""
def process_value(val):
"""Process value.
:param val: Value to be processed.
:type val: object
:returns: Processed value.
:rtype: dict or str or int
"""
if isinstance(val, dict):
for val_k, val_v in val.iteritems():
val[str(val_k)] = process_value(val_v)
return val
elif isinstance(val, list):
for idx, val_l in enumerate(val):
val[idx] = process_value(val_l)
return val
else:
return binascii.hexlify(val) if isinstance(val, str) else val
api_data_processed = list()
for api in api_d:
api_args_processed = dict()
for a_k, a_v in api["api_args"].iteritems():
api_args_processed[str(a_k)] = process_value(a_v)
api_data_processed.append(
dict(api_name=api["api_name"], api_args=api_args_processed))
return api_data_processed
@staticmethod
def _revert_api_reply(api_r):
"""Process API reply / a part of API reply.
Apply binascii.unhexlify() method for unicode values.
TODO: Implement complex solution to process of replies.
:param api_r: API reply.
:type api_r: dict
:returns: Processed API reply / a part of API reply.
:rtype: dict
"""
def process_value(val):
"""Process value.
:param val: Value to be processed.
:type val: object
:returns: Processed value.
:rtype: dict or str or int
"""
if isinstance(val, dict):
for val_k, val_v in val.iteritems():
val[str(val_k)] = process_value(val_v)
return val
elif isinstance(val, list):
for idx, val_l in enumerate(val):
val[idx] = process_value(val_l)
return val
elif isinstance(val, unicode):
return binascii.unhexlify(val)
else:
return val
reply_dict = dict()
reply_value = dict()
for reply_key, reply_v in api_r.iteritems():
for a_k, a_v in reply_v.iteritems():
reply_value[a_k] = process_value(a_v)
reply_dict[reply_key] = reply_value
return reply_dict
def _process_reply(self, api_reply):
"""Process API reply.
:param api_reply: API reply.
:type api_reply: dict or list of dict
:returns: Processed API reply.
:rtype: list or dict
"""
if isinstance(api_reply, list):
reverted_reply = [self._revert_api_reply(a_r) for a_r in api_reply]
else:
reverted_reply = self._revert_api_reply(api_reply)
return reverted_reply
def _execute_papi(self,
api_data,
method='request',
err_msg="",
timeout=120):
"""Execute PAPI command(s) on remote node and store the result.
:param api_data: List of APIs with their arguments.
:param method: VPP Python API method. Supported methods are: 'request',
'dump' and 'stats'.
:param err_msg: The message used if the PAPI command(s) execution fails.
:param timeout: Timeout in seconds.
:type api_data: list
:type method: str
:type err_msg: str
:type timeout: int
:returns: Stdout from remote python utility, to be parsed by caller.
:rtype: str
:raises SSHTimeout: If PAPI command(s) execution has timed out.
:raises RuntimeError: If PAPI executor failed due to another reason.
:raises AssertionError: If PAPI command(s) execution has failed.
"""
if not api_data:
raise RuntimeError("No API data provided.")
json_data = json.dumps(api_data) \
if method in ("stats", "stats_request") \
else json.dumps(self._process_api_data(api_data))
cmd = "{fw_dir}/{papi_provider} --method {method} --data '{json}'".\
format(
fw_dir=Constants.REMOTE_FW_DIR, method=method, json=json_data,
papi_provider=Constants.RESOURCES_PAPI_PROVIDER)
try:
ret_code, stdout, _ = self._ssh.exec_command_sudo(
cmd=cmd, timeout=timeout, log_stdout_err=False)
# TODO: Fail on non-empty stderr?
except SSHTimeout:
logger.error("PAPI command(s) execution timeout on host {host}:"
"\n{apis}".format(host=self._node["host"],
apis=api_data))
raise
except Exception as exc:
raise_from(
RuntimeError("PAPI command(s) execution on host {host} "
"failed: {apis}".format(host=self._node["host"],
apis=api_data)), exc)
if ret_code != 0:
raise AssertionError(err_msg)
return stdout
def _execute(self, method='request', err_msg="", timeout=120):
"""Turn internal command list into data and execute; return replies.
This method also clears the internal command list.
IMPORTANT!
Do not use this method in L1 keywords. Use:
- get_stats()
- get_replies()
- get_details()
:param method: VPP Python API method. Supported methods are: 'request',
'dump' and 'stats'.
:param err_msg: The message used if the PAPI command(s) execution fails.
:param timeout: Timeout in seconds.
:type method: str
:type err_msg: str
:type timeout: int
:returns: Papi responses parsed into a dict-like object,
with field due to API or stats hierarchy.
:rtype: list of dict
:raises KeyError: If the reply is not correct.
"""
local_list = self._api_command_list
# Clear first as execution may fail.
self._api_command_list = list()
stdout = self._execute_papi(local_list,
method=method,
err_msg=err_msg,
timeout=timeout)
replies = list()
try:
json_data = json.loads(stdout)
except ValueError as err:
raise_from(RuntimeError(err_msg), err)
for data in json_data:
if method == "request":
api_reply = self._process_reply(data["api_reply"])
# api_reply contains single key, *_reply.
obj = api_reply.values()[0]
retval = obj["retval"]
if retval != 0:
# TODO: What exactly to log and raise here?
err = AssertionError("Got retval {rv!r}".format(rv=retval))
raise_from(AssertionError(err_msg), err, level="INFO")
replies.append(obj)
elif method == "dump":
api_reply = self._process_reply(data["api_reply"])
# api_reply is a list where item contas single key, *_details.
for item in api_reply:
obj = item.values()[0]
replies.append(obj)
else:
# TODO: Implement support for stats.
raise RuntimeError(
"Unsuported method {method}".format(method=method))
# TODO: Make logging optional?
logger.debug("PAPI replies: {replies}".format(replies=replies))
return replies
class PapiExecutor(object):
"""Contains methods for executing VPP Python API commands on DUTs.
Note: Use only with "with" statement, e.g.:
with PapiExecutor(node) as papi_exec:
papi_resp = papi_exec.add('show_version').get_replies(err_msg)
This class processes three classes of VPP PAPI methods:
1. simple request / reply: method='request',
2. dump functions: method='dump',
3. vpp-stats: method='stats'.
The recommended ways of use are (examples):
1. Simple request / reply
a. One request with no arguments:
with PapiExecutor(node) as papi_exec:
data = papi_exec.add('show_version').get_replies().\
verify_reply()
b. Three requests with arguments, the second and the third ones are the same
but with different arguments.
with PapiExecutor(node) as papi_exec:
data = papi_exec.add(cmd1, **args1).add(cmd2, **args2).\
add(cmd2, **args3).get_replies(err_msg).verify_replies()
2. Dump functions
cmd = 'sw_interface_rx_placement_dump'
with PapiExecutor(node) as papi_exec:
papi_resp = papi_exec.add(cmd, sw_if_index=ifc['vpp_sw_index']).\
get_dump(err_msg)
3. vpp-stats
path = ['^/if', '/err/ip4-input', '/sys/node/ip4-input']
with PapiExecutor(node) as papi_exec:
data = papi_exec.add(api_name='vpp-stats', path=path).get_stats()
print('RX interface core 0, sw_if_index 0:\n{0}'.\
format(data[0]['/if/rx'][0][0]))
or
path_1 = ['^/if', ]
path_2 = ['^/if', '/err/ip4-input', '/sys/node/ip4-input']
with PapiExecutor(node) as papi_exec:
data = papi_exec.add('vpp-stats', path=path_1).\
add('vpp-stats', path=path_2).get_stats()
print('RX interface core 0, sw_if_index 0:\n{0}'.\
format(data[1]['/if/rx'][0][0]))
Note: In this case, when PapiExecutor method 'add' is used:
- its parameter 'csit_papi_command' is used only to keep information
that vpp-stats are requested. It is not further processed but it is
included in the PAPI history this way:
vpp-stats(path=['^/if', '/err/ip4-input', '/sys/node/ip4-input'])
Always use csit_papi_command="vpp-stats" if the VPP PAPI method
is "stats".
- the second parameter must be 'path' as it is used by PapiExecutor
method 'add'.
"""
def __init__(self, node):
"""Initialization.
:param node: Node to run command(s) on.
:type node: dict
"""
# Node to run command(s) on.
self._node = node
# The list of PAPI commands to be executed on the node.
self._api_command_list = list()
self._ssh = SSH()
def __enter__(self):
try:
self._ssh.connect(self._node)
except IOError:
raise RuntimeError(
"Cannot open SSH connection to host {host} to "
"execute PAPI command(s)".format(host=self._node["host"]))
return self
def __exit__(self, exc_type, exc_val, exc_tb):
self._ssh.disconnect(self._node)
def add(self, csit_papi_command="vpp-stats", history=True, **kwargs):
"""Add next command to internal command list; return self.
The argument name 'csit_papi_command' must be unique enough as it cannot
be repeated in kwargs.
:param csit_papi_command: VPP API command.
:param history: Enable/disable adding command to PAPI command history.
:param kwargs: Optional key-value arguments.
:type csit_papi_command: str
:type history: bool
:type kwargs: dict
:returns: self, so that method chaining is possible.
:rtype: PapiExecutor
"""
if history:
PapiHistory.add_to_papi_history(self._node, csit_papi_command,
**kwargs)
self._api_command_list.append(
dict(api_name=csit_papi_command, api_args=kwargs))
return self
def get_stats(self, err_msg="Failed to get statistics.", timeout=120):
"""Get VPP Stats from VPP Python API.
:param err_msg: The message used if the PAPI command(s) execution fails.
:param timeout: Timeout in seconds.
:type err_msg: str
:type timeout: int
:returns: Requested VPP statistics.
:rtype: list
"""
paths = [cmd['api_args']['path'] for cmd in self._api_command_list]
self._api_command_list = list()
stdout, _ = self._execute_papi(paths,
method='stats',
err_msg=err_msg,
timeout=timeout)
return json.loads(stdout)
def get_stats_reply(self,
err_msg="Failed to get statistics.",
timeout=120):
"""Get VPP Stats reply from VPP Python API.
:param err_msg: The message used if the PAPI command(s) execution fails.
:param timeout: Timeout in seconds.
:type err_msg: str
:type timeout: int
:returns: Requested VPP statistics.
:rtype: list
"""
args = self._api_command_list[0]['api_args']
self._api_command_list = list()
stdout, _ = self._execute_papi(args,
method='stats_request',
err_msg=err_msg,
timeout=timeout)
return json.loads(stdout)
def get_replies(self,
err_msg="Failed to get replies.",
process_reply=True,
ignore_errors=False,
timeout=120):
"""Get reply/replies from VPP Python API.
:param err_msg: The message used if the PAPI command(s) execution fails.
:param process_reply: Process PAPI reply if True.
:param ignore_errors: If true, the errors in the reply are ignored.
:param timeout: Timeout in seconds.
:type err_msg: str
:type process_reply: bool
:type ignore_errors: bool
:type timeout: int
:returns: Papi response including: papi reply, stdout, stderr and
return code.
:rtype: PapiResponse
"""
return self._execute(method='request',
process_reply=process_reply,
ignore_errors=ignore_errors,
err_msg=err_msg,
timeout=timeout)
def get_dump(self,
err_msg="Failed to get dump.",
process_reply=True,
ignore_errors=False,
timeout=120):
"""Get dump from VPP Python API.
:param err_msg: The message used if the PAPI command(s) execution fails.
:param process_reply: Process PAPI reply if True.
:param ignore_errors: If true, the errors in the reply are ignored.
:param timeout: Timeout in seconds.
:type err_msg: str
:type process_reply: bool
:type ignore_errors: bool
:type timeout: int
:returns: Papi response including: papi reply, stdout, stderr and
return code.
:rtype: PapiResponse
"""
return self._execute(method='dump',
process_reply=process_reply,
ignore_errors=ignore_errors,
err_msg=err_msg,
timeout=timeout)
@staticmethod
def dump_and_log(node, cmds):
"""Dump and log requested information.
:param node: DUT node.
:param cmds: Dump commands to be executed.
:type node: dict
:type cmds: list
"""
with PapiExecutor(node) as papi_exec:
for cmd in cmds:
dump = papi_exec.add(cmd).get_dump()
logger.debug("{cmd}:\n{data}".format(
cmd=cmd, data=pformat(dump.reply[0]["api_reply"])))
@staticmethod
def run_cli_cmd(node, cmd, log=True):
"""Run a CLI command.
:param node: Node to run command on.
:param cmd: The CLI command to be run on the node.
:param log: If True, the response is logged.
:type node: dict
:type cmd: str
:type log: bool
:returns: Verified data from PAPI response.
:rtype: dict
"""
cli = 'cli_inband'
args = dict(cmd=cmd)
err_msg = "Failed to run 'cli_inband {cmd}' PAPI command on host " \
"{host}".format(host=node['host'], cmd=cmd)
with PapiExecutor(node) as papi_exec:
data = papi_exec.add(cli, **args).get_replies(err_msg). \
verify_reply(err_msg=err_msg)
if log:
logger.info("{cmd}:\n{data}".format(cmd=cmd, data=data["reply"]))
return data
def execute_should_pass(self,
err_msg="Failed to execute PAPI command.",
process_reply=True,
ignore_errors=False,
timeout=120):
"""Execute the PAPI commands and check the return code.
Raise exception if the PAPI command(s) failed.
IMPORTANT!
Do not use this method in L1 keywords. Use:
- get_replies()
- get_dump()
This method will be removed soon.
:param err_msg: The message used if the PAPI command(s) execution fails.
:param process_reply: Indicate whether or not to process PAPI reply.
:param ignore_errors: If true, the errors in the reply are ignored.
:param timeout: Timeout in seconds.
:type err_msg: str
:type process_reply: bool
:type ignore_errors: bool
:type timeout: int
:returns: Papi response including: papi reply, stdout, stderr and
return code.
:rtype: PapiResponse
:raises AssertionError: If PAPI command(s) execution failed.
"""
# TODO: Migrate callers to get_replies and delete this method.
return self.get_replies(process_reply=process_reply,
ignore_errors=ignore_errors,
err_msg=err_msg,
timeout=timeout)
@staticmethod
def _process_api_data(api_d):
"""Process API data for smooth converting to JSON string.
Apply binascii.hexlify() method for string values.
:param api_d: List of APIs with their arguments.
:type api_d: list
:returns: List of APIs with arguments pre-processed for JSON.
:rtype: list
"""
def process_value(val):
"""Process value.
:param val: Value to be processed.
:type val: object
:returns: Processed value.
:rtype: dict or str or int
"""
if isinstance(val, dict):
for val_k, val_v in val.iteritems():
val[str(val_k)] = process_value(val_v)
return val
elif isinstance(val, list):
for idx, val_l in enumerate(val):
val[idx] = process_value(val_l)
return val
else:
return binascii.hexlify(val) if isinstance(val, str) else val
api_data_processed = list()
for api in api_d:
api_args_processed = dict()
for a_k, a_v in api["api_args"].iteritems():
api_args_processed[str(a_k)] = process_value(a_v)
api_data_processed.append(
dict(api_name=api["api_name"], api_args=api_args_processed))
return api_data_processed
@staticmethod
def _revert_api_reply(api_r):
"""Process API reply / a part of API reply.
Apply binascii.unhexlify() method for unicode values.
TODO: Implement complex solution to process of replies.
:param api_r: API reply.
:type api_r: dict
:returns: Processed API reply / a part of API reply.
:rtype: dict
"""
def process_value(val):
"""Process value.
:param val: Value to be processed.
:type val: object
:returns: Processed value.
:rtype: dict or str or int
"""
if isinstance(val, dict):
for val_k, val_v in val.iteritems():
val[str(val_k)] = process_value(val_v)
return val
elif isinstance(val, list):
for idx, val_l in enumerate(val):
val[idx] = process_value(val_l)
return val
elif isinstance(val, unicode):
return binascii.unhexlify(val)
else:
return val
reply_dict = dict()
reply_value = dict()
for reply_key, reply_v in api_r.iteritems():
for a_k, a_v in reply_v.iteritems():
reply_value[a_k] = process_value(a_v)
reply_dict[reply_key] = reply_value
return reply_dict
def _process_reply(self, api_reply):
"""Process API reply.
:param api_reply: API reply.
:type api_reply: dict or list of dict
:returns: Processed API reply.
:rtype: list or dict
"""
if isinstance(api_reply, list):
reverted_reply = [self._revert_api_reply(a_r) for a_r in api_reply]
else:
reverted_reply = self._revert_api_reply(api_reply)
return reverted_reply
def _execute_papi(self,
api_data,
method='request',
err_msg="",
timeout=120):
"""Execute PAPI command(s) on remote node and store the result.
:param api_data: List of APIs with their arguments.
:param method: VPP Python API method. Supported methods are: 'request',
'dump' and 'stats'.
:param err_msg: The message used if the PAPI command(s) execution fails.
:param timeout: Timeout in seconds.
:type api_data: list
:type method: str
:type err_msg: str
:type timeout: int
:returns: Stdout and stderr.
:rtype: 2-tuple of str
:raises SSHTimeout: If PAPI command(s) execution has timed out.
:raises RuntimeError: If PAPI executor failed due to another reason.
:raises AssertionError: If PAPI command(s) execution has failed.
"""
if not api_data:
RuntimeError("No API data provided.")
json_data = json.dumps(api_data) \
if method in ("stats", "stats_request") \
else json.dumps(self._process_api_data(api_data))
cmd = "{fw_dir}/{papi_provider} --method {method} --data '{json}'".\
format(fw_dir=Constants.REMOTE_FW_DIR,
papi_provider=Constants.RESOURCES_PAPI_PROVIDER,
method=method,
json=json_data)
try:
ret_code, stdout, stderr = self._ssh.exec_command_sudo(
cmd=cmd, timeout=timeout, log_stdout_err=False)
except SSHTimeout:
logger.error("PAPI command(s) execution timeout on host {host}:"
"\n{apis}".format(host=self._node["host"],
apis=api_data))
raise
except Exception:
raise RuntimeError("PAPI command(s) execution on host {host} "
"failed: {apis}".format(host=self._node["host"],
apis=api_data))
if ret_code != 0:
raise AssertionError(err_msg)
return stdout, stderr
def _execute(self,
method='request',
process_reply=True,
ignore_errors=False,
err_msg="",
timeout=120):
"""Turn internal command list into proper data and execute; return
PAPI response.
This method also clears the internal command list.
IMPORTANT!
Do not use this method in L1 keywords. Use:
- get_stats()
- get_replies()
- get_dump()
:param method: VPP Python API method. Supported methods are: 'request',
'dump' and 'stats'.
:param process_reply: Process PAPI reply if True.
:param ignore_errors: If true, the errors in the reply are ignored.
:param err_msg: The message used if the PAPI command(s) execution fails.
:param timeout: Timeout in seconds.
:type method: str
:type process_reply: bool
:type ignore_errors: bool
:type err_msg: str
:type timeout: int
:returns: Papi response including: papi reply, stdout, stderr and
return code.
:rtype: PapiResponse
:raises KeyError: If the reply is not correct.
"""
local_list = self._api_command_list
# Clear first as execution may fail.
self._api_command_list = list()
stdout, stderr = self._execute_papi(local_list,
method=method,
err_msg=err_msg,
timeout=timeout)
papi_reply = list()
if process_reply:
try:
json_data = json.loads(stdout)
except ValueError:
logger.error("An error occured while processing the PAPI "
"request:\n{rqst}".format(rqst=local_list))
raise
for data in json_data:
try:
api_reply_processed = dict(api_name=data["api_name"],
api_reply=self._process_reply(
data["api_reply"]))
except KeyError:
if ignore_errors:
continue
else:
raise
papi_reply.append(api_reply_processed)
# Log processed papi reply to be able to check API replies changes
logger.debug("Processed PAPI reply: {reply}".format(reply=papi_reply))
return PapiResponse(papi_reply=papi_reply,
stdout=stdout,
stderr=stderr,
requests=[rqst["api_name"] for rqst in local_list])