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

[Christopher Clark <christopher.w.clark@xxxxxxxxx>]

On Thu, May 29, 2025 at 11:40 PM Teddy Astie <teddy.astie@xxxxxxxxxx> wrote:

Hello Christopher,

Hi Teddy, thanks for the review.

 

Le 28/05/2025 à 23:13, Christopher Clark a écrit :
> Adds approachable documentation describing system components and
> introduces the support statement for feature status.
...
> +# 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".

I agree and I can work on a better description for the next posting.

 

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

Yes (for systems with Linux).

 

> +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, ...).

OK, I wasn't sure what level of detail would be wanted for this so it's useful to know, thanks.

 

> +## 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.

OK, I'll add reference to the design document.

 

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.

Thanks, I appreciate the enthusiasm for it to be written!

best,

Christopher