diff options
Diffstat (limited to 'doc/guides/howto')
| -rw-r--r-- | doc/guides/howto/index.rst | 1 | ||||
| -rw-r--r-- | doc/guides/howto/rte_flow.rst | 32 | ||||
| -rw-r--r-- | doc/guides/howto/telemetry.rst | 85 | ||||
| -rw-r--r-- | doc/guides/howto/virtio_user_as_exceptional_path.rst | 23 | ||||
| -rw-r--r-- | doc/guides/howto/virtio_user_for_container_networking.rst | 2 |
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. |