* [dpdk-dev] [PATCH] doc: update vhost guide
@ 2016-06-24 7:52 Yuanhan Liu
2016-06-26 20:28 ` Mcnamara, John
2016-06-27 5:20 ` [dpdk-dev] [PATCH v2] " Yuanhan Liu
0 siblings, 2 replies; 6+ messages in thread
From: Yuanhan Liu @ 2016-06-24 7:52 UTC (permalink / raw)
To: dev; +Cc: huawei.xie, John McNamara, Thomas Monjalon, Yuanhan Liu
Mainly on updating vhost-user part: we now support client mode.
Also refine some words, and add a bit more explanation.
And made an emphatic statement that you are suggested to use vhost-user
instead of vhost-cuse, because we have enhanced vhost-user a lot since
v2.2 (Actually, I doubt there are any people still using vhost-cuse)
Signed-off-by: Yuanhan Liu <yuanhan.liu@linux.intel.com>
---
doc/guides/prog_guide/vhost_lib.rst | 161 ++++++++++++++++++++++++++----------
1 file changed, 116 insertions(+), 45 deletions(-)
diff --git a/doc/guides/prog_guide/vhost_lib.rst b/doc/guides/prog_guide/vhost_lib.rst
index 48e1fff..ad9ecf8 100644
--- a/doc/guides/prog_guide/vhost_lib.rst
+++ b/doc/guides/prog_guide/vhost_lib.rst
@@ -1,5 +1,5 @@
.. BSD LICENSE
- Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
+ Copyright(c) 2010-2016 Intel Corporation. All rights reserved.
All rights reserved.
Redistribution and use in source and binary forms, with or without
@@ -31,48 +31,100 @@
Vhost Library
=============
-The vhost library implements a user space vhost driver. It supports both vhost-cuse
-(cuse: user space character device) and vhost-user(user space socket server).
-It also creates, manages and destroys vhost devices for corresponding virtio
-devices in the guest. Vhost supported vSwitch could register callbacks to this
-library, which will be called when a vhost device is activated or deactivated
-by guest virtual machine.
+The vhost library implements a user space virtio net server, allowing
+us to manipulate the virtio ring directly. In another word, it allows
+us to fetch/put packets from/to the VM virtio net device. To achieve
+that, we should be able to
+
+* access the guest memory
+
+ For QEMU, this is done by using **-object memory-backend-file,share=on,...**
+ option. Which means QEMU will create a file to serve as the guest RAM.
+ The **share=on** option allows another process to map that file, which
+ means it can access the guest RAM.
+
+* know all the necessary info about the vring, such as where is avail
+ ring stored.
+
+ Vhost defines some messages to tell the backend all the info it needs
+ to know to manipulate the vring.
+
+Currently, there are two ways to pass those messages. That results to we
+have two implementations: vhost-cuse (character devices in user space) and
+vhost-user. Vhost-cuse creates a user space char dev and hook a function
+ioctl, so that all ioctl commands (that represent those messages) sent
+from the frontend (QEMU) will be captured and handled. While vhost-user
+creates a Unix domain socket file, through which those messages are passed.
+
+Note that since DPDK v2.2, we have spent a lot of efforts on enhancing
+vhost-user, such as multiple queue, live migration, reconnect, etc. Thus,
+**you are encouraged to use vhost-user instead of vhost-cuse**.
Vhost API Overview
------------------
-* Vhost driver registration
+* ``rte_vhost_driver_register(path, flags)``
+
+ It registers a vhost driver into the system. For vhost-cuse, a /dev/``path``
+ character device file will be created. For vhost-user server mode, a Unix
+ domain socket file ``path`` will be created.
+
+ We currently support two flags (both are valid for vhost-user only):
+
+ - ``RTE_VHOST_USER_CLIENT``
+
+ DPDK vhost-user will acts as the client when this flag is given. See more
+ detailed info below.
+
+ - ``RTE_VHOST_USER_NO_RECONNECT``
+
+ When DPDK-vhost user acts as the client, it will keep trying to reconnect
+ to the server (QEMU) until it succeeds. This become handy in two cases:
+
+ * when QEMU is not started yet.
+ * when QEMU restarts (say guest OS reboots).
+
+ It's enabled by default. However, you can turn it off by setting this flag.
+
- rte_vhost_driver_register registers the vhost driver into the system.
- For vhost-cuse, character device file will be created under the /dev directory.
- Character device name is specified as the parameter.
- For vhost-user, a Unix domain socket server will be created with the parameter as
- the local socket path.
+* ``rte_vhost_driver_session_start()``
-* Vhost session start
+ It starts the vhost session loop, to handle those vhost messages. It's an
+ infinite loop, therefore, you should call it in a dedicate thread.
- rte_vhost_driver_session_start starts the vhost session loop.
- Vhost session is an infinite blocking loop.
- Put the session in a dedicate DPDK thread.
+* ``rte_vhost_driver_callback_register(virtio_net_device_ops)``
-* Callback register
+ It registers a set of callbacks, to let DPDK applications to take proper
+ actions when some events happen. Currently, we have:
- Vhost supported vSwitch could call rte_vhost_driver_callback_register to
- register two callbacks, new_destory and destroy_device.
- When virtio device is activated or deactivated by guest virtual machine,
- the callback will be called, then vSwitch could put the device onto data
- core or remove the device from data core by setting or unsetting
- VIRTIO_DEV_RUNNING on the device flags.
+ * ``new_device(int vid)``
-* Read/write packets from/to guest virtual machine
+ It's invoked when a virtio net device becomes ready. ``vid`` is the virtio
+ net device ID.
- rte_vhost_enqueue_burst transmit host packets to guest.
- rte_vhost_dequeue_burst receives packets from guest.
+ * ``destroy_device(int vid)``
-* Feature enable/disable
+ It's invoked when a virtio net device shuts down (or when the vhost
+ connection is broken).
+
+ * ``vring_state_changed(int vid, uint16_t queue_id, int enable)``
+
+ It's invoked when a specific queue's state is changed, say, enabled or
+ disabled.
+
+* ``rte_vhost_enqueue_burst(vid, queue_id, pkts, count)``
+
+ Transmits (enqueues) packets ``count`` packets from host to guest.
+
+* ``rte_vhost_dequeue_burst(vid, queue_id, mbuf_pool, pkts, count)``
+
+ Receives (dequeues) ``count`` packets from guest, and stored them at ``pkts``.
+
+* ``rte_vhost_feature_disable/rte_vhost_feature_enable(feature_mask)``
+
+ Disable/enable some features. For example, you could use that to disable
+ mergeable and TSO features, which both are enabled by default.
- Now one negotiate-able feature in vhost is merge-able.
- vSwitch could enable/disable this feature for performance consideration.
Vhost Implementation
--------------------
@@ -102,15 +154,32 @@ When the release call is released, vhost will destroy the device.
Vhost user implementation
~~~~~~~~~~~~~~~~~~~~~~~~~
-When vSwitch registers a vhost driver, it will create a Unix domain socket server
-into the system. This server will listen for a connection and process the vhost message from
-QEMU simulator.
+As stated, vhost-user leverages Unix domain socket for passing messages.
+That means DPDK vhost-user implementation has two options:
+
+* DPDK vhost-user acts as the server
+
+ DPDK will create a Unix domain socket server file, and listen for
+ connections from the frontend.
+
+ Note this is the default mode, and the only mode before DPDK v16.07.
+
+
+* DPDK vhost-user acts as the client
+
+ Unlike the server mode, this mode doesn't not create the socket file;
+ it just tries to connect to the server (who responses to create the
+ file instead).
+
+ When DPDK vhost-user application restarts, DPDK vhost-user will try
+ to connect to the server again. And that's simply how the "reconnect"
+ feature works. Note that you need **QEMU v2.7** (or above) to make it work.
-When there is a new socket connection, it means a new virtio device has been created in
-the guest virtual machine, and the vhost driver will create a vhost device for this virtio device.
+No matter which mode we used, once a connection is established, DPDK
+vhost-user will start receiving and processing vhost messages from QEMU.
-For messages with a file descriptor, the file descriptor could be directly used in the vhost
-process as it is already installed by Unix domain socket.
+For messages with a file descriptor, the file descriptor could be directly
+used in the vhost process as it is already installed by Unix domain socket.
* VHOST_SET_MEM_TABLE
* VHOST_SET_VRING_KICK
@@ -118,18 +187,20 @@ process as it is already installed by Unix domain socket.
* VHOST_SET_LOG_FD
* VHOST_SET_VRING_ERR
-For VHOST_SET_MEM_TABLE message, QEMU will send us information for each memory region and its
-file descriptor in the ancillary data of the message. The fd is used to map that region.
+For VHOST_SET_MEM_TABLE message, QEMU will send us information for each
+memory region and its file descriptor in the ancillary data of the message.
+The fd is used to map that region.
-There is no VHOST_NET_SET_BACKEND message as in vhost cuse to signal us whether virtio device
-is ready or should be stopped.
-VHOST_SET_VRING_KICK is used as the signal to put the vhost device onto data plane.
-VHOST_GET_VRING_BASE is used as the signal to remove vhost device from data plane.
+There is no VHOST_NET_SET_BACKEND message as in vhost cuse to signal us
+whether virtio device is ready or stopped. Instead, VHOST_SET_VRING_KICK
+is used as the signal to put the vhost device onto data plane, and
+VHOST_GET_VRING_BASE is used as the signal to remove vhost device from
+data plane.
When the socket connection is closed, vhost will destroy the device.
Vhost supported vSwitch reference
---------------------------------
-For more vhost details and how to support vhost in vSwitch, please refer to vhost example in the
-DPDK Sample Applications Guide.
+For more vhost details and how to support vhost in vSwitch, please refer to
+vhost example in the DPDK Sample Applications Guide.
--
1.9.0
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [dpdk-dev] [PATCH] doc: update vhost guide
2016-06-24 7:52 [dpdk-dev] [PATCH] doc: update vhost guide Yuanhan Liu
@ 2016-06-26 20:28 ` Mcnamara, John
2016-06-27 5:08 ` Yuanhan Liu
2016-06-27 5:20 ` [dpdk-dev] [PATCH v2] " Yuanhan Liu
1 sibling, 1 reply; 6+ messages in thread
From: Mcnamara, John @ 2016-06-26 20:28 UTC (permalink / raw)
To: Yuanhan Liu, dev; +Cc: Xie, Huawei, Thomas Monjalon
> -----Original Message-----
> From: Yuanhan Liu [mailto:yuanhan.liu@linux.intel.com]
> Sent: Friday, June 24, 2016 8:53 AM
> To: dev@dpdk.org
> Cc: Xie, Huawei <huawei.xie@intel.com>; Mcnamara, John
> <john.mcnamara@intel.com>; Thomas Monjalon <thomas.monjalon@6wind.com>;
> Yuanhan Liu <yuanhan.liu@linux.intel.com>
> Subject: [PATCH] doc: update vhost guide
>
> Mainly on updating vhost-user part: we now support client mode.
> Also refine some words, and add a bit more explanation.
>
> And made an emphatic statement that you are suggested to use vhost-user
> instead of vhost-cuse, because we have enhanced vhost-user a lot since
> v2.2 (Actually, I doubt there are any people still using vhost-cuse)
Hi Yuahan,
Nice doc and updates. Some minor comments below.
> +
> +* access the guest memory
> +
> + For QEMU, this is done by using **-object
> + memory-backend-file,share=on,...**
> + option. Which means QEMU will create a file to serve as the guest RAM.
> + The **share=on** option allows another process to map that file,
> + which means it can access the guest RAM.
Fixed width quotes `` `` would be better here than bold ** **.
> +Currently, there are two ways to pass those messages. That results to
> +we have two implementations: vhost-cuse (character devices in user
> +space) and vhost-user. Vhost-cuse creates a user space char dev and
> +hook a function ioctl, so that all ioctl commands (that represent those
> +messages) sent from the frontend (QEMU) will be captured and handled.
> +While vhost-user creates a Unix domain socket file, through which those
> messages are passed.
Probably better to separate the vhost-cuse and vhost-user into 2 paragraphs
to make the text clearer.
Also, it is probably better to standardize on using a hyphen in vhost-cuse
and vhost-user throughout the doc; there are cases with and without.
> +Note that since DPDK v2.2, we have spent a lot of efforts on enhancing
> +vhost-user, such as multiple queue, live migration, reconnect, etc.
> +Thus, **you are encouraged to use vhost-user instead of vhost-cuse**.
In general I prefer to use a simple "Note" in the text, like this, rather
that the RST Note:: directive which creates a more distinctive but usually
unnecessary callout box. However in this case it is probably worth having
this recommendation displayed prominently. Something like the following:
.. Note::
Since DPDK v2.2, the majority of the development effort has gone into
enhancing vhost-user, such as multiple queue, live migration, and
reconnect. Thus, it is strongly advised to use vhost-user instead of
vhost-cuse.
> * VHOST_SET_LOG_FD
> * VHOST_SET_VRING_ERR
Probably best to prefix this list with a sentence that explains what they
are. Something like:
The supported vhost messages are:
* ``VHOST_SET_MEM_TABLE``
* ``VHOST_SET_VRING_KICK``
* ``VHOST_SET_VRING_CALL``
* ``VHOST_SET_LOG_FD``
* ``VHOST_SET_VRING_ERR``
Also, use fixed width quotes here and elsewhere for function or variable
names coming from code.
I will send you on some other suggestions.
John
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [dpdk-dev] [PATCH] doc: update vhost guide
2016-06-26 20:28 ` Mcnamara, John
@ 2016-06-27 5:08 ` Yuanhan Liu
0 siblings, 0 replies; 6+ messages in thread
From: Yuanhan Liu @ 2016-06-27 5:08 UTC (permalink / raw)
To: Mcnamara, John; +Cc: dev, Xie, Huawei, Thomas Monjalon
On Sun, Jun 26, 2016 at 08:28:12PM +0000, Mcnamara, John wrote:
> > -----Original Message-----
> > From: Yuanhan Liu [mailto:yuanhan.liu@linux.intel.com]
> > Sent: Friday, June 24, 2016 8:53 AM
> > To: dev@dpdk.org
> > Cc: Xie, Huawei <huawei.xie@intel.com>; Mcnamara, John
> > <john.mcnamara@intel.com>; Thomas Monjalon <thomas.monjalon@6wind.com>;
> > Yuanhan Liu <yuanhan.liu@linux.intel.com>
> > Subject: [PATCH] doc: update vhost guide
> >
> > Mainly on updating vhost-user part: we now support client mode.
> > Also refine some words, and add a bit more explanation.
> >
> > And made an emphatic statement that you are suggested to use vhost-user
> > instead of vhost-cuse, because we have enhanced vhost-user a lot since
> > v2.2 (Actually, I doubt there are any people still using vhost-cuse)
>
> Hi Yuahan,
>
> Nice doc and updates. Some minor comments below.
>
>
> > +
> > +* access the guest memory
> > +
> > + For QEMU, this is done by using **-object
> > + memory-backend-file,share=on,...**
> > + option. Which means QEMU will create a file to serve as the guest RAM.
> > + The **share=on** option allows another process to map that file,
> > + which means it can access the guest RAM.
>
> Fixed width quotes `` `` would be better here than bold ** **.
>
>
> > +Currently, there are two ways to pass those messages. That results to
> > +we have two implementations: vhost-cuse (character devices in user
> > +space) and vhost-user. Vhost-cuse creates a user space char dev and
> > +hook a function ioctl, so that all ioctl commands (that represent those
> > +messages) sent from the frontend (QEMU) will be captured and handled.
> > +While vhost-user creates a Unix domain socket file, through which those
> > messages are passed.
>
> Probably better to separate the vhost-cuse and vhost-user into 2 paragraphs
> to make the text clearer.
>
> Also, it is probably better to standardize on using a hyphen in vhost-cuse
> and vhost-user throughout the doc; there are cases with and without.
Yes, we should.
>
> > +Note that since DPDK v2.2, we have spent a lot of efforts on enhancing
> > +vhost-user, such as multiple queue, live migration, reconnect, etc.
> > +Thus, **you are encouraged to use vhost-user instead of vhost-cuse**.
>
> In general I prefer to use a simple "Note" in the text, like this, rather
> that the RST Note:: directive which creates a more distinctive but usually
> unnecessary callout box. However in this case it is probably worth having
> this recommendation displayed prominently. Something like the following:
>
> .. Note::
>
> Since DPDK v2.2, the majority of the development effort has gone into
> enhancing vhost-user, such as multiple queue, live migration, and
> reconnect. Thus, it is strongly advised to use vhost-user instead of
> vhost-cuse.
Much better! I also like the reword a lot.
>
> > * VHOST_SET_LOG_FD
> > * VHOST_SET_VRING_ERR
>
> Probably best to prefix this list with a sentence that explains what they
> are.
Yes, indeed. But I was thinking to defer this task to some point that I
could have plenty time to think about how to rewrite the vhost and vhost
example doc properly.
So far, it's just a short update.
> Something like:
>
> The supported vhost messages are:
>
> * ``VHOST_SET_MEM_TABLE``
> * ``VHOST_SET_VRING_KICK``
> * ``VHOST_SET_VRING_CALL``
> * ``VHOST_SET_LOG_FD``
> * ``VHOST_SET_VRING_ERR``
>
> Also, use fixed width quotes here and elsewhere for function or variable
> names coming from code.
>
> I will send you on some other suggestions.
Thanks a lot for the suggestions.
--yliu
^ permalink raw reply [flat|nested] 6+ messages in thread
* [dpdk-dev] [PATCH v2] doc: update vhost guide
2016-06-24 7:52 [dpdk-dev] [PATCH] doc: update vhost guide Yuanhan Liu
2016-06-26 20:28 ` Mcnamara, John
@ 2016-06-27 5:20 ` Yuanhan Liu
2016-06-27 9:26 ` Mcnamara, John
1 sibling, 1 reply; 6+ messages in thread
From: Yuanhan Liu @ 2016-06-27 5:20 UTC (permalink / raw)
To: dev; +Cc: huawei.xie, John McNamara, Thomas Monjalon, Yuanhan Liu
Mainly on updating vhost-user part: we now support client mode.
Also refine some words, and add a bit more explanation.
And made an emphatic statement that you are suggested to use vhost-user
instead of vhost-cuse, because we have enhanced vhost-user a lot since
v2.2 (Actually, I doubt there are any people still using vhost-cuse)
[John McNamara: rewords, better formats]
Signed-off-by: Yuanhan Liu <yuanhan.liu@linux.intel.com>
---
doc/guides/prog_guide/vhost_lib.rst | 223 +++++++++++++++++++++++++-----------
1 file changed, 156 insertions(+), 67 deletions(-)
diff --git a/doc/guides/prog_guide/vhost_lib.rst b/doc/guides/prog_guide/vhost_lib.rst
index 48e1fff..14d5e67 100644
--- a/doc/guides/prog_guide/vhost_lib.rst
+++ b/doc/guides/prog_guide/vhost_lib.rst
@@ -1,5 +1,5 @@
.. BSD LICENSE
- Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
+ Copyright(c) 2010-2016 Intel Corporation. All rights reserved.
All rights reserved.
Redistribution and use in source and binary forms, with or without
@@ -31,105 +31,194 @@
Vhost Library
=============
-The vhost library implements a user space vhost driver. It supports both vhost-cuse
-(cuse: user space character device) and vhost-user(user space socket server).
-It also creates, manages and destroys vhost devices for corresponding virtio
-devices in the guest. Vhost supported vSwitch could register callbacks to this
-library, which will be called when a vhost device is activated or deactivated
-by guest virtual machine.
+The vhost library implements a user space virtio net server allowing the user
+to manipulate the virtio ring directly. In another words, it allows the user
+to fetch/put packets from/to the VM virtio net device. To achieve this, a
+vhost library should be able to:
+
+* Access the guest memory:
+
+ For QEMU, this is done by using the ``-object memory-backend-file,share=on,...``
+ option. Which means QEMU will create a file to serve as the guest RAM.
+ The ``share=on`` option allows another process to map that file, which
+ means it can access the guest RAM.
+
+* Know all the necessary information about the vring:
+
+ Information such as where the available ring is stored. Vhost defines some
+ messages to tell the backend all the information it needs to know how to
+ manipulate the vring.
+
+Currently, there are two ways to pass these messages and as a result there are
+two Vhost implementations in DPDK: *vhost-cuse* (where the character devices
+are in user space) and *vhost-user*.
+
+Vhost-cuse creates a user space character device and hook to a function ioctl,
+so that all ioctl commands that are sent from the frontend (QEMU) will be
+captured and handled.
+
+Vhost-user creates a Unix domain socket file through which messages are
+passed.
+
+.. Note::
+
+ Since DPDK v2.2, the majority of the development effort has gone into
+ enhancing vhost-user, such as multiple queue, live migration, and
+ reconnect. Thus, it is strongly advised to use vhost-user instead of
+ vhost-cuse.
+
Vhost API Overview
------------------
-* Vhost driver registration
+The following is an overview of the Vhost API functions:
+
+* ``rte_vhost_driver_register(path, flags)``
+
+ This function registers a vhost driver into the system. For vhost-cuse, a
+ ``/dev/path`` character device file will be created. For vhost-user server
+ mode, a Unix domain socket file ``path`` will be created.
+
+ Currently two flags are supported (these are valid for vhost-user only):
+
+ - ``RTE_VHOST_USER_CLIENT``
+
+ DPDK vhost-user will act as the client when this flag is given. See below
+ for an explanation.
+
+ - ``RTE_VHOST_USER_NO_RECONNECT``
+
+ When DPDK vhost-user acts as the client it will keep trying to reconnect
+ to the server (QEMU) until it succeeds. This is useful in two cases:
+
+ * When QEMU is not started yet.
+ * When QEMU restarts (for example due to a guest OS reboot).
+
+ This reconnect option is enabled by default. However, it can be turned off
+ by setting this flag.
- rte_vhost_driver_register registers the vhost driver into the system.
- For vhost-cuse, character device file will be created under the /dev directory.
- Character device name is specified as the parameter.
- For vhost-user, a Unix domain socket server will be created with the parameter as
- the local socket path.
+* ``rte_vhost_driver_session_start()``
-* Vhost session start
+ This function starts the vhost session loop to handle vhost messages. It
+ starts an infinite loop, therefore it should be called in a dedicated
+ thread.
- rte_vhost_driver_session_start starts the vhost session loop.
- Vhost session is an infinite blocking loop.
- Put the session in a dedicate DPDK thread.
+* ``rte_vhost_driver_callback_register(virtio_net_device_ops)``
-* Callback register
+ This function registers a set of callbacks, to let DPDK applications take
+ the appropriate action when some events happen. The following events are
+ currently supported:
- Vhost supported vSwitch could call rte_vhost_driver_callback_register to
- register two callbacks, new_destory and destroy_device.
- When virtio device is activated or deactivated by guest virtual machine,
- the callback will be called, then vSwitch could put the device onto data
- core or remove the device from data core by setting or unsetting
- VIRTIO_DEV_RUNNING on the device flags.
+ * ``new_device(int vid)``
-* Read/write packets from/to guest virtual machine
+ This callback is invoked when a virtio net device becomes ready. ``vid``
+ is the virtio net device ID.
- rte_vhost_enqueue_burst transmit host packets to guest.
- rte_vhost_dequeue_burst receives packets from guest.
+ * ``destroy_device(int vid)``
-* Feature enable/disable
+ This callback is invoked when a virtio net device shuts down (or when the
+ vhost connection is broken).
- Now one negotiate-able feature in vhost is merge-able.
- vSwitch could enable/disable this feature for performance consideration.
+ * ``vring_state_changed(int vid, uint16_t queue_id, int enable)``
-Vhost Implementation
---------------------
+ This callback is invoked when a specific queue's state is changed, for
+ example to enabled or disabled.
-Vhost cuse implementation
+* ``rte_vhost_enqueue_burst(vid, queue_id, pkts, count)``
+
+ Transmits (enqueues) ``count`` packets from host to guest.
+
+* ``rte_vhost_dequeue_burst(vid, queue_id, mbuf_pool, pkts, count)``
+
+ Receives (dequeues) ``count`` packets from guest, and stored them at ``pkts``.
+
+* ``rte_vhost_feature_disable/rte_vhost_feature_enable(feature_mask)``
+
+ This function disables/enables some features. For example, it can be used to
+ disable mergeable buffers and TSO features, which both are enabled by
+ default.
+
+
+Vhost Implementations
+---------------------
+
+Vhost-cuse implementation
~~~~~~~~~~~~~~~~~~~~~~~~~
+
When vSwitch registers the vhost driver, it will register a cuse device driver
into the system and creates a character device file. This cuse driver will
-receive vhost open/release/IOCTL message from QEMU simulator.
+receive vhost open/release/IOCTL messages from the QEMU simulator.
-When the open call is received, vhost driver will create a vhost device for the
-virtio device in the guest.
+When the open call is received, the vhost driver will create a vhost device
+for the virtio device in the guest.
-When VHOST_SET_MEM_TABLE IOCTL is received, vhost searches the memory region
-to find the starting user space virtual address that maps the memory of guest
-virtual machine. Through this virtual address and the QEMU pid, vhost could
-find the file QEMU uses to map the guest memory. Vhost maps this file into its
-address space, in this way vhost could fully access the guest physical memory,
-which means vhost could access the shared virtio ring and the guest physical
-address specified in the entry of the ring.
+When the ``VHOST_SET_MEM_TABLE`` ioctl is received, vhost searches the memory
+region to find the starting user space virtual address that maps the memory of
+the guest virtual machine. Through this virtual address and the QEMU pid,
+vhost can find the file QEMU uses to map the guest memory. Vhost maps this
+file into its address space, in this way vhost can fully access the guest
+physical memory, which means vhost could access the shared virtio ring and the
+guest physical address specified in the entry of the ring.
The guest virtual machine tells the vhost whether the virtio device is ready
-for processing or is de-activated through VHOST_NET_SET_BACKEND message.
-The registered callback from vSwitch will be called.
+for processing or is de-activated through the ``VHOST_NET_SET_BACKEND``
+message. The registered callback from vSwitch will be called.
-When the release call is released, vhost will destroy the device.
+When the release call is made, vhost will destroy the device.
-Vhost user implementation
+Vhost-user implementation
~~~~~~~~~~~~~~~~~~~~~~~~~
-When vSwitch registers a vhost driver, it will create a Unix domain socket server
-into the system. This server will listen for a connection and process the vhost message from
-QEMU simulator.
-When there is a new socket connection, it means a new virtio device has been created in
-the guest virtual machine, and the vhost driver will create a vhost device for this virtio device.
+Vhost-user uses Unix domain sockets for passing messages. This means the DPDK
+vhost-user implementation has two options:
+
+* DPDK vhost-user acts as the server.
+
+ DPDK will create a Unix domain socket server file and listen for
+ connections from the frontend.
+
+ Note, this is the default mode, and the only mode before DPDK v16.07.
+
+
+* DPDK vhost-user acts as the client.
+
+ Unlike the server mode, this mode doesn't create the socket file;
+ it just tries to connect to the server (which responses to create the
+ file instead).
+
+ When the DPDK vhost-user application restarts, DPDK vhost-user will try to
+ connect to the server again. This is how the "reconnect" feature works.
+
+ Note: the "reconnect" feature requires **QEMU v2.7** (or above).
+
+No matter which mode is used, once a connection is established, DPDK
+vhost-user will start receiving and processing vhost messages from QEMU.
+
+For messages with a file descriptor, the file descriptor can be used directly
+in the vhost process as it is already installed by the Unix domain socket.
-For messages with a file descriptor, the file descriptor could be directly used in the vhost
-process as it is already installed by Unix domain socket.
+The supported vhost messages are:
- * VHOST_SET_MEM_TABLE
- * VHOST_SET_VRING_KICK
- * VHOST_SET_VRING_CALL
- * VHOST_SET_LOG_FD
- * VHOST_SET_VRING_ERR
+* ``VHOST_SET_MEM_TABLE``
+* ``VHOST_SET_VRING_KICK``
+* ``VHOST_SET_VRING_CALL``
+* ``VHOST_SET_LOG_FD``
+* ``VHOST_SET_VRING_ERR``
-For VHOST_SET_MEM_TABLE message, QEMU will send us information for each memory region and its
-file descriptor in the ancillary data of the message. The fd is used to map that region.
+For ``VHOST_SET_MEM_TABLE`` message, QEMU will send information for each
+memory region and its file descriptor in the ancillary data of the message.
+The file descriptor is used to map that region.
-There is no VHOST_NET_SET_BACKEND message as in vhost cuse to signal us whether virtio device
-is ready or should be stopped.
-VHOST_SET_VRING_KICK is used as the signal to put the vhost device onto data plane.
-VHOST_GET_VRING_BASE is used as the signal to remove vhost device from data plane.
+There is no ``VHOST_NET_SET_BACKEND`` message as in vhost-cuse to signal
+whether the virtio device is ready or stopped. Instead,
+``VHOST_SET_VRING_KICK`` is used as the signal to put the vhost device into
+the data plane, and ``VHOST_GET_VRING_BASE`` is used as the signal to remove
+the vhost device from the data plane.
When the socket connection is closed, vhost will destroy the device.
Vhost supported vSwitch reference
---------------------------------
-For more vhost details and how to support vhost in vSwitch, please refer to vhost example in the
-DPDK Sample Applications Guide.
+For more vhost details and how to support vhost in vSwitch, please refer to
+the vhost example in the DPDK Sample Applications Guide.
--
1.9.0
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [dpdk-dev] [PATCH v2] doc: update vhost guide
2016-06-27 5:20 ` [dpdk-dev] [PATCH v2] " Yuanhan Liu
@ 2016-06-27 9:26 ` Mcnamara, John
2016-06-30 5:30 ` Yuanhan Liu
0 siblings, 1 reply; 6+ messages in thread
From: Mcnamara, John @ 2016-06-27 9:26 UTC (permalink / raw)
To: Yuanhan Liu, dev; +Cc: Xie, Huawei, Thomas Monjalon
> -----Original Message-----
> From: Yuanhan Liu [mailto:yuanhan.liu@linux.intel.com]
> Sent: Monday, June 27, 2016 6:20 AM
> To: dev@dpdk.org
> Cc: Xie, Huawei <huawei.xie@intel.com>; Mcnamara, John
> <john.mcnamara@intel.com>; Thomas Monjalon <thomas.monjalon@6wind.com>;
> Yuanhan Liu <yuanhan.liu@linux.intel.com>
> Subject: [PATCH v2] doc: update vhost guide
>
> Mainly on updating vhost-user part: we now support client mode.
> Also refine some words, and add a bit more explanation.
>
> And made an emphatic statement that you are suggested to use vhost-user
> instead of vhost-cuse, because we have enhanced vhost-user a lot since
> v2.2 (Actually, I doubt there are any people still using vhost-cuse)
>
> [John McNamara: rewords, better formats]
> Signed-off-by: Yuanhan Liu <yuanhan.liu@linux.intel.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [dpdk-dev] [PATCH v2] doc: update vhost guide
2016-06-27 9:26 ` Mcnamara, John
@ 2016-06-30 5:30 ` Yuanhan Liu
0 siblings, 0 replies; 6+ messages in thread
From: Yuanhan Liu @ 2016-06-30 5:30 UTC (permalink / raw)
To: Mcnamara, John; +Cc: dev, Xie, Huawei, Thomas Monjalon
On Mon, Jun 27, 2016 at 09:26:12AM +0000, Mcnamara, John wrote:
> > -----Original Message-----
> > From: Yuanhan Liu [mailto:yuanhan.liu@linux.intel.com]
> > Sent: Monday, June 27, 2016 6:20 AM
> > To: dev@dpdk.org
> > Cc: Xie, Huawei <huawei.xie@intel.com>; Mcnamara, John
> > <john.mcnamara@intel.com>; Thomas Monjalon <thomas.monjalon@6wind.com>;
> > Yuanhan Liu <yuanhan.liu@linux.intel.com>
> > Subject: [PATCH v2] doc: update vhost guide
> >
> > Mainly on updating vhost-user part: we now support client mode.
> > Also refine some words, and add a bit more explanation.
> >
> > And made an emphatic statement that you are suggested to use vhost-user
> > instead of vhost-cuse, because we have enhanced vhost-user a lot since
> > v2.2 (Actually, I doubt there are any people still using vhost-cuse)
> >
> > [John McNamara: rewords, better formats]
> > Signed-off-by: Yuanhan Liu <yuanhan.liu@linux.intel.com>
>
> Acked-by: John McNamara <john.mcnamara@intel.com>
Applied to dpdk-next-virtio.
--yliu
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2016-06-30 5:30 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-06-24 7:52 [dpdk-dev] [PATCH] doc: update vhost guide Yuanhan Liu
2016-06-26 20:28 ` Mcnamara, John
2016-06-27 5:08 ` Yuanhan Liu
2016-06-27 5:20 ` [dpdk-dev] [PATCH v2] " Yuanhan Liu
2016-06-27 9:26 ` Mcnamara, John
2016-06-30 5:30 ` Yuanhan Liu
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).