RFC2

.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,37 @@
+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
+
+      - 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.4-wd01.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,129 @@
+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.
+
+How much of the bus level should be described in the virtio spec is one item
+we wish to discuss. This draft takes a middle approach by describing the bus
+level and defining some standard bus level messages that MAY be used by the bus.
+It also describes a range of bus messages that are implementation dependent.
+
+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 two 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
+
+* 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
+
+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-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
+  * Once developed this can provide a single kernel demo of virtio-msg
+  * [Work has begun on this]
+
+* 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 RFC1:
+* reformated document to better conform to the virtio spec style
+  - created an introduction chapter
+  - created a basic concept chapter
+  - created bus operation and device initialization and operation chapters
+  - reworked description of transport and bus messages
+  - attempted a "compliance chapter"
+  - reused spec macros
+  - switched to MAY/MUST/SHALL/SHOULD wording
+  - eliminate the use of terms front-end and back-end and use driver and device
+* made the maximum message size variable per bus instance
+* use "device number" for virtio-msg device instances on the bus instead of
+  adding yet another meaning for "device ID"
+* added the configuration generation count and its use
+* described types of things that can be done with bus specific messages
+  such as setup of bus level shared memory and out of band notifications
+* removed wording of notification being optional at transport level and
+  described bus level notifications of in-band, out-of-band, and polled
+  from driver side bus
+* removed the ERROR message from transport level. Errors should be handled at
+  the bus level to better match virtio-pci and virtio-mmio
+* removed bus level reset and status from standard bus messages
+* replaced bus messages DEVICE_{ADDED,REMOVED} with EVENT_DEVICE
+* changed names to GET_DEVICE_FEATURES and SET_DRIVER_FEATURES for clarity
+* made SET_DEVICE_STATE return new state as it may not match
+* Don't echo back the data in SET_VQUEUE (it cannot change)
+* defined request/response vs event message id ranges
+* match field size of next offset and wrap to virtio-{pci,mmio}
+* added maximum number of virtqueues to DEVICE_INFO
+* added admin virtqueue and SHM support
+
+This series is a work in progress and we acknowledge at least the following
+issues we need to work on:
+
+* Better conformance documentation
+* Publish an update to Arm FF-A spec that shows virtio-msg binding (work underway)
+* Publish virtio-msg-amp data structures and messages somewhere
+* Align implementations to this version and send PATCH v1 (non-rfc)
+
+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, they are not yet aligned with each
+other nor 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-new
+[5] https://github.com/arnopo/open-amp/commits/virtio-msg/

.prjinfo/sendmail/send.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+
+PREFIX="PATCH RFC v2"
+SUBJECT="virtio-msg transport layer"
+ME="$(git config --get user.name) <$(git config --get user.email)>"
+ME2="Mr Fake <wm.a.mills+mrfake@gmail.com>"
+REAL=virtio-comment@lists.linux.dev
+US=virtio-msg@lists.linaro.org
+CC="Bertrand Marquis <bertrand.marquis@arm.com>,
+Edgar E. Iglesias <edgar.iglesias@amd.com>,
+Arnaud Pouliquen <arnaud.pouliquen@foss.st.com>,
+Viresh Kumar <viresh.kumar@linaro.org>,
+Alex Bennee <alex.bennee@linaro.org>"
+
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+SINCE=${BRANCH}-patch-base
+IGNORE_TOP=0
+
+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.3-csd01
+virtio-v1.4-wd01

content.tex

@@ -638,6 +638,7 @@ \chapter{Virtio Transport Options}\label{sec:Virtio Transport Options}
 \input{transport-pci.tex}
 \input{transport-mmio.tex}
 \input{transport-ccw.tex}
+\input{transport-msg.tex}
 
 \chapter{Device Types}\label{sec:Device Types}
 

make-setup-generated.sh

@@ -1,16 +1,31 @@
 #! /bin/sh
+#
+# Generate version and metadata preamble for the document
+#
 
 DATESTR=${DATESTR:-`cat REVISION-DATE 2>/dev/null`}
-if [ x"$DATESTR" = x ]; then
-    ISODATE=`git show --format=format:'%cd' --date=iso | head -n 1`
-    DATESTR=`date -d "$DATE" +'%d %B %Y'`
+
+# If a second argument is passed we extract what we can from git
+# metadata (closest lightweight tag) and local tree status. This
+# allows locally generated copies to be tagged appropriately.
+#
+# The formal build process skips this.
+if ! test -z "$2"; then
+    TAG=$(git describe --dirty --tags)
+    # base date on now
+    DATESTR=$(date +'%d %B %Y')
+    COMMIT=$(git rev-parse --short HEAD)
+
+    # Finally check if we have un-committed changes in the tree
+    if ! git diff-index --quiet HEAD -- ; then
+        COMMIT="$COMMIT with local changes"
+    fi
 fi
 
 case "$1" in
     *-wd*)
 	STAGE=wd
 	STAGENAME="Working Draft"
-	WORKINGDRAFT=`basename "$1" | sed 's/.*-wd//'`
 	;;
     *-os*)
 	STAGE=os
@@ -41,6 +56,14 @@ esac
 
 VERSION=`echo "$1"| sed -e 's/virtio-v//' -e 's/-.*//'`
 
+#
+# Finally if we are building a local draft copy append the commit
+# details to the end of the working draft
+#
+if ! test -z "$COMMIT" ; then
+    STAGEEXTRATITLE="$STAGEEXTRATITLE (@ git $COMMIT)"
+fi
+
 #Prepend OASIS unless already there
 case "$STAGENAME" in
 	OASIS*)

makeall.sh

@@ -3,8 +3,8 @@
 export SPECDOC=${SPECDOC:-`cat REVISION`}
 export DATESTR=${DATESTR:-`cat REVISION-DATE`}
 ./makezip.sh
-./makehtml.sh
-./makepdf.sh
+./makehtml.sh $1
+./makepdf.sh $1
 zip $SPECDOC.zip $SPECDOC.pdf
 echo Generated file $SPECDOC.zip
 echo To change output file name, set SPECDOC environment variable

makehtml.sh

@@ -1,7 +1,7 @@
 #!/bin/sh
 
 SPECDOC=${SPECDOC:-`cat REVISION`}
-./make-setup-generated.sh "$SPECDOC"
+./make-setup-generated.sh "$SPECDOC" $1
 
 cp virtio-html.tex $SPECDOC.tex
 

makepdf.sh

@@ -1,7 +1,7 @@
 #!/bin/sh
 
 SPECDOC=${SPECDOC:-`cat REVISION`}
-./make-setup-generated.sh "$SPECDOC"
+./make-setup-generated.sh "$SPECDOC" $1
 
 rm $SPECDOC.aux $SPECDOC.pdf $SPECDOC.out
 xelatex --jobname $SPECDOC virtio.tex