Virtio-msg PATCH v1

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,10 +1,8 @@
-# Thanks for proposing a change to the Virtual I/O Device (VIRTIO) specification!
-The VIRTIO TC is not yet accepting pull requests at this time as they are not
-integrated with our voting system.
+# Thanks for proposing a change to the virtio-msg specification
 
-Instead, please
-- [] Propose the spec change (preferably as a patch) on the [mailing list](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback).
-- [] Open an [issue](https://github.com/oasis-tcs/virtio-spec/issues),
-     including the link to the proposal in the [mailing list archives](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback).
+This is not the same as proposing a change to the VirtIO spec. This
+repository is intended for preparing the virtio-msg transport
+specification before it's submission to the VIRTIO TC.
 
-The TC will vote and apply the change.
+If your intention was to suggestion to change to the upstream please
+propose the change as a patch to the [mailing list](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback).

.github/workflows/deploy.yaml

@@ -0,0 +1,38 @@
+name: Deploy current state
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: xu-cheng/texlive-action@v2
+        with:
+          scheme: full
+          run: |
+            apk add file font-liberation make zip
+            make local-all
+            echo ${{ github.sha }} > Release.txt
+            ls -l *.pdf
+
+      - name: Create Draft Release
+        id: create_release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{github.ref_name}}-${{ github.repository_owner }}-draft-v${{ github.run_number }}
+          release_name: Draft ${{ github.run_number }}
+          draft: false
+          prerelease: false
+
+      - name: Upload Release Asset
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ steps.create_release.outputs.upload_url }}
+          asset_path: virtio-v1.5-wd1.pdf
+          asset_name: ${{github.ref_name}}-${{ github.repository_owner }}-draft-v${{ github.run_number }}.pdf
+          asset_content_type: application/pdf

.github/workflows/test.yml

@@ -0,0 +1,15 @@
+name: CI
+
+on: [pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: xu-cheng/texlive-action@v2
+        with:
+          scheme: full
+          run: |
+            apk add file make zip
+            make local-html

.prjinfo/sendmail/cover.txt

@@ -0,0 +1,122 @@
+This series adds the virtio-msg transport layer.
+
+The individuals and organizations involved in this effort have had difficulty in
+using the existing virtio-transports in various situations and desire to add one
+more transport that performs its transport layer operations by sending and
+receiving messages.
+
+Implementations of virtio-msg will normally be done in multiple layers:
+* common / device level
+* bus level
+
+The common / device level defines the messages exchanged between the driver
+and a device. This common part should lead to a common driver holding most
+of the virtio specifics and can be shared by all virtio-msg bus implementations.
+The kernel implementation in [3] shows this separation. As with other transport
+layers, virtio-msg should not require modifications to existing virtio device
+implementations (virtio-net, virtio-blk etc). The common / device level is the
+main focus of this version of the patch series.
+
+The virtio-msg bus level implements the normal things a bus defines
+(enumeration, dma operations, etc) but also implements the message send and
+receive operations. A number of bus implementations are envisioned,
+some of which will be reusable and general purpose. Other bus implementations
+might be unique to a given situation, for example only used by a PCIe card
+and its driver.
+
+The standard bus messages are an effort to avoid different bus implementations
+doing the same thing in different ways for no good reason. However the
+different environments will require different things. Instead of trying to
+anticipate all needs and provide something very abstract, we think
+implementation specific messages will be needed at the bus level. Over time,
+if we see similar messages across multiple bus implementations, we will move to
+standardize a bus level message for that.
+
+We are working on a few reusable bus implementations:
+
+* virtio-msg-ffa based on Arm FF-A interface for use between:
+  * normal world and secure world
+  * host and VM or VM to VM
+  * Can be used w/ or with out a hypervisor
+  * Any Hypervisor that implements FF-A can be used
+  * We have this working with pKVM and Xen
+  * We have this working with Trusty and OP-TEE
+
+* virtio-msg-amp for use between heterogenous systems
+  * The main processors and its co-processors on an AMP SOC
+  * Two or more systems connected via PCIe
+  * Minimal requirements: bi-directional interrupts and
+    at least one shared memory area
+  * hvac-demo has 2 demos of this
+  * This is working on two hardware platforms
+
+* virtio-msg-loopback for userspace implemented devices
+  * Allows user space to provide devices to its own kernel
+  * This is similar to fuse, cuse or loopback block devices but for virtio
+  * hvac-demo has a demo
+
+We also anticipate a few more:
+
+* virtio-msg-xen specific to Xen
+  * Usable on any Xen system (including x86 where FF-A does not exist)
+  * Using Xen events and page grants
+
+* virtio-msg over admin virtqueues
+  * This allows any virtio-pci device that supports admin virtqueues to also
+    support a virtio-msg bus that supports sub devices
+  * [We are looking for collaborators for this work]
+
+Changes since RFC2:
+
+Spec Functional:
+* Made the common message header 8 bytes and added a token for optional use
+  when parallel outstanding requests are possible
+* Made the 8 byte fields align to 8 byte offsets.
+  This effects the {SET,GET}_VQUEUE messages
+* Many conformance cases have been tightened.
+
+Spec Editorial:
+* Major restructure to better align with virtio spec
+  * Conformance model now matches other transports
+  * Use C structures to define messages instead of tables
+* Added a section to describe how responses are matched to requests
+  This includes the use of the new token field
+* Redefined / better described error handling between transport and bus
+  layers to eliminate the need for the bus to generate fake response messages
+* Included editorial feedback from RFC2
+
+Eco-system:
+* Added virtio-msg-loopback demo
+* Arm has published the first draft of the virtio-msg over FFA spec [6]
+* virtio-msg over FFA has been demonstrated with both Trusty and OP-TEE
+  secure world
+* LKML RFC has been sent [7]
+* QEMU RFC has been sent [8]
+
+This is the first non-RFC patch series. The known short comings have been
+addressed. We ask for review in earnest on this series and thank you for
+any feedback you can provide.
+
+Background info and work in progress implementations:
+* HVAC project page with intro slides [1]
+* HVAC demo repo w/ instructions in README.md [2]
+* Kernel w/ virtio-msg common level and ffa support [3]
+* QEMU w/ support for one form of virtio-msg-amp [4]
+* Portable RTOS library w/ one form of virtio-msg-amp [5]
+
+In addition to the QEMU system based demos in the hvac-demo repo, we also have
+two hardware systems running:
+* AMD x86 + AMD Arm Versal connected via PCIe
+* ST STM32MP157 A7 Linux using virtio-i2c provided by M4 Zephyr
+
+Please note that although the demos work, a few have not been aligned
+with this version of the spec.
+
+[1] https://linaro.atlassian.net/wiki/spaces/HVAC/overview
+[2] https://github.com/wmamills/hvac-demo
+[3] https://git.kernel.org/pub/scm/linux/kernel/git/vireshk/linux.git/log/?h=virtio/msg
+[4] https://github.com/edgarigl/qemu/commits/edgar/virtio-msg-rfc/
+[5] https://github.com/arnopo/open-amp/commits/virtio-msg/
+[6] https://documentation-service.arm.com/static/68f647791134f773ab3f0a7c
+[7] https://lore.kernel.org/all/[email protected]/
+[8] https://mail.gnu.org/archive/html/qemu-devel/2025-10/msg07438.html

.prjinfo/sendmail/send.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+
+PREFIX="PATCH v1"
+SUBJECT="virtio-msg transport layer"
+ME="$(git config --get user.name) <$(git config --get user.email)>"
+ME2="Mr Fake <[email protected]>"
+[email protected]
+[email protected]
+CC="Bertrand Marquis <[email protected]>,
+Edgar E. Iglesias <[email protected]>,
+Arnaud Pouliquen <[email protected]>,
+Viresh Kumar <[email protected]>,
+Alex Bennee <[email protected]>,
+Armelle Laine <[email protected]>"
+
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+SINCE=${BRANCH}-patch-base
+IGNORE_TOP=1
+
+MY_DIR=$(dirname $0)
+BASE_DIR=$(cd $MY_DIR/../..; pwd)
+
+case $1 in
+--for-real)
+    TO="$REAL"
+    ;;
+--just-us)
+    TO="$US"
+    ;;
+--just-me)
+    TO="$ME"
+    CC="$ME2"
+    EXTRA_SEND_OPTS="--no-signed-off-by-cc"
+    ;;
+--dry-run)
+    TO="$ME"
+    EXTRA_SEND_OPTS="--dry-run"
+    ;;
+*)
+    echo "Need --for-real, --just-us, or --just-me"; exit 2
+    ;;
+esac
+
+rm -rf "$BASE_DIR"/.prjinfo/sendmail/patches
+
+git format-patch -o "$BASE_DIR"/.prjinfo/sendmail/patches --cover-letter \
+    --subject-prefix="$PREFIX" ${SINCE}..HEAD~${IGNORE_TOP}
+
+# fixup the cover letter
+(
+    cd "$BASE_DIR"/.prjinfo/sendmail/patches;
+    sed -i -e "s/\*\*\* SUBJECT HERE \*\*\*/${SUBJECT}/"  0000-cover-letter.patch
+    sed -i -e "/\*\*\* BLURB HERE \*\*\*/ r ../cover.txt" 0000-cover-letter.patch
+    sed -i -e "/\*\*\* BLURB HERE \*\*\*/ d" 0000-cover-letter.patch
+)
+
+git send-email --to="$TO" --cc="$CC" $EXTRA_SEND_OPTS \
+    "$BASE_DIR"/.prjinfo/sendmail/patches

Makefile

@@ -0,0 +1,33 @@
+# -*- Mode: makefile -*-
+#
+# Basic Makefile to aid automation of document building
+#
+
+.PHONY: all local
+all:
+	./makeall.sh
+
+local-all:
+	./makeall.sh local
+
+.PHONY: html local-html
+
+html:
+	./makehtml.sh
+
+local-html:
+	./makehtml.sh local
+
+.PHONY: clean
+clean:
+	git clean -fd
+
+.PHONY: help
+help:
+	@echo "Build the VIRTIO specification documents."
+	@echo ""
+	@echo "Possible operations are:"
+	@echo
+	@echo " $(MAKE)         Build everything"
+	@echo " $(MAKE) html    Build local html"
+	@echo " $(MAKE) clean   Remove all intermediate files"

REVISION

@@ -1 +1 @@
-virtio-v1.4-csprd01
+virtio-v1.5-wd1

commands.tex

@@ -7,9 +7,10 @@
 % How we format a field name
 \newcommand{\field}[1]{\emph{#1}}
 
-% Mark a normative section (driver or device)
+% Mark a normative section (driver, device, or bus)
 \newcommand{\drivernormative}[3]{#1{Driver Requirements: #2}\label{drivernormative:#3}}
 \newcommand{\devicenormative}[3]{#1{Device Requirements: #2}\label{devicenormative:#3}}
+\newcommand{\busnormative}[3]{#1{Bus Requirements: #2}\label{busnormative:#3}}
 \newcounter{clausecounter}
 \newcommand{\conformance}[2]{
 	\stepcounter{clausecounter}