From 686a32252768690e01cc4b9d49fbc0f197864ef1 Mon Sep 17 00:00:00 2001 From: Stefano Garzarella Date: Fri, 31 Oct 2025 12:09:52 +0100 Subject: [PATCH] vsock: move design details from the README to crate doc Let's keep the README more focused on user documentation. Removed `packet.rs` description since we removed that module and switched to `virtio-vsock` crate some time ago. Suggested--by: Manos Pitsidianakis Signed-off-by: Stefano Garzarella --- vhost-device-vsock/README.md | 39 ---------------------------------- vhost-device-vsock/src/main.rs | 37 ++++++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+), 39 deletions(-) diff --git a/vhost-device-vsock/README.md b/vhost-device-vsock/README.md index 677424c..f368f0b 100644 --- a/vhost-device-vsock/README.md +++ b/vhost-device-vsock/README.md @@ -1,44 +1,5 @@ # vhost-device-vsock -## Design - -The crate introduces a vhost-device-vsock device that enables communication between an -application running in the guest i.e inside a VM and an application running on the -host i.e outside the VM. The application running in the guest communicates over VM -sockets i.e over AF_VSOCK sockets. The application running on the host connects to a -unix socket on the host i.e communicates over AF_UNIX sockets when using the unix domain -socket backend through the uds-path option or the application in the host listens or -connects to vsock on the host i.e communicates over AF_VSOCK sockets when using the -vsock backend through the forward-cid, forward-listen options. The main components of -the crate are split into various files as described below: - -- [packet.rs](src/packet.rs) - - Introduces the **VsockPacket** structure that represents a single vsock packet - processing methods. -- [rxops.rs](src/rxops.rs) - - Introduces various vsock operations that are enqueued into the rxqueue to be sent to the - guest. Exposes a **RxOps** structure. -- [rxqueue.rs](src/rxqueue.rs) - - rxqueue contains the pending rx operations corresponding to that connection. The queue is - represented as a bitmap as we handle connection-oriented connections. The module contains - various queue manipulation methods. Exposes a **RxQueue** structure. -- [thread_backend.rs](src/thread_backend.rs) - - Multiplexes connections between host and guest and calls into per connection methods that - are responsible for processing data and packets corresponding to the connection. Exposes a - **VsockThreadBackend** structure. -- [txbuf.rs](src/txbuf.rs) - - Module to buffer data that is sent from the guest to the host. The module exposes a **LocalTxBuf** - structure. -- [vhost_user_vsock_thread.rs](src/vhost_user_vsock_thread.rs) - - Module exposes a **VhostUserVsockThread** structure. It also handles new host initiated - connections and provides interfaces for registering host connections with the epoll fd. Also - provides interfaces for iterating through the rx and tx queues. -- [vsock_conn.rs](src/vsock_conn.rs) - - Module introduces a **VsockConnection** structure that represents a single vsock connection - between the guest and the host. It also processes packets according to their type. -- [vhu_vsock.rs](src/vhu_vsock.rs) - - exposes the main vhost user vsock backend interface. - ## Usage Run the vhost-device-vsock device with unix domain socket backend: diff --git a/vhost-device-vsock/src/main.rs b/vhost-device-vsock/src/main.rs index ac2c95b..90e94df 100644 --- a/vhost-device-vsock/src/main.rs +++ b/vhost-device-vsock/src/main.rs @@ -1,5 +1,42 @@ // SPDX-License-Identifier: Apache-2.0 or BSD-3-Clause +//! # Implementation Design +//! +//! The crate introduces a vhost-device-vsock device that enables communication between an +//! application running in the guest (inside a VM) and an application running on the +//! host (outside the VM). +//! +//! The application running in the guest communicates over VM sockets (AF_VSOCK sockets). +//! On the host side, the communication mechanism depends on the backend: +//! - With the Unix domain socket backend (`--uds-path`), the host application communicates over AF_UNIX sockets +//! - With the vsock backend (`--forward-cid`, `--forward-listen`), the host application communicates over AF_VSOCK sockets +//! +//! The main components of the crate are split into various files as described below: +//! +//! - [`rxops`] +//! - Introduces various vsock operations that are enqueued into the rxqueue to be sent to the +//! guest. Exposes a **RxOps** structure. +//! - [`rxqueue`] +//! - rxqueue contains the pending rx operations corresponding to that connection. The queue is +//! represented as a bitmap as we handle connection-oriented connections. The module contains +//! various queue manipulation methods. Exposes a **RxQueue** structure. +//! - [`thread_backend`] +//! - Multiplexes connections between host and guest and calls into per connection methods that +//! are responsible for processing data and packets corresponding to the connection. Exposes a +//! **VsockThreadBackend** structure. +//! - [`txbuf`] +//! - Module to buffer data that is sent from the guest to the host. The module exposes a **LocalTxBuf** +//! structure. +//! - [`vhu_vsock_thread`] +//! - Module exposes a **VhostUserVsockThread** structure. It also handles new host-initiated +//! connections and provides interfaces for registering host connections with the epoll fd. Also +//! provides interfaces for iterating through the rx and tx queues. +//! - [`vsock_conn`] +//! - Module introduces a **VsockConnection** structure that represents a single vsock connection +//! between the guest and the host. It also processes packets according to their type. +//! - [`vhu_vsock`] +//! - Exposes the main vhost-user vsock backend interface. + mod rxops; mod rxqueue; mod thread_backend;