From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga17.intel.com (mga17.intel.com [192.55.52.151]) by dpdk.org (Postfix) with ESMTP id 07F7D5F17 for ; Wed, 19 Sep 2018 15:57:22 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga003.fm.intel.com ([10.253.24.29]) by fmsmga107.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 19 Sep 2018 06:57:21 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.53,394,1531810800"; d="scan'208";a="81683107" Received: from irvmail001.ir.intel.com ([163.33.26.43]) by FMSMGA003.fm.intel.com with ESMTP; 19 Sep 2018 06:56:48 -0700 Received: from sivswdev01.ir.intel.com (sivswdev01.ir.intel.com [10.237.217.45]) by irvmail001.ir.intel.com (8.14.3/8.13.6/MailSET/Hub) with ESMTP id w8JDulX9005034; Wed, 19 Sep 2018 14:56:47 +0100 Received: from sivswdev01.ir.intel.com (localhost [127.0.0.1]) by sivswdev01.ir.intel.com with ESMTP id w8JDulWP023557; Wed, 19 Sep 2018 14:56:47 +0100 Received: (from aburakov@localhost) by sivswdev01.ir.intel.com with LOCAL id w8JDul6B023553; Wed, 19 Sep 2018 14:56:47 +0100 From: Anatoly Burakov To: dev@dpdk.org Cc: John McNamara , Marko Kovacevic , laszlo.madarassy@ericsson.com, laszlo.vadkerti@ericsson.com, andras.kovacs@ericsson.com, winnie.tian@ericsson.com, daniel.andrasi@ericsson.com, janos.kobor@ericsson.com, geza.koblo@ericsson.com, srinath.mannam@broadcom.com, scott.branden@broadcom.com, ajit.khaparde@broadcom.com, keith.wiles@intel.com, bruce.richardson@intel.com, thomas@monjalon.net, shreyansh.jain@nxp.com, shahafs@mellanox.com Date: Wed, 19 Sep 2018 14:56:44 +0100 Message-Id: <9de598beea8706722af7222baf1dc656def1cbe8.1537363687.git.anatoly.burakov@intel.com> X-Mailer: git-send-email 1.7.0.7 In-Reply-To: References: In-Reply-To: References: Subject: [dpdk-dev] [PATCH v2 20/20] doc: add external memory sample application guide X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 19 Sep 2018 13:57:24 -0000 Add a guide for external memory sample application. The application is identical to Basic Forwarding example in everything except parts of initialization code, so the bits that are identical will not be described. It is also not necessary to describe how external memory is being allocated due to the expectation being that user will have their own mechanisms to allocate memory outside of DPDK, and will only be interested in how to integrate said memory into DPDK. Signed-off-by: Anatoly Burakov --- doc/guides/sample_app_ug/external_mem.rst | 115 ++++++++++++++++++++++ doc/guides/sample_app_ug/index.rst | 1 + 2 files changed, 116 insertions(+) create mode 100644 doc/guides/sample_app_ug/external_mem.rst diff --git a/doc/guides/sample_app_ug/external_mem.rst b/doc/guides/sample_app_ug/external_mem.rst new file mode 100644 index 000000000..594c3397a --- /dev/null +++ b/doc/guides/sample_app_ug/external_mem.rst @@ -0,0 +1,115 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2015-2018 Intel Corporation. + +External Memory Sample Application +================================== + +The External Memory sample application is a simple *skeleton* example of a +forwarding application using externally allocated memory. + +It is intended as a demonstration of the basic workflow of using externally +allocated memory in DPDK. This application is based on Basic Forwarding sample +application, and differs only in its initialization path. For more detailed +explanation of port initialization and packet forwarding code, please refer to +*Basic Forwarding sample application user guide*. + +Compiling the Application +------------------------- + +To compile the sample application see :doc:`compiling`. + +The application is located in the ``external_mem`` sub-directory. + +Running the Application +----------------------- + +To run the example in a ``linuxapp`` environment: + +.. code-block:: console + + ./build/extmem -l 1 -n 4 + +Refer to *DPDK Getting Started Guide* for general information on running +applications and the Environment Abstraction Layer (EAL) options. + + +Explanation +----------- + +For general overview of the code and explanation of the main components of this +application, please refer to *Basic Forwarding sample application user guide*. +This guide will only explain sections of the code relevant to using external +memory in DPDK. + +All DPDK library functions used in the sample code are prefixed with ``rte_`` +and are explained in detail in the *DPDK API Documentation*. + + +External Memory Initialization +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``main()`` function performs the initialization and calls the execution +threads for each lcore. + +After initializing the Environment Abstraction Layer, the application also +initializes external memory (in this case, it's allocating a chunk of memory +using anonymous hugepages) inside the ``setup_extmem()`` local function. + +The first step in this process is to create an external heap: + +.. code-block:: c + + ret = rte_malloc_heap_create(EXTMEM_HEAP_NAME); + if (ret < 0) { + printf("Cannot create heap\n"); + return -1; + } + +Once the heap is created, ``create_extmem`` function is called to create the +actual external memory area the application will be using. While the details of +that process will not be described as they are not pertinent to the external +memory API (it is expected that the user will have their own procedures to +create external memory), there are a few important things to note. + +In order to add an externally allocated memory area to the newly created heap, +the application needs the following pieces of information: + +* Pointer to start address of external memory area +* Length of this area +* Page size of memory backing this memory area +* Optionally, a per-page IOVA table + +All of this information is to be provided by the user. Additionally, if VFIO is +in use and if application intends to do DMA using the memory area, VFIO DMA +mapping must also be performed using ``rte_vfio_dma_map`` function. + +Once the external memory is created and mapped for DMA, the application also has +to add this memory to the heap that was created earlier: + +.. code-block:: c + + ret = rte_malloc_heap_memory_add(EXTMEM_HEAP_NAME, + param.addr, param.len, param.iova_table, + param.iova_table_len, param.pgsz); + +If return value indicates success, the memory area has been successfully added +to the heap. The next step is to retrieve the socket ID of this heap: + +.. code-block:: c + + socket_id = rte_malloc_heap_get_socket(EXTMEM_HEAP_NAME); + if (socket_id < 0) + rte_exit(EXIT_FAILURE, "Invalid socket for external heap\n"); + +After that, the socket ID has to be supplied to the mempool creation function: + +.. code-block:: c + + mbuf_pool = rte_pktmbuf_pool_create("MBUF_POOL", + nb_mbufs_per_port * nb_ports, MBUF_CACHE_SIZE, 0, + mbuf_sz, socket_id); + +The rest of the application is identical to the Basic Forwarding example. + +The forwarding loop can be interrupted and the application closed using +``Ctrl-C``. diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst index 5bedf4f6f..0536edb8e 100644 --- a/doc/guides/sample_app_ug/index.rst +++ b/doc/guides/sample_app_ug/index.rst @@ -15,6 +15,7 @@ Sample Applications User Guides exception_path hello_world skeleton + external_mem rxtx_callbacks flow_classify flow_filtering -- 2.17.1