Re: [PATCH v3 1/3] docs: add documentation for Argo as a feature

["Teddy Astie" <teddy.astie@xxxxxxxxxx>]

Hello Christopher,

Le 28/05/2025 à 23:13, Christopher Clark a écrit :
> Adds approachable documentation describing system components and
> introduces the support statement for feature status.
>
> Signed-off-by: Christopher Clark <christopher.w.clark@xxxxxxxxx>
> ---
>   docs/features/argo-feature.pandoc | 99 +++++++++++++++++++++++++++++++
>   1 file changed, 99 insertions(+)
>   create mode 100644 docs/features/argo-feature.pandoc
>
> diff --git a/docs/features/argo-feature.pandoc 
> b/docs/features/argo-feature.pandoc
> new file mode 100644
> index 0000000000..b6a10be78a
> --- /dev/null
> +++ b/docs/features/argo-feature.pandoc
> @@ -0,0 +1,99 @@
> +% Argo interdomain communication
> +% Revision 1
> +
> +\clearpage
> +
> +# Basics
> +
> +---------------- ----------------------------------------------------
> +         Status: **Tech Preview**
> +
> +  Architectures: x86, ARM
> +
> +   Component(s): Hypervisor, guest
> +---------------- ----------------------------------------------------
> +
> +# Overview
> +
> +Argo is a lightweight data transport for communication between virtual
> +machines, with a simple hypervisor interface that is accessible for
> +building embedded systems and designed to work with familiar primitives
> +within guest OS kernels. It supports policy control over communication
> +and isolation between VMs.
> +
> +# User details
> +
> +Argo is present in Xen, included since Xen 4.12. A Linux device driver
> +and userspace library are available and Argo is regularly tested in the
> +Xen Continuous Integration system.
> +

Not really related to the documentation itself, but it would be
preferable to have the Linux driver upstreamed such as this sentence
sounds more as "it is supported" rather than "it's possible to make it
work".

It would also make Argo easier to integrate in Xen-based projects.

> +To configure a Xen system to enable Argo:
> +
> +* ensure that Argo is enabled in the hypervisor with KConfig option
> +
> +* enable Argo on the Xen hypervisor command line
> +
> +* load the Argo guest kernel device driver
> +
> +* ensure that the Argo guest libraries are installed
> +
> +The guest userspace libraries support software designed for Argo
> +interfaces and also enables software designed for networks to
> +communicate between VMs by Argo.  This allows platform software to be
> +plumbed easily between virtual machines, without requiring networking
> +and with system policy controls over this communication.
> +
> +# Technical details
> +
> +## Argo components
> +
> +* Xen: Argo in the hypervisor provides communication between virtual
> +  machines.
> +
> +* Guest kernel: driver provides interfaces for data transport for use
> +  within the kernel, and implements familiar abstractions for
> +  networking software.
> +
> +* Guest libraries: provide application-level support for interdomain
> +  communication.
> +

That sounds a bit confusing to me, the guest kernel provides familiar
abstractions for networking software (I hear through that something like
sockets), yet we still have guest libraries for application-level support.

I think the guest libraries provide a shim for some of the argo-specific
aspects (like ioctls and sockaddr_argo related bits); while the
interface is more unix-oriented with regular sockets operations
(sendmsg, ...).

> +## Argo implementation within Xen
> +
> +See the public Xen headers for the primary interface documentation.
> +

There is the design document in docs/designs/argo.pandoc that explains
the inner design inside Xen. I think the public headers are more for
guest consumption.

As this document also targets guest developers, it would be great to
have some guidance (e.g a docs document) on how a guest should implement
argo support.

> +# Limitations
> +
> +Argo has been developed and tested on x86 and ARM architectures.
> +
> +# Testing
> +
> +The Argo test developed for the Xen Test Framework provides coverage of
> +the hypercall operations.
> +
> +The Xen Project CI provides system test coverage of an Argo-enabled Xen
> +system with Linux.
> +
> +# Areas for improvement
> +
> +## Argo and VirtIO
> +
> +References to design documentation for the development of an Argo
> +transport for VirtIO are available via:
> +https://wiki.xenproject.org/wiki/Virtio_On_Xen
> +

Are there news regarding this ?

There is work done on virtio-msg [1], which looks fairly similar to
virtio-argo (or at least, virtio-msg could work with Argo in a similar
fashion to what's described on the virtio-argo design).

[1] https://linaro.atlassian.net/wiki/spaces/HVAC/overview

> +# Known issues
> +
> +* For development: sysctl/domctls for toolstack to control per-VM access
> +  to Argo
> +

Is it regarding disabling the argo on a per-guest basis, or regarding if
a specific VM can communicate with another VM ? i.e can the toolstack
decide to prevent 2 guest from communicating ?

IIRC, in Argo, a guest on his own can decide who can communicate with
him using separate registered rings. But I am not sure if there is more
on that regard.

> +# References
> +
> +See the ARGO section of the Xen MAINTAINERS document for web reference.
> +
> +# History
> +
> +------------------------------------------------------------------------
> +Date       Revision Version   Notes
> +---------- -------- --------- ------------------------------------------
> +2025-05-28 1        Xen 4.12+ Feature included in Xen 4.12.
> +---------- -------- --------- ------------------------------------------

Teddy


Teddy Astie | Vates XCP-ng Developer

XCP-ng & Xen Orchestra - Vates solutions

web: https://vates.tech