virtio — archive

[PATCH 0/6] rework notifications terminology

From: Halil Pasic <[email protected]>
To: [email protected]
Date: Tue, 15 May 2018 09:10:00 -0000

On 05/14/2018 07:24 PM, Stefan Hajnoczi wrote: > On Thu, Apr 26, 2018 at 12:59:58PM +0200, Halil Pasic wrote: >> Let's introduce notifications as basic virtio facility early on. This >> shall not only increase the cohesion between core and transport >> description by having a well-defined place where notifications are >> introduced, but also give us the opportunity to explain some >> discrepancies. >> >> Namely notifications sent by the device to the driver were often called >> interrupts prior to v1.1. Getting completely rid of that terminology is >> however not viable in case of some names. >> >> Signed-off-by: Halil Pasic <[email protected]> >> --- >> Changelog: >> RFC -> v1: >> * implemented Connies suggestions (thanks Connie) >> --- >> content.tex | 36 ++++++++++++++++++++++++++++++++++++ >> 1 files changed, 36 insertions(+), 0 deletions(-) >> >> diff --git a/content.tex b/content.tex >> index 2e103cf..d7e2b18 100644 >> --- a/content.tex >> +++ b/content.tex >> @@ -8,6 +8,7 @@ device consists of the following parts: >> \begin{itemize} >> \item Device status field >> \item Feature bits >> +\item Notifications >> \item Device Configuration space >> \item One or more virtqueues >> \end{itemize} >> @@ -150,6 +151,41 @@ requirements documented within these legacy interface sections. >> Specification text within these sections generally does not apply >> to non-transitional devices. >> >> +\section{Notifications}\label{sec:Basic Facilities of a Virtio Device >> +/ Notifications} >> + >> +The notion of sending a notification (driver to device or device >> +to driver) plays an important role in this specification. The >> +modus operandi of the notifications is transport specific. >> + >> +There are three types of notifications: >> +\begin{itemize} >> +\item device configuration space notification >> +\item available buffers notification >> +\item used buffer notifications. >> +\end{itemize} > > "buffers" vs "buffer"; singular vs plural is likely to be used > inconsistently. Please choose one (either works). I will go with the singular (as originally intended). The majority also turned out singular -- no idea how I ended up with plural occasionally. $ git grep -i -e 'buffer *notif'|wc -l 62 $ git grep -i -e 'buffers *notif' content.tex:\item available buffers notification split-ring.tex:\item The driver sends an available buffers notification to the device if > > The previous patch said "the term configuration change notification in > kept where called so and consolidated where it's called configuration > change interrupt or similar", but here you say "device configuration > space notification". Please choose one name and use it consistently. > My bad. Seems the usage of 'configuration space notification' seems to be limited to this section. I will replace it with 'configuration change notification'. Many thanks for spotting these! >> + >> +Device configuration space notifications and used buffer notifications >> +are sent by the device, the recipient is the driver. A device >> +configuration space notification indicates that a configuration space >> +has changed; a used buffer notification indicates that a buffer may >> +have been made used on the virtqueue designated by the notification. >> + >> +Available buffer notifications are sent by the driver, the recipient is >> +the device. This type of notification indicates that a buffer may have >> +been made available on the virtqueue designated by the notification. >> + >> +The semantic, the transport-specific implementations and other >> +important aspects of the different notifications are specified in detail >> +in the following chapters > > Missing period. > Will fix. >> + >> +Most transports implement notifications sent by the device to the >> +driver using interrupts. Therefore, in previous versions of this >> +specification, these notifications were often called interrupts. >> +Some names defined in this specification still retain this interrupt >> +terminology. Occasionally, the term event is used to refer to >> +a notification or a receipt of a notification. >> + >> \section{Device Configuration Space}\label{sec:Basic Facilities of a Virtio Device / Device Configuration Space} >> >> Device configuration space is generally used for rarely-changing or >> -- >> 1.7.1 >> >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: [email protected] >> For additional commands, e-mail: [email protected] >>