From b612c3e5d4e0cb5060e869a6bb83667d3a1dd27e Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Tue, 14 Jan 2025 19:56:23 +0100 Subject: [PATCH] First attempt for bus content Add bus messages definitions and several TODO to be discussed. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 139 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) diff --git a/transport-msg.tex b/transport-msg.tex index a1f46b2..b18be28 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -479,4 +479,143 @@ \subsection{Message Bus}\label{sec:Virtio Transport Options / Virtio Over Messag A Message Bus implementation must provide interfaces to transmit and receive messages from the other side. +\subsubsection{Discovery}\label{sec:Virtio Transport Options / Virtio Over Messages / Message Bus / Discovery} + +The Message Bus is responsible of listing the available busses and to enumerate +all devices available on each bus. + +This can done in a static way using a device tree or in a more dynamic way using +messages to communicate with the other side of the bus to discover available +devices. + +\subsubsection{Messages}\label{sec:Virtio Transport Options / Virtio Over Messages / Message Bus / Messages} + +While the Bus implementation and how communication of the messages is done +between the devices and the drivers is completely out of the scope of the +specification, this chapter provides a set of standard Bus messages to help +reusing as much as possible a part of the bus implementation. + +The Bus messages are transfered using the *bus-msg* type in VIRTIO_MSG_TYPE and +have the following format: + +\begin{tabularx}{\textwidth}{|l|l|l|X|} +\hline +Name & Offset & Size (bytes) & Content \\ +\hline \hline +VIRTIO_MSG_TYPE & 0 & 1 & Bit[0]: 0=Request, 1=Answer \newline Bit[1]: 1=bus-msg \newline Bit[2-7]: Reserved \\ +\hline +VIRTIO_MSG_ID & 1 & 1 & Message ID \\ +\hline +VIRTIO_MSG_PAYLOAD & 2 & 38 & Payload \\ +\hline +\end{tabularx} + +The following table is listing the different Bus messages and the sender for +each for them. + +\begin{tabular}{|l|l|l|} +\hline +Name & ID & Sender \\ +\hline +\hline +BUS_MSG_ERROR & 0x0 & Any \\ +\hline +BUS_MSG_GET_DEVICES & 0x1 & Driver \\ +\hline +BUS_MSG_DEVICE_ADDED & 0x2 & Device \\ +\hline +BUS_MSG_DEVICE_REMOVED & 0x3 & Device \\ +\hline +BUS_MSG_PING & 0x4 & Any \\ +\hline +BUS_MSG_RESET & 0x5 & Driver \\ +\hline +\end{tabular} + +Bus message ID 6-127 are reserved for future use in the specification and +message ID 128-255 can be used for implementation specific needs. + +The following sections are giving more details of the usage of each message +and the encoding of the payload for the request and answer (when applicable). + +\newcommand{\busdef}[1]{\paragraph{BUS_MSG_#1}\label{sec:Virtio Transport Options / Virtio Over Messages / Message Bus / Messages / BUS_MSG_#1}} + +\busdef{ERROR} + +The Error message is used by one side of the bus to inform the other side that +one message could not be processed correctly. The message contains an error +code defined using the Standard Posix Error Codes (TODO: add a reference). + +TODO: what cases, what content ? + +\begin{tabular}{|l|l|l|l|} +\hline +Type & Offset & Size (bytes) & Content \\ +\hline \hline +Any & 0 & 4 & Posix Error Code \\ + & 4 & 34 & Reserved (MBZ) \\ +\hline +\end{tabular} + +\busdef{GET_DEVICES} + +The Get Devices message is used by the driver side to retrieve the ID of the +devices available on the device side of the bus. +The driver side requests the availibility at an offset and the device side of +the bus returns a bitmap in which each bit indicates if a device is available +or not for this ID. The device side also return a next offset that indicates +to the driver side what offset to request next. + +This message shall be used in the following way: +- driver side request devices at offset 0. +- device side answers with the availibility of devices 0 to 31 and indicates to + the driver what offset to request next. +- driver side request devices at the offset mentioned by the device side. +This repeats until the device side gives a next offset of 0 meaning that no +more devices are available after the currently requested offset. + +This message is sent by the driver side of the bus to the device side and +expects an answer from the device side. + +\begin{tabular}{|l|l|l|l|} +\hline +Type & Offset & Size (bytes) & Content \\ +\hline \hline +Request & 0 & 2 & Offset \\ + & 2 & 34 & Reserved (MBZ) \\ +\hline +Answer & 0 & 2 & Offset \\ + & 2 & 2 & Next offset or 0 if no devices after Offset \\ + & 4 & 2 & Reserved (MBZ) \\ + & 6 & 32 & Bit[n]: Device[offset + n] not availble(0)/available(1) \\ +\hline +\end{tabular} + +\busdef{DEVICE_ADDED} + +This message is sent by the device side of the bus to signal to the driver side +that a new device appeared on the bus. + +TODO: when should the device side start sending those messages? how to detect +that the driver side did scan the bus and a new device appeared since ? +TODO: do we need a kind of init message to solve that ? + +\busdef{DEVICE_REMOVED} + +This message is sent by the device side of the bus to signal to the driver side +that a device was removed from the bus. + +\busdef{PING} + +TODO: confirm how keep alive should work and be configured. + +\busdef{RESET} + +This message is sent by the driver side of the bus to request the device side +to reset the bus and all devices on it. +This message shall be sent as first message by a Bus implementation to make +sure that no device is in an unknown state from a possible previous usage of +it by a driver. + +TODO: shall this message be used for added/removed notif ?