[PATCH] Introducing virtio-increment-edu.

[Yoni Bettan <ybettan@redhat.com>]

The main goal is to create an educational example to be used as template or
guideline for contributors when they wish to create a new virtio
device and to document "the right way" to do so.

The device functionality is simple as possible so contributors can have
their focus on the virtio protocol rather on the device functionality to
give them an "easy start".

It consists of several parts:

    1. The device specification
        * this patch content

    2. The device implementation for Qemu-KVM hypervisor
        * it will hopefully be added to the Qemu project
        * for now it can be found at https://github.com/ybettan/qemu/blob/\
                virtio/hw/virtio/virtio-example.c

    3. The device driver for linux
        * it will hopefully be added to linux
        * for now it can be found at https://github.com/ybettan/\
                QemuDeviceDrivers/blob/master/virtio/virtio_example_driver.c

    4. A blog on virtio
        * introducing the virtio concept
        * gives some motivation for virtio-devices to be used
        * bring extra documentation on "how to write":
            - device specification
            - device implementation
            - device driver for linux
        * it can be found at https://howtovms.wordpress.com

Signed-off-by: Yoni Bettan <ybettan@redhat.com>
---


Here are some questions I would like to here your opinion on:

    * do you think such device should be included in the virtio-specification ?

    * do you think the documentation for the whole process (spec->device->driver)
      should be blog (current state) or a github repository so others can
      contribute to it ?

    * how does the virtio-ID should be chosen for this device ?
        - specification says:
            # "PCI Device ID 0x1000 through 0x107F inclusive is a virtio device"
            # "The PCI Device ID is calculated by adding 0x1040 to the Virtio
               Device ID"
            # under "what device number":
              "Meanwhile for experimental drivers, use 65535 and work backwards"
        - those conditions doesn't fit together


 conformance.tex          | 16 +++++++++++
 content.tex              |  1 +
 virtio-increment-edu.tex | 62 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 79 insertions(+)
 create mode 100644 virtio-increment-edu.tex

diff --git a/conformance.tex b/conformance.tex
index 42f702a..66f401a 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -183,6 +183,14 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \item \ref{drivernormative:Device Types / Socket Device / Device Operation / Device Events}
 \end{itemize}
 
+\conformance{\subsection}{Increment-edu Driver Conformance}\label{sec:Conformance / Driver Conformance / Increment-edu Driver Conformance}
+
+An Increment-edu driver MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{drivernormative:Device Types / Increment-edu Device / Device Operation}
+\end{itemize}
+
 \conformance{\section}{Device Conformance}\label{sec:Conformance / Device Conformance}
 
 A device MUST conform to the following normative statements:
@@ -336,6 +344,14 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \item \ref{devicenormative:Device Types / Socket Device / Device Operation / Receive and Transmit}
 \end{itemize}
 
+\conformance{\subsection}{Increment-edu Device Conformance}\label{sec:Conformance / Device Conformance / Increment-edu Device Conformance}
+
+An Increment-edu device MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{devicenormative:Device Types / Increment-edu Device / Device Operation}
+\end{itemize}
+
 \conformance{\section}{Legacy Interface: Transitional Device and Transitional Driver Conformance}\label{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}
 A conformant implementation MUST be either transitional or
 non-transitional, see \ref{intro:Legacy
diff --git a/content.tex b/content.tex
index 193b6e1..be154db 100644
--- a/content.tex
+++ b/content.tex
@@ -5594,6 +5594,7 @@ \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
 \input{virtio-input.tex}
 \input{virtio-crypto.tex}
 \input{virtio-vsock.tex}
+\input{virtio-increment-edu.tex}
 
 \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
 
diff --git a/virtio-increment-edu.tex b/virtio-increment-edu.tex
new file mode 100644
index 0000000..59fc44a
--- /dev/null
+++ b/virtio-increment-edu.tex
@@ -0,0 +1,62 @@
+\section{Increment-edu Device}\label{sec:Device Types / Increment-edu Device}
+
+The virtio Increment-edu device is a simple virtual incremental device that
+increment the number represented by its input by 1.
+Read and write requests are placed in the queue, and serviced
+(probably out of order) by the device.
+The main purpose of this device is to be used as a reference for new contributors
+if they wish to create a new virtio device, therefore, it contains minimum
+functionality and mostly describe the building blocks of the virtio-protocol.
+
+\subsection{Device ID}\label{sec:Device Types / Increment-edu Device / Device ID}
+  21
+
+\subsection{Virtqueues}\label{sec:Device Types / Increment-edu Device / Virtqueues}
+\begin{description}
+\item[0] requestq
+\end{description}
+
+\subsection{Feature bits}\label{sec:Device Types / Increment-edu Device / Feature bits}
+
+None currently defined.
+
+\subsection{Device configuration layout}\label{sec:Device Types / Increment-edu Device / Device configuration layout}
+
+None currently defined.
+
+\subsection{Device Initialization}\label{sec:Device Types / Increment-edu Device / Device Initialization}
+
+\begin{enumerate}
+\item The virtqueue is initialized
+\end{enumerate}
+
+\subsection{Device Operation}\label{sec:Device Types / Increment-edu Device / Device Operation}
+
+When the driver need computation, it places a request that consist of both
+input and output elements into the queue.
+The first element is used as an input for the device and contain a 4 bytes
+integer, and the second is given for the device to fill the result in it as a
+4 bytes integer indeed.
+
+Both the input and the output are in little-endian bytes order.
+
+The device is increasing this integer by 1, meaning the LSB will be
+increased by 1 and if needed the carry will be carried to the next byte.
+
+If the device get a number that is out of the range of a 4 bytes integer only
+the lower bytes that fit the size of a 4 bytes integer will represent the input
+and the upper bytes will be ignored.
+If the result is out of range then only the lower bytes will be written as
+result as well.
+
+\drivernormative{\subsubsection}{Device Operation}{Device Types / Increment-edu Device / Device Operation}
+
+The driver MUST place the 2 elements in the same request (buffer) in order to
+make a request atomically handled by the device, the first element contains the
+input and should be read-only and the second should be write-only.
+
+\devicenormative{\subsubsection}{Device Operation}{Device Types / Increment-edu Device / Device Operation}
+
+The device MUST place the result inside the output element allocated by the
+driver.
+
-- 
2.21.0