Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/45021/?format=api
{ "id": 45021, "url": "http://patches.dpdk.org/api/patches/45021/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/patch/3e00aba3b6baa83b585bd8b450a87d15d0a1b5b7.1537443103.git.anatoly.burakov@intel.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": "<3e00aba3b6baa83b585bd8b450a87d15d0a1b5b7.1537443103.git.anatoly.burakov@intel.com>", "list_archive_url": "https://inbox.dpdk.org/dev/3e00aba3b6baa83b585bd8b450a87d15d0a1b5b7.1537443103.git.anatoly.burakov@intel.com", "date": "2018-09-20T11:36:33", "name": "[v3,20/20] doc: add external memory sample application guide", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "b911e3d55a1e6457033f6e06c18d451c0786c95a", "submitter": { "id": 4, "url": "http://patches.dpdk.org/api/people/4/?format=api", "name": "Anatoly Burakov", "email": "anatoly.burakov@intel.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/3e00aba3b6baa83b585bd8b450a87d15d0a1b5b7.1537443103.git.anatoly.burakov@intel.com/mbox/", "series": [ { "id": 1415, "url": "http://patches.dpdk.org/api/series/1415/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/list/?series=1415", "date": "2018-09-20T11:36:13", "name": "Support externally allocated memory in DPDK", "version": 3, "mbox": "http://patches.dpdk.org/series/1415/mbox/" } ], "comments": "http://patches.dpdk.org/api/patches/45021/comments/", "check": "success", "checks": "http://patches.dpdk.org/api/patches/45021/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@dpdk.org", "Delivered-To": "patchwork@dpdk.org", "Received": [ "from [92.243.14.124] (localhost [127.0.0.1])\n\tby dpdk.org (Postfix) with ESMTP id 6A9481B12F;\n\tThu, 20 Sep 2018 13:37:20 +0200 (CEST)", "from mga14.intel.com (mga14.intel.com [192.55.52.115])\n\tby dpdk.org (Postfix) with ESMTP id BDAC45F27\n\tfor <dev@dpdk.org>; Thu, 20 Sep 2018 13:36:46 +0200 (CEST)", "from fmsmga006.fm.intel.com ([10.253.24.20])\n\tby fmsmga103.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384;\n\t20 Sep 2018 04:36:45 -0700", "from irvmail001.ir.intel.com ([163.33.26.43])\n\tby fmsmga006.fm.intel.com with ESMTP; 20 Sep 2018 04:36:42 -0700", "from sivswdev01.ir.intel.com (sivswdev01.ir.intel.com\n\t[10.237.217.45])\n\tby irvmail001.ir.intel.com (8.14.3/8.13.6/MailSET/Hub) with ESMTP id\n\tw8KBaf6s022855; Thu, 20 Sep 2018 12:36:41 +0100", "from sivswdev01.ir.intel.com (localhost [127.0.0.1])\n\tby sivswdev01.ir.intel.com with ESMTP id w8KBafNU011609;\n\tThu, 20 Sep 2018 12:36:41 +0100", "(from aburakov@localhost)\n\tby sivswdev01.ir.intel.com with LOCAL id w8KBafFS011605;\n\tThu, 20 Sep 2018 12:36:41 +0100" ], "X-Amp-Result": "SKIPPED(no attachment in message)", "X-Amp-File-Uploaded": "False", "X-ExtLoop1": "1", "X-IronPort-AV": "E=Sophos;i=\"5.53,398,1531810800\"; d=\"scan'208\";a=\"265202986\"", "From": "Anatoly Burakov <anatoly.burakov@intel.com>", "To": "dev@dpdk.org", "Cc": "John McNamara <john.mcnamara@intel.com>,\n\tMarko Kovacevic <marko.kovacevic@intel.com>,\n\tlaszlo.madarassy@ericsson.com, laszlo.vadkerti@ericsson.com,\n\tandras.kovacs@ericsson.com, winnie.tian@ericsson.com,\n\tdaniel.andrasi@ericsson.com, janos.kobor@ericsson.com,\n\tgeza.koblo@ericsson.com, srinath.mannam@broadcom.com,\n\tscott.branden@broadcom.com, ajit.khaparde@broadcom.com,\n\tkeith.wiles@intel.com, bruce.richardson@intel.com, thomas@monjalon.net,\n\tshreyansh.jain@nxp.com, shahafs@mellanox.com, arybchenko@solarflare.com", "Date": "Thu, 20 Sep 2018 12:36:33 +0100", "Message-Id": "<3e00aba3b6baa83b585bd8b450a87d15d0a1b5b7.1537443103.git.anatoly.burakov@intel.com>", "X-Mailer": "git-send-email 1.7.0.7", "In-Reply-To": [ "<cover.1537443103.git.anatoly.burakov@intel.com>", "<cover.1537443103.git.anatoly.burakov@intel.com>" ], "References": [ "<cover.1537443103.git.anatoly.burakov@intel.com>", "<cover.1537363686.git.anatoly.burakov@intel.com>\n\t<cover.1537443103.git.anatoly.burakov@intel.com>" ], "Subject": "[dpdk-dev] [PATCH v3 20/20] doc: add external memory sample\n\tapplication guide", "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\t<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\t<mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org", "Sender": "\"dev\" <dev-bounces@dpdk.org>" }, "content": "Add a guide for external memory sample application. The application\nis identical to Basic Forwarding example in everything except parts\nof initialization code, so the bits that are identical will not be\ndescribed.\n\nIt is also not necessary to describe how external memory is being\nallocated due to the expectation being that user will have their\nown mechanisms to allocate memory outside of DPDK, and will only\nbe interested in how to integrate said memory into DPDK.\n\nSigned-off-by: Anatoly Burakov <anatoly.burakov@intel.com>\n---\n doc/guides/sample_app_ug/external_mem.rst | 115 ++++++++++++++++++++++\n doc/guides/sample_app_ug/index.rst | 1 +\n 2 files changed, 116 insertions(+)\n create mode 100644 doc/guides/sample_app_ug/external_mem.rst", "diff": "diff --git a/doc/guides/sample_app_ug/external_mem.rst b/doc/guides/sample_app_ug/external_mem.rst\nnew file mode 100644\nindex 000000000..594c3397a\n--- /dev/null\n+++ b/doc/guides/sample_app_ug/external_mem.rst\n@@ -0,0 +1,115 @@\n+.. SPDX-License-Identifier: BSD-3-Clause\n+ Copyright(c) 2015-2018 Intel Corporation.\n+\n+External Memory Sample Application\n+==================================\n+\n+The External Memory sample application is a simple *skeleton* example of a\n+forwarding application using externally allocated memory.\n+\n+It is intended as a demonstration of the basic workflow of using externally\n+allocated memory in DPDK. This application is based on Basic Forwarding sample\n+application, and differs only in its initialization path. For more detailed\n+explanation of port initialization and packet forwarding code, please refer to\n+*Basic Forwarding sample application user guide*.\n+\n+Compiling the Application\n+-------------------------\n+\n+To compile the sample application see :doc:`compiling`.\n+\n+The application is located in the ``external_mem`` sub-directory.\n+\n+Running the Application\n+-----------------------\n+\n+To run the example in a ``linuxapp`` environment:\n+\n+.. code-block:: console\n+\n+ ./build/extmem -l 1 -n 4\n+\n+Refer to *DPDK Getting Started Guide* for general information on running\n+applications and the Environment Abstraction Layer (EAL) options.\n+\n+\n+Explanation\n+-----------\n+\n+For general overview of the code and explanation of the main components of this\n+application, please refer to *Basic Forwarding sample application user guide*.\n+This guide will only explain sections of the code relevant to using external\n+memory in DPDK.\n+\n+All DPDK library functions used in the sample code are prefixed with ``rte_``\n+and are explained in detail in the *DPDK API Documentation*.\n+\n+\n+External Memory Initialization\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+The ``main()`` function performs the initialization and calls the execution\n+threads for each lcore.\n+\n+After initializing the Environment Abstraction Layer, the application also\n+initializes external memory (in this case, it's allocating a chunk of memory\n+using anonymous hugepages) inside the ``setup_extmem()`` local function.\n+\n+The first step in this process is to create an external heap:\n+\n+.. code-block:: c\n+\n+ ret = rte_malloc_heap_create(EXTMEM_HEAP_NAME);\n+ if (ret < 0) {\n+ printf(\"Cannot create heap\\n\");\n+ return -1;\n+ }\n+\n+Once the heap is created, ``create_extmem`` function is called to create the\n+actual external memory area the application will be using. While the details of\n+that process will not be described as they are not pertinent to the external\n+memory API (it is expected that the user will have their own procedures to\n+create external memory), there are a few important things to note.\n+\n+In order to add an externally allocated memory area to the newly created heap,\n+the application needs the following pieces of information:\n+\n+* Pointer to start address of external memory area\n+* Length of this area\n+* Page size of memory backing this memory area\n+* Optionally, a per-page IOVA table\n+\n+All of this information is to be provided by the user. Additionally, if VFIO is\n+in use and if application intends to do DMA using the memory area, VFIO DMA\n+mapping must also be performed using ``rte_vfio_dma_map`` function.\n+\n+Once the external memory is created and mapped for DMA, the application also has\n+to add this memory to the heap that was created earlier:\n+\n+.. code-block:: c\n+\n+ ret = rte_malloc_heap_memory_add(EXTMEM_HEAP_NAME,\n+ param.addr, param.len, param.iova_table,\n+ param.iova_table_len, param.pgsz);\n+\n+If return value indicates success, the memory area has been successfully added\n+to the heap. The next step is to retrieve the socket ID of this heap:\n+\n+.. code-block:: c\n+\n+ socket_id = rte_malloc_heap_get_socket(EXTMEM_HEAP_NAME);\n+ if (socket_id < 0)\n+ rte_exit(EXIT_FAILURE, \"Invalid socket for external heap\\n\");\n+\n+After that, the socket ID has to be supplied to the mempool creation function:\n+\n+.. code-block:: c\n+\n+ mbuf_pool = rte_pktmbuf_pool_create(\"MBUF_POOL\",\n+ nb_mbufs_per_port * nb_ports, MBUF_CACHE_SIZE, 0,\n+ mbuf_sz, socket_id);\n+\n+The rest of the application is identical to the Basic Forwarding example.\n+\n+The forwarding loop can be interrupted and the application closed using\n+``Ctrl-C``.\ndiff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst\nindex 5bedf4f6f..0536edb8e 100644\n--- a/doc/guides/sample_app_ug/index.rst\n+++ b/doc/guides/sample_app_ug/index.rst\n@@ -15,6 +15,7 @@ Sample Applications User Guides\n exception_path\n hello_world\n skeleton\n+ external_mem\n rxtx_callbacks\n flow_classify\n flow_filtering\n", "prefixes": [ "v3", "20/20" ] }