summaryrefslogtreecommitdiffstats
path: root/doc/guides/howto
diff options
context:
space:
mode:
Diffstat (limited to 'doc/guides/howto')
-rw-r--r--doc/guides/howto/index.rst1
-rw-r--r--doc/guides/howto/rte_flow.rst32
-rw-r--r--doc/guides/howto/telemetry.rst85
-rw-r--r--doc/guides/howto/virtio_user_as_exceptional_path.rst23
-rw-r--r--doc/guides/howto/virtio_user_for_container_networking.rst2
5 files changed, 116 insertions, 27 deletions
diff --git a/doc/guides/howto/index.rst b/doc/guides/howto/index.rst
index e13a090c..a642a2be 100644
--- a/doc/guides/howto/index.rst
+++ b/doc/guides/howto/index.rst
@@ -17,3 +17,4 @@ HowTo Guides
virtio_user_for_container_networking
virtio_user_as_exceptional_path
packet_capture_framework
+ telemetry
diff --git a/doc/guides/howto/rte_flow.rst b/doc/guides/howto/rte_flow.rst
index caa4e1af..6a8534d9 100644
--- a/doc/guides/howto/rte_flow.rst
+++ b/doc/guides/howto/rte_flow.rst
@@ -32,10 +32,10 @@ Code
.. code-block:: c
/* create the attribute structure */
- struct rte_flow_attr attr = {.ingress = 1};
+ struct rte_flow_attr attr = { .ingress = 1 };
struct rte_flow_item pattern[MAX_PATTERN_IN_FLOW];
struct rte_flow_action actions[MAX_ACTIONS_IN_FLOW];
- struct rte_flow_item_etc eth;
+ struct rte_flow_item_eth eth;
struct rte_flow_item_vlan vlan;
struct rte_flow_item_ipv4 ipv4;
struct rte_flow *flow;
@@ -55,15 +55,15 @@ Code
pattern[2].spec = &ipv4;
/* end the pattern array */
- pattern[3].type = RTE_FLOW_ITEM)TYPE_END;
+ pattern[3].type = RTE_FLOW_ITEM_TYPE_END;
/* create the drop action */
actions[0].type = RTE_FLOW_ACTION_TYPE_DROP;
actions[1].type = RTE_FLOW_ACTION_TYPE_END;
/* validate and create the flow rule */
- if (!rte_flow_validate(port_id, &attr, pattern, actions, &error)
- flow = rte_flow_create(port_id, &attr, pattern, actions, &error)
+ if (!rte_flow_validate(port_id, &attr, pattern, actions, &error))
+ flow = rte_flow_create(port_id, &attr, pattern, actions, &error);
Output
~~~~~~
@@ -120,7 +120,7 @@ clarity)::
tpmd> flow create 0 ingress pattern eth / vlan /
ipv4 dst spec 192.168.3.0 dst mask 255.255.255.0 /
- end actions drop / end
+ end actions drop / end
Code
~~~~
@@ -130,7 +130,7 @@ Code
struct rte_flow_attr attr = {.ingress = 1};
struct rte_flow_item pattern[MAX_PATTERN_IN_FLOW];
struct rte_flow_action actions[MAX_ACTIONS_IN_FLOW];
- struct rte_flow_item_etc eth;
+ struct rte_flow_item_eth eth;
struct rte_flow_item_vlan vlan;
struct rte_flow_item_ipv4 ipv4;
struct rte_flow_item_ipv4 ipv4_mask;
@@ -153,15 +153,15 @@ Code
pattern[2].mask = &ipv4_mask;
/* end the pattern array */
- pattern[3].type = RTE_FLOW_ITEM)TYPE_END;
+ pattern[3].type = RTE_FLOW_ITEM_TYPE_END;
/* create the drop action */
actions[0].type = RTE_FLOW_ACTION_TYPE_DROP;
actions[1].type = RTE_FLOW_ACTION_TYPE_END;
/* validate and create the flow rule */
- if (!rte_flow_validate(port_id, &attr, pattern, actions, &error)
- flow = rte_flow_create(port_id, &attr, pattern, actions, &error)
+ if (!rte_flow_validate(port_id, &attr, pattern, actions, &error))
+ flow = rte_flow_create(port_id, &attr, pattern, actions, &error);
Output
~~~~~~
@@ -227,10 +227,10 @@ Code
.. code-block:: c
- struct rte_flow_attr attr = {.ingress = 1};
+ struct rte_flow_attr attr = { .ingress = 1 };
struct rte_flow_item pattern[MAX_PATTERN_IN_FLOW];
struct rte_flow_action actions[MAX_ACTIONS_IN_FLOW];
- struct rte_flow_item_etc eth;
+ struct rte_flow_item_eth eth;
struct rte_flow_item_vlan vlan;
struct rte_flow_action_queue queue = { .index = 3 };
struct rte_flow *flow;
@@ -246,16 +246,16 @@ Code
pattern[1].spec = &vlan;
/* end the pattern array */
- pattern[2].type = RTE_FLOW_ITEM)TYPE_END;
+ pattern[2].type = RTE_FLOW_ITEM_TYPE_END;
/* create the queue action */
actions[0].type = RTE_FLOW_ACTION_TYPE_QUEUE;
- actions[0].conf = &queue
+ actions[0].conf = &queue;
actions[1].type = RTE_FLOW_ACTION_TYPE_END;
/* validate and create the flow rule */
- if (!rte_flow_validate(port_id, &attr, pattern, actions, &error)
- flow = rte_flow_create(port_id, &attr, pattern, actions, &error)
+ if (!rte_flow_validate(port_id, &attr, pattern, actions, &error))
+ flow = rte_flow_create(port_id, &attr, pattern, actions, &error);
Output
~~~~~~
diff --git a/doc/guides/howto/telemetry.rst b/doc/guides/howto/telemetry.rst
new file mode 100644
index 00000000..3fcb0619
--- /dev/null
+++ b/doc/guides/howto/telemetry.rst
@@ -0,0 +1,85 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2018 Intel Corporation.
+
+DPDK Telemetry API User Guide
+==============================
+
+This document describes how the Data Plane Development Kit(DPDK) Telemetry API
+is used for querying port statistics from incoming traffic.
+
+Introduction
+------------
+
+The ``librte_telemetry`` provides the functionality so that users may query
+metrics from incoming port traffic. The application which initializes packet
+forwarding will act as the server, sending metrics to the requesting application
+which acts as the client.
+
+In DPDK, applications are used to initialize the ``telemetry``. To view incoming
+traffic on featured ports, the application should be run first (ie. after ports
+are configured). Once the application is running, the service assurance agent
+(for example the collectd plugin) should be run to begin querying the API.
+
+A client connects their Service Assurance application to the DPDK application
+via a UNIX socket. Once a connection is established, a client can send JSON
+messages to the DPDK application requesting metrics via another UNIX client.
+This request is then handled and parsed if valid. The response is then
+formatted in JSON and sent back to the requesting client.
+
+Pre-requisites
+~~~~~~~~~~~~~~
+
+* Python ≥ 2.5
+
+* Jansson library for JSON serialization
+
+Test Environment
+----------------
+
+``telemetry`` offers a range of selftests that a client can run within
+the DPDK application.
+
+Selftests are disabled by default. They can be enabled by setting the 'selftest'
+variable to 1 in rte_telemetry_initial_accept().
+
+Note: this 'hardcoded' value is temporary.
+
+Configuration
+-------------
+
+Enable the telemetry API by modifying the following config option before
+building DPDK::
+
+ CONFIG_RTE_LIBRTE_TELEMETRY=y
+
+Note: Meson will pick this up automatically if ``libjansson`` is available.
+
+Running the Application
+-----------------------
+
+The following steps demonstrate how to run the ``telemetry`` API to query all
+statistics on all active ports, using the ``telemetry_client`` python script
+to query.
+Note: This guide assumes packet generation is applicable and the user is
+testing with testpmd as a DPDK primary application to forward packets, although
+any DPDK application is applicable.
+
+#. Launch testpmd as the primary application with ``telemetry``.::
+
+ ./app/testpmd --telemetry
+
+#. Launch the ``telemetry`` python script with a client filepath.::
+
+ python usertools/telemetry_client.py /var/run/some_client
+
+ The client filepath is going to be used to setup our UNIX connection with the
+ DPDK primary application, in this case ``testpmd``
+ This will initialize a menu where a client can proceed to recursively query
+ statistics, request statistics once or unregister the file_path, thus exiting
+ the menu.
+
+#. Send traffic to any or all available ports from a traffic generator.
+ Select a query option(recursive or singular polling).
+ The metrics will then be displayed on the client terminal in JSON format.
+
+#. Once finished, unregister the client using the menu command.
diff --git a/doc/guides/howto/virtio_user_as_exceptional_path.rst b/doc/guides/howto/virtio_user_as_exceptional_path.rst
index 6a13c761..4910c12d 100644
--- a/doc/guides/howto/virtio_user_as_exceptional_path.rst
+++ b/doc/guides/howto/virtio_user_as_exceptional_path.rst
@@ -57,8 +57,8 @@ compiling the kernel and those kernel modules should be inserted.
$(testpmd) -l 2-3 -n 4 \
--vdev=virtio_user0,path=/dev/vhost-net,queue_size=1024 \
- -- -i --txqflags=0x0 --enable-lro \
- --enable-rx-cksum --rxd=1024 --txd=1024
+ -- -i --tx-offloads=0x0000002c --enable-lro \
+ --txd=1024 --rxd=1024
This command runs testpmd with two ports, one physical NIC to communicate
with outside, and one virtio-user to communicate with kernel.
@@ -69,11 +69,6 @@ compiling the kernel and those kernel modules should be inserted.
VIRTIO_NET_F_GUEST_TSO6 feature so that large packets from kernel can be
transmitted to DPDK application and further TSOed by physical NIC.
-* ``--enable-rx-cksum``
-
- This is used to negotiate VIRTIO_NET_F_GUEST_CSUM so that packets from
- kernel can be deemed as valid Rx checksumed.
-
* ``queue_size``
256 by default. To avoid shortage of descriptors, we can increase it to 1024.
@@ -86,9 +81,17 @@ compiling the kernel and those kernel modules should be inserted.
$(testpmd) -l 2-3 -n 4 \
--vdev=virtio_user0,path=/dev/vhost-net,queues=2,queue_size=1024 \
- -- -i --txqflags=0x0 --enable-lro \
- --enable-rx-cksum --txq=2 --rxq=2 --rxd=1024 \
- --txd=1024
+ -- -i --tx-offloads=0x0000002c --enable-lro \
+ --txq=2 --rxq=2 --txd=1024 --rxd=1024
+
+#. Enable Rx checksum offloads in testpmd:
+
+ .. code-block:: console
+
+ (testpmd) port stop 0
+ (testpmd) port config 0 rx_offload tcp_cksum on
+ (testpmd) port config 0 rx_offload udp_cksum on
+ (testpmd) port start 0
#. Start testpmd:
diff --git a/doc/guides/howto/virtio_user_for_container_networking.rst b/doc/guides/howto/virtio_user_for_container_networking.rst
index 476ce3a6..2313dc79 100644
--- a/doc/guides/howto/virtio_user_for_container_networking.rst
+++ b/doc/guides/howto/virtio_user_for_container_networking.rst
@@ -96,7 +96,7 @@ some minor changes.
dpdk-app-testpmd testpmd -l 6-7 -n 4 -m 1024 --no-pci \
--vdev=virtio_user0,path=/var/run/usvhost \
--file-prefix=container \
- -- -i --txqflags=0xf00 --disable-hw-vlan
+ -- -i
Note: If we run all above setup on the host, it's a shm-based IPC.