DPDK patches and discussions
 help / color / mirror / Atom feed
From: Andrzej Ostruszka <aostruszka@marvell.com>
To: <dev@dpdk.org>, Thomas Monjalon <thomas@monjalon.net>,
	John McNamara <john.mcnamara@intel.com>,
	Marko Kovacevic <marko.kovacevic@intel.com>
Subject: [dpdk-dev] [PATCH v4 2/4] if_proxy: add library documentation
Date: Mon, 22 Jun 2020 11:21:25 +0200
Message-ID: <20200622092128.3560-3-aostruszka@marvell.com> (raw)
In-Reply-To: <20200622092128.3560-1-aostruszka@marvell.com>

This commit adds documentation of IF Proxy library.

Signed-off-by: Andrzej Ostruszka <aostruszka@marvell.com>
---
 MAINTAINERS                            |   1 +
 doc/guides/prog_guide/if_proxy_lib.rst | 142 +++++++++++++++++++++++++
 doc/guides/prog_guide/index.rst        |   1 +
 3 files changed, 144 insertions(+)
 create mode 100644 doc/guides/prog_guide/if_proxy_lib.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index 65c5a18723..c817d06c6b 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1502,6 +1502,7 @@ F: lib/librte_node/
 IF Proxy - EXPERIMENTAL
 M: Andrzej Ostruszka <aostruszka@marvell.com>
 F: lib/librte_if_proxy/
+F: doc/guides/prog_guide/if_proxy_lib.rst
 
 Test Applications
 -----------------
diff --git a/doc/guides/prog_guide/if_proxy_lib.rst b/doc/guides/prog_guide/if_proxy_lib.rst
new file mode 100644
index 0000000000..f0b9ed70d8
--- /dev/null
+++ b/doc/guides/prog_guide/if_proxy_lib.rst
@@ -0,0 +1,142 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(C) 2020 Marvell International Ltd.
+
+.. _IF_Proxy_Library:
+
+IF Proxy Library
+================
+
+When a network interface is assigned to DPDK it usually disappears from
+the system and user looses ability to configure it via typical
+configuration tools.
+There are basically two options to deal with this situation:
+
+- configure it via command line arguments and/or load configuration
+  from some file,
+- add support for live configuration via some IPC mechanism.
+
+The first option is static and the second one requires some work to add
+communication loop (e.g. separate thread listening/communicating on
+a socket).
+
+This library adds a possibility to configure DPDK ports by using normal
+configuration utilities (e.g. from iproute2 suite).
+It requires user to configure additional DPDK ports that are visible to
+the system (such as Tap or KNI - actually any port that has valid
+`if_index` in ``struct rte_eth_dev_info`` will do) and designate them as
+a port representor (a proxy) in the system.
+
+Let's see typical intended usage by an example.
+Suppose that you have application that handles traffic on two ports (in
+the white list below)::
+
+    ./app -w 00:14.0 -w 00:16.0 --vdev=net_tap0 --vdev=net_tap1
+
+So in addition to the "regular" ports you need to configure proxy ports.
+These proxy ports can be created via a command line (like above) or from
+within the application (e.g. by using `rte_ifpx_proxy_create()`
+function).
+
+When you have proxy ports you need to bind them to the "regular" ports::
+
+    rte_ifpx_port_bind(port0, proxy0);
+    rte_ifpx_port_bind(port1, proxy1);
+
+This binding is a logical one - there is no automatic packet forwarding
+configured.
+This is because library cannot tell upfront what portion of the traffic
+received on ports 0/1 should be redirected to the system via proxies and
+also it does not know how the application is structured (what packet
+processing engines it uses).
+Therefore it is application writer responsibility to include proxy ports
+into its packet processing and forward appropriate packets between
+proxies and ports.
+What the library actually does is that it gets network configuration
+from the system and listens to its changes.
+This information is then matched against `if_index` of the configured
+proxies and passed to the application.
+
+There are two mechanisms via which library passes notifications to the
+application.
+First is the set of global callbacks that user has
+to register via::
+
+    rte_ifpx_callbacks_register(&cbs);
+
+Here `cbs` is a ``struct rte_ifpx_callbacks`` which has following
+members::
+
+    int (*mac_change)(const struct rte_ifpx_mac_change *event);
+    int (*mtu_change)(const struct rte_ifpx_mtu_change *event);
+    int (*link_change)(const struct rte_ifpx_link_change *event);
+    int (*addr_add)(const struct rte_ifpx_addr_change *event);
+    int (*addr_del)(const struct rte_ifpx_addr_change *event);
+    int (*addr6_add)(const struct rte_ifpx_addr6_change *event);
+    int (*addr6_del)(const struct rte_ifpx_addr6_change *event);
+    int (*route_add)(const struct rte_ifpx_route_change *event);
+    int (*route_del)(const struct rte_ifpx_route_change *event);
+    int (*route6_add)(const struct rte_ifpx_route6_change *event);
+    int (*route6_del)(const struct rte_ifpx_route6_change *event);
+    int (*neigh_add)(const struct rte_ifpx_neigh_change *event);
+    int (*neigh_del)(const struct rte_ifpx_neigh_change *event);
+    int (*neigh6_add)(const struct rte_ifpx_neigh6_change *event);
+    int (*neigh6_del)(const struct rte_ifpx_neigh6_change *event);
+    int (*cfg_done)(void);
+
+All of them should be self explanatory apart from the last one which is
+library specific callback - called when initial network configuration
+query is finished.
+
+So for example when the user issues command::
+
+    ip link set dev dtap0 mtu 1600
+
+then library will call `mtu_change()` callback with MTU change event
+having port_id equal to `port0` (id of the port bound to this proxy) and
+`mtu` equal to 1600 (``dtap0`` is the default interface name for
+``net_tap0``).
+Application can simply use `rte_eth_dev_set_mtu()` in this callback.
+The same way `rte_eth_dev_default_mac_addr_set()` can be used in
+`mac_change()` and `rte_eth_dev_set_link_up/down()` inside the
+`link_change()` callback that does dispatch based on `is_up` member of
+its `event` argument.
+
+Please note however that the context in which these callbacks are called
+is most probably different from the one in which packets are handled and
+it is application writer responsibility to use proper synchronization
+mechanisms - if they are needed.
+
+Second notification mechanism relies on queueing of event notifications
+to the configured notification rings.
+Application can add queue via::
+
+    int rte_ifpx_queue_add(struct rte_ring *r);
+
+This type of notification is used when there is no callback registered
+for given type of event or when it is registered but it returns 0.
+This way application has following choices:
+
+- if the data structure that needs to be updated due to notification
+  is safe to be modified by a single writer (while being used by other
+  readers) then it can simply do that inside the callback and return
+  non-zero value to signal end of the event handling
+
+- otherwise, when there are some common preparation steps that needs
+  to be done only once, application can register callback that will
+  perform these steps and return 0 - library will then add an event to
+  each registered notification queue
+
+- if the data structures are replicated and there are no common steps
+  then application can simply skip registering of the callbacks and
+  configure notification queues (e.g. 1 per each lcore)
+
+Once we have bindings in place and notification configured, the only
+essential part that remains is to get the current network configuration
+and start listening to its changes.
+This is accomplished via a call to::
+
+    int rte_ifpx_listen(void);
+
+From that moment you should see notifications coming to your
+application: first ones resulting from querying of current system
+configurations and subsequent on the configuration changes.
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index 6f63f300af..9dfc473dc3 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -60,6 +60,7 @@ Programmer's Guide
     bpf_lib
     ipsec_lib
     graph_lib
+    if_proxy_lib
     source_org
     dev_kit_build_system
     dev_kit_root_make_help
-- 
2.17.1


  parent reply	other threads:[~2020-06-22  9:21 UTC|newest]

Thread overview: 64+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-03-06 16:41 [dpdk-dev] [PATCH 0/4] Introduce IF proxy library Andrzej Ostruszka
2020-03-06 16:41 ` [dpdk-dev] [PATCH 1/4] lib: introduce IF Proxy library Andrzej Ostruszka
2020-03-31 12:36   ` Harman Kalra
2020-03-31 15:37     ` Andrzej Ostruszka [C]
2020-04-01  5:29   ` Varghese, Vipin
2020-04-01 20:08     ` Andrzej Ostruszka [C]
2020-04-08  3:04       ` Varghese, Vipin
2020-04-08 18:13         ` Andrzej Ostruszka [C]
2020-03-06 16:41 ` [dpdk-dev] [PATCH 2/4] if_proxy: add library documentation Andrzej Ostruszka
2020-03-06 16:41 ` [dpdk-dev] [PATCH 3/4] if_proxy: add simple functionality test Andrzej Ostruszka
2020-03-06 16:41 ` [dpdk-dev] [PATCH 4/4] if_proxy: add example application Andrzej Ostruszka
2020-03-06 17:17 ` [dpdk-dev] [PATCH 0/4] Introduce IF proxy library Andrzej Ostruszka
2020-03-10 11:10 ` [dpdk-dev] [PATCH v2 " Andrzej Ostruszka
2020-03-10 11:10   ` [dpdk-dev] [PATCH v2 1/4] lib: introduce IF Proxy library Andrzej Ostruszka
2020-07-02  0:34     ` Stephen Hemminger
2020-07-07 20:13       ` Andrzej Ostruszka [C]
2020-07-08 16:07         ` Morten Brørup
2020-07-09  8:43           ` Andrzej Ostruszka [C]
2020-07-22  0:40             ` Thomas Monjalon
2020-07-22  8:45               ` Jerin Jacob
2020-07-22  8:56                 ` Thomas Monjalon
2020-07-22  9:09                   ` Jerin Jacob
2020-07-22  9:27                     ` Thomas Monjalon
2020-07-22  9:54                       ` Jerin Jacob
2020-07-23 14:09                         ` [dpdk-dev] [EXT] " Andrzej Ostruszka [C]
2020-03-10 11:10   ` [dpdk-dev] [PATCH v2 2/4] if_proxy: add library documentation Andrzej Ostruszka
2020-03-10 11:10   ` [dpdk-dev] [PATCH v2 3/4] if_proxy: add simple functionality test Andrzej Ostruszka
2020-03-10 11:10   ` [dpdk-dev] [PATCH v2 4/4] if_proxy: add example application Andrzej Ostruszka
2020-03-25  8:08   ` [dpdk-dev] [PATCH v2 0/4] Introduce IF proxy library David Marchand
2020-03-25 11:11     ` Morten Brørup
2020-03-26 17:42       ` Andrzej Ostruszka
2020-04-02 13:48         ` Andrzej Ostruszka [C]
2020-04-03 17:19           ` Thomas Monjalon
2020-04-03 19:09             ` Jerin Jacob
2020-04-03 21:18               ` Morten Brørup
2020-04-03 21:57                 ` Thomas Monjalon
2020-04-04 10:18                   ` Jerin Jacob
2020-04-10 10:41                     ` Morten Brørup
2020-04-04 18:30             ` Andrzej Ostruszka [C]
2020-04-04 19:58               ` Thomas Monjalon
2020-04-10 10:03                 ` Morten Brørup
2020-04-10 12:28                   ` Jerin Jacob
2020-03-26 12:41     ` Andrzej Ostruszka
2020-03-30 19:23       ` Andrzej Ostruszka
2020-04-03 21:42   ` Thomas Monjalon
2020-04-04 18:07     ` Andrzej Ostruszka [C]
2020-04-04 19:51       ` Thomas Monjalon
2020-04-16 16:11 ` [dpdk-dev] [PATCH " Stephen Hemminger
2020-04-16 16:49   ` Jerin Jacob
2020-04-16 17:04     ` Stephen Hemminger
2020-04-16 17:26       ` Andrzej Ostruszka [C]
2020-04-16 17:27       ` Jerin Jacob
2020-04-16 17:12     ` Andrzej Ostruszka [C]
2020-04-16 17:19       ` Stephen Hemminger
2020-05-04  8:53 ` [dpdk-dev] [PATCH v3 " Andrzej Ostruszka
2020-05-04  8:53   ` [dpdk-dev] [PATCH v3 1/4] lib: introduce IF Proxy library Andrzej Ostruszka
2020-05-04  8:53   ` [dpdk-dev] [PATCH v3 2/4] if_proxy: add library documentation Andrzej Ostruszka
2020-05-04  8:53   ` [dpdk-dev] [PATCH v3 3/4] if_proxy: add simple functionality test Andrzej Ostruszka
2020-05-04  8:53   ` [dpdk-dev] [PATCH v3 4/4] if_proxy: add example application Andrzej Ostruszka
2020-06-22  9:21 ` [dpdk-dev] [PATCH v4 0/4] Introduce IF proxy library Andrzej Ostruszka
2020-06-22  9:21   ` [dpdk-dev] [PATCH v4 1/4] lib: introduce IF Proxy library Andrzej Ostruszka
2020-06-22  9:21   ` Andrzej Ostruszka [this message]
2020-06-22  9:21   ` [dpdk-dev] [PATCH v4 3/4] if_proxy: add simple functionality test Andrzej Ostruszka
2020-06-22  9:21   ` [dpdk-dev] [PATCH v4 4/4] if_proxy: add example application Andrzej Ostruszka

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200622092128.3560-3-aostruszka@marvell.com \
    --to=aostruszka@marvell.com \
    --cc=dev@dpdk.org \
    --cc=john.mcnamara@intel.com \
    --cc=marko.kovacevic@intel.com \
    --cc=thomas@monjalon.net \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

DPDK patches and discussions

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://inbox.dpdk.org/dev/0 dev/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 dev dev/ https://inbox.dpdk.org/dev \
		dev@dpdk.org
	public-inbox-index dev

Example config snippet for mirrors.
Newsgroup available over NNTP:
	nntp://inbox.dpdk.org/inbox.dpdk.dev


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git