Skip to content

Commit

Permalink
virtio-console: Maintain console device spec in separate directory
Browse files Browse the repository at this point in the history 
Move virtio console device specification to its own file similar to
recent virtio devices.
While at it, place device specification, its driver and device
conformance into its own directory to have self contained device
specification.

Fixes: #153

Acked-by: Michael S. Tsirkin <mst@redhat.com>
Signed-off-by: Parav Pandit <parav@nvidia.com>
Signed-off-by: Cornelia Huck <cohuck@redhat.com>
  • Loading branch information
@paravmellanox @cohuck
paravmellanox authored and cohuck committed Jan 30, 2023
1 parent 335342f commit d3d0618
Show file tree
Hide file tree
Showing 5 changed files with 250 additions and 250 deletions.
20 changes: 2 additions & 18 deletions conformance.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -136,15 +136,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}

\input{device-types/net/driver-conformance.tex}
\input{device-types/blk/driver-conformance.tex}

\conformance{\subsection}{Console Driver Conformance}\label{sec:Conformance / Driver Conformance / Console Driver Conformance}

A console driver MUST conform to the following normative statements:

\begin{itemize}
\item \ref{drivernormative:Device Types / Console Device / Device Operation}
\item \ref{drivernormative:Device Types / Console Device / Device Operation / Multiport Device Operation}
\end{itemize}
\input{device-types/console/driver-conformance.tex}

\conformance{\subsection}{Entropy Driver Conformance}\label{sec:Conformance / Driver Conformance / Entropy Driver Conformance}

Expand Down Expand Up @@ -379,15 +371,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}

\input{device-types/net/device-conformance.tex}
\input{device-types/blk/device-conformance.tex}

\conformance{\subsection}{Console Device Conformance}\label{sec:Conformance / Device Conformance / Console Device Conformance}

A console device MUST conform to the following normative statements:

\begin{itemize}
\item \ref{devicenormative:Device Types / Console Device / Device Initialization}
\item \ref{devicenormative:Device Types / Console Device / Device Operation / Multiport Device Operation}
\end{itemize}
\input{device-types/console/device-conformance.tex}

\conformance{\subsection}{Entropy Device Conformance}\label{sec:Conformance / Device Conformance / Entropy Device Conformance}

Expand Down
233 changes: 1 addition & 232 deletions content.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3005,238 +3005,7 @@ \chapter{Device Types}\label{sec:Device Types}

\input{device-types/net/description.tex}
\input{device-types/blk/description.tex}

\section{Console Device}\label{sec:Device Types / Console Device}

The virtio console device is a simple device for data input and
output. A device MAY have one or more ports. Each port has a pair
of input and output virtqueues. Moreover, a device has a pair of
control IO virtqueues. The control virtqueues are used to
communicate information between the device and the driver about
ports being opened and closed on either side of the connection,
indication from the device about whether a particular port is a
console port, adding new ports, port hot-plug/unplug, etc., and
indication from the driver about whether a port or a device was
successfully added, port open/close, etc. For data IO, one or
more empty buffers are placed in the receive queue for incoming
data and outgoing characters are placed in the transmit queue.

\subsection{Device ID}\label{sec:Device Types / Console Device / Device ID}

3

\subsection{Virtqueues}\label{sec:Device Types / Console Device / Virtqueues}

\begin{description}
\item[0] receiveq(port0)
\item[1] transmitq(port0)
\item[2] control receiveq
\item[3] control transmitq
\item[4] receiveq(port1)
\item[5] transmitq(port1)
\item[\ldots]
\end{description}

The port 0 receive and transmit queues always exist: other queues
only exist if VIRTIO_CONSOLE_F_MULTIPORT is set.

\subsection{Feature bits}\label{sec:Device Types / Console Device / Feature bits}

\begin{description}
\item[VIRTIO_CONSOLE_F_SIZE (0)] Configuration \field{cols} and \field{rows}
are valid.

\item[VIRTIO_CONSOLE_F_MULTIPORT (1)] Device has support for multiple
ports; \field{max_nr_ports} is valid and control virtqueues will be used.

\item[VIRTIO_CONSOLE_F_EMERG_WRITE (2)] Device has support for emergency write.
Configuration field emerg_wr is valid.
\end{description}

\subsection{Device configuration layout}\label{sec:Device Types / Console Device / Device configuration layout}

The size of the console is supplied
in the configuration space if the VIRTIO_CONSOLE_F_SIZE feature
is set. Furthermore, if the VIRTIO_CONSOLE_F_MULTIPORT feature
is set, the maximum number of ports supported by the device can
be fetched.

If VIRTIO_CONSOLE_F_EMERG_WRITE is set then the driver can use emergency write
to output a single character without initializing virtio queues, or even
acknowledging the feature.

\begin{lstlisting}
struct virtio_console_config {
le16 cols;
le16 rows;
le32 max_nr_ports;
le32 emerg_wr;
};
\end{lstlisting}

\subsubsection{Legacy Interface: Device configuration layout}\label{sec:Device Types / Console Device / Device configuration layout / Legacy Interface: Device configuration layout}
When using the legacy interface, transitional devices and drivers
MUST format the fields in struct virtio_console_config
according to the native endian of the guest rather than
(necessarily when not using the legacy interface) little-endian.

\subsection{Device Initialization}\label{sec:Device Types / Console Device / Device Initialization}

\begin{enumerate}
\item If the VIRTIO_CONSOLE_F_EMERG_WRITE feature is offered,
\field{emerg_wr} field of the configuration can be written at any time.
Thus it works for very early boot debugging output as well as
catastophic OS failures (eg. virtio ring corruption).

\item If the VIRTIO_CONSOLE_F_SIZE feature is negotiated, the driver
can read the console dimensions from \field{cols} and \field{rows}.

\item If the VIRTIO_CONSOLE_F_MULTIPORT feature is negotiated, the
driver can spawn multiple ports, not all of which are necessarily
attached to a console. Some could be generic ports. In this
case, the control virtqueues are enabled and according to
\field{max_nr_ports}, the appropriate number
of virtqueues are created. A control message indicating the
driver is ready is sent to the device. The device can then send
control messages for adding new ports to the device. After
creating and initializing each port, a
VIRTIO_CONSOLE_PORT_READY control message is sent to the device
for that port so the device can let the driver know of any additional
configuration options set for that port.

\item The receiveq for each port is populated with one or more
receive buffers.
\end{enumerate}

\devicenormative{\subsubsection}{Device Initialization}{Device Types / Console Device / Device Initialization}

The device MUST allow a write to \field{emerg_wr}, even on an
unconfigured device.

The device SHOULD transmit the lower byte written to \field{emerg_wr} to
an appropriate log or output method.

\subsection{Device Operation}\label{sec:Device Types / Console Device / Device Operation}

\begin{enumerate}
\item For output, a buffer containing the characters is placed in
the port's transmitq\footnote{Because this is high importance and low bandwidth, the current
Linux implementation polls for the buffer to become used, rather than
waiting for a used buffer notification, simplifying the implementation
significantly. However, for generic serial ports with the
O_NONBLOCK flag set, the polling limitation is relaxed and the
consumed buffers are freed upon the next write or poll call or
when a port is closed or hot-unplugged.
}.

\item When a buffer is used in the receiveq (signalled by a
used buffer notification), the contents is the input to the port associated
with the virtqueue for which the notification was received.

\item If the driver negotiated the VIRTIO_CONSOLE_F_SIZE feature, a
configuration change notification indicates that the updated size can
be read from the configuration fields. This size applies to port 0 only.

\item If the driver negotiated the VIRTIO_CONSOLE_F_MULTIPORT
feature, active ports are announced by the device using the
VIRTIO_CONSOLE_PORT_ADD control message. The same message is
used for port hot-plug as well.
\end{enumerate}

\drivernormative{\subsubsection}{Device Operation}{Device Types / Console Device / Device Operation}

The driver MUST NOT put a device-readable buffer in a receiveq. The driver
MUST NOT put a device-writable buffer in a transmitq.

\subsubsection{Multiport Device Operation}\label{sec:Device Types / Console Device / Device Operation / Multiport Device Operation}

If the driver negotiated the VIRTIO_CONSOLE_F_MULTIPORT, the two
control queues are used to manipulate the different console ports: the
control receiveq for messages from the device to the driver, and the
control sendq for driver-to-device messages. The layout of the
control messages is:

\begin{lstlisting}
struct virtio_console_control {
le32 id; /* Port number */
le16 event; /* The kind of control event */
le16 value; /* Extra information for the event */
};
\end{lstlisting}

The values for \field{event} are:
\begin{description}
\item [VIRTIO_CONSOLE_DEVICE_READY (0)] Sent by the driver at initialization
to indicate that it is ready to receive control messages. A value of
1 indicates success, and 0 indicates failure. The port number \field{id} is unused.
\item [VIRTIO_CONSOLE_DEVICE_ADD (1)] Sent by the device, to create a new
port. \field{value} is unused.
\item [VIRTIO_CONSOLE_DEVICE_REMOVE (2)] Sent by the device, to remove an
existing port. \field{value} is unused.
\item [VIRTIO_CONSOLE_PORT_READY (3)] Sent by the driver in response
to the device's VIRTIO_CONSOLE_PORT_ADD message, to indicate that
the port is ready to be used. A \field{value} of 1 indicates success, and 0
indicates failure.
\item [VIRTIO_CONSOLE_CONSOLE_PORT (4)] Sent by the device to nominate
a port as a console port. There MAY be more than one console port.
\item [VIRTIO_CONSOLE_RESIZE (5)] Sent by the device to indicate
a console size change. \field{value} is unused. The buffer is followed by the number of columns and rows:
\begin{lstlisting}
struct virtio_console_resize {
le16 cols;
le16 rows;
};
\end{lstlisting}
\item [VIRTIO_CONSOLE_PORT_OPEN (6)] This message is sent by both the
device and the driver. \field{value} indicates the state: 0 (port
closed) or 1 (port open). This allows for ports to be used directly
by guest and host processes to communicate in an application-defined
manner.
\item [VIRTIO_CONSOLE_PORT_NAME (7)] Sent by the device to give a tag
to the port. This control command is immediately
followed by the UTF-8 name of the port for identification
within the guest (without a NUL terminator).
\end{description}

\devicenormative{\paragraph}{Multiport Device Operation}{Device Types / Console Device / Device Operation / Multiport Device Operation}

The device MUST NOT specify a port which exists in a
VIRTIO_CONSOLE_DEVICE_ADD message, nor a port which is equal or
greater than \field{max_nr_ports}.

The device MUST NOT specify a port in VIRTIO_CONSOLE_DEVICE_REMOVE
which has not been created with a previous VIRTIO_CONSOLE_DEVICE_ADD.

\drivernormative{\paragraph}{Multiport Device Operation}{Device Types / Console Device / Device Operation / Multiport Device Operation}

The driver MUST send a VIRTIO_CONSOLE_DEVICE_READY message if
VIRTIO_CONSOLE_F_MULTIPORT is negotiated.

Upon receipt of a VIRTIO_CONSOLE_CONSOLE_PORT message, the driver
SHOULD treat the port in a manner suitable for text console access
and MUST respond with a VIRTIO_CONSOLE_PORT_OPEN message, which MUST
have \field{value} set to 1.

\subsubsection{Legacy Interface: Device Operation}\label{sec:Device Types / Console Device / Device Operation / Legacy Interface: Device Operation}
When using the legacy interface, transitional devices and drivers
MUST format the fields in struct virtio_console_control
according to the native endian of the guest rather than
(necessarily when not using the legacy interface) little-endian.

When using the legacy interface, the driver SHOULD ignore the
used length values for the transmit queues
and the control transmitq.
\begin{note}
Historically, some devices put the total descriptor length there,
even though no data was actually written.
\end{note}

\subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
Types / Console Device / Legacy Interface: Framing Requirements}

When using legacy interfaces, transitional drivers which have not
negotiated VIRTIO_F_ANY_LAYOUT MUST use only a single
descriptor for all buffers in the control receiveq and control transmitq.
\input{device-types/console/description.tex}

\section{Entropy Device}\label{sec:Device Types / Entropy Device}

Expand Down
Loading

0 comments on commit d3d0618

Please sign in to comment.