[virtio-dev] [PATCH] Add virtio parameter server device specification

[virtio-dev] [PATCH] Add virtio parameter server device specification

[Hao Chen]

This patch introduces a new type of device: parameter server. The device
acts as a key-value store and the driver can read from, write to or
subscribe to the properties in the server.

Signed-off-by: Hao Chen <chenhaosjtuacm@google.com>
---
 conformance.tex |  26 +++++--
 content.tex     |   1 +
 virtio-ps.tex   | 188 ++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 211 insertions(+), 4 deletions(-)
 create mode 100644 virtio-ps.tex

diff --git a/conformance.tex b/conformance.tex
index a164cbb..0d6b1a5 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -29,8 +29,9 @@ \section{Conformance Targets}\label{sec:Conformance
/ Conformance Targets}
 \ref{sec:Conformance / Driver Conformance / IOMMU Driver Conformance},
 \ref{sec:Conformance / Driver Conformance / Sound Driver Conformance},
 \ref{sec:Conformance / Driver Conformance / Memory Driver Conformance},
-\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance} or
-\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance}.
+\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance},
+\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance} or
+\ref{sec:Conformance / Driver Conformance / Parameter Server Driver
Conformance}.

     \item Clause \ref{sec:Conformance / Legacy Interface:
Transitional Device and Transitional Driver Conformance}.
   \end{itemize}
@@ -52,8 +53,9 @@ \section{Conformance Targets}\label{sec:Conformance
/ Conformance Targets}
 \ref{sec:Conformance / Device Conformance / IOMMU Device Conformance},
 \ref{sec:Conformance / Device Conformance / Sound Device Conformance},
 \ref{sec:Conformance / Device Conformance / Memory Device Conformance},
-\ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance} or
-\ref{sec:Conformance / Device Conformance / SCMI Device Conformance}.
+\ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance},
+\ref{sec:Conformance / Device Conformance / SCMI Device Conformance}or
+\ref{sec:Conformance / Device Conformance / Parameter Server Device
Conformance}.

     \item Clause \ref{sec:Conformance / Legacy Interface:
Transitional Device and Transitional Driver Conformance}.
   \end{itemize}
@@ -288,6 +290,14 @@ \section{Conformance
Targets}\label{sec:Conformance / Conformance Targets}
 \item \ref{drivernormative:Device Types / SCMI Device / Device
Operation / Setting Up eventq Buffers}
 \end{itemize}

+\conformance{\subsection}{Parameter Server Driver
Conformance}\label{sec:Conformance / Driver Conformance / Parameter
Server Driver Conformance}
+
+A parameter server driver MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{drivernormative:Device Types / Parameter Server / Device Operation}
+\end{itemize}
+
 \conformance{\section}{Device Conformance}\label{sec:Conformance /
Device Conformance}

 A device MUST conform to the following normative statements:
@@ -527,6 +537,14 @@ \section{Conformance
Targets}\label{sec:Conformance / Conformance Targets}
 \item \ref{devicenormative:Device Types / SCMI Device / Device
Operation / Shared Memory Operation}
 \end{itemize}

+\conformance{\subsection}{Parameter Server Device
Conformance}\label{sec:Conformance / Device Conformance / Parameter
Server Device Conformance}
+
+A parameter server device MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{devicenormative:Device Types / Parameter Server / 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 9232d5c..b980a93 100644
--- a/content.tex
+++ b/content.tex
@@ -6568,6 +6568,7 @@ \subsubsection{Legacy Interface: Framing
Requirements}\label{sec:Device
 \input{virtio-mem.tex}
 \input{virtio-i2c.tex}
 \input{virtio-scmi.tex}
+\input{virtio-ps.tex}

 \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}

diff --git a/virtio-ps.tex b/virtio-ps.tex
new file mode 100644
index 0000000..fa0930a
--- /dev/null
+++ b/virtio-ps.tex
@@ -0,0 +1,188 @@
+\section{Parameter Server}\label{sec:Device Types / Parameter Server}
+
+The parameter server device manages a set of values with unique
property IDs. These values may
+either be static (i.e. have a constant value) or be dynamic (i.e.
value may change over time).
+The driver can get and set values, get value configurations,
subscribe and unsubscribe dynamic
+properties from the device. The device processes the requests from
the driver, enforces the value
+access rules, and may potentially alter the behavior of external
systems as a result of driver
+operations.
+
+\subsection{Device ID}\label{sec:Device Types / Parameter Server / Device ID}
+
+38
+
+\subsection{Virtqueues}\label{sec:Device Types / Parameter Server / Virtqueues}
+
+\begin{description}
+\item[0] cmdq
+\item[1] eventq
+\end{description}
+
+\subsection{Feature Bits}\label{sec:Device Types / Parameter Server /
Feature Bits}
+
+None currently defined.
+
+\subsection{Device Configuration Layout}\label{sec:Device Types /
Parameter Server / Device Configuration Layout}
+
+\begin{lstlisting}
+struct virtio_parameter_server_config {
+    char name[128];
+};
+\end{lstlisting}
+
+A device configuration space only contains the name of the device,
which can be used by the
+userspace for identification.
+
+\subsection{Device Initialization}
+
+\begin{enumerate}
+\item The virtqueues are initialized.
+\end{enumerate}
+
+\subsection{Device Operation}\label{sec:Device Types / Parameter
Server / Device Operation}
+
+The driver puts the requests to the cmdq virtqueue. The responses
from the device also go into
+the cmdq virtqueue. Updates on the subscribed values are put into the
eventq virtqueue. The
+\field{prop_id}, \field{prop_item_id} pair is the primary key for the
values stored in the
+parameter server, while the values with the same \field{prop_id}
share the same configuration.
+Subscriptions are also on \field{prop_id}.
+
+The layout of requests and responses are defined below:
+
+\begin{lstlisting}
+struct virtio_parameter_server_request {
+    le64 timestamp;
+    le32 prop_id;
+    le32 prop_item_id;
+    le32 payload_size;
+    u8 op;
+    u8 payload[<actual payload size>];
+};
+
+struct virtio_parameter_server_response {
+    le64 timestamp;
+    le32 prop_id;
+    le32 prop_item_id;
+    le32 payload_size;
+    u16 op;
+    u16 ret_value;
+    u8 payload[<actual payload size>];
+};
+
+/* Reserved prop_id and prop_item_id */
+#define VIRTIO_PARAMETER_SERVER_OP_ALL_PROP INT_MAX
+
+/* Supported operations */
+#define VIRTIO_PARAMETER_SERVER_OP_INVALID 0
+#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_CONFIG 1
+#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_VALUE 2
+#define VIRTIO_PARAMETER_SERVER_OP_SET_PROP_VALUE 3
+#define VIRTIO_PARAMETER_SERVER_OP_SUBSCRIBE_PROP 4
+#define VIRTIO_PARAMETER_SERVER_OP_UNSUBSCRIBE_PROP 5
+\end{lstlisting}
+
+The layout of messages in eventq is defined below:
+
+\begin{lstlisting}
+struct virtio_parameter_server_event_msg {
+    le64 timestamp;
+    le32 prop_id;
+    le32 prop_item_id;
+    le32 payload_size;
+    u8 payload[<actual payload size>];
+};
+\end{lstlisting}
+
+There will be exactly one response for each request in the cmdq, even
if \field{op} is invalid. For some operations,
+the \field{payload} of requests and/or responses may be empty. If the
\field{payload} is non-empty, it can be either
+property configuration(s) or value. The \field{payload} of messages
in the eventq virtqueue is always value.
+
+\subsubsection{Property Configuration Layout}\label{sec:Device Types
/ Parameter Server / Device Operation / Property Configuration Layout}
+
+\begin{lstlisting}
+struct virtio_parameter_server_prop_config {
+    le32 prop_id;
+    le32 mode;
+    le32 min_sample_freq;
+    le32 max_sample_freq;
+    le32 encoding[5];
+    le32 param_size;
+    char desc[256];
+    u8 params[<actual param size>];
+};
+\end{lstlisting}
+
+while \field{mode} is the bitwise-or-combination of the following:
+
+\begin{lstlisting}
+enum virtio_parameter_server_prop_mode {
+    /* access */
+    VIRTIO_PARAMETER_SERVER_M_READ = 0x1,
+    VIRTIO_PARAMETER_SERVER_M_WRITE = 0x2,
+    VIRTIO_PARAMETER_SERVER_M_READ_WRITE = 0x3,
+
+    /* change */
+    VIRTIO_PARAMETER_SERVER_M_STATIC = 0x4,
+    VIRTIO_PARAMETER_SERVER_M_MUTABLE = 0x8,
+    VIRTIO_PARAMETER_SERVER_M_CONTINUOUS = 0xc,
+};
+\end{lstlisting}
+
+Both VIRTIO_PARAMETER_SERVER_M_MUTABLE and
VIRTIO_PARAMETER_SERVER_M_CONTINUOUS are dynamic
+properties. A VIRTIO_PARAMETER_SERVER_M_MUTABLE value will change due
to the set value operation
+from the driver, or actions of the external system; a
VIRTIO_PARAMETER_SERVER_M_CONTINUOUS value
+is expected to be generated by means of a sensor updating at a steady
frequency.
+
+The properties with the same \field{prop_id} share the configuration.
\field{min_sample_freq} and
+\field{max_sample_freq} are the sampling rate range for the
+\field{VIRTIO_PARAMETER_SERVER_M_CONTINUOUS} values. \field{desc} is
the optional string
+description. \field{params} are for the customized configuration parameters.
+
+The integer array \field{encoding} specifies the number of different
primitive value in the
+property value.
+
+\begin{lstlisting}
+#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT64 0
+#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_FLOAT64 1
+#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT32 2
+#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_BYTE 3
+#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_HAS_STRING 4
+
+#define VIRTIO_PARAMETER_SERVER_VARIABLE_LENGTH -2
+\end{lstlisting}
+
+If the driver asks for ALL property configurations, then the \field{payload} of
+virtio_parameter_server_response will be multiple property
configurations, serialized 1-by-1.
+
+\subsubsection{Property Value Layout}\label{sec:Device Types /
Parameter Server / Device Operation / Property Value Layout}
+
+The property value payload begins with 5 arrays. The order is the
same as the \field{encoding} array defined above.
+For each array, it begins with a 32-bit integer for length (number of
elements). Empty array will be a 32-bit 0, while
+-1 means the array does not exist. The elements follows the length,
and the size of the encoded array will be padded
+to 4 bytes. String is encoded as char16_t, zero-terminated array.
+
+After the arrays, there may be customized data, which is encoded as a
byte array.
+
+\drivernormative{\subsubsection}{Device Operation}{Device Types /
Parameter Server / Device Operation}
+
+The driver MUST NOT send undefined ops.
+
+The driver MUST NOT put device-readable descriptors into the eventq.
+
+The payload size of requests MUST be padded to 4 bytes.
+
+\devicenormative{\subsubsection}{Device Operation}{Device Types /
Parameter Server / Device Operation}
+
+\field{name} of the device configuration MUST be non-empty.
+
+The unused bits of the message header MUST be 0.
+
+The \field{prop_item_id} of VIRTIO_PARAMETER_SERVER_OP_GET_PROP_CONFIG,
+VIRTIO_PARAMETER_SERVER_OP_SUBSCRIBE_PROP and
VIRTIO_PARAMETER_SERVER_OP_UNSUBSCRIBE_PROP requests
+MUST be ignored.
+
+The device MUST send exact 1 response for every received request.
+
+The payload size of responses and event messages MUST be padded to 4 bytes.
+
+The param size of property configurations MUST be padded to 4 bytes.
--
2.31.1.368.gbe11c130af-goog

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

Re: [virtio-dev] [PATCH] Add virtio parameter server device specification

[Cornelia Huck]

On Tue, 20 Apr 2021 17:33:17 -0700
Hao Chen <chenhaosjtuacm@google.com> wrote:

> This patch introduces a new type of device: parameter server. The device
> acts as a key-value store and the driver can read from, write to or
> subscribe to the properties in the server.
> 
> Signed-off-by: Hao Chen <chenhaosjtuacm@google.com>
> ---
>  conformance.tex |  26 +++++--
>  content.tex     |   1 +
>  virtio-ps.tex   | 188 ++++++++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 211 insertions(+), 4 deletions(-)
>  create mode 100644 virtio-ps.tex
> 
> diff --git a/conformance.tex b/conformance.tex
> index a164cbb..0d6b1a5 100644
> --- a/conformance.tex
> +++ b/conformance.tex
> @@ -29,8 +29,9 @@ \section{Conformance Targets}\label{sec:Conformance
> / Conformance Targets}
>  \ref{sec:Conformance / Driver Conformance / IOMMU Driver Conformance},
>  \ref{sec:Conformance / Driver Conformance / Sound Driver Conformance},
>  \ref{sec:Conformance / Driver Conformance / Memory Driver Conformance},
> -\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance} or
> -\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance}.
> +\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance},
> +\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance} or
> +\ref{sec:Conformance / Driver Conformance / Parameter Server Driver
> Conformance}.

Your client seems to introduce line wraps, which means the patch cannot
be applied without extra massaging by the committer, which is simply
not feasible for a larger patch. Can you please check why it breaks,
and try to fix it?

> 
>      \item Clause \ref{sec:Conformance / Legacy Interface:
> Transitional Device and Transitional Driver Conformance}.
>    \end{itemize}

(...)

> diff --git a/virtio-ps.tex b/virtio-ps.tex
> new file mode 100644
> index 0000000..fa0930a
> --- /dev/null
> +++ b/virtio-ps.tex
> @@ -0,0 +1,188 @@
> +\section{Parameter Server}\label{sec:Device Types / Parameter Server}
> +
> +The parameter server device manages a set of values with unique
> property IDs. These values may
> +either be static (i.e. have a constant value) or be dynamic (i.e.
> value may change over time).
> +The driver can get and set values, get value configurations,
> subscribe and unsubscribe dynamic
> +properties from the device. The device processes the requests from

What does 'subscribe' mean? Does the driver get notifications from the
device when a subscribed value changes?

> the driver, enforces the value
> +access rules, and may potentially alter the behavior of external
> systems as a result of driver
> +operations.
> +
> +\subsection{Device ID}\label{sec:Device Types / Parameter Server / Device ID}
> +
> +38
> +
> +\subsection{Virtqueues}\label{sec:Device Types / Parameter Server / Virtqueues}
> +
> +\begin{description}
> +\item[0] cmdq
> +\item[1] eventq
> +\end{description}
> +
> +\subsection{Feature Bits}\label{sec:Device Types / Parameter Server /
> Feature Bits}
> +
> +None currently defined.
> +
> +\subsection{Device Configuration Layout}\label{sec:Device Types /
> Parameter Server / Device Configuration Layout}
> +
> +\begin{lstlisting}
> +struct virtio_parameter_server_config {
> +    char name[128];
> +};
> +\end{lstlisting}
> +
> +A device configuration space only contains the name of the device,
> which can be used by the
> +userspace for identification.
> +
> +\subsection{Device Initialization}
> +
> +\begin{enumerate}
> +\item The virtqueues are initialized.
> +\end{enumerate}
> +
> +\subsection{Device Operation}\label{sec:Device Types / Parameter
> Server / Device Operation}
> +
> +The driver puts the requests to the cmdq virtqueue. The responses

Maybe "The driver puts requests to read, write, subscribe to, or
unsubscribe from, parameters onto the cmdq virtqueue."?

> from the device also go into
> +the cmdq virtqueue. Updates on the subscribed values are put into the

"The device also puts its responses to the driver's requests onto the
cmdq virtqueue. The device puts any updates to values that the driver
has subscribed to onto the eventq virtqueue."

?

> eventq virtqueue. The
> +\field{prop_id}, \field{prop_item_id} pair is the primary key for the
> values stored in the
> +parameter server, while the values with the same \field{prop_id}
> share the same configuration.

I don't quite understand what the second part of the sentence means. Do
you have e.g. a prop_id 42 for a certain property foo, and
prop_item_ids 0, 1, 2, so that (42, 0), (42, 1), (42, 2) are of the
same kind?

> +Subscriptions are also on \field{prop_id}.

Does that mean that if the driver subscribes to prop_id 42, it gets
updates for any of (42, 0), (42, 1), (42, 2)?

> +
> +The layout of requests and responses are defined below:
> +
> +\begin{lstlisting}
> +struct virtio_parameter_server_request {
> +    le64 timestamp;
> +    le32 prop_id;
> +    le32 prop_item_id;
> +    le32 payload_size;
> +    u8 op;
> +    u8 payload[<actual payload size>];
> +};
> +
> +struct virtio_parameter_server_response {
> +    le64 timestamp;
> +    le32 prop_id;
> +    le32 prop_item_id;
> +    le32 payload_size;
> +    u16 op;
> +    u16 ret_value;
> +    u8 payload[<actual payload size>];
> +};
> +
> +/* Reserved prop_id and prop_item_id */
> +#define VIRTIO_PARAMETER_SERVER_OP_ALL_PROP INT_MAX
> +
> +/* Supported operations */
> +#define VIRTIO_PARAMETER_SERVER_OP_INVALID 0
> +#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_CONFIG 1
> +#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_VALUE 2
> +#define VIRTIO_PARAMETER_SERVER_OP_SET_PROP_VALUE 3
> +#define VIRTIO_PARAMETER_SERVER_OP_SUBSCRIBE_PROP 4
> +#define VIRTIO_PARAMETER_SERVER_OP_UNSUBSCRIBE_PROP 5
> +\end{lstlisting}
> +
> +The layout of messages in eventq is defined below:
> +
> +\begin{lstlisting}
> +struct virtio_parameter_server_event_msg {
> +    le64 timestamp;
> +    le32 prop_id;
> +    le32 prop_item_id;
> +    le32 payload_size;
> +    u8 payload[<actual payload size>];
> +};
> +\end{lstlisting}
> +
> +There will be exactly one response for each request in the cmdq, even
> if \field{op} is invalid. For some operations,
> +the \field{payload} of requests and/or responses may be empty. If the
> \field{payload} is non-empty, it can be either
> +property configuration(s) or value. The \field{payload} of messages

I'd simply say that the contents of the payload depend on the operation?

> in the eventq virtqueue is always value.
> +
> +\subsubsection{Property Configuration Layout}\label{sec:Device Types
> / Parameter Server / Device Operation / Property Configuration Layout}
> +
> +\begin{lstlisting}
> +struct virtio_parameter_server_prop_config {
> +    le32 prop_id;
> +    le32 mode;
> +    le32 min_sample_freq;
> +    le32 max_sample_freq;
> +    le32 encoding[5];
> +    le32 param_size;
> +    char desc[256];
> +    u8 params[<actual param size>];
> +};
> +\end{lstlisting}
> +
> +while \field{mode} is the bitwise-or-combination of the following:
> +
> +\begin{lstlisting}
> +enum virtio_parameter_server_prop_mode {
> +    /* access */
> +    VIRTIO_PARAMETER_SERVER_M_READ = 0x1,
> +    VIRTIO_PARAMETER_SERVER_M_WRITE = 0x2,
> +    VIRTIO_PARAMETER_SERVER_M_READ_WRITE = 0x3,
> +
> +    /* change */
> +    VIRTIO_PARAMETER_SERVER_M_STATIC = 0x4,
> +    VIRTIO_PARAMETER_SERVER_M_MUTABLE = 0x8,
> +    VIRTIO_PARAMETER_SERVER_M_CONTINUOUS = 0xc,
> +};
> +\end{lstlisting}
> +
> +Both VIRTIO_PARAMETER_SERVER_M_MUTABLE and
> VIRTIO_PARAMETER_SERVER_M_CONTINUOUS are dynamic
> +properties. A VIRTIO_PARAMETER_SERVER_M_MUTABLE value will change due
> to the set value operation
> +from the driver, or actions of the external system; a
> VIRTIO_PARAMETER_SERVER_M_CONTINUOUS value
> +is expected to be generated by means of a sensor updating at a steady
> frequency.

Do these two types need to be handled differently? If I set up a
subscription "poll this parameter every n ms", it doesn't really matter
why the parameter changes, does it? In any case, it is not under
control of the driver, as "actions of the external system" may also
change a mutable parameter.

> +
> +The properties with the same \field{prop_id} share the configuration.
> \field{min_sample_freq} and
> +\field{max_sample_freq} are the sampling rate range for the
> +\field{VIRTIO_PARAMETER_SERVER_M_CONTINUOUS} values. \field{desc} is
> the optional string
> +description. \field{params} are for the customized configuration parameters.
> +
> +The integer array \field{encoding} specifies the number of different
> primitive value in the
> +property value.
> +
> +\begin{lstlisting}
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT64 0
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_FLOAT64 1
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT32 2
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_BYTE 3
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_HAS_STRING 4
> +
> +#define VIRTIO_PARAMETER_SERVER_VARIABLE_LENGTH -2

What does that '-2' mean?

> +\end{lstlisting}
> +
> +If the driver asks for ALL property configurations, then the \field{payload} of
> +virtio_parameter_server_response will be multiple property
> configurations, serialized 1-by-1.

How does it ask for all configurations?

> +
> +\subsubsection{Property Value Layout}\label{sec:Device Types /
> Parameter Server / Device Operation / Property Value Layout}
> +
> +The property value payload begins with 5 arrays. The order is the
> same as the \field{encoding} array defined above.
> +For each array, it begins with a 32-bit integer for length (number of
> elements). Empty array will be a 32-bit 0, while
> +-1 means the array does not exist. The elements follows the length,
> and the size of the encoded array will be padded
> +to 4 bytes. String is encoded as char16_t, zero-terminated array.

I don't think we've specified what a char16_t is.


To check whether I understand this correctly, each 'array' seems to be
of the form

<u32 length> <list of data types as specified by length>

and is succeeded by further 'arrays' in the int64..string order
outlined above.

So, does the 'length' correspond to the values specified in the
encoding? Is HAS_STRING indicating the presence of a string or its
length?

> +
> +After the arrays, there may be customized data, which is encoded as a
> byte array.
> +
> +\drivernormative{\subsubsection}{Device Operation}{Device Types /
> Parameter Server / Device Operation}
> +
> +The driver MUST NOT send undefined ops.
> +
> +The driver MUST NOT put device-readable descriptors into the eventq.

s/device-readable// ?

> +
> +The payload size of requests MUST be padded to 4 bytes.
> +
> +\devicenormative{\subsubsection}{Device Operation}{Device Types /
> Parameter Server / Device Operation}
> +
> +\field{name} of the device configuration MUST be non-empty.
> +
> +The unused bits of the message header MUST be 0.
> +
> +The \field{prop_item_id} of VIRTIO_PARAMETER_SERVER_OP_GET_PROP_CONFIG,
> +VIRTIO_PARAMETER_SERVER_OP_SUBSCRIBE_PROP and
> VIRTIO_PARAMETER_SERVER_OP_UNSUBSCRIBE_PROP requests
> +MUST be ignored.
> +
> +The device MUST send exact 1 response for every received request.
> +
> +The payload size of responses and event messages MUST be padded to 4 bytes.
> +
> +The param size of property configurations MUST be padded to 4 bytes.


---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

Re: [virtio-dev] [PATCH] Add virtio parameter server device specification

[Hao Chen]

> Your client seems to introduce line wraps...

Thanks for pointing it out, we will fix it in the following patches.

> Do these two types need to be handled differently? If I set up a
> subscription "poll this parameter every n ms", it doesn't really matter
> why the parameter changes, does it? In any case, it is not under
> control of the driver, as "actions of the external system" may also
> change a mutable parameter.

The reason we want to handle "MUTABLE" and "CONTNUOUS" differently is,
the MUTABLE values are not constantly changing, so the device may be able to
send every updates of it to the driver; while CONTINUOUS values are changing
frequently (e.g., sensor outputs) and the device should decide how to sample it
and provide a sample rate range ("min_sample_freq" and "max_sample_freq")

> s/device-readable// ?

If I understand correctly, the driver need to fill the virtqueues no
matter who is the
reader, so "device-readable" is necessary here. What do you think?

Thanks,
Hao

On Fri, Apr 30, 2021 at 3:55 AM Cornelia Huck <cohuck@redhat.com> wrote:
>
> On Tue, 20 Apr 2021 17:33:17 -0700
> Hao Chen <chenhaosjtuacm@google.com> wrote:
>
> > This patch introduces a new type of device: parameter server. The device
> > acts as a key-value store and the driver can read from, write to or
> > subscribe to the properties in the server.
> >
> > Signed-off-by: Hao Chen <chenhaosjtuacm@google.com>
> > ---
> >  conformance.tex |  26 +++++--
> >  content.tex     |   1 +
> >  virtio-ps.tex   | 188 ++++++++++++++++++++++++++++++++++++++++++++++++
> >  3 files changed, 211 insertions(+), 4 deletions(-)
> >  create mode 100644 virtio-ps.tex
> >
> > diff --git a/conformance.tex b/conformance.tex
> > index a164cbb..0d6b1a5 100644
> > --- a/conformance.tex
> > +++ b/conformance.tex
> > @@ -29,8 +29,9 @@ \section{Conformance Targets}\label{sec:Conformance
> > / Conformance Targets}
> >  \ref{sec:Conformance / Driver Conformance / IOMMU Driver Conformance},
> >  \ref{sec:Conformance / Driver Conformance / Sound Driver Conformance},
> >  \ref{sec:Conformance / Driver Conformance / Memory Driver Conformance},
> > -\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance} or
> > -\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance}.
> > +\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance},
> > +\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance} or
> > +\ref{sec:Conformance / Driver Conformance / Parameter Server Driver
> > Conformance}.
>
> Your client seems to introduce line wraps, which means the patch cannot
> be applied without extra massaging by the committer, which is simply
> not feasible for a larger patch. Can you please check why it breaks,
> and try to fix it?
>
> >
> >      \item Clause \ref{sec:Conformance / Legacy Interface:
> > Transitional Device and Transitional Driver Conformance}.
> >    \end{itemize}
>
> (...)
>
> > diff --git a/virtio-ps.tex b/virtio-ps.tex
> > new file mode 100644
> > index 0000000..fa0930a
> > --- /dev/null
> > +++ b/virtio-ps.tex
> > @@ -0,0 +1,188 @@
> > +\section{Parameter Server}\label{sec:Device Types / Parameter Server}
> > +
> > +The parameter server device manages a set of values with unique
> > property IDs. These values may
> > +either be static (i.e. have a constant value) or be dynamic (i.e.
> > value may change over time).
> > +The driver can get and set values, get value configurations,
> > subscribe and unsubscribe dynamic
> > +properties from the device. The device processes the requests from
>
> What does 'subscribe' mean? Does the driver get notifications from the
> device when a subscribed value changes?
>
> > the driver, enforces the value
> > +access rules, and may potentially alter the behavior of external
> > systems as a result of driver
> > +operations.
> > +
> > +\subsection{Device ID}\label{sec:Device Types / Parameter Server / Device ID}
> > +
> > +38
> > +
> > +\subsection{Virtqueues}\label{sec:Device Types / Parameter Server / Virtqueues}
> > +
> > +\begin{description}
> > +\item[0] cmdq
> > +\item[1] eventq
> > +\end{description}
> > +
> > +\subsection{Feature Bits}\label{sec:Device Types / Parameter Server /
> > Feature Bits}
> > +
> > +None currently defined.
> > +
> > +\subsection{Device Configuration Layout}\label{sec:Device Types /
> > Parameter Server / Device Configuration Layout}
> > +
> > +\begin{lstlisting}
> > +struct virtio_parameter_server_config {
> > +    char name[128];
> > +};
> > +\end{lstlisting}
> > +
> > +A device configuration space only contains the name of the device,
> > which can be used by the
> > +userspace for identification.
> > +
> > +\subsection{Device Initialization}
> > +
> > +\begin{enumerate}
> > +\item The virtqueues are initialized.
> > +\end{enumerate}
> > +
> > +\subsection{Device Operation}\label{sec:Device Types / Parameter
> > Server / Device Operation}
> > +
> > +The driver puts the requests to the cmdq virtqueue. The responses
>
> Maybe "The driver puts requests to read, write, subscribe to, or
> unsubscribe from, parameters onto the cmdq virtqueue."?
>
> > from the device also go into
> > +the cmdq virtqueue. Updates on the subscribed values are put into the
>
> "The device also puts its responses to the driver's requests onto the
> cmdq virtqueue. The device puts any updates to values that the driver
> has subscribed to onto the eventq virtqueue."
>
> ?
>
> > eventq virtqueue. The
> > +\field{prop_id}, \field{prop_item_id} pair is the primary key for the
> > values stored in the
> > +parameter server, while the values with the same \field{prop_id}
> > share the same configuration.
>
> I don't quite understand what the second part of the sentence means. Do
> you have e.g. a prop_id 42 for a certain property foo, and
> prop_item_ids 0, 1, 2, so that (42, 0), (42, 1), (42, 2) are of the
> same kind?
>
> > +Subscriptions are also on \field{prop_id}.
>
> Does that mean that if the driver subscribes to prop_id 42, it gets
> updates for any of (42, 0), (42, 1), (42, 2)?
>
> > +
> > +The layout of requests and responses are defined below:
> > +
> > +\begin{lstlisting}
> > +struct virtio_parameter_server_request {
> > +    le64 timestamp;
> > +    le32 prop_id;
> > +    le32 prop_item_id;
> > +    le32 payload_size;
> > +    u8 op;
> > +    u8 payload[<actual payload size>];
> > +};
> > +
> > +struct virtio_parameter_server_response {
> > +    le64 timestamp;
> > +    le32 prop_id;
> > +    le32 prop_item_id;
> > +    le32 payload_size;
> > +    u16 op;
> > +    u16 ret_value;
> > +    u8 payload[<actual payload size>];
> > +};
> > +
> > +/* Reserved prop_id and prop_item_id */
> > +#define VIRTIO_PARAMETER_SERVER_OP_ALL_PROP INT_MAX
> > +
> > +/* Supported operations */
> > +#define VIRTIO_PARAMETER_SERVER_OP_INVALID 0
> > +#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_CONFIG 1
> > +#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_VALUE 2
> > +#define VIRTIO_PARAMETER_SERVER_OP_SET_PROP_VALUE 3
> > +#define VIRTIO_PARAMETER_SERVER_OP_SUBSCRIBE_PROP 4
> > +#define VIRTIO_PARAMETER_SERVER_OP_UNSUBSCRIBE_PROP 5
> > +\end{lstlisting}
> > +
> > +The layout of messages in eventq is defined below:
> > +
> > +\begin{lstlisting}
> > +struct virtio_parameter_server_event_msg {
> > +    le64 timestamp;
> > +    le32 prop_id;
> > +    le32 prop_item_id;
> > +    le32 payload_size;
> > +    u8 payload[<actual payload size>];
> > +};
> > +\end{lstlisting}
> > +
> > +There will be exactly one response for each request in the cmdq, even
> > if \field{op} is invalid. For some operations,
> > +the \field{payload} of requests and/or responses may be empty. If the
> > \field{payload} is non-empty, it can be either
> > +property configuration(s) or value. The \field{payload} of messages
>
> I'd simply say that the contents of the payload depend on the operation?
>
> > in the eventq virtqueue is always value.
> > +
> > +\subsubsection{Property Configuration Layout}\label{sec:Device Types
> > / Parameter Server / Device Operation / Property Configuration Layout}
> > +
> > +\begin{lstlisting}
> > +struct virtio_parameter_server_prop_config {
> > +    le32 prop_id;
> > +    le32 mode;
> > +    le32 min_sample_freq;
> > +    le32 max_sample_freq;
> > +    le32 encoding[5];
> > +    le32 param_size;
> > +    char desc[256];
> > +    u8 params[<actual param size>];
> > +};
> > +\end{lstlisting}
> > +
> > +while \field{mode} is the bitwise-or-combination of the following:
> > +
> > +\begin{lstlisting}
> > +enum virtio_parameter_server_prop_mode {
> > +    /* access */
> > +    VIRTIO_PARAMETER_SERVER_M_READ = 0x1,
> > +    VIRTIO_PARAMETER_SERVER_M_WRITE = 0x2,
> > +    VIRTIO_PARAMETER_SERVER_M_READ_WRITE = 0x3,
> > +
> > +    /* change */
> > +    VIRTIO_PARAMETER_SERVER_M_STATIC = 0x4,
> > +    VIRTIO_PARAMETER_SERVER_M_MUTABLE = 0x8,
> > +    VIRTIO_PARAMETER_SERVER_M_CONTINUOUS = 0xc,
> > +};
> > +\end{lstlisting}
> > +
> > +Both VIRTIO_PARAMETER_SERVER_M_MUTABLE and
> > VIRTIO_PARAMETER_SERVER_M_CONTINUOUS are dynamic
> > +properties. A VIRTIO_PARAMETER_SERVER_M_MUTABLE value will change due
> > to the set value operation
> > +from the driver, or actions of the external system; a
> > VIRTIO_PARAMETER_SERVER_M_CONTINUOUS value
> > +is expected to be generated by means of a sensor updating at a steady
> > frequency.
>
> Do these two types need to be handled differently? If I set up a
> subscription "poll this parameter every n ms", it doesn't really matter
> why the parameter changes, does it? In any case, it is not under
> control of the driver, as "actions of the external system" may also
> change a mutable parameter.
>
> > +
> > +The properties with the same \field{prop_id} share the configuration.
> > \field{min_sample_freq} and
> > +\field{max_sample_freq} are the sampling rate range for the
> > +\field{VIRTIO_PARAMETER_SERVER_M_CONTINUOUS} values. \field{desc} is
> > the optional string
> > +description. \field{params} are for the customized configuration parameters.
> > +
> > +The integer array \field{encoding} specifies the number of different
> > primitive value in the
> > +property value.
> > +
> > +\begin{lstlisting}
> > +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT64 0
> > +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_FLOAT64 1
> > +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT32 2
> > +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_BYTE 3
> > +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_HAS_STRING 4
> > +
> > +#define VIRTIO_PARAMETER_SERVER_VARIABLE_LENGTH -2
>
> What does that '-2' mean?
>
> > +\end{lstlisting}
> > +
> > +If the driver asks for ALL property configurations, then the \field{payload} of
> > +virtio_parameter_server_response will be multiple property
> > configurations, serialized 1-by-1.
>
> How does it ask for all configurations?
>
> > +
> > +\subsubsection{Property Value Layout}\label{sec:Device Types /
> > Parameter Server / Device Operation / Property Value Layout}
> > +
> > +The property value payload begins with 5 arrays. The order is the
> > same as the \field{encoding} array defined above.
> > +For each array, it begins with a 32-bit integer for length (number of
> > elements). Empty array will be a 32-bit 0, while
> > +-1 means the array does not exist. The elements follows the length,
> > and the size of the encoded array will be padded
> > +to 4 bytes. String is encoded as char16_t, zero-terminated array.
>
> I don't think we've specified what a char16_t is.
>
>
> To check whether I understand this correctly, each 'array' seems to be
> of the form
>
> <u32 length> <list of data types as specified by length>
>
> and is succeeded by further 'arrays' in the int64..string order
> outlined above.
>
> So, does the 'length' correspond to the values specified in the
> encoding? Is HAS_STRING indicating the presence of a string or its
> length?
>
> > +
> > +After the arrays, there may be customized data, which is encoded as a
> > byte array.
> > +
> > +\drivernormative{\subsubsection}{Device Operation}{Device Types /
> > Parameter Server / Device Operation}
> > +
> > +The driver MUST NOT send undefined ops.
> > +
> > +The driver MUST NOT put device-readable descriptors into the eventq.
>
> s/device-readable// ?
>
> > +
> > +The payload size of requests MUST be padded to 4 bytes.
> > +
> > +\devicenormative{\subsubsection}{Device Operation}{Device Types /
> > Parameter Server / Device Operation}
> > +
> > +\field{name} of the device configuration MUST be non-empty.
> > +
> > +The unused bits of the message header MUST be 0.
> > +
> > +The \field{prop_item_id} of VIRTIO_PARAMETER_SERVER_OP_GET_PROP_CONFIG,
> > +VIRTIO_PARAMETER_SERVER_OP_SUBSCRIBE_PROP and
> > VIRTIO_PARAMETER_SERVER_OP_UNSUBSCRIBE_PROP requests
> > +MUST be ignored.
> > +
> > +The device MUST send exact 1 response for every received request.
> > +
> > +The payload size of responses and event messages MUST be padded to 4 bytes.
> > +
> > +The param size of property configurations MUST be padded to 4 bytes.
>

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

Re: [virtio-dev] [PATCH] Add virtio parameter server device specification

[Cornelia Huck]

On Fri, 7 May 2021 16:06:41 -0700
Hao Chen <chenhaosjtuacm@google.com> wrote:

> > Your client seems to introduce line wraps...  
> 
> Thanks for pointing it out, we will fix it in the following patches.
> 
> > Do these two types need to be handled differently? If I set up a
> > subscription "poll this parameter every n ms", it doesn't really matter
> > why the parameter changes, does it? In any case, it is not under
> > control of the driver, as "actions of the external system" may also
> > change a mutable parameter.  
> 
> The reason we want to handle "MUTABLE" and "CONTNUOUS" differently is,
> the MUTABLE values are not constantly changing, so the device may be able to
> send every updates of it to the driver; while CONTINUOUS values are changing
> frequently (e.g., sensor outputs) and the device should decide how to sample it
> and provide a sample rate range ("min_sample_freq" and "max_sample_freq")

Can you add that explanation to the paragraph? It gives good guidance
when to use which type.

> 
> > s/device-readable// ?  
> 
> If I understand correctly, the driver need to fill the virtqueues no
> matter who is the
> reader, so "device-readable" is necessary here. What do you think?

But isn't the eventq supposed to relay information from the device to
the driver?


---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

Re: [virtio-dev] [PATCH] Add virtio parameter server device specification

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 511 bytes --]

On Tue, Apr 20, 2021 at 05:33:17PM -0700, Hao Chen wrote:
> This patch introduces a new type of device: parameter server. The device
> acts as a key-value store and the driver can read from, write to or
> subscribe to the properties in the server.

Can you share a bit about the reason for defining a new VIRTIO device
instead of running an existing key-value store over virtio-vsock or
virtio-net?

I'm not against adding this new device but I would like to understand
what the advantages are.

Thanks,
Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [virtio-dev] [PATCH] Add virtio parameter server device specification

[Hao Chen]

> Can you share a bit about the reason for defining a new VIRTIO device
> instead of running an existing key-value store over virtio-vsock or
> virtio-net?

The reason for defining a virtio-parameter-server device is we are interacting
with some devices in a "key-value store" pattern. For example, we interact with
"vehicle device" in Android using this pattern.

Ad-hoc protocol over vsock to a k-v store works, but we want to
standardize these
types of devices so that the VM doesn't need to know the
vendor-specific key-value
protocols for a specific device implementation.

Thanks,
Hao

On Thu, May 13, 2021 at 7:46 AM Stefan Hajnoczi <stefanha@redhat.com> wrote:
>
> On Tue, Apr 20, 2021 at 05:33:17PM -0700, Hao Chen wrote:
> > This patch introduces a new type of device: parameter server. The device
> > acts as a key-value store and the driver can read from, write to or
> > subscribe to the properties in the server.
>
> Can you share a bit about the reason for defining a new VIRTIO device
> instead of running an existing key-value store over virtio-vsock or
> virtio-net?
>
> I'm not against adding this new device but I would like to understand
> what the advantages are.
>
> Thanks,
> Stefan

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

[virtio-dev] [PATCH v2] Add virtio parameter server device specification

[Hao Chen]

This patch introduces a new type of device: parameter server. The device
acts as a key-value store and the driver can read from, write to or
subscribe to the properties in the server.

Signed-off-by: Hao Chen <chenhaosjtuacm@google.com>
---
 conformance.tex |  26 +++++--
 content.tex     |   1 +
 virtio-ps.tex   | 188 ++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 211 insertions(+), 4 deletions(-)
 create mode 100644 virtio-ps.tex

diff --git a/conformance.tex b/conformance.tex
index a164cbb..0d6b1a5 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -29,8 +29,9 @@ \section{Conformance Targets}\label{sec:Conformance
/ Conformance Targets}
 \ref{sec:Conformance / Driver Conformance / IOMMU Driver Conformance},
 \ref{sec:Conformance / Driver Conformance / Sound Driver Conformance},
 \ref{sec:Conformance / Driver Conformance / Memory Driver Conformance},
-\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance} or
-\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance}.
+\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance},
+\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance} or
+\ref{sec:Conformance / Driver Conformance / Parameter Server Driver
Conformance}.

     \item Clause \ref{sec:Conformance / Legacy Interface:
Transitional Device and Transitional Driver Conformance}.
   \end{itemize}
@@ -52,8 +53,9 @@ \section{Conformance Targets}\label{sec:Conformance
/ Conformance Targets}
 \ref{sec:Conformance / Device Conformance / IOMMU Device Conformance},
 \ref{sec:Conformance / Device Conformance / Sound Device Conformance},
 \ref{sec:Conformance / Device Conformance / Memory Device Conformance},
-\ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance} or
-\ref{sec:Conformance / Device Conformance / SCMI Device Conformance}.
+\ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance},
+\ref{sec:Conformance / Device Conformance / SCMI Device Conformance}or
+\ref{sec:Conformance / Device Conformance / Parameter Server Device
Conformance}.

     \item Clause \ref{sec:Conformance / Legacy Interface:
Transitional Device and Transitional Driver Conformance}.
   \end{itemize}
@@ -288,6 +290,14 @@ \section{Conformance
Targets}\label{sec:Conformance / Conformance Targets}
 \item \ref{drivernormative:Device Types / SCMI Device / Device
Operation / Setting Up eventq Buffers}
 \end{itemize}

+\conformance{\subsection}{Parameter Server Driver
Conformance}\label{sec:Conformance / Driver Conformance / Parameter
Server Driver Conformance}
+
+A parameter server driver MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{drivernormative:Device Types / Parameter Server / Device Operation}
+\end{itemize}
+
 \conformance{\section}{Device Conformance}\label{sec:Conformance /
Device Conformance}

 A device MUST conform to the following normative statements:
@@ -527,6 +537,14 @@ \section{Conformance
Targets}\label{sec:Conformance / Conformance Targets}
 \item \ref{devicenormative:Device Types / SCMI Device / Device
Operation / Shared Memory Operation}
 \end{itemize}

+\conformance{\subsection}{Parameter Server Device
Conformance}\label{sec:Conformance / Device Conformance / Parameter
Server Device Conformance}
+
+A parameter server device MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{devicenormative:Device Types / Parameter Server / 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 9232d5c..b980a93 100644
--- a/content.tex
+++ b/content.tex
@@ -6568,6 +6568,7 @@ \subsubsection{Legacy Interface: Framing
Requirements}\label{sec:Device
 \input{virtio-mem.tex}
 \input{virtio-i2c.tex}
 \input{virtio-scmi.tex}
+\input{virtio-ps.tex}

 \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}

diff --git a/virtio-ps.tex b/virtio-ps.tex
new file mode 100644
index 0000000..fa0930a
--- /dev/null
+++ b/virtio-ps.tex
@@ -0,0 +1,188 @@
+\section{Parameter Server}\label{sec:Device Types / Parameter Server}
+
+The parameter server device manages a set of values with unique
property IDs. These values may
+either be static (i.e. have a constant value) or be dynamic (i.e.
value may change over time).
+The driver can get and set values, get value configurations,
subscribe and unsubscribe dynamic
+properties from the device. The device processes the requests from
the driver, enforces the value
+access rules, and may potentially alter the behavior of external
systems as a result of driver
+operations.
+
+\subsection{Device ID}\label{sec:Device Types / Parameter Server / Device ID}
+
+38
+
+\subsection{Virtqueues}\label{sec:Device Types / Parameter Server / Virtqueues}
+
+\begin{description}
+\item[0] cmdq
+\item[1] eventq
+\end{description}
+
+\subsection{Feature Bits}\label{sec:Device Types / Parameter Server /
Feature Bits}
+
+None currently defined.
+
+\subsection{Device Configuration Layout}\label{sec:Device Types /
Parameter Server / Device Configuration Layout}
+
+\begin{lstlisting}
+struct virtio_parameter_server_config {
+    char name[128];
+};
+\end{lstlisting}
+
+A device configuration space only contains the name of the device,
which can be used by the
+userspace for identification.
+
+\subsection{Device Initialization}
+
+\begin{enumerate}
+\item The virtqueues are initialized.
+\end{enumerate}
+
+\subsection{Device Operation}\label{sec:Device Types / Parameter
Server / Device Operation}
+
+The driver puts the requests to the cmdq virtqueue. The responses
from the device also go into
+the cmdq virtqueue. Updates on the subscribed values are put into the
eventq virtqueue. The
+\field{prop_id}, \field{prop_item_id} pair is the primary key for the
values stored in the
+parameter server, while the values with the same \field{prop_id}
share the same configuration.
+Subscriptions are also on \field{prop_id}.
+
+The layout of requests and responses are defined below:
+
+\begin{lstlisting}
+struct virtio_parameter_server_request {
+    le64 timestamp;
+    le32 prop_id;
+    le32 prop_item_id;
+    le32 payload_size;
+    u8 op;
+    u8 payload[<actual payload size>];
+};
+
+struct virtio_parameter_server_response {
+    le64 timestamp;
+    le32 prop_id;
+    le32 prop_item_id;
+    le32 payload_size;
+    u16 op;
+    u16 ret_value;
+    u8 payload[<actual payload size>];
+};
+
+/* Reserved prop_id and prop_item_id */
+#define VIRTIO_PARAMETER_SERVER_OP_ALL_PROP INT_MAX
+
+/* Supported operations */
+#define VIRTIO_PARAMETER_SERVER_OP_INVALID 0
+#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_CONFIG 1
+#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_VALUE 2
+#define VIRTIO_PARAMETER_SERVER_OP_SET_PROP_VALUE 3
+#define VIRTIO_PARAMETER_SERVER_OP_SUBSCRIBE_PROP 4
+#define VIRTIO_PARAMETER_SERVER_OP_UNSUBSCRIBE_PROP 5
+\end{lstlisting}
+
+The layout of messages in eventq is defined below:
+
+\begin{lstlisting}
+struct virtio_parameter_server_event_msg {
+    le64 timestamp;
+    le32 prop_id;
+    le32 prop_item_id;
+    le32 payload_size;
+    u8 payload[<actual payload size>];
+};
+\end{lstlisting}
+
+There will be exactly one response for each request in the cmdq, even
if \field{op} is invalid. For some operations,
+the \field{payload} of requests and/or responses may be empty. If the
\field{payload} is non-empty, it can be either
+property configuration(s) or value. The \field{payload} of messages
in the eventq virtqueue is always value.
+
+\subsubsection{Property Configuration Layout}\label{sec:Device Types
/ Parameter Server / Device Operation / Property Configuration Layout}
+
+\begin{lstlisting}
+struct virtio_parameter_server_prop_config {
+    le32 prop_id;
+    le32 mode;
+    le32 min_sample_freq;
+    le32 max_sample_freq;
+    le32 encoding[5];
+    le32 param_size;
+    char desc[256];
+    u8 params[<actual param size>];
+};
+\end{lstlisting}
+
+while \field{mode} is the bitwise-or-combination of the following:
+
+\begin{lstlisting}
+enum virtio_parameter_server_prop_mode {
+    /* access */
+    VIRTIO_PARAMETER_SERVER_M_READ = 0x1,
+    VIRTIO_PARAMETER_SERVER_M_WRITE = 0x2,
+    VIRTIO_PARAMETER_SERVER_M_READ_WRITE = 0x3,
+
+    /* change */
+    VIRTIO_PARAMETER_SERVER_M_STATIC = 0x4,
+    VIRTIO_PARAMETER_SERVER_M_MUTABLE = 0x8,
+    VIRTIO_PARAMETER_SERVER_M_CONTINUOUS = 0xc,
+};
+\end{lstlisting}
+
+Both VIRTIO_PARAMETER_SERVER_M_MUTABLE and
VIRTIO_PARAMETER_SERVER_M_CONTINUOUS are dynamic
+properties. A VIRTIO_PARAMETER_SERVER_M_MUTABLE value will change due
to the set value operation
+from the driver, or actions of the external system; a
VIRTIO_PARAMETER_SERVER_M_CONTINUOUS value
+is expected to be generated by means of a sensor updating at a steady
frequency.
+
+The properties with the same \field{prop_id} share the configuration.
\field{min_sample_freq} and
+\field{max_sample_freq} are the sampling rate range for the
+\field{VIRTIO_PARAMETER_SERVER_M_CONTINUOUS} values. \field{desc} is
the optional string
+description. \field{params} are for the customized configuration parameters.
+
+The integer array \field{encoding} specifies the number of different
primitive value in the
+property value.
+
+\begin{lstlisting}
+#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT64 0
+#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_FLOAT64 1
+#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT32 2
+#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_BYTE 3
+#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_HAS_STRING 4
+
+#define VIRTIO_PARAMETER_SERVER_VARIABLE_LENGTH -2
+\end{lstlisting}
+
+If the driver asks for ALL property configurations, then the \field{payload} of
+virtio_parameter_server_response will be multiple property
configurations, serialized 1-by-1.
+
+\subsubsection{Property Value Layout}\label{sec:Device Types /
Parameter Server / Device Operation / Property Value Layout}
+
+The property value payload begins with 5 arrays. The order is the
same as the \field{encoding} array defined above.
+For each array, it begins with a 32-bit integer for length (number of
elements). Empty array will be a 32-bit 0, while
+-1 means the array does not exist. The elements follows the length,
and the size of the encoded array will be padded
+to 4 bytes. String is encoded as char16_t, zero-terminated array.
+
+After the arrays, there may be customized data, which is encoded as a
byte array.
+
+\drivernormative{\subsubsection}{Device Operation}{Device Types /
Parameter Server / Device Operation}
+
+The driver MUST NOT send undefined ops.
+
+The driver MUST NOT put device-readable descriptors into the eventq.
+
+The payload size of requests MUST be padded to 4 bytes.
+
+\devicenormative{\subsubsection}{Device Operation}{Device Types /
Parameter Server / Device Operation}
+
+\field{name} of the device configuration MUST be non-empty.
+
+The unused bits of the message header MUST be 0.
+
+The \field{prop_item_id} of VIRTIO_PARAMETER_SERVER_OP_GET_PROP_CONFIG,
+VIRTIO_PARAMETER_SERVER_OP_SUBSCRIBE_PROP and
VIRTIO_PARAMETER_SERVER_OP_UNSUBSCRIBE_PROP requests
+MUST be ignored.
+
+The device MUST send exact 1 response for every received request.
+
+The payload size of responses and event messages MUST be padded to 4 bytes.
+
+The param size of property configurations MUST be padded to 4 bytes.
--
2.31.1.751.gd2f1c929bd-goog

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

[virtio-dev] Fwd: [PATCH v3] Add virtio parameter server device specification

[Hao Chen]

This patch introduces a new type of device: parameter server. The device
acts as a key-value store and the driver can read from, write to or
subscribe to the properties in the server.

Signed-off-by: Hao Chen <chenhaosjtuacm@google.com>
---
 conformance.tex |  26 ++++++-
 content.tex     |   1 +
 virtio-ps.tex   | 197 ++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 220 insertions(+), 4 deletions(-)
 create mode 100644 virtio-ps.tex

diff --git a/conformance.tex b/conformance.tex
index a164cbb..0d6b1a5 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -29,8 +29,9 @@ \section{Conformance Targets}\label{sec:Conformance
/ Conformance Targets}
 \ref{sec:Conformance / Driver Conformance / IOMMU Driver Conformance},
 \ref{sec:Conformance / Driver Conformance / Sound Driver Conformance},
 \ref{sec:Conformance / Driver Conformance / Memory Driver Conformance},
-\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance} or
-\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance}.
+\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance},
+\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance} or
+\ref{sec:Conformance / Driver Conformance / Parameter Server Driver
Conformance}.

     \item Clause \ref{sec:Conformance / Legacy Interface:
Transitional Device and Transitional Driver Conformance}.
   \end{itemize}
@@ -52,8 +53,9 @@ \section{Conformance Targets}\label{sec:Conformance
/ Conformance Targets}
 \ref{sec:Conformance / Device Conformance / IOMMU Device Conformance},
 \ref{sec:Conformance / Device Conformance / Sound Device Conformance},
 \ref{sec:Conformance / Device Conformance / Memory Device Conformance},
-\ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance} or
-\ref{sec:Conformance / Device Conformance / SCMI Device Conformance}.
+\ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance},
+\ref{sec:Conformance / Device Conformance / SCMI Device Conformance}or
+\ref{sec:Conformance / Device Conformance / Parameter Server Device
Conformance}.

     \item Clause \ref{sec:Conformance / Legacy Interface:
Transitional Device and Transitional Driver Conformance}.
   \end{itemize}
@@ -288,6 +290,14 @@ \section{Conformance
Targets}\label{sec:Conformance / Conformance Targets}
 \item \ref{drivernormative:Device Types / SCMI Device / Device
Operation / Setting Up eventq Buffers}
 \end{itemize}

+\conformance{\subsection}{Parameter Server Driver
Conformance}\label{sec:Conformance / Driver Conformance / Parameter
Server Driver Conformance}
+
+A parameter server driver MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{drivernormative:Device Types / Parameter Server / Device Operation}
+\end{itemize}
+
 \conformance{\section}{Device Conformance}\label{sec:Conformance /
Device Conformance}

 A device MUST conform to the following normative statements:
@@ -527,6 +537,14 @@ \section{Conformance
Targets}\label{sec:Conformance / Conformance Targets}
 \item \ref{devicenormative:Device Types / SCMI Device / Device
Operation / Shared Memory Operation}
 \end{itemize}

+\conformance{\subsection}{Parameter Server Device
Conformance}\label{sec:Conformance / Device Conformance / Parameter
Server Device Conformance}
+
+A parameter server device MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{devicenormative:Device Types / Parameter Server / 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 9232d5c..b980a93 100644
--- a/content.tex
+++ b/content.tex
@@ -6568,6 +6568,7 @@ \subsubsection{Legacy Interface: Framing
Requirements}\label{sec:Device
 \input{virtio-mem.tex}
 \input{virtio-i2c.tex}
 \input{virtio-scmi.tex}
+\input{virtio-ps.tex}

 \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}

diff --git a/virtio-ps.tex b/virtio-ps.tex
new file mode 100644
index 0000000..f84b211
--- /dev/null
+++ b/virtio-ps.tex
@@ -0,0 +1,197 @@
+\section{Parameter Server}\label{sec:Device Types / Parameter Server}
+
+The parameter server device manages a set of values with unique
property IDs. These values may
+either be static (i.e. have a constant value) or be dynamic (i.e.
value may change over time).
+The driver can get and set values, get value configurations,
subscribe and unsubscribe dynamic
+properties from the device. The driver will get updates when
subscribed value changes. The device
+processes the requests from the driver, enforces the value access
rules, and may potentially alter
+the behavior of external systems as a result of driver operations.
+
+\subsection{Device ID}\label{sec:Device Types / Parameter Server / Device ID}
+
+38
+
+\subsection{Virtqueues}\label{sec:Device Types / Parameter Server / Virtqueues}
+
+\begin{description}
+\item[0] cmdq
+\item[1] eventq
+\end{description}
+
+\subsection{Feature Bits}\label{sec:Device Types / Parameter Server /
Feature Bits}
+
+None currently defined.
+
+\subsection{Device Configuration Layout}\label{sec:Device Types /
Parameter Server / Device Configuration Layout}
+
+\begin{lstlisting}
+struct virtio_parameter_server_config {
+    char name[128];
+};
+\end{lstlisting}
+
+A device configuration space only contains the name of the device,
which can be used by the
+userspace for identification.
+
+\subsection{Device Initialization}
+
+\begin{enumerate}
+\item The virtqueues are initialized.
+\end{enumerate}
+
+\subsection{Device Operation}\label{sec:Device Types / Parameter
Server / Device Operation}
+
+The driver puts requests to read, write, subscribe to, or unsubscribe
from, parameters onto the
+cmdq virtqueue. The device also puts its responses to the driver's
requests onto the cmdq
+virtqueue. The device puts any updates to values that the driver has
subscribed to onto the
+eventq virtqueue. The
+\field{prop_id}, \field{prop_item_id} pair is the primary key for the
values stored in the
+parameter server, while the values with the same \field{prop_id}
share the same configuration.
+For example, \field{prop_id} 12 with \field{prop_item_id} 0, 1 and 2
represent 3 different values
+sharing the same \field{virtio_parameter_server_config}.
Subscriptions are also on \field{prop_id},
+so if \field{prop_id} 12 is subscribed, the driver will receive
updates on (12, 0), (12, 1) and
+(12, 2).
+
+The layout of requests and responses are defined below:
+
+\begin{lstlisting}
+struct virtio_parameter_server_request {
+    le64 timestamp;
+    le32 prop_id;
+    le32 prop_item_id;
+    le32 payload_size;
+    u8 op;
+    u8 payload[<actual payload size>];
+};
+
+struct virtio_parameter_server_response {
+    le64 timestamp;
+    le32 prop_id;
+    le32 prop_item_id;
+    le32 payload_size;
+    u16 op;
+    u16 ret_value;
+    u8 payload[<actual payload size>];
+};
+
+/* Reserved prop_id and prop_item_id */
+#define VIRTIO_PARAMETER_SERVER_OP_ALL_PROP INT_MAX
+
+/* Supported operations */
+#define VIRTIO_PARAMETER_SERVER_OP_INVALID 0
+#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_CONFIG 1
+#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_VALUE 2
+#define VIRTIO_PARAMETER_SERVER_OP_SET_PROP_VALUE 3
+#define VIRTIO_PARAMETER_SERVER_OP_SUBSCRIBE_PROP 4
+#define VIRTIO_PARAMETER_SERVER_OP_UNSUBSCRIBE_PROP 5
+\end{lstlisting}
+
+The layout of messages in eventq is defined below:
+
+\begin{lstlisting}
+struct virtio_parameter_server_event_msg {
+    le64 timestamp;
+    le32 prop_id;
+    le32 prop_item_id;
+    le32 payload_size;
+    u8 payload[<actual payload size>];
+};
+\end{lstlisting}
+
+There will be exactly one response for each request in the cmdq, even
if \field{op} is invalid. For some operations,
+the \field{payload} of requests and/or responses may be empty. The
content of the payload depend on the operation.
+
+\subsubsection{Property Configuration Layout}\label{sec:Device Types
/ Parameter Server / Device Operation / Property Configuration Layout}
+
+\begin{lstlisting}
+struct virtio_parameter_server_prop_config {
+    le32 prop_id;
+    le32 mode;
+    le32 min_sample_freq;
+    le32 max_sample_freq;
+    le32 encoding[5];
+    le32 param_size;
+    char desc[256];
+    u8 params[<actual param size>];
+};
+\end{lstlisting}
+
+while \field{mode} is the bitwise-or-combination of the following:
+
+\begin{lstlisting}
+enum virtio_parameter_server_prop_mode {
+    /* access */
+    VIRTIO_PARAMETER_SERVER_M_READ = 0x1,
+    VIRTIO_PARAMETER_SERVER_M_WRITE = 0x2,
+    VIRTIO_PARAMETER_SERVER_M_READ_WRITE = 0x3,
+
+    /* change */
+    VIRTIO_PARAMETER_SERVER_M_STATIC = 0x4,
+    VIRTIO_PARAMETER_SERVER_M_MUTABLE = 0x8,
+    VIRTIO_PARAMETER_SERVER_M_CONTINUOUS = 0xc,
+};
+\end{lstlisting}
+
+Both VIRTIO_PARAMETER_SERVER_M_MUTABLE and
VIRTIO_PARAMETER_SERVER_M_CONTINUOUS are dynamic
+properties. A VIRTIO_PARAMETER_SERVER_M_MUTABLE value will change due
to the set value operation
+from the driver, or actions of the external system; a
VIRTIO_PARAMETER_SERVER_M_CONTINUOUS value
+is expected to be generated by means of a sensor updating at a steady
frequency.
+
+The reason we want to handle "MUTABLE" and "CONTNUOUS" differently
is, the MUTABLE values are not
+constantly changing, so the device may be able to send every updates
of it to the driver; while
+CONTINUOUS values are changing frequently (e.g., sensor outputs) and
the device should decide how
+to sample it and provide a sample rate range (\field{min_sample_freq}
and \field{max_sample_freq})
+
+The properties with the same \field{prop_id} share the configuration.
\field{min_sample_freq} and
+\field{max_sample_freq} are the sampling rate range for the
+\field{VIRTIO_PARAMETER_SERVER_M_CONTINUOUS} values. \field{desc} is
the optional string
+description. \field{params} are for the customized configuration parameters.
+
+The integer array \field{encoding} specifies the number of different
primitive value in the
+property value.
+
+\begin{lstlisting}
+#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT64 0
+#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_FLOAT64 1
+#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT32 2
+#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_BYTE 3
+#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_HAS_STRING 4
+\end{lstlisting}
+
+If the driver asks for ALL property configurations by setting the
\field{prop_id} of the request to
+VIRTIO_PARAMETER_SERVER_OP_ALL_PROP, then the \field{payload} of
virtio_parameter_server_response
+will be multiple property configurations, serialized 1-by-1.
+
+\subsubsection{Property Value Layout}\label{sec:Device Types /
Parameter Server / Device Operation / Property Value Layout}
+
+The property value payload begins with 5 arrays. The order is the
same as the \field{encoding} array defined above.
+For each array, it begins with a 32-bit integer for length (number of
elements). Empty array will be a 32-bit 0, while
+-1 means the array does not exist. The elements follows the length,
and the size of the encoded array will be padded
+to 4 bytes. String is encoded as char, zero-terminated array,
+\field{encoding[VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_HAS_STRING]}
indicates the existence of the string.
+
+After the arrays, there may be customized data, which is encoded as a
byte array.
+
+\drivernormative{\subsubsection}{Device Operation}{Device Types /
Parameter Server / Device Operation}
+
+The driver MUST NOT send undefined ops.
+
+The driver MUST NOT put descriptors into the eventq.
+
+The payload size of requests MUST be padded to 4 bytes.
+
+\devicenormative{\subsubsection}{Device Operation}{Device Types /
Parameter Server / Device Operation}
+
+\field{name} of the device configuration MUST be non-empty.
+
+The unused bits of the message header MUST be 0.
+
+The \field{prop_item_id} of VIRTIO_PARAMETER_SERVER_OP_GET_PROP_CONFIG,
+VIRTIO_PARAMETER_SERVER_OP_SUBSCRIBE_PROP and
VIRTIO_PARAMETER_SERVER_OP_UNSUBSCRIBE_PROP requests
+MUST be ignored.
+
+The device MUST send exact 1 response for every received request.
+
+The payload size of responses and event messages MUST be padded to 4 bytes.
+
+The param size of property configurations MUST be padded to 4 bytes.
--
2.31.1.751.gd2f1c929bd-goog

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

Re: [virtio-dev] [PATCH] Add virtio parameter server device specification

[Enrico Weigelt, metux IT consult]

On 17.05.21 21:28, Hao Chen wrote:
> The reason for defining a virtio-parameter-server device is we are interacting
> with some devices in a "key-value store" pattern. For example, we interact with
> "vehicle device" in Android using this pattern.

What kind of devices are these ?


--mtx
-- 
---
Hinweis: unverschlüsselte E-Mails können leicht abgehört und manipuliert
werden ! Für eine vertrauliche Kommunikation senden Sie bitte ihren
GPG/PGP-Schlüssel zu.
---
Enrico Weigelt, metux IT consult
Free software and Linux embedded engineering
info@metux.net -- +49-151-27565287

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

Re: [virtio-dev] [PATCH] Add virtio parameter server device specification

[Hao Chen]

In our use case, we treat vehicle as a virtual device. For example, we
send values to it to control the HVAC, and we receive values like car
speed from the vehicle. We are not using virtio-can because 1. the
vehicle bus does not have to be CAN and 2. we are doing something
which more than just a pipe to the car bus (e.g., power management).

Hao

On Mon, May 17, 2021 at 11:02 PM Enrico Weigelt, metux IT consult
<lkml@metux.net> wrote:
>
> On 17.05.21 21:28, Hao Chen wrote:
> > The reason for defining a virtio-parameter-server device is we are interacting
> > with some devices in a "key-value store" pattern. For example, we interact with
> > "vehicle device" in Android using this pattern.
>
> What kind of devices are these ?
>
>
> --mtx
> --
> ---
> Hinweis: unverschlüsselte E-Mails können leicht abgehört und manipuliert
> werden ! Für eine vertrauliche Kommunikation senden Sie bitte ihren
> GPG/PGP-Schlüssel zu.
> ---
> Enrico Weigelt, metux IT consult
> Free software and Linux embedded engineering
> info@metux.net -- +49-151-27565287
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
>

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

[virtio-dev] Re: [PATCH v3] Add virtio parameter server device specification

[Cornelia Huck]

On Mon, 17 May 2021 12:37:30 -0700
Hao Chen <chenhaosjtuacm@google.com> wrote:

> This patch introduces a new type of device: parameter server. The device
> acts as a key-value store and the driver can read from, write to or
> subscribe to the properties in the server.
> 
> Signed-off-by: Hao Chen <chenhaosjtuacm@google.com>
> ---
>  conformance.tex |  26 ++++++-
>  content.tex     |   1 +
>  virtio-ps.tex   | 197 ++++++++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 220 insertions(+), 4 deletions(-)
>  create mode 100644 virtio-ps.tex

Can you please provide some kind of change log?

> diff --git a/conformance.tex b/conformance.tex
> index a164cbb..0d6b1a5 100644
> --- a/conformance.tex
> +++ b/conformance.tex
> @@ -29,8 +29,9 @@ \section{Conformance Targets}\label{sec:Conformance
> / Conformance Targets}

I'm afraid the line wrapping is still happening...

>  \ref{sec:Conformance / Driver Conformance / IOMMU Driver Conformance},
>  \ref{sec:Conformance / Driver Conformance / Sound Driver Conformance},
>  \ref{sec:Conformance / Driver Conformance / Memory Driver Conformance},
> -\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance} or
> -\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance}.
> +\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance},
> +\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance} or
> +\ref{sec:Conformance / Driver Conformance / Parameter Server Driver
> Conformance}.
> 
>      \item Clause \ref{sec:Conformance / Legacy Interface:
> Transitional Device and Transitional Driver Conformance}.
>    \end{itemize}

(...)

> diff --git a/virtio-ps.tex b/virtio-ps.tex
> new file mode 100644
> index 0000000..f84b211
> --- /dev/null
> +++ b/virtio-ps.tex
> @@ -0,0 +1,197 @@
> +\section{Parameter Server}\label{sec:Device Types / Parameter Server}
> +
> +The parameter server device manages a set of values with unique
> property IDs. These values may
> +either be static (i.e. have a constant value) or be dynamic (i.e.
> value may change over time).
> +The driver can get and set values, get value configurations,
> subscribe and unsubscribe dynamic
> +properties from the device. The driver will get updates when
> subscribed value changes. The device

'a subscribed value', or 'subscribed values', I guess.

You also need to explain what 'subscribed' means. Subscription to
change notifications/updates?

> +processes the requests from the driver, enforces the value access
> rules, and may potentially alter
> +the behavior of external systems as a result of driver operations.
> +
> +\subsection{Device ID}\label{sec:Device Types / Parameter Server / Device ID}
> +
> +38
> +
> +\subsection{Virtqueues}\label{sec:Device Types / Parameter Server / Virtqueues}
> +
> +\begin{description}
> +\item[0] cmdq
> +\item[1] eventq
> +\end{description}
> +
> +\subsection{Feature Bits}\label{sec:Device Types / Parameter Server /
> Feature Bits}
> +
> +None currently defined.
> +
> +\subsection{Device Configuration Layout}\label{sec:Device Types /
> Parameter Server / Device Configuration Layout}
> +
> +\begin{lstlisting}
> +struct virtio_parameter_server_config {
> +    char name[128];
> +};
> +\end{lstlisting}
> +
> +A device configuration space only contains the name of the device,
> which can be used by the
> +userspace for identification.

What is 'userspace' in the context of this spec? I'd write

"\field{name} contains a name identifying the device."

Are there any further requirements (e.g. may the name be empty?)

<need to look at the remainder later>


---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

Re: [virtio-dev] [PATCH] Add virtio parameter server device specification

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 1173 bytes --]

On Mon, May 17, 2021 at 12:28:14PM -0700, Hao Chen wrote:
> > Can you share a bit about the reason for defining a new VIRTIO device
> > instead of running an existing key-value store over virtio-vsock or
> > virtio-net?
> 
> The reason for defining a virtio-parameter-server device is we are interacting
> with some devices in a "key-value store" pattern. For example, we interact with
> "vehicle device" in Android using this pattern.
> 
> Ad-hoc protocol over vsock to a k-v store works, but we want to
> standardize these
> types of devices so that the VM doesn't need to know the
> vendor-specific key-value
> protocols for a specific device implementation.

Thanks for explaining. Would publishing a k-v store protocol spec for
use with vsock? That way it's a well-known protocol that anyone wishing
to use k-v store functionality can use.

One nice effect of defining a protocol over vsock instead of a new
VIRTIO device is that implementation could be as simple as a
Python/Go/Rust/etc library that's easy to integrate into applications. A
VIRTIO device is more low-level and complex, making it more costly for
others to implement.

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [virtio-dev] [PATCH] Add virtio parameter server device specification

[Hao Chen]

> Thanks for explaining. Would publishing a k-v store protocol spec for
> use with vsock?

Does "standard protocol over vsock" exist in virtio-spec? We can say
"we use this protocol on vsock for this device, and it works very
well", but I guess it is still different than writing it somewhere in
the spec.

On Mon, May 24, 2021 at 7:38 AM Stefan Hajnoczi <stefanha@redhat.com> wrote:
>
> On Mon, May 17, 2021 at 12:28:14PM -0700, Hao Chen wrote:
> > > Can you share a bit about the reason for defining a new VIRTIO device
> > > instead of running an existing key-value store over virtio-vsock or
> > > virtio-net?
> >
> > The reason for defining a virtio-parameter-server device is we are interacting
> > with some devices in a "key-value store" pattern. For example, we interact with
> > "vehicle device" in Android using this pattern.
> >
> > Ad-hoc protocol over vsock to a k-v store works, but we want to
> > standardize these
> > types of devices so that the VM doesn't need to know the
> > vendor-specific key-value
> > protocols for a specific device implementation.
>
> Thanks for explaining. Would publishing a k-v store protocol spec for
> use with vsock? That way it's a well-known protocol that anyone wishing
> to use k-v store functionality can use.
>
> One nice effect of defining a protocol over vsock instead of a new
> VIRTIO device is that implementation could be as simple as a
> Python/Go/Rust/etc library that's easy to integrate into applications. A
> VIRTIO device is more low-level and complex, making it more costly for
> others to implement.
>
> Stefan

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

Re: [virtio-dev] [PATCH] Add virtio parameter server device specification

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 864 bytes --]

On Mon, May 24, 2021 at 11:45:43AM -0700, Hao Chen wrote:
> > Thanks for explaining. Would publishing a k-v store protocol spec for
> > use with vsock?
> 
> Does "standard protocol over vsock" exist in virtio-spec? We can say
> "we use this protocol on vsock for this device, and it works very
> well", but I guess it is still different than writing it somewhere in
> the spec.

Right, there is not vsock protocol authority but anyone can publish the
necessary information themselves or through a standards body. If your
goal is just to have a standard protocol then I think you can make it
much easier for others to implement by publishing your own protocol spec
that runs over a vsock socket.

Again, I'm not against adding this as a VIRTIO device. If you decide it
needs to be a VIRTIO device I'd be happy to review this patch fully.

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [virtio-dev] [PATCH] Add virtio parameter server device specification

[Enrico Weigelt, metux IT consult]

On 18.05.21 23:56, Hao Chen wrote:
> In our use case, we treat vehicle as a virtual device. For example, we
> send values to it to control the HVAC, and we receive values like car
> speed from the vehicle. We are not using virtio-can because 1. the
> vehicle bus does not have to be CAN and 2. we are doing something
> which more than just a pipe to the car bus (e.g., power management).

If its just reading / setting some kind of "variables" via some path
name, why not using 9P for that ?


--mtx

-- 
---
Hinweis: unverschlüsselte E-Mails können leicht abgehört und manipuliert
werden ! Für eine vertrauliche Kommunikation senden Sie bitte ihren
GPG/PGP-Schlüssel zu.
---
Enrico Weigelt, metux IT consult
Free software and Linux embedded engineering
info@metux.net -- +49-151-27565287

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

Re: [virtio-dev] [PATCH] Add virtio parameter server device specification

[Hao Chen]

> If your goal is just to have a standard protocol then I think you can make
> it much easier for others to implement by publishing your own protocol
> spec that runs over a vsock socket.

> If its just reading / setting some kind of "variables" via some path
> name, why not using 9P for that ?

We can use any protocol to implement this, and publish it somewhere, but it
does not carry the same weight as putting it in the virtio spec. It is
easier to say
"we use virtio, and for this device we use virtio-xxx device", but it
would be weird to
say "we use virtio, but for this device, we use vsock+some other non-standard
protocol, please support this or you will break the compatibility".
That is why we
want to put parameter server as a new virtio device.

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

Re: [virtio-dev] [PATCH] Add virtio parameter server device specification

[Enrico Weigelt, metux IT consult]

On 02.06.21 22:09, Hao Chen wrote:

> We can use any protocol to implement this, and publish it somewhere, but it
> does not carry the same weight as putting it in the virtio spec. It is
> easier to say
> "we use virtio, and for this device we use virtio-xxx device", but it
> would be weird to
> say "we use virtio, but for this device, we use vsock+some other non-standard
> protocol, please support this or you will break the compatibility".

Why not directly putting 9P links into virtio devices ?

In both cases we still have the problem knowing the actual meaning of
the individual parameters. Not so different from some raw IO space
(just a bit easier to parse).

I believe we need some layer above for describing the actual meanings.


--mtx

-- 
---
Hinweis: unverschlüsselte E-Mails können leicht abgehört und manipuliert
werden ! Für eine vertrauliche Kommunikation senden Sie bitte ihren
GPG/PGP-Schlüssel zu.
---
Enrico Weigelt, metux IT consult
Free software and Linux embedded engineering
info@metux.net -- +49-151-27565287

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

Re: [virtio-dev] [PATCH] Add virtio parameter server device specification

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 16195 bytes --]

On Tue, Apr 20, 2021 at 05:33:17PM -0700, Hao Chen wrote:
> This patch introduces a new type of device: parameter server. The device
> acts as a key-value store and the driver can read from, write to or
> subscribe to the properties in the server.
> 
> Signed-off-by: Hao Chen <chenhaosjtuacm@google.com>
> ---
>  conformance.tex |  26 +++++--
>  content.tex     |   1 +
>  virtio-ps.tex   | 188 ++++++++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 211 insertions(+), 4 deletions(-)
>  create mode 100644 virtio-ps.tex
> 
> diff --git a/conformance.tex b/conformance.tex
> index a164cbb..0d6b1a5 100644
> --- a/conformance.tex
> +++ b/conformance.tex
> @@ -29,8 +29,9 @@ \section{Conformance Targets}\label{sec:Conformance
> / Conformance Targets}
>  \ref{sec:Conformance / Driver Conformance / IOMMU Driver Conformance},
>  \ref{sec:Conformance / Driver Conformance / Sound Driver Conformance},
>  \ref{sec:Conformance / Driver Conformance / Memory Driver Conformance},
> -\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance} or
> -\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance}.
> +\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance},
> +\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance} or
> +\ref{sec:Conformance / Driver Conformance / Parameter Server Driver
> Conformance}.
> 
>      \item Clause \ref{sec:Conformance / Legacy Interface:
> Transitional Device and Transitional Driver Conformance}.
>    \end{itemize}
> @@ -52,8 +53,9 @@ \section{Conformance Targets}\label{sec:Conformance
> / Conformance Targets}
>  \ref{sec:Conformance / Device Conformance / IOMMU Device Conformance},
>  \ref{sec:Conformance / Device Conformance / Sound Device Conformance},
>  \ref{sec:Conformance / Device Conformance / Memory Device Conformance},
> -\ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance} or
> -\ref{sec:Conformance / Device Conformance / SCMI Device Conformance}.
> +\ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance},
> +\ref{sec:Conformance / Device Conformance / SCMI Device Conformance}or
> +\ref{sec:Conformance / Device Conformance / Parameter Server Device
> Conformance}.
> 
>      \item Clause \ref{sec:Conformance / Legacy Interface:
> Transitional Device and Transitional Driver Conformance}.
>    \end{itemize}
> @@ -288,6 +290,14 @@ \section{Conformance
> Targets}\label{sec:Conformance / Conformance Targets}
>  \item \ref{drivernormative:Device Types / SCMI Device / Device
> Operation / Setting Up eventq Buffers}
>  \end{itemize}
> 
> +\conformance{\subsection}{Parameter Server Driver
> Conformance}\label{sec:Conformance / Driver Conformance / Parameter
> Server Driver Conformance}
> +
> +A parameter server driver MUST conform to the following normative statements:
> +
> +\begin{itemize}
> +\item \ref{drivernormative:Device Types / Parameter Server / Device Operation}
> +\end{itemize}
> +
>  \conformance{\section}{Device Conformance}\label{sec:Conformance /
> Device Conformance}
> 
>  A device MUST conform to the following normative statements:
> @@ -527,6 +537,14 @@ \section{Conformance
> Targets}\label{sec:Conformance / Conformance Targets}
>  \item \ref{devicenormative:Device Types / SCMI Device / Device
> Operation / Shared Memory Operation}
>  \end{itemize}
> 
> +\conformance{\subsection}{Parameter Server Device
> Conformance}\label{sec:Conformance / Device Conformance / Parameter
> Server Device Conformance}
> +
> +A parameter server device MUST conform to the following normative statements:
> +
> +\begin{itemize}
> +\item \ref{devicenormative:Device Types / Parameter Server / 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 9232d5c..b980a93 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -6568,6 +6568,7 @@ \subsubsection{Legacy Interface: Framing
> Requirements}\label{sec:Device
>  \input{virtio-mem.tex}
>  \input{virtio-i2c.tex}
>  \input{virtio-scmi.tex}
> +\input{virtio-ps.tex}
> 
>  \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
> 
> diff --git a/virtio-ps.tex b/virtio-ps.tex
> new file mode 100644
> index 0000000..fa0930a
> --- /dev/null
> +++ b/virtio-ps.tex
> @@ -0,0 +1,188 @@
> +\section{Parameter Server}\label{sec:Device Types / Parameter Server}
> +
> +The parameter server device manages a set of values with unique
> property IDs. These values may
> +either be static (i.e. have a constant value) or be dynamic (i.e.
> value may change over time).
> +The driver can get and set values, get value configurations,
> subscribe and unsubscribe dynamic
> +properties from the device. The device processes the requests from
> the driver, enforces the value
> +access rules, and may potentially alter the behavior of external
> systems as a result of driver
> +operations.
>
> +\subsection{Device ID}\label{sec:Device Types / Parameter Server / Device ID}
> +
> +38
> +
> +\subsection{Virtqueues}\label{sec:Device Types / Parameter Server / Virtqueues}
> +
> +\begin{description}
> +\item[0] cmdq
> +\item[1] eventq
> +\end{description}
> +
> +\subsection{Feature Bits}\label{sec:Device Types / Parameter Server /
> Feature Bits}
> +
> +None currently defined.
> +
> +\subsection{Device Configuration Layout}\label{sec:Device Types /
> Parameter Server / Device Configuration Layout}
> +
> +\begin{lstlisting}
> +struct virtio_parameter_server_config {
> +    char name[128];
> +};
> +\end{lstlisting}
> +
> +A device configuration space only contains the name of the device,
> which can be used by the
> +userspace for identification.

What is the character encoding?

Is this field NUL-terminated?

Can the name be 128 chars long (no NUL terminator)?

> +
> +\subsection{Device Initialization}
> +
> +\begin{enumerate}
> +\item The virtqueues are initialized.
> +\end{enumerate}
> +
> +\subsection{Device Operation}\label{sec:Device Types / Parameter
> Server / Device Operation}
> +
> +The driver puts the requests to the cmdq virtqueue. The responses
> from the device also go into
> +the cmdq virtqueue. Updates on the subscribed values are put into the
> eventq virtqueue. The
> +\field{prop_id}, \field{prop_item_id} pair is the primary key for the
> values stored in the
> +parameter server, while the values with the same \field{prop_id}
> share the same configuration.

What does "share the same configuration" mean? I guess prop_id might be
a unique system identifier like a DNS domain name, an IP address, or a
UUID and you're saying that all parameters associated with that system
are stored under the same prop_id? That's one convention for using this
device interface, but there may be others that are also valid and
useful. I'm not sure if the spec should mention this (unless you go into
more detail about the structure of the keys later).

> +Subscriptions are also on \field{prop_id}.

Does this mean

  "Subscriptions monitor all <prop_id, prop_item_id> pairs for a given
  prop_id. It is not possible to monitor an individual <prop_id,
  prop_item_id> pair without also monitoring all other pairs with the
  same prop_id."

or

  "Subscriptions can monitor individual <prop_id, prop_item_id> pairs or
  all <prop_id, prop_item_id> pairs for a given prop_id"

?

> +
> +The layout of requests and responses are defined below:
> +
> +\begin{lstlisting}
> +struct virtio_parameter_server_request {
> +    le64 timestamp;

What are the units of this timestamp (nanoseconds, milliseconds,
seconds)?

Is there a reference clock so the device and driver can expect to be
synchronized (e.g. time since the UNIX epoch)?

What is the purpose of this field? Is there a timeout/time-to-live
feature?

> +    le32 prop_id;
> +    le32 prop_item_id;
> +    le32 payload_size;

There is no need to include a payload_size field because the device can
infer it from the buffer length:

  payload_size = virtq_elem_length - sizeof(struct virtio_parameter_server_request)

> +    u8 op;
> +    u8 payload[<actual payload size>];
> +};
> +
> +struct virtio_parameter_server_response {
> +    le64 timestamp;
> +    le32 prop_id;
> +    le32 prop_item_id;
> +    le32 payload_size;
> +    u16 op;
> +    u16 ret_value;
> +    u8 payload[<actual payload size>];
> +};
> +
> +/* Reserved prop_id and prop_item_id */
> +#define VIRTIO_PARAMETER_SERVER_OP_ALL_PROP INT_MAX
> +
> +/* Supported operations */
> +#define VIRTIO_PARAMETER_SERVER_OP_INVALID 0
> +#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_CONFIG 1
> +#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_VALUE 2
> +#define VIRTIO_PARAMETER_SERVER_OP_SET_PROP_VALUE 3
> +#define VIRTIO_PARAMETER_SERVER_OP_SUBSCRIBE_PROP 4
> +#define VIRTIO_PARAMETER_SERVER_OP_UNSUBSCRIBE_PROP 5
> +\end{lstlisting}
> +
> +The layout of messages in eventq is defined below:
> +
> +\begin{lstlisting}
> +struct virtio_parameter_server_event_msg {
> +    le64 timestamp;
> +    le32 prop_id;
> +    le32 prop_item_id;
> +    le32 payload_size;
> +    u8 payload[<actual payload size>];
> +};
> +\end{lstlisting}
> +
> +There will be exactly one response for each request in the cmdq, even
> if \field{op} is invalid. For some operations,
> +the \field{payload} of requests and/or responses may be empty. If the
> \field{payload} is non-empty, it can be either
> +property configuration(s) or value. The \field{payload} of messages
> in the eventq virtqueue is always value.

A common request layout for devices is:

  struct request {
      struct request_header header;
      u8 data[];
      struct request_footer footer;
  };

The data[] field has a variable size depending on the payload being
transferred. It can even support bi-directional transfers where the data
being written to the device comes first, followed by the data being read
from the device.

I suggest using this layout since other devices are also designed like
this. A few notes compared to what you have described:
1. There is no need for payload_size fields because the payload size can
   be inferred from the buffer (virtqueue element) length.
2. The footer is filled in by the device. There's no need to explicitly
   mention that the footer (struct virtio_parameter_server_response) is
   placed on the cmdq since it's embedded in struct request.
3. There's a 1:1 relationship between header and footer. There is no
   need to mention that most requests have a response associated with
   them.

> +
> +\subsubsection{Property Configuration Layout}\label{sec:Device Types
> / Parameter Server / Device Operation / Property Configuration Layout}
> +
> +\begin{lstlisting}
> +struct virtio_parameter_server_prop_config {
> +    le32 prop_id;
> +    le32 mode;
> +    le32 min_sample_freq;
> +    le32 max_sample_freq;
> +    le32 encoding[5];
> +    le32 param_size;
> +    char desc[256];
> +    u8 params[<actual param size>];
> +};
> +\end{lstlisting}
> +
> +while \field{mode} is the bitwise-or-combination of the following:
> +
> +\begin{lstlisting}
> +enum virtio_parameter_server_prop_mode {
> +    /* access */
> +    VIRTIO_PARAMETER_SERVER_M_READ = 0x1,
> +    VIRTIO_PARAMETER_SERVER_M_WRITE = 0x2,
> +    VIRTIO_PARAMETER_SERVER_M_READ_WRITE = 0x3,
> +
> +    /* change */
> +    VIRTIO_PARAMETER_SERVER_M_STATIC = 0x4,
> +    VIRTIO_PARAMETER_SERVER_M_MUTABLE = 0x8,
> +    VIRTIO_PARAMETER_SERVER_M_CONTINUOUS = 0xc,
> +};
> +\end{lstlisting}
> +
> +Both VIRTIO_PARAMETER_SERVER_M_MUTABLE and
> VIRTIO_PARAMETER_SERVER_M_CONTINUOUS are dynamic
> +properties. A VIRTIO_PARAMETER_SERVER_M_MUTABLE value will change due
> to the set value operation
> +from the driver, or actions of the external system; a
> VIRTIO_PARAMETER_SERVER_M_CONTINUOUS value
> +is expected to be generated by means of a sensor updating at a steady
> frequency.

Can you rephrase the definition of MUTABLE? I don't understand what it
means, especially since there is already a WRITE permission that
indicates read-only parameters. Why is MUTABLE needed?

Does CONTINUOUS mean that the device expects to update the value? You
mentioned a "steady frequency", is that the key characteristic being
described here? If so, then PERIODIC might be a clearer name than
CONTINUOUS (which could have other meanings, like that the value will be
different every time it's read).

> +The properties with the same \field{prop_id} share the configuration.

It is not clear to mean what a "configuration" is.

> \field{min_sample_freq} and
> +\field{max_sample_freq} are the sampling rate range for the
> +\field{VIRTIO_PARAMETER_SERVER_M_CONTINUOUS} values.

Is this really needed since the device interface also supports pub/sub?
If the application/driver wants to monitor a parameter that's
periodically updated by the device it can just subscribe to be notified
rather than reading at the max sample frequency and discarding unchanged
values.

By the way, is there a "current sample frequency"? If not, then I guess
the application/driver needs to assume min/max, depending on its
requirement. This could be inefficient.

> \field{desc} is
> the optional string
> +description.

Please indicate the character encoding and NUL termination of this
string.

Is this the parameter's name ("temperature_sensor_4") or is it a
description ("Main board temperature sensor")?

> \field{params} are for the customized configuration parameters.

This looks like a vendor-specific extension mechanism. It's opaque so
there's no way for the driver to skip over parameters it doesn't
understand. That could be a problem for version compatibility if the
device/driver are updated and expect different param[] data formats.
Perhaps it would help to define the structure that allows the driver to
skip unknown parameters?

How does the driver know how large to make the struct
virtio_parameter_server_prop_config buffer? Maybe there should be a
max_params_len configuration space field.

> +The integer array \field{encoding} specifies the number of different
> primitive value in the
> +property value.
> +
> +\begin{lstlisting}
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT64 0
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_FLOAT64 1
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT32 2
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_BYTE 3
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_HAS_STRING 4
> +
> +#define VIRTIO_PARAMETER_SERVER_VARIABLE_LENGTH -2
> +\end{lstlisting}
> +
> +If the driver asks for ALL property configurations, then the \field{payload} of
> +virtio_parameter_server_response will be multiple property
> configurations, serialized 1-by-1.
> +
> +\subsubsection{Property Value Layout}\label{sec:Device Types /
> Parameter Server / Device Operation / Property Value Layout}
> +
> +The property value payload begins with 5 arrays. The order is the
> same as the \field{encoding} array defined above.
> +For each array, it begins with a 32-bit integer for length (number of
> elements). Empty array will be a 32-bit 0, while
> +-1 means the array does not exist. The elements follows the length,
> and the size of the encoded array will be padded
> +to 4 bytes. String is encoded as char16_t, zero-terminated array.

Please include examples to illustrate this.

The character encoding of char16_t is implementation-defined in the C11
specification. So I guess it could be UCS-2, UTF-16, or any other 16-bit
encoding. Therefore char16_t is not enough to precisely describe
character encoding. Please state a character encoding (e.g. UTF-8,
UTF-16, etc).

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [virtio-dev] [PATCH] Add virtio parameter server device specification

[Hao Chen]

[-- Attachment #1: Type: text/plain, Size: 1592 bytes --]

> Why not directly putting 9P links into virtio devices ?

We have thought about using files to represent properties, but it turns out
we may need to subscribe to a large amount of
properties, so opening all of those files and polling is not ideal. Also
the cross-property time-order matters in our case, so we abandoned this
idea.

On Fri, Jun 4, 2021 at 3:50 AM Enrico Weigelt, metux IT consult <
lkml@metux.net> wrote:

> On 02.06.21 22:09, Hao Chen wrote:
>
> > We can use any protocol to implement this, and publish it somewhere, but
> it
> > does not carry the same weight as putting it in the virtio spec. It is
> > easier to say
> > "we use virtio, and for this device we use virtio-xxx device", but it
> > would be weird to
> > say "we use virtio, but for this device, we use vsock+some other
> non-standard
> > protocol, please support this or you will break the compatibility".
>
> Why not directly putting 9P links into virtio devices ?
>
> In both cases we still have the problem knowing the actual meaning of
> the individual parameters. Not so different from some raw IO space
> (just a bit easier to parse).
>
> I believe we need some layer above for describing the actual meanings.
>
>
> --mtx
>
> --
> ---
> Hinweis: unverschlüsselte E-Mails können leicht abgehört und manipuliert
> werden ! Für eine vertrauliche Kommunikation senden Sie bitte ihren
> GPG/PGP-Schlüssel zu.
> ---
> Enrico Weigelt, metux IT consult
> Free software and Linux embedded engineering
> info@metux.net -- +49-151-27565287 <+49%201512%207565287>
>

[-- Attachment #2: Type: text/html, Size: 2098 bytes --]

Re: [virtio-dev] [PATCH] Add virtio parameter server device specification

[Enrico Weigelt, metux IT consult]

On 09.06.21 22:30, Hao Chen wrote:
>  > Why not directly putting 9P links into virtio devices ?
> 
> We have thought about using files to represent properties, but it turns 
> out we may need to subscribe to a large amount of
> properties, so opening all of those files and polling is not ideal. Also 
> the cross-property time-order matters in our case, so we abandoned this 
> idea.

On 9P it would just be issuing one Tread per file you're intersted in
(of course, after Rread comes in, you'll have to send it again, if you
wanna continue to read).

How is that so different from subscriptions ?

--mtx

-- 
---
Hinweis: unverschlüsselte E-Mails können leicht abgehört und manipuliert
werden ! Für eine vertrauliche Kommunikation senden Sie bitte ihren
GPG/PGP-Schlüssel zu.
---
Enrico Weigelt, metux IT consult
Free software and Linux embedded engineering
info@metux.net -- +49-151-27565287

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

Re: [virtio-dev] [PATCH] Add virtio parameter server device specification

[Hao Chen]

[-- Attachment #1: Type: text/plain, Size: 5539 bytes --]

Hi Stefan and Enrico,

> What does "share the same configuration" mean? ...

It means these values share the virtio_parameter_server_prop_config.
So they will have the same mode (e.g., all of them are read-only and
static).
Also they have the same encoding rule, for example, each value contains one
64-bit integer and three 64-bit floating point numbers.

> What are the units of this timestamp (nanoseconds, milliseconds,
> seconds)?

I don't know if I should define the unit, in our current usecase,
it can be unix timestamp in milliseconds, but I don't know if it is
true for all potential usecases. Maybe in some cases there will not
be real-world timestamp but using sequential numbers instead. So I
leave it blank here. The reason of having this field is the guest VM
userspace may need to know the order of the generation of the data.
In some cases the guest userspace may also care about the real generation
time. Do you prefer having a clearer definition here?

> A common request layout for devices is:
>
>  struct request {
>      struct request_header header;
>      u8 data[];
>      struct request_footer footer;
>  };

I didn't see any "footers" in the current spec. Could you please explain
more?

> Can you rephrase the definition of MUTABLE? I don't understand what it
> means, especially since there is already a WRITE permission that
> indicates read-only parameters. Why is MUTABLE needed?

Write permission and mutable variables are different things. For example,
if we use a flag to indicate if it is sunny outside, we cannot write to it
since we cannot control the weather, but the value is definitely mutable
because weather may change.

> Does CONTINUOUS mean that the device expects to update the value?
> ...  then PERIODIC might be a clearer name than CONTINUOUS

Both MUTABLE and CONTINUOUS variables may be changed by the device,
but MUTABLE value changes usually represent async value updates (like
IP address changed, gear switched, or weather changed, etc.), the value
need to be send to the driver in every updates; while CONTINOUS values
are more like rated sensor data.

> > +The properties with the same \field{prop_id} share the configuration.

> It is not clear to mean what a "configuration" is.

"configuration" means "virtio_parameter_server_prop_config"


> > \field{min_sample_freq} and
> > +\field{max_sample_freq} are the sampling rate range for the
> > +\field{VIRTIO_PARAMETER_SERVER_M_CONTINUOUS} values.

> Is this really needed since the device interface also supports pub/sub?

It is, those numbers indicate how fast the device will sample the data for
the driver. The driver doesn't fetch the value at the max rate, it just
check.

> > \field{desc} is
> > the optional string
> > +description.

> Is this the parameter's name ("temperature_sensor_4") or is it a
> description ("Main board temperature sensor")?

What is the difference? The device use the prop_id to identify parameters
and this is for human anyways.

> > \field{params} are for the customized configuration parameters.

> This looks like a vendor-specific extension mechanism. It's opaque so
> there's no way for the driver to skip over parameters it doesn't
> understand. That could be a problem for version compatibility if the
> device/driver are updated and expect different param[] data formats.
> Perhaps it would help to define the structure that allows the driver to
> skip unknown parameters?

The driver does not care. The driver's behavior is nothing to do with the
configs. The configs are for the userspace to understand the value it
receives. In each specific case, there will be some special "configs" that
the userspace app may need to know, but the driver is still act as a general
parameter server driver.

> On 9P it would just be issuing one Tread per file you're intersted in
> (of course, after Rread comes in, you'll have to send it again, if you
> wanna continue to read).

> How is that so different from subscriptions ?

I have to say I am not familar with 9P, but in our case we don't need to
launch
1000+ threads to read on files or open 1000+ fds to poll on them (we
literally
have that many properties!). We just process the data from the eventq. Also,
by using a single eventq, we are free from maintaining a data structure like
priority queue to make sure the data is processed in-order.

On Thu, Jun 10, 2021 at 9:06 AM Enrico Weigelt, metux IT consult <
lkml@metux.net> wrote:

> On 09.06.21 22:30, Hao Chen wrote:
> >  > Why not directly putting 9P links into virtio devices ?
> >
> > We have thought about using files to represent properties, but it turns
> > out we may need to subscribe to a large amount of
> > properties, so opening all of those files and polling is not ideal. Also
> > the cross-property time-order matters in our case, so we abandoned this
> > idea.
>
> On 9P it would just be issuing one Tread per file you're intersted in
> (of course, after Rread comes in, you'll have to send it again, if you
> wanna continue to read).
>
> How is that so different from subscriptions ?
>
> --mtx
>
> --
> ---
> Hinweis: unverschlüsselte E-Mails können leicht abgehört und manipuliert
> werden ! Für eine vertrauliche Kommunikation senden Sie bitte ihren
> GPG/PGP-Schlüssel zu.
> ---
> Enrico Weigelt, metux IT consult
> Free software and Linux embedded engineering
> info@metux.net -- +49-151-27565287 <+49%201512%207565287>
>

[-- Attachment #2: Type: text/html, Size: 6484 bytes --]

[virtio-dev] Re: [PATCH v4] Add virtio parameter server device specification

[Hao Chen]

[-- Attachment #1: Type: text/plain, Size: 14333 bytes --]

On Thu, Jun 10, 2021 at 4:19 PM Hao Chen <chenhaosjtuacm@google.com> wrote:

> This patch introduces a new type of device: parameter server. The device
> acts as a key-value store and the driver can read from, write to or
> subscribe to the properties in the server.
>
> Signed-off-by: Hao Chen <chenhaosjtuacm@google.com>
> ---
>  conformance.tex |  26 +++++-
>  content.tex     |   1 +
>  virtio-ps.tex   | 216 ++++++++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 239 insertions(+), 4 deletions(-)
>  create mode 100644 virtio-ps.tex
>
> diff --git a/conformance.tex b/conformance.tex
> index a164cbb..0d6b1a5 100644
> --- a/conformance.tex
> +++ b/conformance.tex
> @@ -29,8 +29,9 @@ \section{Conformance Targets}\label{sec:Conformance /
> Conformance Targets}
>  \ref{sec:Conformance / Driver Conformance / IOMMU Driver Conformance},
>  \ref{sec:Conformance / Driver Conformance / Sound Driver Conformance},
>  \ref{sec:Conformance / Driver Conformance / Memory Driver Conformance},
> -\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver
> Conformance} or
> -\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance}.
> +\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver
> Conformance},
> +\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance} or
> +\ref{sec:Conformance / Driver Conformance / Parameter Server Driver
> Conformance}.
>
>      \item Clause \ref{sec:Conformance / Legacy Interface: Transitional
> Device and Transitional Driver Conformance}.
>    \end{itemize}
> @@ -52,8 +53,9 @@ \section{Conformance Targets}\label{sec:Conformance /
> Conformance Targets}
>  \ref{sec:Conformance / Device Conformance / IOMMU Device Conformance},
>  \ref{sec:Conformance / Device Conformance / Sound Device Conformance},
>  \ref{sec:Conformance / Device Conformance / Memory Device Conformance},
> -\ref{sec:Conformance / Device Conformance / I2C Adapter Device
> Conformance} or
> -\ref{sec:Conformance / Device Conformance / SCMI Device Conformance}.
> +\ref{sec:Conformance / Device Conformance / I2C Adapter Device
> Conformance},
> +\ref{sec:Conformance / Device Conformance / SCMI Device Conformance}or
> +\ref{sec:Conformance / Device Conformance / Parameter Server Device
> Conformance}.
>
>      \item Clause \ref{sec:Conformance / Legacy Interface: Transitional
> Device and Transitional Driver Conformance}.
>    \end{itemize}
> @@ -288,6 +290,14 @@ \section{Conformance Targets}\label{sec:Conformance /
> Conformance Targets}
>  \item \ref{drivernormative:Device Types / SCMI Device / Device Operation
> / Setting Up eventq Buffers}
>  \end{itemize}
>
> +\conformance{\subsection}{Parameter Server Driver
> Conformance}\label{sec:Conformance / Driver Conformance / Parameter Server
> Driver Conformance}
> +
> +A parameter server driver MUST conform to the following normative
> statements:
> +
> +\begin{itemize}
> +\item \ref{drivernormative:Device Types / Parameter Server / Device
> Operation}
> +\end{itemize}
> +
>  \conformance{\section}{Device Conformance}\label{sec:Conformance / Device
> Conformance}
>
>  A device MUST conform to the following normative statements:
> @@ -527,6 +537,14 @@ \section{Conformance Targets}\label{sec:Conformance /
> Conformance Targets}
>  \item \ref{devicenormative:Device Types / SCMI Device / Device Operation
> / Shared Memory Operation}
>  \end{itemize}
>
> +\conformance{\subsection}{Parameter Server Device
> Conformance}\label{sec:Conformance / Device Conformance / Parameter Server
> Device Conformance}
> +
> +A parameter server device MUST conform to the following normative
> statements:
> +
> +\begin{itemize}
> +\item \ref{devicenormative:Device Types / Parameter Server / 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 9232d5c..b980a93 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -6568,6 +6568,7 @@ \subsubsection{Legacy Interface: Framing
> Requirements}\label{sec:Device
>  \input{virtio-mem.tex}
>  \input{virtio-i2c.tex}
>  \input{virtio-scmi.tex}
> +\input{virtio-ps.tex}
>
>  \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
>
> diff --git a/virtio-ps.tex b/virtio-ps.tex
> new file mode 100644
> index 0000000..2a226c4
> --- /dev/null
> +++ b/virtio-ps.tex
> @@ -0,0 +1,216 @@
> +\section{Parameter Server}\label{sec:Device Types / Parameter Server}
> +
> +The parameter server device manages a set of values with unique property
> IDs. These values may
> +either be static (i.e. have a constant value) or be dynamic (i.e. value
> may change over time).
> +The driver can get and set values, get value configurations, subscribe
> and unsubscribe dynamic
> +properties from the device. The driver will get updates when subscribed
> value changes. The device
> +processes the requests from the driver, enforces the value access rules,
> and may potentially alter
> +the behavior of external systems as a result of driver operations.
> +
> +\subsection{Device ID}\label{sec:Device Types / Parameter Server / Device
> ID}
> +
> +38
> +
> +\subsection{Virtqueues}\label{sec:Device Types / Parameter Server /
> Virtqueues}
> +
> +\begin{description}
> +\item[0] cmdq
> +\item[1] eventq
> +\end{description}
> +
> +\subsection{Feature Bits}\label{sec:Device Types / Parameter Server /
> Feature Bits}
> +
> +None currently defined.
> +
> +\subsection{Device Configuration Layout}\label{sec:Device Types /
> Parameter Server / Device Configuration Layout}
> +
> +\begin{lstlisting}
> +struct virtio_parameter_server_config {
> +    char name[128];
> +};
> +\end{lstlisting}
> +
> +A device configuration space only contains the name of the device, which
> can be used by the
> +userspace for identification. \field{name} is a zero-terminated char
> string. The maximum length
> +of \field{name} is 127.
> +
> +\subsection{Device Initialization}
> +
> +\begin{enumerate}
> +\item The virtqueues are initialized.
> +\end{enumerate}
> +
> +\subsection{Device Operation}\label{sec:Device Types / Parameter Server /
> Device Operation}
> +
> +The driver puts requests to read, write, subscribe to, or unsubscribe
> from, parameters onto the
> +cmdq virtqueue. The device also puts its responses to the driver's
> requests onto the cmdq
> +virtqueue. The device puts any updates to values that the driver has
> subscribed to onto the
> +eventq virtqueue. The
> +\field{prop_id}, \field{prop_item_id} pair is the primary key for the
> values stored in the
> +parameter server, while the values with the same \field{prop_id} share
> the same configuration.
> +For example, \field{prop_id} 12 with \field{prop_item_id} 0, 1 and 2
> represent 3 different values
> +sharing the same \field{virtio_parameter_server_config}. \field{prop_id}
> is also used for
> +subscriptions, meaning that if you subscribe on a prop_id, you will
> receive every updates on that
> +prop_id regardless of what prop_item_id it contains. \field{prop_item_id}
> is not used in
> +subscription.
> +
> +The layout of requests and responses are defined below:
> +
> +\begin{lstlisting}
> +struct virtio_parameter_server_request {
> +    le64 timestamp;
> +    le32 prop_id;
> +    le32 prop_item_id;
> +    u8 op;
> +    u8 payload[<actual payload size>];
> +};
> +
> +struct virtio_parameter_server_response {
> +    le64 timestamp;
> +    le32 prop_id;
> +    le32 prop_item_id;
> +    u16 op;
> +    u16 ret_value;
> +    u8 payload[<actual payload size>];
> +};
> +
> +/* Reserved prop_id and prop_item_id */
> +#define VIRTIO_PARAMETER_SERVER_OP_ALL_PROP INT_MAX
> +
> +/* Supported operations */
> +#define VIRTIO_PARAMETER_SERVER_OP_INVALID 0
> +#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_CONFIG 1
> +#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_VALUE 2
> +#define VIRTIO_PARAMETER_SERVER_OP_SET_PROP_VALUE 3
> +#define VIRTIO_PARAMETER_SERVER_OP_SUBSCRIBE_PROP 4
> +#define VIRTIO_PARAMETER_SERVER_OP_UNSUBSCRIBE_PROP 5
> +\end{lstlisting}
> +
> +The layout of messages in eventq is defined below:
> +
> +\begin{lstlisting}
> +struct virtio_parameter_server_event_msg {
> +    le64 timestamp;
> +    le32 prop_id;
> +    le32 prop_item_id;
> +    u8 payload[<actual payload size>];
> +};
> +\end{lstlisting}
> +
> +There will be exactly one response for each request in the cmdq, even if
> \field{op} is invalid. For some operations,
> +the \field{payload} of requests and/or responses may be empty. The
> content of the payload depend on the operation.
> +
> +\subsubsection{Property Configuration Layout}\label{sec:Device Types /
> Parameter Server / Device Operation / Property Configuration Layout}
> +
> +\begin{lstlisting}
> +// The max size of virtio_parameter_server_config, including
> +// fixed-length members and params
> +#define VIRTIO_PARAMETER_SERVER_CONFIG_MAX_SIZE_BYTE 4096
> +
> +struct virtio_parameter_server_prop_config {
> +    le32 prop_id;
> +    le32 mode;
> +    le32 min_sample_freq;
> +    le32 max_sample_freq;
> +    le32 encoding[5];
> +    le32 param_size;
> +    char desc[256];
> +    u8 params[<actual param size>];
> +};
> +\end{lstlisting}
> +
> +while \field{mode} is the bitwise-or-combination of the following:
> +
> +\begin{lstlisting}
> +enum virtio_parameter_server_prop_mode {
> +    /* access */
> +    VIRTIO_PARAMETER_SERVER_M_READ = 0x1,
> +    VIRTIO_PARAMETER_SERVER_M_WRITE = 0x2,
> +    VIRTIO_PARAMETER_SERVER_M_READ_WRITE = 0x3,
> +
> +    /* change */
> +    VIRTIO_PARAMETER_SERVER_M_STATIC = 0x4,
> +    VIRTIO_PARAMETER_SERVER_M_MUTABLE = 0x8,
> +    VIRTIO_PARAMETER_SERVER_M_CONTINUOUS = 0xc,
> +};
> +\end{lstlisting}
> +
> +Both VIRTIO_PARAMETER_SERVER_M_MUTABLE and
> VIRTIO_PARAMETER_SERVER_M_CONTINUOUS are dynamic
> +properties. A VIRTIO_PARAMETER_SERVER_M_MUTABLE value will change due to
> the set value operation
> +from the driver, or actions of the external system; a
> VIRTIO_PARAMETER_SERVER_M_CONTINUOUS value
> +is expected to be generated by means of a sensor updating at a steady
> frequency.
> +
> +The reason we want to handle "MUTABLE" and "CONTNUOUS" differently is,
> the MUTABLE values are not
> +constantly changing, so the device may be able to send every updates of
> it to the driver; while
> +CONTINUOUS values are changing frequently (e.g., sensor outputs) and the
> device should decide how
> +to sample it and provide a sample rate range (\field{min_sample_freq} and
> \field{max_sample_freq})
> +
> +The properties with the same \field{prop_id} share the configuration.
> \field{min_sample_freq} and
> +\field{max_sample_freq} are the sampling rate range for the
> +\field{VIRTIO_PARAMETER_SERVER_M_CONTINUOUS} values. \field{desc} is the
> optional zero-terminated
> +char string description. \field{params} are for the customized
> configuration parameters.
> +
> +The integer array \field{encoding} specifies the number of different
> primitive value in the
> +property value.
> +
> +\begin{lstlisting}
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT64 0
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_FLOAT64 1
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT32 2
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_BYTE 3
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_HAS_STRING 4
> +\end{lstlisting}
> +
> +If the driver asks for ALL property configurations by setting the
> \field{prop_id} of the request to
> +VIRTIO_PARAMETER_SERVER_OP_ALL_PROP, then the \field{payload} of
> virtio_parameter_server_response
> +will be multiple property configurations, serialized 1-by-1.
> +
> +\subsubsection{Property Value Layout}\label{sec:Device Types / Parameter
> Server / Device Operation / Property Value Layout}
> +
> +The property value payload begins with 5 arrays. The order is the same as
> the \field{encoding} array defined above.
> +For each array, it begins with a 32-bit integer for length (number of
> elements). Empty array will be a 32-bit 0, while
> +-1 means the array does not exist. The elements follows the length, and
> the size of the encoded array will be padded
> +to 4 bytes. String is encoded as a zero-terminated char array,
> +\field{encoding[VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_HAS_STRING]}
> indicates the existence of the string.
> +
> +After the arrays, there may be customized data, which is encoded as a
> byte array.
> +
> +For example, if \field{encoding} of virtio_parameter_server_prop_config
> of property A is \field{[2, 0, 0, 0, 1]},
> +then property A contains two 64-bit integers and a string. The encoded
> value consists of the following (from top to bottom):
> +
> +\begin{lstlisting}
> +2 (32-bit, meaning 2 64-bit integers)
> +64-bit integer
> +64-bit integer
> +-1 (32-bit, meaning no 64-bit float number array)
> +-1 (32-bit, meaning no 32-bit integer array)
> +-1 (32-bit, meaning no byte array)
> +14 (32-bit integer, length of the char string, including trailing zero,
> excluding padding zeros)
> +"sample string\0"
> +padding zeros to 4 bytes. In this case there will be 2 zero bytes.
> +(optional) byte array length + data if there are customized data
> +\end{lstlisting}
> +
> +\drivernormative{\subsubsection}{Device Operation}{Device Types /
> Parameter Server / Device Operation}
> +
> +The driver MUST NOT send undefined ops.
> +
> +The driver MUST NOT put descriptors into the eventq.
> +
> +The payload size of requests MUST be padded to 4 bytes.
> +
> +\devicenormative{\subsubsection}{Device Operation}{Device Types /
> Parameter Server / Device Operation}
> +
> +\field{name} of the device configuration MUST be non-empty.
> +
> +The unused bits of the message header MUST be 0.
> +
> +The \field{prop_item_id} of VIRTIO_PARAMETER_SERVER_OP_GET_PROP_CONFIG,
> +VIRTIO_PARAMETER_SERVER_OP_SUBSCRIBE_PROP and
> VIRTIO_PARAMETER_SERVER_OP_UNSUBSCRIBE_PROP requests
> +MUST be ignored.
> +
> +The device MUST send exact 1 response for every received request.
> +
> +The payload size of responses and event messages MUST be padded to 4
> bytes.
> +
> +The param size of property configurations MUST be padded to 4 bytes.
> --
> 2.32.0.272.g935e593368-goog
>
>

[-- Attachment #2: Type: text/html, Size: 15633 bytes --]

[virtio-dev] Re: [PATCH v4] Add virtio parameter server device specification

[Hao Chen]

On Thu, Jun 10, 2021 at 4:19 PM Hao Chen <chenhaosjtuacm@google.com> wrote:
>
> This patch introduces a new type of device: parameter server. The device
> acts as a key-value store and the driver can read from, write to or
> subscribe to the properties in the server.
>
> Signed-off-by: Hao Chen <chenhaosjtuacm@google.com>
> ---
>  conformance.tex |  26 +++++-
>  content.tex     |   1 +
>  virtio-ps.tex   | 216 ++++++++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 239 insertions(+), 4 deletions(-)
>  create mode 100644 virtio-ps.tex
>
> diff --git a/conformance.tex b/conformance.tex
> index a164cbb..0d6b1a5 100644
> --- a/conformance.tex
> +++ b/conformance.tex
> @@ -29,8 +29,9 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
>  \ref{sec:Conformance / Driver Conformance / IOMMU Driver Conformance},
>  \ref{sec:Conformance / Driver Conformance / Sound Driver Conformance},
>  \ref{sec:Conformance / Driver Conformance / Memory Driver Conformance},
> -\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance} or
> -\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance}.
> +\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance},
> +\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance} or
> +\ref{sec:Conformance / Driver Conformance / Parameter Server Driver Conformance}.
>
>      \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}.
>    \end{itemize}
> @@ -52,8 +53,9 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
>  \ref{sec:Conformance / Device Conformance / IOMMU Device Conformance},
>  \ref{sec:Conformance / Device Conformance / Sound Device Conformance},
>  \ref{sec:Conformance / Device Conformance / Memory Device Conformance},
> -\ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance} or
> -\ref{sec:Conformance / Device Conformance / SCMI Device Conformance}.
> +\ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance},
> +\ref{sec:Conformance / Device Conformance / SCMI Device Conformance}or
> +\ref{sec:Conformance / Device Conformance / Parameter Server Device Conformance}.
>
>      \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}.
>    \end{itemize}
> @@ -288,6 +290,14 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
>  \item \ref{drivernormative:Device Types / SCMI Device / Device Operation / Setting Up eventq Buffers}
>  \end{itemize}
>
> +\conformance{\subsection}{Parameter Server Driver Conformance}\label{sec:Conformance / Driver Conformance / Parameter Server Driver Conformance}
> +
> +A parameter server driver MUST conform to the following normative statements:
> +
> +\begin{itemize}
> +\item \ref{drivernormative:Device Types / Parameter Server / Device Operation}
> +\end{itemize}
> +
>  \conformance{\section}{Device Conformance}\label{sec:Conformance / Device Conformance}
>
>  A device MUST conform to the following normative statements:
> @@ -527,6 +537,14 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
>  \item \ref{devicenormative:Device Types / SCMI Device / Device Operation / Shared Memory Operation}
>  \end{itemize}
>
> +\conformance{\subsection}{Parameter Server Device Conformance}\label{sec:Conformance / Device Conformance / Parameter Server Device Conformance}
> +
> +A parameter server device MUST conform to the following normative statements:
> +
> +\begin{itemize}
> +\item \ref{devicenormative:Device Types / Parameter Server / 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 9232d5c..b980a93 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -6568,6 +6568,7 @@ \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
>  \input{virtio-mem.tex}
>  \input{virtio-i2c.tex}
>  \input{virtio-scmi.tex}
> +\input{virtio-ps.tex}
>
>  \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
>
> diff --git a/virtio-ps.tex b/virtio-ps.tex
> new file mode 100644
> index 0000000..2a226c4
> --- /dev/null
> +++ b/virtio-ps.tex
> @@ -0,0 +1,216 @@
> +\section{Parameter Server}\label{sec:Device Types / Parameter Server}
> +
> +The parameter server device manages a set of values with unique property IDs. These values may
> +either be static (i.e. have a constant value) or be dynamic (i.e. value may change over time).
> +The driver can get and set values, get value configurations, subscribe and unsubscribe dynamic
> +properties from the device. The driver will get updates when subscribed value changes. The device
> +processes the requests from the driver, enforces the value access rules, and may potentially alter
> +the behavior of external systems as a result of driver operations.
> +
> +\subsection{Device ID}\label{sec:Device Types / Parameter Server / Device ID}
> +
> +38
> +
> +\subsection{Virtqueues}\label{sec:Device Types / Parameter Server / Virtqueues}
> +
> +\begin{description}
> +\item[0] cmdq
> +\item[1] eventq
> +\end{description}
> +
> +\subsection{Feature Bits}\label{sec:Device Types / Parameter Server / Feature Bits}
> +
> +None currently defined.
> +
> +\subsection{Device Configuration Layout}\label{sec:Device Types / Parameter Server / Device Configuration Layout}
> +
> +\begin{lstlisting}
> +struct virtio_parameter_server_config {
> +    char name[128];
> +};
> +\end{lstlisting}
> +
> +A device configuration space only contains the name of the device, which can be used by the
> +userspace for identification. \field{name} is a zero-terminated char string. The maximum length
> +of \field{name} is 127.
> +
> +\subsection{Device Initialization}
> +
> +\begin{enumerate}
> +\item The virtqueues are initialized.
> +\end{enumerate}
> +
> +\subsection{Device Operation}\label{sec:Device Types / Parameter Server / Device Operation}
> +
> +The driver puts requests to read, write, subscribe to, or unsubscribe from, parameters onto the
> +cmdq virtqueue. The device also puts its responses to the driver's requests onto the cmdq
> +virtqueue. The device puts any updates to values that the driver has subscribed to onto the
> +eventq virtqueue. The
> +\field{prop_id}, \field{prop_item_id} pair is the primary key for the values stored in the
> +parameter server, while the values with the same \field{prop_id} share the same configuration.
> +For example, \field{prop_id} 12 with \field{prop_item_id} 0, 1 and 2 represent 3 different values
> +sharing the same \field{virtio_parameter_server_config}. \field{prop_id} is also used for
> +subscriptions, meaning that if you subscribe on a prop_id, you will receive every updates on that
> +prop_id regardless of what prop_item_id it contains. \field{prop_item_id} is not used in
> +subscription.
> +
> +The layout of requests and responses are defined below:
> +
> +\begin{lstlisting}
> +struct virtio_parameter_server_request {
> +    le64 timestamp;
> +    le32 prop_id;
> +    le32 prop_item_id;
> +    u8 op;
> +    u8 payload[<actual payload size>];
> +};
> +
> +struct virtio_parameter_server_response {
> +    le64 timestamp;
> +    le32 prop_id;
> +    le32 prop_item_id;
> +    u16 op;
> +    u16 ret_value;
> +    u8 payload[<actual payload size>];
> +};
> +
> +/* Reserved prop_id and prop_item_id */
> +#define VIRTIO_PARAMETER_SERVER_OP_ALL_PROP INT_MAX
> +
> +/* Supported operations */
> +#define VIRTIO_PARAMETER_SERVER_OP_INVALID 0
> +#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_CONFIG 1
> +#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_VALUE 2
> +#define VIRTIO_PARAMETER_SERVER_OP_SET_PROP_VALUE 3
> +#define VIRTIO_PARAMETER_SERVER_OP_SUBSCRIBE_PROP 4
> +#define VIRTIO_PARAMETER_SERVER_OP_UNSUBSCRIBE_PROP 5
> +\end{lstlisting}
> +
> +The layout of messages in eventq is defined below:
> +
> +\begin{lstlisting}
> +struct virtio_parameter_server_event_msg {
> +    le64 timestamp;
> +    le32 prop_id;
> +    le32 prop_item_id;
> +    u8 payload[<actual payload size>];
> +};
> +\end{lstlisting}
> +
> +There will be exactly one response for each request in the cmdq, even if \field{op} is invalid. For some operations,
> +the \field{payload} of requests and/or responses may be empty. The content of the payload depend on the operation.
> +
> +\subsubsection{Property Configuration Layout}\label{sec:Device Types / Parameter Server / Device Operation / Property Configuration Layout}
> +
> +\begin{lstlisting}
> +// The max size of virtio_parameter_server_config, including
> +// fixed-length members and params
> +#define VIRTIO_PARAMETER_SERVER_CONFIG_MAX_SIZE_BYTE 4096
> +
> +struct virtio_parameter_server_prop_config {
> +    le32 prop_id;
> +    le32 mode;
> +    le32 min_sample_freq;
> +    le32 max_sample_freq;
> +    le32 encoding[5];
> +    le32 param_size;
> +    char desc[256];
> +    u8 params[<actual param size>];
> +};
> +\end{lstlisting}
> +
> +while \field{mode} is the bitwise-or-combination of the following:
> +
> +\begin{lstlisting}
> +enum virtio_parameter_server_prop_mode {
> +    /* access */
> +    VIRTIO_PARAMETER_SERVER_M_READ = 0x1,
> +    VIRTIO_PARAMETER_SERVER_M_WRITE = 0x2,
> +    VIRTIO_PARAMETER_SERVER_M_READ_WRITE = 0x3,
> +
> +    /* change */
> +    VIRTIO_PARAMETER_SERVER_M_STATIC = 0x4,
> +    VIRTIO_PARAMETER_SERVER_M_MUTABLE = 0x8,
> +    VIRTIO_PARAMETER_SERVER_M_CONTINUOUS = 0xc,
> +};
> +\end{lstlisting}
> +
> +Both VIRTIO_PARAMETER_SERVER_M_MUTABLE and VIRTIO_PARAMETER_SERVER_M_CONTINUOUS are dynamic
> +properties. A VIRTIO_PARAMETER_SERVER_M_MUTABLE value will change due to the set value operation
> +from the driver, or actions of the external system; a VIRTIO_PARAMETER_SERVER_M_CONTINUOUS value
> +is expected to be generated by means of a sensor updating at a steady frequency.
> +
> +The reason we want to handle "MUTABLE" and "CONTNUOUS" differently is, the MUTABLE values are not
> +constantly changing, so the device may be able to send every updates of it to the driver; while
> +CONTINUOUS values are changing frequently (e.g., sensor outputs) and the device should decide how
> +to sample it and provide a sample rate range (\field{min_sample_freq} and \field{max_sample_freq})
> +
> +The properties with the same \field{prop_id} share the configuration. \field{min_sample_freq} and
> +\field{max_sample_freq} are the sampling rate range for the
> +\field{VIRTIO_PARAMETER_SERVER_M_CONTINUOUS} values. \field{desc} is the optional zero-terminated
> +char string description. \field{params} are for the customized configuration parameters.
> +
> +The integer array \field{encoding} specifies the number of different primitive value in the
> +property value.
> +
> +\begin{lstlisting}
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT64 0
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_FLOAT64 1
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT32 2
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_BYTE 3
> +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_HAS_STRING 4
> +\end{lstlisting}
> +
> +If the driver asks for ALL property configurations by setting the \field{prop_id} of the request to
> +VIRTIO_PARAMETER_SERVER_OP_ALL_PROP, then the \field{payload} of virtio_parameter_server_response
> +will be multiple property configurations, serialized 1-by-1.
> +
> +\subsubsection{Property Value Layout}\label{sec:Device Types / Parameter Server / Device Operation / Property Value Layout}
> +
> +The property value payload begins with 5 arrays. The order is the same as the \field{encoding} array defined above.
> +For each array, it begins with a 32-bit integer for length (number of elements). Empty array will be a 32-bit 0, while
> +-1 means the array does not exist. The elements follows the length, and the size of the encoded array will be padded
> +to 4 bytes. String is encoded as a zero-terminated char array,
> +\field{encoding[VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_HAS_STRING]} indicates the existence of the string.
> +
> +After the arrays, there may be customized data, which is encoded as a byte array.
> +
> +For example, if \field{encoding} of virtio_parameter_server_prop_config of property A is \field{[2, 0, 0, 0, 1]},
> +then property A contains two 64-bit integers and a string. The encoded value consists of the following (from top to bottom):
> +
> +\begin{lstlisting}
> +2 (32-bit, meaning 2 64-bit integers)
> +64-bit integer
> +64-bit integer
> +-1 (32-bit, meaning no 64-bit float number array)
> +-1 (32-bit, meaning no 32-bit integer array)
> +-1 (32-bit, meaning no byte array)
> +14 (32-bit integer, length of the char string, including trailing zero, excluding padding zeros)
> +"sample string\0"
> +padding zeros to 4 bytes. In this case there will be 2 zero bytes.
> +(optional) byte array length + data if there are customized data
> +\end{lstlisting}
> +
> +\drivernormative{\subsubsection}{Device Operation}{Device Types / Parameter Server / Device Operation}
> +
> +The driver MUST NOT send undefined ops.
> +
> +The driver MUST NOT put descriptors into the eventq.
> +
> +The payload size of requests MUST be padded to 4 bytes.
> +
> +\devicenormative{\subsubsection}{Device Operation}{Device Types / Parameter Server / Device Operation}
> +
> +\field{name} of the device configuration MUST be non-empty.
> +
> +The unused bits of the message header MUST be 0.
> +
> +The \field{prop_item_id} of VIRTIO_PARAMETER_SERVER_OP_GET_PROP_CONFIG,
> +VIRTIO_PARAMETER_SERVER_OP_SUBSCRIBE_PROP and VIRTIO_PARAMETER_SERVER_OP_UNSUBSCRIBE_PROP requests
> +MUST be ignored.
> +
> +The device MUST send exact 1 response for every received request.
> +
> +The payload size of responses and event messages MUST be padded to 4 bytes.
> +
> +The param size of property configurations MUST be padded to 4 bytes.
> --
> 2.32.0.272.g935e593368-goog
>

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

[virtio-dev] Re: [PATCH v4] Add virtio parameter server device specification

[Hao Chen]

Hi folks,

I had some issues when trying to implement the sample driver for this
device proposal. When the device wants to send some values to the
driver,
the size of the values may vary a lot, and the size may not be
determined when the driver allocates buffers for them. The device
knows more about
that. I think it will be great if the device can allocate buffers, but
I didn't see that in the spec. I wonder what will be the current
solution here.

Thanks!
Hao

On Fri, Jun 11, 2021 at 11:44 AM Hao Chen <chenhaosjtuacm@google.com> wrote:
>
> On Thu, Jun 10, 2021 at 4:19 PM Hao Chen <chenhaosjtuacm@google.com> wrote:
> >
> > This patch introduces a new type of device: parameter server. The device
> > acts as a key-value store and the driver can read from, write to or
> > subscribe to the properties in the server.
> >
> > Signed-off-by: Hao Chen <chenhaosjtuacm@google.com>
> > ---
> >  conformance.tex |  26 +++++-
> >  content.tex     |   1 +
> >  virtio-ps.tex   | 216 ++++++++++++++++++++++++++++++++++++++++++++++++
> >  3 files changed, 239 insertions(+), 4 deletions(-)
> >  create mode 100644 virtio-ps.tex
> >
> > diff --git a/conformance.tex b/conformance.tex
> > index a164cbb..0d6b1a5 100644
> > --- a/conformance.tex
> > +++ b/conformance.tex
> > @@ -29,8 +29,9 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
> >  \ref{sec:Conformance / Driver Conformance / IOMMU Driver Conformance},
> >  \ref{sec:Conformance / Driver Conformance / Sound Driver Conformance},
> >  \ref{sec:Conformance / Driver Conformance / Memory Driver Conformance},
> > -\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance} or
> > -\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance}.
> > +\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance},
> > +\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance} or
> > +\ref{sec:Conformance / Driver Conformance / Parameter Server Driver Conformance}.
> >
> >      \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}.
> >    \end{itemize}
> > @@ -52,8 +53,9 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
> >  \ref{sec:Conformance / Device Conformance / IOMMU Device Conformance},
> >  \ref{sec:Conformance / Device Conformance / Sound Device Conformance},
> >  \ref{sec:Conformance / Device Conformance / Memory Device Conformance},
> > -\ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance} or
> > -\ref{sec:Conformance / Device Conformance / SCMI Device Conformance}.
> > +\ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance},
> > +\ref{sec:Conformance / Device Conformance / SCMI Device Conformance}or
> > +\ref{sec:Conformance / Device Conformance / Parameter Server Device Conformance}.
> >
> >      \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}.
> >    \end{itemize}
> > @@ -288,6 +290,14 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
> >  \item \ref{drivernormative:Device Types / SCMI Device / Device Operation / Setting Up eventq Buffers}
> >  \end{itemize}
> >
> > +\conformance{\subsection}{Parameter Server Driver Conformance}\label{sec:Conformance / Driver Conformance / Parameter Server Driver Conformance}
> > +
> > +A parameter server driver MUST conform to the following normative statements:
> > +
> > +\begin{itemize}
> > +\item \ref{drivernormative:Device Types / Parameter Server / Device Operation}
> > +\end{itemize}
> > +
> >  \conformance{\section}{Device Conformance}\label{sec:Conformance / Device Conformance}
> >
> >  A device MUST conform to the following normative statements:
> > @@ -527,6 +537,14 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
> >  \item \ref{devicenormative:Device Types / SCMI Device / Device Operation / Shared Memory Operation}
> >  \end{itemize}
> >
> > +\conformance{\subsection}{Parameter Server Device Conformance}\label{sec:Conformance / Device Conformance / Parameter Server Device Conformance}
> > +
> > +A parameter server device MUST conform to the following normative statements:
> > +
> > +\begin{itemize}
> > +\item \ref{devicenormative:Device Types / Parameter Server / 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 9232d5c..b980a93 100644
> > --- a/content.tex
> > +++ b/content.tex
> > @@ -6568,6 +6568,7 @@ \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
> >  \input{virtio-mem.tex}
> >  \input{virtio-i2c.tex}
> >  \input{virtio-scmi.tex}
> > +\input{virtio-ps.tex}
> >
> >  \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
> >
> > diff --git a/virtio-ps.tex b/virtio-ps.tex
> > new file mode 100644
> > index 0000000..2a226c4
> > --- /dev/null
> > +++ b/virtio-ps.tex
> > @@ -0,0 +1,216 @@
> > +\section{Parameter Server}\label{sec:Device Types / Parameter Server}
> > +
> > +The parameter server device manages a set of values with unique property IDs. These values may
> > +either be static (i.e. have a constant value) or be dynamic (i.e. value may change over time).
> > +The driver can get and set values, get value configurations, subscribe and unsubscribe dynamic
> > +properties from the device. The driver will get updates when subscribed value changes. The device
> > +processes the requests from the driver, enforces the value access rules, and may potentially alter
> > +the behavior of external systems as a result of driver operations.
> > +
> > +\subsection{Device ID}\label{sec:Device Types / Parameter Server / Device ID}
> > +
> > +38
> > +
> > +\subsection{Virtqueues}\label{sec:Device Types / Parameter Server / Virtqueues}
> > +
> > +\begin{description}
> > +\item[0] cmdq
> > +\item[1] eventq
> > +\end{description}
> > +
> > +\subsection{Feature Bits}\label{sec:Device Types / Parameter Server / Feature Bits}
> > +
> > +None currently defined.
> > +
> > +\subsection{Device Configuration Layout}\label{sec:Device Types / Parameter Server / Device Configuration Layout}
> > +
> > +\begin{lstlisting}
> > +struct virtio_parameter_server_config {
> > +    char name[128];
> > +};
> > +\end{lstlisting}
> > +
> > +A device configuration space only contains the name of the device, which can be used by the
> > +userspace for identification. \field{name} is a zero-terminated char string. The maximum length
> > +of \field{name} is 127.
> > +
> > +\subsection{Device Initialization}
> > +
> > +\begin{enumerate}
> > +\item The virtqueues are initialized.
> > +\end{enumerate}
> > +
> > +\subsection{Device Operation}\label{sec:Device Types / Parameter Server / Device Operation}
> > +
> > +The driver puts requests to read, write, subscribe to, or unsubscribe from, parameters onto the
> > +cmdq virtqueue. The device also puts its responses to the driver's requests onto the cmdq
> > +virtqueue. The device puts any updates to values that the driver has subscribed to onto the
> > +eventq virtqueue. The
> > +\field{prop_id}, \field{prop_item_id} pair is the primary key for the values stored in the
> > +parameter server, while the values with the same \field{prop_id} share the same configuration.
> > +For example, \field{prop_id} 12 with \field{prop_item_id} 0, 1 and 2 represent 3 different values
> > +sharing the same \field{virtio_parameter_server_config}. \field{prop_id} is also used for
> > +subscriptions, meaning that if you subscribe on a prop_id, you will receive every updates on that
> > +prop_id regardless of what prop_item_id it contains. \field{prop_item_id} is not used in
> > +subscription.
> > +
> > +The layout of requests and responses are defined below:
> > +
> > +\begin{lstlisting}
> > +struct virtio_parameter_server_request {
> > +    le64 timestamp;
> > +    le32 prop_id;
> > +    le32 prop_item_id;
> > +    u8 op;
> > +    u8 payload[<actual payload size>];
> > +};
> > +
> > +struct virtio_parameter_server_response {
> > +    le64 timestamp;
> > +    le32 prop_id;
> > +    le32 prop_item_id;
> > +    u16 op;
> > +    u16 ret_value;
> > +    u8 payload[<actual payload size>];
> > +};
> > +
> > +/* Reserved prop_id and prop_item_id */
> > +#define VIRTIO_PARAMETER_SERVER_OP_ALL_PROP INT_MAX
> > +
> > +/* Supported operations */
> > +#define VIRTIO_PARAMETER_SERVER_OP_INVALID 0
> > +#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_CONFIG 1
> > +#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_VALUE 2
> > +#define VIRTIO_PARAMETER_SERVER_OP_SET_PROP_VALUE 3
> > +#define VIRTIO_PARAMETER_SERVER_OP_SUBSCRIBE_PROP 4
> > +#define VIRTIO_PARAMETER_SERVER_OP_UNSUBSCRIBE_PROP 5
> > +\end{lstlisting}
> > +
> > +The layout of messages in eventq is defined below:
> > +
> > +\begin{lstlisting}
> > +struct virtio_parameter_server_event_msg {
> > +    le64 timestamp;
> > +    le32 prop_id;
> > +    le32 prop_item_id;
> > +    u8 payload[<actual payload size>];
> > +};
> > +\end{lstlisting}
> > +
> > +There will be exactly one response for each request in the cmdq, even if \field{op} is invalid. For some operations,
> > +the \field{payload} of requests and/or responses may be empty. The content of the payload depend on the operation.
> > +
> > +\subsubsection{Property Configuration Layout}\label{sec:Device Types / Parameter Server / Device Operation / Property Configuration Layout}
> > +
> > +\begin{lstlisting}
> > +// The max size of virtio_parameter_server_config, including
> > +// fixed-length members and params
> > +#define VIRTIO_PARAMETER_SERVER_CONFIG_MAX_SIZE_BYTE 4096
> > +
> > +struct virtio_parameter_server_prop_config {
> > +    le32 prop_id;
> > +    le32 mode;
> > +    le32 min_sample_freq;
> > +    le32 max_sample_freq;
> > +    le32 encoding[5];
> > +    le32 param_size;
> > +    char desc[256];
> > +    u8 params[<actual param size>];
> > +};
> > +\end{lstlisting}
> > +
> > +while \field{mode} is the bitwise-or-combination of the following:
> > +
> > +\begin{lstlisting}
> > +enum virtio_parameter_server_prop_mode {
> > +    /* access */
> > +    VIRTIO_PARAMETER_SERVER_M_READ = 0x1,
> > +    VIRTIO_PARAMETER_SERVER_M_WRITE = 0x2,
> > +    VIRTIO_PARAMETER_SERVER_M_READ_WRITE = 0x3,
> > +
> > +    /* change */
> > +    VIRTIO_PARAMETER_SERVER_M_STATIC = 0x4,
> > +    VIRTIO_PARAMETER_SERVER_M_MUTABLE = 0x8,
> > +    VIRTIO_PARAMETER_SERVER_M_CONTINUOUS = 0xc,
> > +};
> > +\end{lstlisting}
> > +
> > +Both VIRTIO_PARAMETER_SERVER_M_MUTABLE and VIRTIO_PARAMETER_SERVER_M_CONTINUOUS are dynamic
> > +properties. A VIRTIO_PARAMETER_SERVER_M_MUTABLE value will change due to the set value operation
> > +from the driver, or actions of the external system; a VIRTIO_PARAMETER_SERVER_M_CONTINUOUS value
> > +is expected to be generated by means of a sensor updating at a steady frequency.
> > +
> > +The reason we want to handle "MUTABLE" and "CONTNUOUS" differently is, the MUTABLE values are not
> > +constantly changing, so the device may be able to send every updates of it to the driver; while
> > +CONTINUOUS values are changing frequently (e.g., sensor outputs) and the device should decide how
> > +to sample it and provide a sample rate range (\field{min_sample_freq} and \field{max_sample_freq})
> > +
> > +The properties with the same \field{prop_id} share the configuration. \field{min_sample_freq} and
> > +\field{max_sample_freq} are the sampling rate range for the
> > +\field{VIRTIO_PARAMETER_SERVER_M_CONTINUOUS} values. \field{desc} is the optional zero-terminated
> > +char string description. \field{params} are for the customized configuration parameters.
> > +
> > +The integer array \field{encoding} specifies the number of different primitive value in the
> > +property value.
> > +
> > +\begin{lstlisting}
> > +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT64 0
> > +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_FLOAT64 1
> > +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT32 2
> > +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_BYTE 3
> > +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_HAS_STRING 4
> > +\end{lstlisting}
> > +
> > +If the driver asks for ALL property configurations by setting the \field{prop_id} of the request to
> > +VIRTIO_PARAMETER_SERVER_OP_ALL_PROP, then the \field{payload} of virtio_parameter_server_response
> > +will be multiple property configurations, serialized 1-by-1.
> > +
> > +\subsubsection{Property Value Layout}\label{sec:Device Types / Parameter Server / Device Operation / Property Value Layout}
> > +
> > +The property value payload begins with 5 arrays. The order is the same as the \field{encoding} array defined above.
> > +For each array, it begins with a 32-bit integer for length (number of elements). Empty array will be a 32-bit 0, while
> > +-1 means the array does not exist. The elements follows the length, and the size of the encoded array will be padded
> > +to 4 bytes. String is encoded as a zero-terminated char array,
> > +\field{encoding[VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_HAS_STRING]} indicates the existence of the string.
> > +
> > +After the arrays, there may be customized data, which is encoded as a byte array.
> > +
> > +For example, if \field{encoding} of virtio_parameter_server_prop_config of property A is \field{[2, 0, 0, 0, 1]},
> > +then property A contains two 64-bit integers and a string. The encoded value consists of the following (from top to bottom):
> > +
> > +\begin{lstlisting}
> > +2 (32-bit, meaning 2 64-bit integers)
> > +64-bit integer
> > +64-bit integer
> > +-1 (32-bit, meaning no 64-bit float number array)
> > +-1 (32-bit, meaning no 32-bit integer array)
> > +-1 (32-bit, meaning no byte array)
> > +14 (32-bit integer, length of the char string, including trailing zero, excluding padding zeros)
> > +"sample string\0"
> > +padding zeros to 4 bytes. In this case there will be 2 zero bytes.
> > +(optional) byte array length + data if there are customized data
> > +\end{lstlisting}
> > +
> > +\drivernormative{\subsubsection}{Device Operation}{Device Types / Parameter Server / Device Operation}
> > +
> > +The driver MUST NOT send undefined ops.
> > +
> > +The driver MUST NOT put descriptors into the eventq.
> > +
> > +The payload size of requests MUST be padded to 4 bytes.
> > +
> > +\devicenormative{\subsubsection}{Device Operation}{Device Types / Parameter Server / Device Operation}
> > +
> > +\field{name} of the device configuration MUST be non-empty.
> > +
> > +The unused bits of the message header MUST be 0.
> > +
> > +The \field{prop_item_id} of VIRTIO_PARAMETER_SERVER_OP_GET_PROP_CONFIG,
> > +VIRTIO_PARAMETER_SERVER_OP_SUBSCRIBE_PROP and VIRTIO_PARAMETER_SERVER_OP_UNSUBSCRIBE_PROP requests
> > +MUST be ignored.
> > +
> > +The device MUST send exact 1 response for every received request.
> > +
> > +The payload size of responses and event messages MUST be padded to 4 bytes.
> > +
> > +The param size of property configurations MUST be padded to 4 bytes.
> > --
> > 2.32.0.272.g935e593368-goog
> >

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

[virtio-dev] Re: [PATCH v4] Add virtio parameter server device specification

[Hao Chen]

[-- Attachment #1: Type: text/plain, Size: 16623 bytes --]

Hi folks,

Could anyone please help us figure out how to allocate the buffer when the
size of the to-be-sent values are unknown?

Thanks!
Hao

On Mon, Oct 4, 2021 at 11:25 AM Hao Chen <chenhaosjtuacm@google.com> wrote:

> ---------- Forwarded message ---------
> From: Hao Chen <chenhaosjtuacm@google.com>
> Date: Wed, Sep 8, 2021 at 1:42 PM
> Subject: Re: [PATCH v4] Add virtio parameter server device specification
> To: <virtio-dev@lists.oasis-open.org>
>
>
> Hi folks,
>
> I had some issues when trying to implement the sample driver for this
> device proposal. When the device wants to send some values to the
> driver,
> the size of the values may vary a lot, and the size may not be
> determined when the driver allocates buffers for them. The device
> knows more about
> that. I think it will be great if the device can allocate buffers, but
> I didn't see that in the spec. I wonder what will be the current
> solution here.
>
> Thanks!
> Hao
>
> On Fri, Jun 11, 2021 at 11:44 AM Hao Chen <chenhaosjtuacm@google.com>
> wrote:
> >
> > On Thu, Jun 10, 2021 at 4:19 PM Hao Chen <chenhaosjtuacm@google.com>
> wrote:
> > >
> > > This patch introduces a new type of device: parameter server. The
> device
> > > acts as a key-value store and the driver can read from, write to or
> > > subscribe to the properties in the server.
> > >
> > > Signed-off-by: Hao Chen <chenhaosjtuacm@google.com>
> > > ---
> > >  conformance.tex |  26 +++++-
> > >  content.tex     |   1 +
> > >  virtio-ps.tex   | 216 ++++++++++++++++++++++++++++++++++++++++++++++++
> > >  3 files changed, 239 insertions(+), 4 deletions(-)
> > >  create mode 100644 virtio-ps.tex
> > >
> > > diff --git a/conformance.tex b/conformance.tex
> > > index a164cbb..0d6b1a5 100644
> > > --- a/conformance.tex
> > > +++ b/conformance.tex
> > > @@ -29,8 +29,9 @@ \section{Conformance Targets}\label{sec:Conformance
> / Conformance Targets}
> > >  \ref{sec:Conformance / Driver Conformance / IOMMU Driver Conformance},
> > >  \ref{sec:Conformance / Driver Conformance / Sound Driver Conformance},
> > >  \ref{sec:Conformance / Driver Conformance / Memory Driver
> Conformance},
> > > -\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver
> Conformance} or
> > > -\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance}.
> > > +\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver
> Conformance},
> > > +\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance}
> or
> > > +\ref{sec:Conformance / Driver Conformance / Parameter Server Driver
> Conformance}.
> > >
> > >      \item Clause \ref{sec:Conformance / Legacy Interface:
> Transitional Device and Transitional Driver Conformance}.
> > >    \end{itemize}
> > > @@ -52,8 +53,9 @@ \section{Conformance Targets}\label{sec:Conformance
> / Conformance Targets}
> > >  \ref{sec:Conformance / Device Conformance / IOMMU Device Conformance},
> > >  \ref{sec:Conformance / Device Conformance / Sound Device Conformance},
> > >  \ref{sec:Conformance / Device Conformance / Memory Device
> Conformance},
> > > -\ref{sec:Conformance / Device Conformance / I2C Adapter Device
> Conformance} or
> > > -\ref{sec:Conformance / Device Conformance / SCMI Device Conformance}.
> > > +\ref{sec:Conformance / Device Conformance / I2C Adapter Device
> Conformance},
> > > +\ref{sec:Conformance / Device Conformance / SCMI Device Conformance}or
> > > +\ref{sec:Conformance / Device Conformance / Parameter Server Device
> Conformance}.
> > >
> > >      \item Clause \ref{sec:Conformance / Legacy Interface:
> Transitional Device and Transitional Driver Conformance}.
> > >    \end{itemize}
> > > @@ -288,6 +290,14 @@ \section{Conformance
> Targets}\label{sec:Conformance / Conformance Targets}
> > >  \item \ref{drivernormative:Device Types / SCMI Device / Device
> Operation / Setting Up eventq Buffers}
> > >  \end{itemize}
> > >
> > > +\conformance{\subsection}{Parameter Server Driver
> Conformance}\label{sec:Conformance / Driver Conformance / Parameter Server
> Driver Conformance}
> > > +
> > > +A parameter server driver MUST conform to the following normative
> statements:
> > > +
> > > +\begin{itemize}
> > > +\item \ref{drivernormative:Device Types / Parameter Server / Device
> Operation}
> > > +\end{itemize}
> > > +
> > >  \conformance{\section}{Device Conformance}\label{sec:Conformance /
> Device Conformance}
> > >
> > >  A device MUST conform to the following normative statements:
> > > @@ -527,6 +537,14 @@ \section{Conformance
> Targets}\label{sec:Conformance / Conformance Targets}
> > >  \item \ref{devicenormative:Device Types / SCMI Device / Device
> Operation / Shared Memory Operation}
> > >  \end{itemize}
> > >
> > > +\conformance{\subsection}{Parameter Server Device
> Conformance}\label{sec:Conformance / Device Conformance / Parameter Server
> Device Conformance}
> > > +
> > > +A parameter server device MUST conform to the following normative
> statements:
> > > +
> > > +\begin{itemize}
> > > +\item \ref{devicenormative:Device Types / Parameter Server / 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 9232d5c..b980a93 100644
> > > --- a/content.tex
> > > +++ b/content.tex
> > > @@ -6568,6 +6568,7 @@ \subsubsection{Legacy Interface: Framing
> Requirements}\label{sec:Device
> > >  \input{virtio-mem.tex}
> > >  \input{virtio-i2c.tex}
> > >  \input{virtio-scmi.tex}
> > > +\input{virtio-ps.tex}
> > >
> > >  \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
> > >
> > > diff --git a/virtio-ps.tex b/virtio-ps.tex
> > > new file mode 100644
> > > index 0000000..2a226c4
> > > --- /dev/null
> > > +++ b/virtio-ps.tex
> > > @@ -0,0 +1,216 @@
> > > +\section{Parameter Server}\label{sec:Device Types / Parameter Server}
> > > +
> > > +The parameter server device manages a set of values with unique
> property IDs. These values may
> > > +either be static (i.e. have a constant value) or be dynamic (i.e.
> value may change over time).
> > > +The driver can get and set values, get value configurations,
> subscribe and unsubscribe dynamic
> > > +properties from the device. The driver will get updates when
> subscribed value changes. The device
> > > +processes the requests from the driver, enforces the value access
> rules, and may potentially alter
> > > +the behavior of external systems as a result of driver operations.
> > > +
> > > +\subsection{Device ID}\label{sec:Device Types / Parameter Server /
> Device ID}
> > > +
> > > +38
> > > +
> > > +\subsection{Virtqueues}\label{sec:Device Types / Parameter Server /
> Virtqueues}
> > > +
> > > +\begin{description}
> > > +\item[0] cmdq
> > > +\item[1] eventq
> > > +\end{description}
> > > +
> > > +\subsection{Feature Bits}\label{sec:Device Types / Parameter Server /
> Feature Bits}
> > > +
> > > +None currently defined.
> > > +
> > > +\subsection{Device Configuration Layout}\label{sec:Device Types /
> Parameter Server / Device Configuration Layout}
> > > +
> > > +\begin{lstlisting}
> > > +struct virtio_parameter_server_config {
> > > +    char name[128];
> > > +};
> > > +\end{lstlisting}
> > > +
> > > +A device configuration space only contains the name of the device,
> which can be used by the
> > > +userspace for identification. \field{name} is a zero-terminated char
> string. The maximum length
> > > +of \field{name} is 127.
> > > +
> > > +\subsection{Device Initialization}
> > > +
> > > +\begin{enumerate}
> > > +\item The virtqueues are initialized.
> > > +\end{enumerate}
> > > +
> > > +\subsection{Device Operation}\label{sec:Device Types / Parameter
> Server / Device Operation}
> > > +
> > > +The driver puts requests to read, write, subscribe to, or unsubscribe
> from, parameters onto the
> > > +cmdq virtqueue. The device also puts its responses to the driver's
> requests onto the cmdq
> > > +virtqueue. The device puts any updates to values that the driver has
> subscribed to onto the
> > > +eventq virtqueue. The
> > > +\field{prop_id}, \field{prop_item_id} pair is the primary key for the
> values stored in the
> > > +parameter server, while the values with the same \field{prop_id}
> share the same configuration.
> > > +For example, \field{prop_id} 12 with \field{prop_item_id} 0, 1 and 2
> represent 3 different values
> > > +sharing the same \field{virtio_parameter_server_config}.
> \field{prop_id} is also used for
> > > +subscriptions, meaning that if you subscribe on a prop_id, you will
> receive every updates on that
> > > +prop_id regardless of what prop_item_id it contains.
> \field{prop_item_id} is not used in
> > > +subscription.
> > > +
> > > +The layout of requests and responses are defined below:
> > > +
> > > +\begin{lstlisting}
> > > +struct virtio_parameter_server_request {
> > > +    le64 timestamp;
> > > +    le32 prop_id;
> > > +    le32 prop_item_id;
> > > +    u8 op;
> > > +    u8 payload[<actual payload size>];
> > > +};
> > > +
> > > +struct virtio_parameter_server_response {
> > > +    le64 timestamp;
> > > +    le32 prop_id;
> > > +    le32 prop_item_id;
> > > +    u16 op;
> > > +    u16 ret_value;
> > > +    u8 payload[<actual payload size>];
> > > +};
> > > +
> > > +/* Reserved prop_id and prop_item_id */
> > > +#define VIRTIO_PARAMETER_SERVER_OP_ALL_PROP INT_MAX
> > > +
> > > +/* Supported operations */
> > > +#define VIRTIO_PARAMETER_SERVER_OP_INVALID 0
> > > +#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_CONFIG 1
> > > +#define VIRTIO_PARAMETER_SERVER_OP_GET_PROP_VALUE 2
> > > +#define VIRTIO_PARAMETER_SERVER_OP_SET_PROP_VALUE 3
> > > +#define VIRTIO_PARAMETER_SERVER_OP_SUBSCRIBE_PROP 4
> > > +#define VIRTIO_PARAMETER_SERVER_OP_UNSUBSCRIBE_PROP 5
> > > +\end{lstlisting}
> > > +
> > > +The layout of messages in eventq is defined below:
> > > +
> > > +\begin{lstlisting}
> > > +struct virtio_parameter_server_event_msg {
> > > +    le64 timestamp;
> > > +    le32 prop_id;
> > > +    le32 prop_item_id;
> > > +    u8 payload[<actual payload size>];
> > > +};
> > > +\end{lstlisting}
> > > +
> > > +There will be exactly one response for each request in the cmdq, even
> if \field{op} is invalid. For some operations,
> > > +the \field{payload} of requests and/or responses may be empty. The
> content of the payload depend on the operation.
> > > +
> > > +\subsubsection{Property Configuration Layout}\label{sec:Device Types
> / Parameter Server / Device Operation / Property Configuration Layout}
> > > +
> > > +\begin{lstlisting}
> > > +// The max size of virtio_parameter_server_config, including
> > > +// fixed-length members and params
> > > +#define VIRTIO_PARAMETER_SERVER_CONFIG_MAX_SIZE_BYTE 4096
> > > +
> > > +struct virtio_parameter_server_prop_config {
> > > +    le32 prop_id;
> > > +    le32 mode;
> > > +    le32 min_sample_freq;
> > > +    le32 max_sample_freq;
> > > +    le32 encoding[5];
> > > +    le32 param_size;
> > > +    char desc[256];
> > > +    u8 params[<actual param size>];
> > > +};
> > > +\end{lstlisting}
> > > +
> > > +while \field{mode} is the bitwise-or-combination of the following:
> > > +
> > > +\begin{lstlisting}
> > > +enum virtio_parameter_server_prop_mode {
> > > +    /* access */
> > > +    VIRTIO_PARAMETER_SERVER_M_READ = 0x1,
> > > +    VIRTIO_PARAMETER_SERVER_M_WRITE = 0x2,
> > > +    VIRTIO_PARAMETER_SERVER_M_READ_WRITE = 0x3,
> > > +
> > > +    /* change */
> > > +    VIRTIO_PARAMETER_SERVER_M_STATIC = 0x4,
> > > +    VIRTIO_PARAMETER_SERVER_M_MUTABLE = 0x8,
> > > +    VIRTIO_PARAMETER_SERVER_M_CONTINUOUS = 0xc,
> > > +};
> > > +\end{lstlisting}
> > > +
> > > +Both VIRTIO_PARAMETER_SERVER_M_MUTABLE and
> VIRTIO_PARAMETER_SERVER_M_CONTINUOUS are dynamic
> > > +properties. A VIRTIO_PARAMETER_SERVER_M_MUTABLE value will change due
> to the set value operation
> > > +from the driver, or actions of the external system; a
> VIRTIO_PARAMETER_SERVER_M_CONTINUOUS value
> > > +is expected to be generated by means of a sensor updating at a steady
> frequency.
> > > +
> > > +The reason we want to handle "MUTABLE" and "CONTNUOUS" differently
> is, the MUTABLE values are not
> > > +constantly changing, so the device may be able to send every updates
> of it to the driver; while
> > > +CONTINUOUS values are changing frequently (e.g., sensor outputs) and
> the device should decide how
> > > +to sample it and provide a sample rate range (\field{min_sample_freq}
> and \field{max_sample_freq})
> > > +
> > > +The properties with the same \field{prop_id} share the configuration.
> \field{min_sample_freq} and
> > > +\field{max_sample_freq} are the sampling rate range for the
> > > +\field{VIRTIO_PARAMETER_SERVER_M_CONTINUOUS} values. \field{desc} is
> the optional zero-terminated
> > > +char string description. \field{params} are for the customized
> configuration parameters.
> > > +
> > > +The integer array \field{encoding} specifies the number of different
> primitive value in the
> > > +property value.
> > > +
> > > +\begin{lstlisting}
> > > +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT64 0
> > > +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_FLOAT64 1
> > > +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_INT32 2
> > > +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_NUM_BYTE 3
> > > +#define VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_HAS_STRING 4
> > > +\end{lstlisting}
> > > +
> > > +If the driver asks for ALL property configurations by setting the
> \field{prop_id} of the request to
> > > +VIRTIO_PARAMETER_SERVER_OP_ALL_PROP, then the \field{payload} of
> virtio_parameter_server_response
> > > +will be multiple property configurations, serialized 1-by-1.
> > > +
> > > +\subsubsection{Property Value Layout}\label{sec:Device Types /
> Parameter Server / Device Operation / Property Value Layout}
> > > +
> > > +The property value payload begins with 5 arrays. The order is the
> same as the \field{encoding} array defined above.
> > > +For each array, it begins with a 32-bit integer for length (number of
> elements). Empty array will be a 32-bit 0, while
> > > +-1 means the array does not exist. The elements follows the length,
> and the size of the encoded array will be padded
> > > +to 4 bytes. String is encoded as a zero-terminated char array,
> > > +\field{encoding[VIRTIO_PARAMETER_SERVER_ENCODING_INDEX_HAS_STRING]}
> indicates the existence of the string.
> > > +
> > > +After the arrays, there may be customized data, which is encoded as a
> byte array.
> > > +
> > > +For example, if \field{encoding} of
> virtio_parameter_server_prop_config of property A is \field{[2, 0, 0, 0,
> 1]},
> > > +then property A contains two 64-bit integers and a string. The
> encoded value consists of the following (from top to bottom):
> > > +
> > > +\begin{lstlisting}
> > > +2 (32-bit, meaning 2 64-bit integers)
> > > +64-bit integer
> > > +64-bit integer
> > > +-1 (32-bit, meaning no 64-bit float number array)
> > > +-1 (32-bit, meaning no 32-bit integer array)
> > > +-1 (32-bit, meaning no byte array)
> > > +14 (32-bit integer, length of the char string, including trailing
> zero, excluding padding zeros)
> > > +"sample string\0"
> > > +padding zeros to 4 bytes. In this case there will be 2 zero bytes.
> > > +(optional) byte array length + data if there are customized data
> > > +\end{lstlisting}
> > > +
> > > +\drivernormative{\subsubsection}{Device Operation}{Device Types /
> Parameter Server / Device Operation}
> > > +
> > > +The driver MUST NOT send undefined ops.
> > > +
> > > +The driver MUST NOT put descriptors into the eventq.
> > > +
> > > +The payload size of requests MUST be padded to 4 bytes.
> > > +
> > > +\devicenormative{\subsubsection}{Device Operation}{Device Types /
> Parameter Server / Device Operation}
> > > +
> > > +\field{name} of the device configuration MUST be non-empty.
> > > +
> > > +The unused bits of the message header MUST be 0.
> > > +
> > > +The \field{prop_item_id} of
> VIRTIO_PARAMETER_SERVER_OP_GET_PROP_CONFIG,
> > > +VIRTIO_PARAMETER_SERVER_OP_SUBSCRIBE_PROP and
> VIRTIO_PARAMETER_SERVER_OP_UNSUBSCRIBE_PROP requests
> > > +MUST be ignored.
> > > +
> > > +The device MUST send exact 1 response for every received request.
> > > +
> > > +The payload size of responses and event messages MUST be padded to 4
> bytes.
> > > +
> > > +The param size of property configurations MUST be padded to 4 bytes.
> > > --
> > > 2.32.0.272.g935e593368-goog
> > >
>

[-- Attachment #2: Type: text/html, Size: 20182 bytes --]