Merge pull request #1 from stsquad/virtio-msg-automation-base

Virtio msg automation base

.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,27 @@
+name: Deploy current state
+
+on:
+  push:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Tools
+        run: |
+          sudo apt install texlive-full
+
+      - name: Build Docs
+        run: |
+          make local-all
+          echo ${{ github.sha }} > Release.txt
+
+      - name: Create a Draft Release
+        uses: softprops/action-gh-release@v2
+        with:
+          draft: true
+          name: working-draft
+          files: |
+            Release.txt
+            virtio-v1.4-wd01.pdf

.github/workflows/test.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Tools
+        run: |
+          sudo apt install texlive-full
+
+      - name: Build HTML
+        run: |
+          make local-html

DIFFVERSION

@@ -1 +1 @@
-v1.2-cs01
+v1.3-wd02

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

admin-cmds-capabilities.tex

@@ -0,0 +1,249 @@
+\subsubsection{Device and driver capabilities}\label{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities}
+
+Device and driver capabilities are implemented as structured groupings for
+specific device functionality and their related resource objects. The device exposes
+its supported functionality and resource object limits through an administration
+command, utilizing the 'self group type.' Each capability possesses a
+unique ID. Through an administration command, also employing the
+'self group type,' the driver reports the functionality and
+resource object limits it intends to use. Before executing any operations
+related to the capabilities, the driver communicates these
+capabilities to the device. The driver is allowed to set the
+capability at any time, provided there are no pending operations
+at the device level associated with that capability.
+
+The device presents the supported capability IDs to the driver as a bitmap.
+The driver uses the administration command to learn about the
+supported capabilities bitmap.
+
+A capability consists of one or more fields, where each field can be a
+limit number, a bitmap, or an array of entries. In an array field,
+the structure depends on the specific array and the capability type.
+For each bitmap field, the driver sets the desired bits - but only out of
+those bits in a bitmap that the device has presented.
+The driver sets each limit number field to a desired value that
+is smaller than or equal to the value the device presented.
+Similarly, for an array field, the driver sets the desired capability
+entries but only out of the capability entries that the device has presented.
+
+It is anticipated that any necessary new fields for a capability will be
+appended to the structure's end, ensuring both forward and backward
+compatibility between the device and driver. Furthermore, to avoid
+indefinite growth of a single capability, it is expected that new
+functionality will lead to the creation of new capability rather
+than expanding existing ones.
+
+Capabilities are categorized into two ranges by their IDs, as listed:
+
+\begin{table}[H]
+\caption{Capability ids}
+\label{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / capability ids}
+\begin{tabularx}{\textwidth}{ |l|X| }
+\hline
+Id & Description  \\
+\hline \hline
+0x0000-0x07ff & Generic capability for all device types \\
+\hline
+0x0800-0x0fff & Device type specific capability \\
+\hline
+0x1000 - 0xFFFF & Reserved for future \\
+\hline
+\end{tabularx}
+\end{table}
+
+Common capabilities are listed:
+
+\begin{table}[H]
+\caption{Common capability ids}
+\label{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / Common capability ids}
+\begin{tabularx}{\textwidth}{ |l|l|X| }
+\hline
+Id & Name & Description  \\
+\hline \hline
+0x0000 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO-DEV-PARTS-CAP]{VIRTIO_DEV_PARTS_CAP} & Device parts capability \\
+\hline
+0x0001-0x07ff & - & Generic capability for all device types \\
+\hline
+\end{tabularx}
+\end{table}
+
+Device type specific capabilities are described separately for each device
+type under \field{Device and driver capabilities}.
+
+The device and driver capabilities commands are currently defined for self group
+type.
+
+\begin{enumerate}
+\item VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY
+\item VIRTIO_ADMIN_CMD_DEVICE_CAP_GET
+\item VIRTIO_ADMIN_CMD_DRIVER_CAP_SET
+\end{enumerate}
+
+\paragraph{VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO-ADMIN-CMD-CAP-ID-LIST-QUERY}
+
+This command queries the bitmap of capability ids
+listed in \ref{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / capability ids}.
+
+For the command VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY, \field{opcode} is set to 0x7.
+\field{group_member_id} is set to zero.
+
+This command has no command specific data.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_query_cap_id_result {
+        le64 supported_caps[];
+};
+\end{lstlisting}
+
+When the command completes successfully, \field{command_specific_result}
+is in the format \field{struct virtio_admin_cmd_query_cap_id_result}.
+
+\field{supported_caps} is an array of 64 bit values in little-endian byte
+order, in which a bit is set if the specific capability is supported.
+Thus, \field{supported_caps[0]} refers to the first 64-bit value in this
+array corresponding to capability ids 0 to
+63, \field{supported_caps[1]} is the second 64-bit value corresponding to
+capability ids 64 to 127, etc. For example, the array of size 2 including
+the values 0x3 in \field{supported_caps[0]} and 0x1 in
+\field{supported_caps[1]} indicates that only capability id 0, 1
+and 64 are supported.
+The length of the array depends on the supported capabilities - it is
+large enough to include bits set for all supported capability ids,
+that is the length can be calculated by starting with the largest
+supported capability id adding one, dividing by 64 and rounding up.
+In other words, for VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY the length of
+\field{command_specific_result} will be
+$DIV_ROUND_UP(max_cap_id, 64) * 8$ where DIV_ROUND_UP is integer division
+with round up and \field{max_cap_id} is the largest available capability id.
+
+The array is also allowed to be larger and to additionally include an arbitrary
+number of all-zero entries.
+
+\paragraph{VIRTIO_ADMIN_CMD_DEVICE_CAP_GET}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO-ADMIN-CMD-DEVICE-CAP-GET}
+
+This command gets the device capability for the specified capability
+id \field{id}.
+
+For the command VIRTIO_ADMIN_CMD_DEVICE_CAP_GET, \field{opcode} is set to 0x8.
+\field{group_member_id} is set to zero.
+
+\field{command_specific_data} is in format
+\field{struct virtio_admin_cmd_cap_get_data}.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_cap_get_data {
+        le16 id;
+        u8 reserved[6];
+};
+\end{lstlisting}
+
+\field{id} refers to the capability id listed in \ref{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / capability ids}.
+\field{reserved} is reserved for future use and set to zero.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_cap_get_result {
+        u8 cap_specific_data[];
+};
+\end{lstlisting}
+
+When the command completes successfully, \field{command_specific_result}
+is in the format \field{struct virtio_admin_cmd_cap_get_result} responded
+by the device. Each capability uses different capability specific
+\field{cap_specific_data} and is described separately.
+
+\paragraph{VIRTIO_ADMIN_CMD_DRIVER_CAP_SET}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO-ADMIN-CMD-DRIVER-CAP-SET}
+
+This command sets the driver capability, indicating to the device which capability
+the driver uses. The driver can set a resource object limit capability that is smaller
+than or equal to the value published by the device capability.
+If the capability is a set of flags, the driver sets the flag bits that are set
+in the device capability; the driver does not set any flag bits that are not
+set by the device.
+
+For the command VIRTIO_ADMIN_CMD_DRIVER_CAP_SET, \field{opcode} is set to 0x9.
+\field{group_member_id} is set to zero.
+The \field{command_specific_data} is in the format
+\field{struct virtio_admin_cmd_cap_set_data}.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_cap_set_data {
+        le16 id;
+        u8 reserved[6];
+        u8 cap_specific_data[];
+};
+\end{lstlisting}
+
+\field{id} refers to the capability id listed in \ref{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / capability ids}.
+\field{reserved} is reserved for future use and set to zero.
+
+There is no command specific result.
+When the command completes successfully, the driver capability is updated to
+the values supplied in \field{cap_specific_data}.
+
+\devicenormative{\paragraph}{Device and driver capabilities}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities}
+
+If the device supports capabilities, it MUST support the commands
+VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY,
+VIRTIO_ADMIN_CMD_DRIVER_CAP_SET, and
+VIRTIO_ADMIN_CMD_DEVICE_CAP_GET.
+
+For the VIRTIO_ADMIN_CMD_DRIVER_CAP_SET command,
+\begin{itemize}
+\item the device MUST support the setting of resource object limit driver capability to a
+value that is same as or smaller than the one reported in the device
+capability,
+\item the device MUST support the setting of capability flags bits to
+all or fewer bits than the one reported in the device capability;
+\end{itemize}
+this is applicable unless specific capability fields are explicitly
+stated as non-writable in the VIRTIO_ADMIN_CMD_DEVICE_CAP_GET command.
+
+The device MAY complete the command VIRTIO_ADMIN_CMD_DRIVER_CAP_SET with
+\field{status} set to VIRTIO_ADMIN_STATUS_EINVAL,
+if the capability resource object limit is larger than the value reported by the
+device's capability, or the capability flag bit is set, which is not set in
+the device's capability.
+
+The device MUST complete the commands VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY,
+VIRTIO_ADMIN_CMD_DRIVER_CAP_GET, and VIRTIO_ADMIN_CMD_DRIVER_CAP_SET
+with \field{status} set to VIRTIO_ADMIN_STATUS_EINVAL if the commands are not
+for the self group type.
+
+The device SHOULD complete the commands VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY,
+VIRTIO_ADMIN_CMD_DRIVER_CAP_GET, VIRTIO_ADMIN_CMD_DRIVER_CAP_SET with
+\field{status} set to VIRTIO_ADMIN_STATUS_EINVAL if the commands are not for the
+self group type.
+
+The device SHOULD complete the command VIRTIO_ADMIN_CMD_DRIVER_CAP_SET with
+\field{status} set to VIRTIO_ADMIN_STATUS_EBUSY if the command requests to disable
+a capability while the device still has valid resource objects related to the
+capability being disabled.
+
+The device SHOULD complete the comands VIRTIO_ADMIN_CMD_DEVICE_CAP_GET and
+VIRTIO_ADMIN_CMD_DRIVER_CAP_SET with \field{status} set to
+VIRTIO_ADMIN_STATUS_ENXIO if the capability id is not reported
+in command VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY.
+
+Upon a device reset, the device MUST reset all driver capabilities.
+
+The device SHOULD treat the driver resource limits as zero if the
+driver has not set such capability, unless otherwise explicitly stated.
+
+\drivernormative{\paragraph}{Device and driver capabilities}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities}
+
+The driver MUST send the command VIRTIO_ADMIN_CMD_DRIVER_CAP_SET before
+using any resource objects that depend on such a capability.
+
+In VIRTIO_ADMIN_CMD_DRIVER_CAP_SET command, the driver MUST NOT set
+\begin{itemize}
+\item the resource object limit value larger than the value reported
+by the device in the command VIRTIO_ADMIN_CMD_DEVICE_CAP_GET,
+\item flags bits which was not reported by the device in the command
+VIRTIO_ADMIN_CMD_DEVICE_CAP_GET,
+\item array entries not reported by the device in the command
+VIRTIO_ADMIN_CMD_DEVICE_CAP_GET.
+\end{itemize}
+
+The driver MUST NOT disable any of the driver capability using the command
+VIRTIO_ADMIN_CMD_DRIVER_CAP_SET when related resource objects
+are created but not destroyed.