HLD: Python API in CSIT

Jira: CSIT-1335

Change-Id: Ifeebc6dad1e217e24455c4e627af740013429b56
Signed-off-by: Jan Gelety <jgelety@cisco.com>

diff --git a/resources/tools/papi/doc/python_api_hld.rst b/resources/tools/papi/doc/python_api_hld.rst
new file mode 100644 (file)
index 0000000..7bbcb5b
--- /dev/null
+++ b/resources/tools/papi/doc/python_api_hld.rst
@@ -0,0 +1,133 @@
+Python API high level description
+=================================
+
+Overview
+--------
+
+`Python API <https://wiki.fd.io/view/VPP/Python_API>`_ provides python binding
+for VPP API via vpp-papi module in ``vpp-api/python/``.
+
+Each Python API call uses arguments as specified in the API definitions file
+(e.g. vpe.api). The "client_index" and "context" fields are handled by the
+module itself.
+
+::
+
+    vpp.api.show_version()
+    vpp.api.sw_interface_dump(name_filter_valid=1,
+        name_filter="GigabitEthernet0/10/0")
+
+
+A call returns a named tuple or a list of named tuples.
+
+::
+
+    show_version_reply(_0=832, context=1, retval=0, program='vpe\x00\x00\x00\x00
+        \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
+        \x00\x00\x00\x00\x00\x00\x00', version='18.10-rc0~593-gb7620fd~b5386\x00
+        \x00\x00\x00', build_date='Fri Oct  5 18:40:55 UTC 2018\x00\x00\x00
+        \x00',build_directory='/w/workspace/vpp-merge-master-ubuntu1604\x00\x00
+        \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
+        \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
+        \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
+        \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
+        \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
+        \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
+        \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
+        \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
+        \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
+        \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
+        \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
+        \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')
+    [sw_interface_details(_0=86, context=5, sw_if_index=3, sup_sw_if_index=3,
+        l2_address_length=6, l2_address="\x08\x00'\x1f\xdf\xf5\x00\x00",
+        interface_name='GigabitEthernet0/10/0\x00\x00\x00\x00\x00\x00\x00\x00
+        \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
+        \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00',
+        admin_up_down=0, link_up_down=0, link_duplex=2, link_speed=4,
+        link_mtu=9202, mtu=[9000, 0, 0, 0], sub_id=0, sub_dot1ad=0,
+        sub_dot1ah=0, sub_number_of_tags=0, sub_outer_vlan_id=0,
+        sub_inner_vlan_id=0, sub_exact_match=0, sub_default=0,
+        sub_outer_vlan_id_any=0, sub_inner_vlan_id_any=0, vtr_op=0,
+        vtr_push_dot1q=0, vtr_tag1=0, vtr_tag2=0, tag='\x00\x00\x00\x00\x00\x00
+        \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
+        \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
+        \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
+        \x00\x00\x00\x00', outer_tag=0, b_dmac='\x00\x00\x00\x00\x00\x00',
+        b_smac='\x00\x00\x00\x00\x00\x00', b_vlanid=0, i_sid=0)]
+
+
+Implementation in CSIT
+----------------------
+
+Usage of Python API in CSIT requires splitting the implementation into two
+parts:
+
+1) Executable python script that will run on remote host (DUT) where VPP is
+   installed and running.
+
+2) Papi library that will be used on local host (e.g. jenkins slave) where Robot
+   Framework is running.
+
+Executable python script provides:
+
+- creation of VPP API object,
+- connection to / disconnection from VPP API object,
+- execution of API functions and returning the reply message(s).
+
+PAPI library is responsible for:
+
+- providing necessary API data (API name, API arguments),
+- processing of received reply message(s).
+
+Data between executable python script and PAPI library is exchanged in JSON
+format.
+
+JSON data in direction from Robot framework executor library to remote python
+script running on DUT (API request) consist of list of dictionaries with APIs
+and their arguments:
+
+::
+
+    [
+        {
+            "api_name": "show_version",
+            "api_args": {}
+        },
+        {
+            "api_name": "sw_interface_dump",
+            "api_args": {
+                "name_filter_valid": 1,
+                "name_filter": "GigabitEthernet0/10/0"
+                        }
+        }
+    ]
+
+
+where
+
+- api_name is the name of the command to be executed,
+- api_args is the dictionary of input arguments with their values for command.
+
+JSON data in direction from remote python script running on DUT to Robot
+framework executor library (API reply) consist of list of dictionaries with
+API names and replies to these APIs:
+
+::
+
+    [
+        {
+            "api_name": "show_version",
+            "api_reply": show_version_reply(_0=832, context=1, retval=0, program='vpe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00', version='18.10-rc0~593-gb7620fd~b5386\x00\x00\x00\x00', build_date='Fri Oct  5 18:40:55 UTC 2018\x00\x00\x00\x00', build_directory='/w/workspace/vpp-merge-master-ubuntu1604\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')
+        },
+        {
+            "api_name": "sw_interface_dump",
+            "api_reply": [sw_interface_details(_0=86, context=2, sw_if_index=3, sup_sw_if_index=3, l2_address_length=6, l2_address="\x08\x00'\x1f\xdf\xf5\x00\x00", interface_name='GigabitEthernet0/10/0\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00', admin_up_down=0, link_up_down=0, link_duplex=2, link_speed=4, link_mtu=9202, mtu=[9000, 0, 0, 0], sub_id=0, sub_dot1ad=0, sub_dot1ah=0, sub_number_of_tags=0, sub_outer_vlan_id=0, sub_inner_vlan_id=0, sub_exact_match=0, sub_default=0, sub_outer_vlan_id_any=0, sub_inner_vlan_id_any=0, vtr_op=0, vtr_push_dot1q=0, vtr_tag1=0, vtr_tag2=0, tag='\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00', outer_tag=0, b_dmac='\x00\x00\x00\x00\x00\x00', b_smac='\x00\x00\x00\x00\x00\x00', b_vlanid=0, i_sid=0)]
+        }
+    ]
+
+
+where
+
+- api_name is the name of executed command,
+- api_reply is named tuple or a list of named tuples for executed command.