samples: drivers: virtualization: add vhost sample application

Add sample application demonstrating vhost driver usage for
VIRTIO backend implementations. Includes basic setup and
configuration examples for Xen MMIO VirtIO backend.

Signed-off-by: TOKITA Hiroshi <[email protected]>

Author: soburi

samples/drivers/virtualization/vhost/CMakeLists.txt

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(vhost)
+
+target_sources(app PRIVATE src/main.c)

samples/drivers/virtualization/vhost/README.rst

@@ -0,0 +1,52 @@
+.. zephyr:code-sample:: vhost
+   :name: Vhost sample application
+
+Overview
+********
+
+This sample demonstrates the use of the vhost driver subsystem for implementing
+VIRTIO backends in Zephyr. The application shows how to:
+
+* Initialize and configure vhost devices
+* Handle VIRTIO queue operations
+* Process guest requests using the vringh utility
+* Implement a basic VIRTIO backend for Xen virtualization
+
+The sample sets up a vhost device that can communicate with VIRTIO frontend
+drivers in guest virtual machines, specifically designed for Xen MMIO
+virtualization environments.
+
+Requirements
+************
+
+This sample requires:
+
+* A Xen hypervisor environment
+* Xen domain management tools
+* A board that supports Xen virtualization (e.g., xenvm)
+
+Building and Running
+********************
+
+This application can be built and executed on Xen as follows:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/drivers/virtualization/vhost
+   :host-os: unix
+   :board: xenvm
+   :goals: run
+   :compact:
+
+The application will initialize the vhost subsystem and wait for VIRTIO
+frontend connections from guest domains. When a guest connects and sends
+requests, the sample will process them and provide responses.
+
+Expected Output
+***************
+
+When running successfully, you should see output similar to::
+
+   *** Booting Zephyr OS build zephyr-v3.x.x ***
+   [00:00:00.000,000] <inf> vhost: VHost device ready
+   [00:00:00.000,000] <dbg> vhost: queue_ready_handler(dev=0x..., qid=0, data=0x...)
+   [00:00:00.000,000] <dbg> vhost: vringh_handler: queue_id=0

samples/drivers/virtualization/vhost/boards/xenvm.overlay

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) 2025 TOKITA Hiroshi
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/ {
+	vhost: xen-vhost-mmio {
+		compatible = "xen,vhost-mmio";
+		device-id = <4>;
+		vendor-id = <0x7a707972>; /* "zphy" */
+		num-queues = <2>;
+		queue-size-max= <16>;
+		base = <0x2000000>;
+	};
+};

samples/drivers/virtualization/vhost/boards/xenvm_xenvm_gicv3.overlay

@@ -0,0 +1,7 @@
+/*
+ * Copyright (c) 2025 TOKITA Hiroshi
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "xenvm.overlay"

samples/drivers/virtualization/vhost/prj.conf

@@ -0,0 +1,6 @@
+CONFIG_VHOST=y
+CONFIG_LOG=y
+CONFIG_HEAP_MEM_POOL_SIZE=8388608
+CONFIG_LOG_MODE_IMMEDIATE=y
+CONFIG_LOG_DEFAULT_LEVEL=3
+CONFIG_VHOST_LOG_LEVEL_DBG=y

samples/drivers/virtualization/vhost/sample.yaml

@@ -0,0 +1,20 @@
+sample:
+  description: VHost driver sample for VIRTIO backend implementation
+  name: vhost
+common:
+  integration_platforms:
+    - xenvm
+  platform_allow: xenvm
+  harness: console
+  harness_config:
+    type: multi_line
+    regex:
+      - "VHost device ready"
+      - "VHost sample application started"
+  timeout: 60
+  depends_on: vhost
+tests:
+  sample.drivers.virtualization.vhost:
+    tags: drivers virtualization vhost xen
+    min_ram: 32
+    extra_args: CONFIG_LOG_MODE_IMMEDIATE=y

samples/drivers/virtualization/vhost/src/main.c

@@ -0,0 +1,106 @@
+/*
+ * Copyright (c) 2025 TOKITA Hiroshi
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/drivers/vhost.h>
+#include <zephyr/drivers/vhost/vringh.h>
+#include <zephyr/logging/log.h>
+
+LOG_MODULE_REGISTER(vhost);
+
+struct vhost_iovec riovec[16];
+struct vhost_iovec wiovec[16];
+
+struct vringh_iov riov = {
+	.iov = riovec,
+	.max_num = 16,
+};
+
+struct vringh_iov wiov = {
+	.iov = wiovec,
+	.max_num = 16,
+};
+
+struct vringh vrh_inst;
+
+void vringh_handler(struct vringh *vrh)
+{
+	LOG_DBG("%s: queue_id=%lu", __func__, vrh->queue_id);
+	uint16_t head;
+
+	while (true) {
+		int ret = vringh_getdesc(vrh, &riov, &wiov, &head);
+
+		if (ret < 0) {
+			LOG_ERR("vringh_getdesc failed: %d", ret);
+			return;
+		}
+
+		if (ret == 0) {
+			return;
+		}
+
+		/* Process writable iovecs */
+		for (uint32_t s = 0; s < wiov.used; s++) {
+			uint8_t *dst = wiov.iov[s].iov_base;
+			uint32_t len = wiov.iov[s].iov_len;
+
+			LOG_DBG("%s: addr=%p len=%u", __func__, dst, len);
+
+			for (uint32_t i = 0; i < len; i++) {
+				sys_write8(i, (mem_addr_t)&dst[i]);
+			}
+		}
+
+		barrier_dmem_fence_full();
+
+		uint32_t total_len = 0;
+		for (uint32_t i = 0; i < wiov.used; i++) {
+			total_len += wiov.iov[i].iov_len;
+		}
+
+		vringh_complete(vrh, head, total_len);
+
+		if (vringh_need_notify(vrh) > 0) {
+			vringh_notify(vrh);
+		}
+
+		/* Reset iovecs for next iteration */
+		vringh_iov_reset(&riov);
+		vringh_iov_reset(&wiov);
+	}
+}
+
+void queue_ready_handler(const struct device *dev, uint16_t qid, void *data)
+{
+	LOG_DBG("%s(dev=%p, qid=%u, data=%p)", __func__, dev, qid, data);
+
+	/* Initialize iovecs before descriptor processing */
+	vringh_iov_init(&riov, riov.iov, riov.max_num);
+	vringh_iov_init(&wiov, wiov.iov, wiov.max_num);
+
+	int err = vringh_init_device(&vrh_inst, dev, qid, vringh_handler);
+	if (err) {
+		LOG_ERR("vringh_init_device failed: %d", err);
+		return;
+	}
+}
+
+int main(void)
+{
+	const struct device *device = DEVICE_DT_GET(DT_NODELABEL(vhost));
+
+	if (!device_is_ready(device)) {
+		LOG_ERR("VHost device not ready");
+		return -ENODEV;
+	}
+
+	LOG_INF("VHost device ready");
+	vhost_set_ready_callback(device, queue_ready_handler, (void *)device);
+
+	LOG_INF("VHost sample application started, waiting for guest connections...");
+	k_sleep(K_FOREVER);
+	return 0;
+}