DPDK patches and discussions
 help / color / mirror / Atom feed
From: patrick.fu@intel.com
To: dev@dpdk.org, maxime.coquelin@redhat.com, chenbo.xia@intel.com
Cc: Patrick Fu <patrick.fu@intel.com>
Subject: [dpdk-dev] [PATCH v2 1/2] doc: update guides for vhost async APIs
Date: Wed, 22 Jul 2020 23:01:52 +0800
Message-ID: <20200722150153.3422450-2-patrick.fu@intel.com> (raw)
In-Reply-To: <20200722150153.3422450-1-patrick.fu@intel.com>

From: Patrick Fu <patrick.fu@intel.com>

Update vhost guides to document vhost async APIs

Signed-off-by: Patrick Fu <patrick.fu@intel.com>
---
 doc/guides/prog_guide/vhost_lib.rst | 86 ++++++++++++++++++++++++++---
 1 file changed, 77 insertions(+), 9 deletions(-)

diff --git a/doc/guides/prog_guide/vhost_lib.rst b/doc/guides/prog_guide/vhost_lib.rst
index db921f922..b892eec67 100644
--- a/doc/guides/prog_guide/vhost_lib.rst
+++ b/doc/guides/prog_guide/vhost_lib.rst
@@ -147,6 +147,21 @@ The following is an overview of some key Vhost API functions:
 
     It is disabled by default.
 
+  - ``RTE_VHOST_USER_ASYNC_COPY``
+
+    Asynchronous data path will be enabled when this flag is set. Async data
+    path allows applications to register async copy devices (typically
+    hardware DMA channels) to the vhost queues. Vhost leverages the copy
+    device registered to free CPU from memory copy operations. A set of
+    async data path APIs are defined for DPDK applications to make use of
+    the async capability. Only packets enqueued/dequeued by async APIs are
+    processed through the async data path.
+
+    Currently this feature is only implemented on split ring enqueue data
+    path.
+
+    It is disabled by default.
+
 * ``rte_vhost_driver_set_features(path, features)``
 
   This function sets the feature bits the vhost-user driver supports. The
@@ -235,6 +250,59 @@ The following is an overview of some key Vhost API functions:
 
   Enable or disable zero copy feature of the vhost crypto backend.
 
+* ``rte_vhost_async_channel_register(vid, queue_id, features, ops)``
+
+  Register a vhost queue with async copy device channel.
+  Following device ``features`` must be specified together with the
+  registration:
+
+  * ``async_inorder``
+
+    Async copy device can guarantee the ordering of copy completion
+    sequence. Copies are completed in the same order with that at
+    the submission time.
+
+    Currently, only ``async_inorder`` capable device is supported by vhost.
+
+  * ``async_threshold``
+
+    The copy length (in bytes) below which CPU copy will be used even if
+    applications call async vhost APIs to enqueue/dequeue data.
+
+    Typical value is 512~1024 depending on the async device capability.
+
+  Applications must provide following ``ops`` callbacks for vhost lib to
+  work with the async copy devices:
+
+  * ``transfer_data(vid, queue_id, descs, opaque_data, count)``
+
+    vhost invokes this function to submit copy data to the async devices.
+    For non-async_inorder capable devices, ``opaque_data`` could be used
+    for identifying the completed packets.
+
+  * ``check_completed_copies(vid, queue_id, opaque_data, max_packets)``
+
+    vhost invokes this function to get the copy data completed by async
+    devices.
+
+* ``rte_vhost_async_channel_unregister(vid, queue_id)``
+
+  Unregister the async copy device channel from a vhost queue.
+
+* ``rte_vhost_submit_enqueue_burst(vid, queue_id, pkts, count)``
+
+  Submit an enqueue request to transmit ``count`` packets from host to guest
+  by async data path. Enqueue is not guaranteed to finish upon the return of
+  this API call.
+
+  Applications must not free the packets submitted for enqueue until the
+  packets are completed.
+
+* ``rte_vhost_poll_enqueue_completed(vid, queue_id, pkts, count)``
+
+  Poll enqueue completion status from async data path. Completed packets
+  are returned to applications through ``pkts``.
+
 Vhost-user Implementations
 --------------------------
 
@@ -294,16 +362,16 @@ Guest memory requirement
 
 * Memory pre-allocation
 
-  For non-zerocopy, guest memory pre-allocation is not a must. This can help
-  save of memory. If users really want the guest memory to be pre-allocated
-  (e.g., for performance reason), we can add option ``-mem-prealloc`` when
-  starting QEMU. Or, we can lock all memory at vhost side which will force
-  memory to be allocated when mmap at vhost side; option --mlockall in
-  ovs-dpdk is an example in hand.
+  For non-zerocopy non-async data path, guest memory pre-allocation is not a
+  must. This can help save of memory. If users really want the guest memory
+  to be pre-allocated (e.g., for performance reason), we can add option
+  ``-mem-prealloc`` when starting QEMU. Or, we can lock all memory at vhost
+  side which will force memory to be allocated when mmap at vhost side;
+  option --mlockall in ovs-dpdk is an example in hand.
 
-  For zerocopy, we force the VM memory to be pre-allocated at vhost lib when
-  mapping the guest memory; and also we need to lock the memory to prevent
-  pages being swapped out to disk.
+  For async and zerocopy data path, we force the VM memory to be
+  pre-allocated at vhost lib when mapping the guest memory; and also we need
+  to lock the memory to prevent pages being swapped out to disk.
 
 * Memory sharing
 
-- 
2.18.4


  reply	other threads:[~2020-07-22 15:04 UTC|newest]

Thread overview: 15+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-07-22 10:57 [dpdk-dev] [PATCH v1 0/2] update docs for vhost async API patrick.fu
2020-07-22 10:57 ` [dpdk-dev] [PATCH v1 1/2] doc: update guides for vhost async APIs patrick.fu
2020-07-22 11:21   ` Xia, Chenbo
2020-07-22 15:06     ` Fu, Patrick
2020-07-22 10:57 ` [dpdk-dev] [PATCH v1 2/2] doc: update release notes " patrick.fu
2020-07-22 11:25   ` Xia, Chenbo
2020-07-22 15:07     ` Fu, Patrick
2020-07-22 15:01 ` [dpdk-dev] [PATCH v2 0/2] update docs " patrick.fu
2020-07-22 15:01   ` patrick.fu [this message]
2020-07-25  6:58     ` [dpdk-dev] [PATCH v2 1/2] doc: update guides " Xia, Chenbo
2020-07-28  9:01     ` Maxime Coquelin
2020-07-22 15:01   ` [dpdk-dev] [PATCH v2 2/2] doc: update release notes " patrick.fu
2020-07-25  6:59     ` Xia, Chenbo
2020-07-28  9:06     ` Maxime Coquelin
2020-07-28 15:26   ` [dpdk-dev] [PATCH v2 0/2] update docs " Maxime Coquelin

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=20200722150153.3422450-2-patrick.fu@intel.com \
    --to=patrick.fu@intel.com \
    --cc=chenbo.xia@intel.com \
    --cc=dev@dpdk.org \
    --cc=maxime.coquelin@redhat.com \
    /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