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
next prev 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