documenation for neighboring protocols

Signed-off-by: imarom <imarom@cisco.com>

4 files changed, 258 insertions, 0 deletions

diff --git a/doc/images/port_normal_mode.png b/doc/images/port_normal_mode.png
new file mode 100644
index 00000000..3ea01d7f
--- /dev/null
+++ b/doc/images/port_normal_mode.png
diff --git a/doc/images/port_service_mode.png b/doc/images/port_service_mode.png
new file mode 100644
index 00000000..a689e34d
--- /dev/null
+++ b/doc/images/port_service_mode.png
diff --git a/doc/images/router_arp.png b/doc/images/router_arp.png
new file mode 100644
index 00000000..ad642c16
--- /dev/null
+++ b/doc/images/router_arp.png
diff --git a/doc/trex_stateless.asciidoc b/doc/trex_stateless.asciidoc
index 419df9b3..ce1d7d94 100755
--- a/doc/trex_stateless.asciidoc
+++ b/doc/trex_stateless.asciidoc
@@ -239,6 +239,264 @@ If you are confused you probably need Stateless. :-)
 | /automation/trex_control_plane/stl/examples     | Stateless Examples
 |=============================
 
+=== Port Layer Mode Configuration
+
+TRex ports can operate in two different mutual exclusive modes:
+
+* *Layer 2 mode* - MAC level configuration
+* *Layer 3 mode* - IPv4/IPv6 configuration
+
+When configuring a port for L2 mode, it is only required to provide
+the destination MAC address for the port.
+
+When configuring a port for L3, it is required to provide both
+source IPv4/IPv6 address and a IPv4/IPv6 destination address.
+
+As an intergral part of configuring L3, the client will try to ARP resolve the
+destination address and automatically configure the correct destination MAC.
+(instead of sending ARP request when starting traffic)
+
+[NOTE]
+While in L3 mode, TRex server will generate *gratuitous ARP* packets to make sure
+that no ARP timeout on the DUT/router will result in a faliure of the test.
+
+*Example of configuring L2 mode*
+
+[source,bash]
+----
+
+*TRex Console:*
+
+trex>l2 --help
+usage: port [-h] --port PORT --dst DST_MAC
+
+Configures a port in L2 mode
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --port PORT, -p PORT  source port for the action
+  --dst DST_MAC         Configure destination MAC address
+
+
+trex(service)>l2 -p 0 --dst 6A:A7:B5:3A:4E:FF
+
+Setting port 0 in L2 mode:                                   [SUCCESS]
+
+
+*TRex API:*
+
+client.set_service_mode(port = 0, enabled = True)
+
+client.set_l2_mode(port = 0, dst_mac = "6A:A7:B5:3A:4E:FF")
+
+client.set_service_mode(port = 0, enabled = False)
+----
+
+*Example of configuring L3 mode*
+
+[source,bash]
+----
+
+*TRex console:*
+
+trex(service)>l3 --help
+usage: port [-h] --port PORT --src SRC_IPV4 --dst DST_IPV4
+
+Configures a port in L3 mode
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --port PORT, -p PORT  source port for the action
+  --src SRC_IPV4        Configure source IPv4 address
+  --dst DST_IPV4        Configure destination IPv4 address
+
+trex(service)>l3 -p 0 --src 1.1.1.2 --dst 1.1.1.1
+
+Setting port 0 in L3 mode:                                   [SUCCESS]
+
+
+ARP resolving address '1.1.1.1':                             [SUCCESS]
+
+
+*TRex API:*
+
+client.set_service_mode(port = 0, enabled = True)
+
+client.set_l3_mode(port = 0, src_ipv4 = '1.1.1.2', dst_ipv4 = '1.1.1.1')
+
+client.set_service_mode(port = 0, enabled = False)
+
+----
+
+
+=== Port Service Mode
+
+
+In 'normal operation mode', to preserve high speed processing of packets,
+TRex ignores most of the RX traffic, with the exception of counting and handling
+latency flows.
+
+
+In the following diagram it is illustrated how RX packets are handled.
+Only a portion is forwarded to the RX handling module and none of forward back
+to the Python client.
+
+image::images/port_normal_mode.png[title="Port Under Normal Mode",align="left",width={p_width}, link="images/port_normal_mode.png"]
+
+
+
+We provide another mode called 'service mode' in which a port will respond to ping, ARP requests
+and also provide a capabality in this mode to forward packets to the Python control plane for
+applying full duplex protocols (DCHP, IPv6 neighboring and etc.)
+
+The following diagram illustrates of packets can be forwarded back to the Python client
+
+image::images/port_service_mode.png[title="Port Under Service Mode",align="left",width={p_width}, link="images/port_service_mode.png"]
+
+
+*Example Of Switcing Between 'Service' And 'Normal' Mode*
+[source,bash]
+----
+
+*TRex Console:*
+
+trex(service)>service --help
+usage: service [-h] [--port PORTS [PORTS ...] | -a] [--off]
+
+Configures port for service mode. In service mode ports will reply to ARP,
+PING and etc.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --port PORTS [PORTS ...], -p PORTS [PORTS ...]
+                        A list of ports on which to apply the command
+  -a                    Set this flag to apply the command on all available
+                        ports
+  --off                 Deactivates services on port(s)
+
+
+trex>service
+
+Enabling service mode on port(s) [0, 1]:                     [SUCCESS]
+
+trex(service)>service --off
+
+Disabling service mode on port(s) [0, 1]:                    [SUCCESS]
+
+
+*TRex API*:
+
+client.set_service_mode(ports = [0, 1], enabled = True)
+client.set_service_mode(ports = [0, 1], enabled = False)
+
+----
+
+==== ARP / ICMP response
+[IMPORTANT]
+Only while in service mode, ports will reply to ICMP echo requests and ARP requests.
+
+
+=== Neighboring Protocols
+As mentioned, in order to preserve high speed traffic generation,
+TRex handles neighboring protocols in pre test phase.
+
+A test that requires running a neighboring protocol should first move
+to 'service mode', execute the required steps in Python, switch back to 'normal mode'
+and start the actual test.
+
+==== ARP
+A basic neighboring protocol that is provided as part of TRex is ARP.
+
+For example, let's take a look at the following setup:
+
+image::images/router_arp.png[title="Router ARP",align="left",width={p_width}, link="images/router_arp.png"]
+
+[source,bash]
+----
+
+*TRex Console*:
+
+trex>service
+
+Enabling service mode on port(s) [0, 1]:                     [SUCCESS]
+
+trex(service)>arp -p 0 1
+
+Resolving destination on port(s) [0, 1]:                     [SUCCESS]
+
+
+Port 0 - Recieved ARP reply from: 1.1.1.1, hw: d0:d0:fd:a8:a1:01
+Port 1 - Recieved ARP reply from: 1.1.2.1, hw: d0:d0:fd:a8:a1:02
+
+
+*TRex API*:
+
+client.set_service_mode(ports = [0, 1], enabled = True)
+
+# configure port 0, 1 to Layer 3 mode
+client.set_l3_mode(port = 0, src_ipv4 = '1.1.1.2', dst_ipv4 = '1.1.1.2')
+client.set_l3_mode(port = 1, src_ipv4 = '1.1.2.2', dst_ipv4 = '1.1.2.1')
+    
+# ARP resolve ports 0, 1
+c.resolve(ports = [0, 1])
+
+client.set_service_mode(ports = [0, 1], enabled = False)
+
+----
+
+==== ICMP
+
+Another basic protocol provided with TRex is ICMP.
+It is possible, under service mode to ping the DUT or even a TRex port
+from the console / API.
+
+[source,bash]
+----
+
+*TRex Console*:
+
+trex(service)>ping --help
+usage: ping [-h] --port PORT -d PING_IPV4 [-s PKT_SIZE] [-n COUNT]
+
+pings the server / specific IP
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --port PORT, -p PORT  source port for the action
+  -d PING_IPV4          which IPv4 to ping
+  -s PKT_SIZE           packet size to use
+  -n COUNT, --count COUNT
+                        How many times to ping [default is 5]
+
+trex(service)>ping -p 0 -d 1.1.2.2
+
+Pinging 1.1.2.2 from port 0 with 64 bytes of data:
+Reply from 1.1.2.2: bytes=64, time=27.72ms, TTL=127
+Reply from 1.1.2.2: bytes=64, time=1.40ms, TTL=127
+Reply from 1.1.2.2: bytes=64, time=1.31ms, TTL=127
+Reply from 1.1.2.2: bytes=64, time=1.78ms, TTL=127
+Reply from 1.1.2.2: bytes=64, time=1.95ms, TTL=127
+
+
+*Trex API*:
+
+# move to service mode
+client.set_service_mode(ports = ports, enabled = True)
+    
+# configure port 0, 1 to Layer 3 mode
+client.set_l3_mode(port = 0, src_ipv4 = '1.1.1.2', dst_ipv4 = '1.1.1.1')
+client.set_l3_mode(port = 1, src_ipv4 = '1.1.2.2', dst_ipv4 = '1.1.2.1')
+
+# ping port 1 from port 0 through the router
+client.ping_ip(src_port = 0, dst_ipv4 = '1.1.2.2', pkt_size = 64)
+    
+# disable service mode
+client.set_service_mode(enabled = False)
+
+----
+
+
+
 === Tutorials
 
 The tutorials in this section demonstrate basic TRex *stateless* use cases. Examples include common and moderately advanced TRex concepts.