[PATCH v1 0/2] Fix the documentation for vfio-user and multi-process QEMU

[PATCH v1 0/2] Fix the documentation for vfio-user and multi-process QEMU

[Jagannathan Raman]

This series addresses recent comments from Markus Armbruster in the
"Machine x-remote property auto-shutdown" email thread.

Jagannathan Raman (2):
  vfio-user: update comments
  docs: fix multi-process QEMU documentation

 docs/system/multi-process.rst |  2 +-
 hw/remote/vfio-user-obj.c     | 14 +++++++++++---
 2 files changed, 12 insertions(+), 4 deletions(-)

-- 
2.20.1

[PATCH v1 1/2] vfio-user: update comments

[Jagannathan Raman]

Clarify the behavior of TYPE_VFU_OBJECT when TYPE_REMOTE_MACHINE enables
the auto-shutdown property. Also, add notes to VFU_OBJECT_ERROR.

Signed-off-by: Jagannathan Raman <jag.raman@oracle.com>
---
 hw/remote/vfio-user-obj.c | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/hw/remote/vfio-user-obj.c b/hw/remote/vfio-user-obj.c
index 88ffafc73e..8b10c32a3c 100644
--- a/hw/remote/vfio-user-obj.c
+++ b/hw/remote/vfio-user-obj.c
@@ -30,6 +30,11 @@
  *
  * notes - x-vfio-user-server could block IO and monitor during the
  *         initialization phase.
+ *
+ *         When x-remote machine has the auto-shutdown property
+ *         enabled (default), x-vfio-user-server terminates after the last
+ *         client disconnects. Otherwise, it will continue running until
+ *         explicitly killed.
  */
 
 #include "qemu/osdep.h"
@@ -61,9 +66,12 @@
 OBJECT_DECLARE_TYPE(VfuObject, VfuObjectClass, VFU_OBJECT)
 
 /**
- * VFU_OBJECT_ERROR - reports an error message. If auto_shutdown
- * is set, it aborts the machine on error. Otherwise, it logs an
- * error message without aborting.
+ * VFU_OBJECT_ERROR - reports an error message.
+ *
+ * If auto_shutdown is set, it aborts the machine on error. Otherwise,
+ * it logs an error message without aborting. auto_shutdown is disabled
+ * when the server serves clients from multiple VMs; as such, an error
+ * from one VM shouldn't be able to disrupt other VM's services.
  */
 #define VFU_OBJECT_ERROR(o, fmt, ...)                                     \
     {                                                                     \
-- 
2.20.1

Re: [PATCH v1 1/2] vfio-user: update comments

[Markus Armbruster]

Jagannathan Raman <jag.raman@oracle.com> writes:

> Clarify the behavior of TYPE_VFU_OBJECT when TYPE_REMOTE_MACHINE enables
> the auto-shutdown property. Also, add notes to VFU_OBJECT_ERROR.
>
> Signed-off-by: Jagannathan Raman <jag.raman@oracle.com>
> ---
>  hw/remote/vfio-user-obj.c | 14 +++++++++++---
>  1 file changed, 11 insertions(+), 3 deletions(-)
>
> diff --git a/hw/remote/vfio-user-obj.c b/hw/remote/vfio-user-obj.c
> index 88ffafc73e..8b10c32a3c 100644
> --- a/hw/remote/vfio-user-obj.c
> +++ b/hw/remote/vfio-user-obj.c
> @@ -30,6 +30,11 @@
>   *
>   * notes - x-vfio-user-server could block IO and monitor during the
>   *         initialization phase.
> + *
> + *         When x-remote machine has the auto-shutdown property
> + *         enabled (default), x-vfio-user-server terminates after the last
> + *         client disconnects. Otherwise, it will continue running until
> + *         explicitly killed.
>   */
>  
>  #include "qemu/osdep.h"
> @@ -61,9 +66,12 @@
>  OBJECT_DECLARE_TYPE(VfuObject, VfuObjectClass, VFU_OBJECT)
>  
>  /**
> - * VFU_OBJECT_ERROR - reports an error message. If auto_shutdown
> - * is set, it aborts the machine on error. Otherwise, it logs an
> - * error message without aborting.
> + * VFU_OBJECT_ERROR - reports an error message.
> + *
> + * If auto_shutdown is set, it aborts the machine on error. Otherwise,
> + * it logs an error message without aborting. auto_shutdown is disabled
> + * when the server serves clients from multiple VMs; as such, an error
> + * from one VM shouldn't be able to disrupt other VM's services.
>   */
>  #define VFU_OBJECT_ERROR(o, fmt, ...)                                     \
>      {                                                                     \

I still very much doubt an error can be severe enough to justify abort()
in one configuration, yet harmless enough to permit carrying on in
another configuration.  But this patch merely documents what the code
does, so

Reviewed-by: Markus Armbruster <armbru@redhat.com>

Re: [PATCH v1 1/2] vfio-user: update comments

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 2390 bytes --]

On Thu, May 25, 2023 at 05:02:03PM +0200, Markus Armbruster wrote:
> Jagannathan Raman <jag.raman@oracle.com> writes:
> 
> > Clarify the behavior of TYPE_VFU_OBJECT when TYPE_REMOTE_MACHINE enables
> > the auto-shutdown property. Also, add notes to VFU_OBJECT_ERROR.
> >
> > Signed-off-by: Jagannathan Raman <jag.raman@oracle.com>
> > ---
> >  hw/remote/vfio-user-obj.c | 14 +++++++++++---
> >  1 file changed, 11 insertions(+), 3 deletions(-)
> >
> > diff --git a/hw/remote/vfio-user-obj.c b/hw/remote/vfio-user-obj.c
> > index 88ffafc73e..8b10c32a3c 100644
> > --- a/hw/remote/vfio-user-obj.c
> > +++ b/hw/remote/vfio-user-obj.c
> > @@ -30,6 +30,11 @@
> >   *
> >   * notes - x-vfio-user-server could block IO and monitor during the
> >   *         initialization phase.
> > + *
> > + *         When x-remote machine has the auto-shutdown property
> > + *         enabled (default), x-vfio-user-server terminates after the last
> > + *         client disconnects. Otherwise, it will continue running until
> > + *         explicitly killed.
> >   */
> >  
> >  #include "qemu/osdep.h"
> > @@ -61,9 +66,12 @@
> >  OBJECT_DECLARE_TYPE(VfuObject, VfuObjectClass, VFU_OBJECT)
> >  
> >  /**
> > - * VFU_OBJECT_ERROR - reports an error message. If auto_shutdown
> > - * is set, it aborts the machine on error. Otherwise, it logs an
> > - * error message without aborting.
> > + * VFU_OBJECT_ERROR - reports an error message.
> > + *
> > + * If auto_shutdown is set, it aborts the machine on error. Otherwise,
> > + * it logs an error message without aborting. auto_shutdown is disabled
> > + * when the server serves clients from multiple VMs; as such, an error
> > + * from one VM shouldn't be able to disrupt other VM's services.
> >   */
> >  #define VFU_OBJECT_ERROR(o, fmt, ...)                                     \
> >      {                                                                     \
> 
> I still very much doubt an error can be severe enough to justify abort()
> in one configuration, yet harmless enough to permit carrying on in
> another configuration.  But this patch merely documents what the code
> does, so

In both cases this vfio-user device is broken after the error occurs.
The difference in behavior is that in a multi-device server the other
devices should not be disrupted when one of them breaks.

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

[PATCH v1 2/2] docs: fix multi-process QEMU documentation

[Jagannathan Raman]

Fix a typo in the system documentation for multi-process QEMU.

Signed-off-by: Jagannathan Raman <jag.raman@oracle.com>
---
 docs/system/multi-process.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/system/multi-process.rst b/docs/system/multi-process.rst
index 16f0352416..2008a67809 100644
--- a/docs/system/multi-process.rst
+++ b/docs/system/multi-process.rst
@@ -4,7 +4,7 @@ Multi-process QEMU
 ==================
 
 This document describes how to configure and use multi-process qemu.
-For the design document refer to docs/devel/qemu-multiprocess.
+For the design document refer to docs/devel/multi-process.rst.
 
 1) Configuration
 ----------------
-- 
2.20.1

Re: [PATCH v1 2/2] docs: fix multi-process QEMU documentation

[Markus Armbruster]

Jagannathan Raman <jag.raman@oracle.com> writes:

> Fix a typo in the system documentation for multi-process QEMU.
>
> Signed-off-by: Jagannathan Raman <jag.raman@oracle.com>
> ---
>  docs/system/multi-process.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/docs/system/multi-process.rst b/docs/system/multi-process.rst
> index 16f0352416..2008a67809 100644
> --- a/docs/system/multi-process.rst
> +++ b/docs/system/multi-process.rst
> @@ -4,7 +4,7 @@ Multi-process QEMU
>  ==================
>  
>  This document describes how to configure and use multi-process qemu.
> -For the design document refer to docs/devel/qemu-multiprocess.
> +For the design document refer to docs/devel/multi-process.rst.
>  
>  1) Configuration
>  ----------------

Reviewed-by: Markus Armbruster <armbru@redhat.com>

Re: [PATCH v1 0/2] Fix the documentation for vfio-user and multi-process QEMU

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 541 bytes --]

On Wed, May 17, 2023 at 04:43:55PM +0000, Jagannathan Raman wrote:
> This series addresses recent comments from Markus Armbruster in the
> "Machine x-remote property auto-shutdown" email thread.
> 
> Jagannathan Raman (2):
>   vfio-user: update comments
>   docs: fix multi-process QEMU documentation
> 
>  docs/system/multi-process.rst |  2 +-
>  hw/remote/vfio-user-obj.c     | 14 +++++++++++---
>  2 files changed, 12 insertions(+), 4 deletions(-)
> 
> -- 
> 2.20.1
> 

Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]