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 v1 1/2] doc: update guides for vhost async APIs
Date: Wed, 22 Jul 2020 18:57:40 +0800 [thread overview]
Message-ID: <20200722105741.3421255-2-patrick.fu@intel.com> (raw)
In-Reply-To: <20200722105741.3421255-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..cce8b6ae7 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 offload 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 copye 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 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 data path or 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.
* Memory sharing
--
2.18.4
next prev parent reply other threads:[~2020-07-22 11:00 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 ` patrick.fu [this message]
2020-07-22 11:21 ` [dpdk-dev] [PATCH v1 1/2] doc: update guides for vhost async APIs 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 ` [dpdk-dev] [PATCH v2 1/2] doc: update guides " patrick.fu
2020-07-25 6:58 ` 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=20200722105741.3421255-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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).