[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [PATCH v4] Add virtio parameter server device specification
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 >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]