Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/66505/?format=api
{ "id": 66505, "url": "http://patches.dpdk.org/api/patches/66505/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/patch/20200310111037.31451-3-aostruszka@marvell.com/", "project": { "id": 1, "url": "http://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<20200310111037.31451-3-aostruszka@marvell.com>", "list_archive_url": "https://inbox.dpdk.org/dev/20200310111037.31451-3-aostruszka@marvell.com", "date": "2020-03-10T11:10:35", "name": "[v2,2/4] if_proxy: add library documentation", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "0d9dbe2d3c75b0cd3324816b44521aedee06ff9d", "submitter": { "id": 1429, "url": "http://patches.dpdk.org/api/people/1429/?format=api", "name": "Andrzej Ostruszka [C]", "email": "aostruszka@marvell.com" }, "delegate": { "id": 1, "url": "http://patches.dpdk.org/api/users/1/?format=api", "username": "tmonjalo", "first_name": "Thomas", "last_name": "Monjalon", "email": "thomas@monjalon.net" }, "mbox": "http://patches.dpdk.org/project/dpdk/patch/20200310111037.31451-3-aostruszka@marvell.com/mbox/", "series": [ { "id": 8868, "url": "http://patches.dpdk.org/api/series/8868/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/list/?series=8868", "date": "2020-03-10T11:10:33", "name": "Introduce IF proxy library", "version": 2, "mbox": "http://patches.dpdk.org/series/8868/mbox/" } ], "comments": "http://patches.dpdk.org/api/patches/66505/comments/", "check": "fail", "checks": "http://patches.dpdk.org/api/patches/66505/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@inbox.dpdk.org", "Delivered-To": "patchwork@inbox.dpdk.org", "Received": [ "from dpdk.org (dpdk.org [92.243.14.124])\n\tby inbox.dpdk.org (Postfix) with ESMTP id C9FB5A0565;\n\tTue, 10 Mar 2020 12:11:13 +0100 (CET)", "from [92.243.14.124] (localhost [127.0.0.1])\n\tby dpdk.org (Postfix) with ESMTP id 130C31C030;\n\tTue, 10 Mar 2020 12:10:51 +0100 (CET)", "from mx0b-0016f401.pphosted.com (mx0b-0016f401.pphosted.com\n [67.231.156.173]) by dpdk.org (Postfix) with ESMTP id 0D0B11BFFD\n for <dev@dpdk.org>; Tue, 10 Mar 2020 12:10:46 +0100 (CET)", "from pps.filterd (m0045851.ppops.net [127.0.0.1])\n by mx0b-0016f401.pphosted.com (8.16.0.42/8.16.0.42) with SMTP id\n 02AB5gBd007525; Tue, 10 Mar 2020 04:10:46 -0700", "from sc-exch01.marvell.com ([199.233.58.181])\n by mx0b-0016f401.pphosted.com with ESMTP id 2yp04fjt4c-2\n (version=TLSv1.2 cipher=ECDHE-RSA-AES256-SHA384 bits=256 verify=NOT);\n Tue, 10 Mar 2020 04:10:46 -0700", "from SC-EXCH03.marvell.com (10.93.176.83) by SC-EXCH01.marvell.com\n (10.93.176.81) with Microsoft SMTP Server (TLS) id 15.0.1497.2; Tue, 10 Mar\n 2020 04:10:43 -0700", "from maili.marvell.com (10.93.176.43) by SC-EXCH03.marvell.com\n (10.93.176.83) with Microsoft SMTP Server id 15.0.1497.2 via Frontend\n Transport; Tue, 10 Mar 2020 04:10:43 -0700", "from amok.marvell.com (unknown [10.95.130.113])\n by maili.marvell.com (Postfix) with ESMTP id 6E4163F7043;\n Tue, 10 Mar 2020 04:10:42 -0700 (PDT)" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed; d=marvell.com;\n h=from : to : subject\n : date : message-id : in-reply-to : references : mime-version :\n content-transfer-encoding : content-type; s=pfpt0818;\n bh=K/xkmxv/4YHgHoQkjxVDe2u3CxGkPqTSwYLMzYrtBS0=;\n b=gdMkgWc4TDyjYGqAFVDHPjwkdVWul4mhUo/HeN9NDVacKiz5SNgbCO8p/tdawQ1gcAG8\n /mIqgO8+A3JwLPyMojUH4v69s7aSdSE3uvRHcCbBQwG5Yz6LoUuNzp33B3VbtLizy2n8\n cuh5RwIGN7NwDwigIoANeXee1HOt1+f1jqMvhAJyWsSWUDHBBvBfOXL7o1SCfp1sjibJ\n W4ILOEOqnusLCJm2NnF2iunx27U7F2ZeuaR3xvu/GdkrAlhJZVd5dhzMIBSUkyfNVQdR\n fnalVOjzMzYVkfne8rew2ij0daWEXspMzyaky/n0rQQldVbndJGVBcugYHPxVaRxa6Cy 0A==", "From": "Andrzej Ostruszka <aostruszka@marvell.com>", "To": "<dev@dpdk.org>, Thomas Monjalon <thomas@monjalon.net>, John McNamara\n <john.mcnamara@intel.com>, Marko Kovacevic <marko.kovacevic@intel.com>", "Date": "Tue, 10 Mar 2020 12:10:35 +0100", "Message-ID": "<20200310111037.31451-3-aostruszka@marvell.com>", "X-Mailer": "git-send-email 2.17.1", "In-Reply-To": "<20200310111037.31451-1-aostruszka@marvell.com>", "References": "<20200306164104.15528-1-aostruszka@marvell.com>\n <20200310111037.31451-1-aostruszka@marvell.com>", "MIME-Version": "1.0", "Content-Transfer-Encoding": "8bit", "Content-Type": "text/plain", "X-Proofpoint-Virus-Version": "vendor=fsecure engine=2.50.10434:6.0.138, 18.0.572\n definitions=2020-03-10_06:2020-03-10,\n 2020-03-10 signatures=0", "Subject": "[dpdk-dev] [PATCH v2 2/4] if_proxy: add library documentation", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.15", "Precedence": "list", "List-Id": "DPDK patches and discussions <dev.dpdk.org>", "List-Unsubscribe": "<https://mails.dpdk.org/options/dev>,\n <mailto:dev-request@dpdk.org?subject=unsubscribe>", "List-Archive": "<http://mails.dpdk.org/archives/dev/>", "List-Post": "<mailto:dev@dpdk.org>", "List-Help": "<mailto:dev-request@dpdk.org?subject=help>", "List-Subscribe": "<https://mails.dpdk.org/listinfo/dev>,\n <mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org", "Sender": "\"dev\" <dev-bounces@dpdk.org>" }, "content": "This commit adds documentation of IF Proxy library.\n\nSigned-off-by: Andrzej Ostruszka <aostruszka@marvell.com>\n---\n MAINTAINERS | 1 +\n doc/guides/prog_guide/if_proxy_lib.rst | 142 +++++++++++++++++++++++++\n doc/guides/prog_guide/index.rst | 1 +\n 3 files changed, 144 insertions(+)\n create mode 100644 doc/guides/prog_guide/if_proxy_lib.rst", "diff": "diff --git a/MAINTAINERS b/MAINTAINERS\nindex aec7326ca..3854d7661 100644\n--- a/MAINTAINERS\n+++ b/MAINTAINERS\n@@ -1472,6 +1472,7 @@ F: doc/guides/prog_guide/bpf_lib.rst\n IF Proxy - EXPERIMENTAL\n M: Andrzej Ostruszka <aostruszka@marvell.com>\n F: lib/librte_if_proxy/\n+F: doc/guides/prog_guide/if_proxy_lib.rst\n \n Test Applications\n -----------------\ndiff --git a/doc/guides/prog_guide/if_proxy_lib.rst b/doc/guides/prog_guide/if_proxy_lib.rst\nnew file mode 100644\nindex 000000000..f0b9ed70d\n--- /dev/null\n+++ b/doc/guides/prog_guide/if_proxy_lib.rst\n@@ -0,0 +1,142 @@\n+.. SPDX-License-Identifier: BSD-3-Clause\n+ Copyright(C) 2020 Marvell International Ltd.\n+\n+.. _IF_Proxy_Library:\n+\n+IF Proxy Library\n+================\n+\n+When a network interface is assigned to DPDK it usually disappears from\n+the system and user looses ability to configure it via typical\n+configuration tools.\n+There are basically two options to deal with this situation:\n+\n+- configure it via command line arguments and/or load configuration\n+ from some file,\n+- add support for live configuration via some IPC mechanism.\n+\n+The first option is static and the second one requires some work to add\n+communication loop (e.g. separate thread listening/communicating on\n+a socket).\n+\n+This library adds a possibility to configure DPDK ports by using normal\n+configuration utilities (e.g. from iproute2 suite).\n+It requires user to configure additional DPDK ports that are visible to\n+the system (such as Tap or KNI - actually any port that has valid\n+`if_index` in ``struct rte_eth_dev_info`` will do) and designate them as\n+a port representor (a proxy) in the system.\n+\n+Let's see typical intended usage by an example.\n+Suppose that you have application that handles traffic on two ports (in\n+the white list below)::\n+\n+ ./app -w 00:14.0 -w 00:16.0 --vdev=net_tap0 --vdev=net_tap1\n+\n+So in addition to the \"regular\" ports you need to configure proxy ports.\n+These proxy ports can be created via a command line (like above) or from\n+within the application (e.g. by using `rte_ifpx_proxy_create()`\n+function).\n+\n+When you have proxy ports you need to bind them to the \"regular\" ports::\n+\n+ rte_ifpx_port_bind(port0, proxy0);\n+ rte_ifpx_port_bind(port1, proxy1);\n+\n+This binding is a logical one - there is no automatic packet forwarding\n+configured.\n+This is because library cannot tell upfront what portion of the traffic\n+received on ports 0/1 should be redirected to the system via proxies and\n+also it does not know how the application is structured (what packet\n+processing engines it uses).\n+Therefore it is application writer responsibility to include proxy ports\n+into its packet processing and forward appropriate packets between\n+proxies and ports.\n+What the library actually does is that it gets network configuration\n+from the system and listens to its changes.\n+This information is then matched against `if_index` of the configured\n+proxies and passed to the application.\n+\n+There are two mechanisms via which library passes notifications to the\n+application.\n+First is the set of global callbacks that user has\n+to register via::\n+\n+ rte_ifpx_callbacks_register(&cbs);\n+\n+Here `cbs` is a ``struct rte_ifpx_callbacks`` which has following\n+members::\n+\n+ int (*mac_change)(const struct rte_ifpx_mac_change *event);\n+ int (*mtu_change)(const struct rte_ifpx_mtu_change *event);\n+ int (*link_change)(const struct rte_ifpx_link_change *event);\n+ int (*addr_add)(const struct rte_ifpx_addr_change *event);\n+ int (*addr_del)(const struct rte_ifpx_addr_change *event);\n+ int (*addr6_add)(const struct rte_ifpx_addr6_change *event);\n+ int (*addr6_del)(const struct rte_ifpx_addr6_change *event);\n+ int (*route_add)(const struct rte_ifpx_route_change *event);\n+ int (*route_del)(const struct rte_ifpx_route_change *event);\n+ int (*route6_add)(const struct rte_ifpx_route6_change *event);\n+ int (*route6_del)(const struct rte_ifpx_route6_change *event);\n+ int (*neigh_add)(const struct rte_ifpx_neigh_change *event);\n+ int (*neigh_del)(const struct rte_ifpx_neigh_change *event);\n+ int (*neigh6_add)(const struct rte_ifpx_neigh6_change *event);\n+ int (*neigh6_del)(const struct rte_ifpx_neigh6_change *event);\n+ int (*cfg_done)(void);\n+\n+All of them should be self explanatory apart from the last one which is\n+library specific callback - called when initial network configuration\n+query is finished.\n+\n+So for example when the user issues command::\n+\n+ ip link set dev dtap0 mtu 1600\n+\n+then library will call `mtu_change()` callback with MTU change event\n+having port_id equal to `port0` (id of the port bound to this proxy) and\n+`mtu` equal to 1600 (``dtap0`` is the default interface name for\n+``net_tap0``).\n+Application can simply use `rte_eth_dev_set_mtu()` in this callback.\n+The same way `rte_eth_dev_default_mac_addr_set()` can be used in\n+`mac_change()` and `rte_eth_dev_set_link_up/down()` inside the\n+`link_change()` callback that does dispatch based on `is_up` member of\n+its `event` argument.\n+\n+Please note however that the context in which these callbacks are called\n+is most probably different from the one in which packets are handled and\n+it is application writer responsibility to use proper synchronization\n+mechanisms - if they are needed.\n+\n+Second notification mechanism relies on queueing of event notifications\n+to the configured notification rings.\n+Application can add queue via::\n+\n+ int rte_ifpx_queue_add(struct rte_ring *r);\n+\n+This type of notification is used when there is no callback registered\n+for given type of event or when it is registered but it returns 0.\n+This way application has following choices:\n+\n+- if the data structure that needs to be updated due to notification\n+ is safe to be modified by a single writer (while being used by other\n+ readers) then it can simply do that inside the callback and return\n+ non-zero value to signal end of the event handling\n+\n+- otherwise, when there are some common preparation steps that needs\n+ to be done only once, application can register callback that will\n+ perform these steps and return 0 - library will then add an event to\n+ each registered notification queue\n+\n+- if the data structures are replicated and there are no common steps\n+ then application can simply skip registering of the callbacks and\n+ configure notification queues (e.g. 1 per each lcore)\n+\n+Once we have bindings in place and notification configured, the only\n+essential part that remains is to get the current network configuration\n+and start listening to its changes.\n+This is accomplished via a call to::\n+\n+ int rte_ifpx_listen(void);\n+\n+From that moment you should see notifications coming to your\n+application: first ones resulting from querying of current system\n+configurations and subsequent on the configuration changes.\ndiff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst\nindex fb250abf5..2fd5a8c72 100644\n--- a/doc/guides/prog_guide/index.rst\n+++ b/doc/guides/prog_guide/index.rst\n@@ -57,6 +57,7 @@ Programmer's Guide\n metrics_lib\n bpf_lib\n ipsec_lib\n+ if_proxy_lib\n source_org\n dev_kit_build_system\n dev_kit_root_make_help\n", "prefixes": [ "v2", "2/4" ] }