[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [PATCH] Introducing virtio-increment-edu.
On Sun, Jun 16, 2019 at 03:01:37PM +0300, Yoni Bettan wrote: > 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 ? Not necessarily. But I think it's a good excercise and lessons learned can be added to a spec section explaining how to do this and what are the common mistakes to avoid. > * 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. So this is a problem. Elements are phys contigious chunks. Devices normally should not make raming requirements thus should not discuss elements at all. Saying it's a single element requires 4 bytes a contigious. What you should say is that driver makes a buffer available. Buffer consists of 4 device-readable bytes followed by 4 device-writeable bytes. > + > +Both the input and the output are in little-endian bytes order. I'd use a struct to describe the format. > + > +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. I would describe the behaviour, overflow and such here. > + > -- > 2.21.0 so as described this can be used by driver to test hypervisor latency I guess? Can we tweak this so hypervisor can test guest latency too? That would be a bit more useful ...
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]