forked from oasis-tcs/virtio-spec
-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathtransport-msg.tex
439 lines (360 loc) · 12.5 KB
/
transport-msg.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
\section{Virtio Over Messages}\label{sec:Virtio Transport Options / Virtio Over Messages}
The goal of the messages transport is to have commands communicated between the
frontend (driver) and backend (device) sides over a message based conduit
allowing to reach destination endpoints such as another VM, a TEE or a remote
compute engine using different communication channels.
The messages transport is designed to work efficiently between VMs on an hypervisor
based configuration or between heterogeneous systems by using messages to
reduce the number of context switches between the device and the driver sides
when each of them is in a different VM. In the same way, this is also reducing
cross system communications required in an heterogeneous system configuration.
\subsection{Messages Format}\label{sec:Virtio Transport Options / Virtio Over Messages / Messages Format}
The messages have the following properties:
\begin{itemize}
\item A message size is 40 bytes.
\item Most messages are driver/device initialisation messages.
\item Messages are expected to be sent at low frequencies and quick roundtrip is
not necessary and should not impact global performances (as communication
requiring performance should use virtqueues).
\end{itemize}
The virtio-MSG messages are encoded as following:
\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]: 0=virtio-msg, 1=bus-msg \newline Bit[2-7]: Reserved \\
\hline
VIRTIO_MSG_ID & 1 & 1 & Message ID \\
\hline
VIRTIO_MSG_DEV_ID & 2 & 2 & Device ID \\
\hline
VIRTIO_MSG_PAYLOAD & 4 & 36 & Payload \\
\hline
\end{tabularx}
\subsection{Messages Definition}\label{sec:Virtio Transport Options / Virtio Over Messages / Messages Definition}
The following table is listing the different Virtio-MSG messages and the sender
for each of them.
\begin{tabular}{|l|l|l|}
\hline
Name & ID & Sender \\
\hline
\hline
VIRTIO_MSG_CONNECT & 0x1 & Driver \\
\hline
VIRTIO_MSG_DISCONNECT & 0x2 & Driver \\
\hline
VIRTIO_MSG_GET_DEVICE_INFO & 0x3 & Driver \\
\hline
VIRTIO_MSG_GET_FEATURES & 0x4 & Driver \\
\hline
VIRTIO_MSG_SET_FEATURES & 0x5 & Driver \\
\hline
VIRTIO_MSG_GET_CONFIG & 0x6 & Driver \\
\hline
VIRTIO_MSG_SET_CONFIG & 0x7 & Driver \\
\hline
VIRTIO_MSG_GET_CONFIG_GEN & 0x8 & Driver \\
\hline
VIRTIO_MSG_GET_DEVICE_STATUS & 0x9 & Driver \\
\hline
VIRTIO_MSG_SET_DEVICE_STATUS & 0xA & Driver \\
\hline
VIRTIO_MSG_GET_VQUEUE & 0xB & Driver \\
\hline
VIRTIO_MSG_SET_VQUEUE & 0xC & Driver \\
\hline
VIRTIO_MSG_RESET_VQUEUE & 0xD & Driver \\
\hline
VIRTIO_MSG_EVENT_CONFIG & 0x10 & Device \\
\hline
VIRTIO_MSG_EVENT_AVAIL & 0x11 & Driver \\
\hline
VIRTIO_MSG_EVENT_USED & 0x12 & Device \\
\hline
\end{tabular}
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{\msgdef}[1]{\subsubsection{VIRTIO_MSG_#1}\label{sec:Virtio Transport Options / Virtio Over Messages / Messages Definition / VIRTIO_MSG_#1}}
\msgdef{CONNECT}
The Connect message is used to signal to the device that the driver will start
to use it. It gives an opportunity for the device to get ready for usage.
This message is sent by the driver to the device and expects an answer from the
device.
\begin{tabular}{|l|l|l|l|}
\hline
Type & Offset & Size (bytes) & Content \\
\hline \hline
Request & 0 & 36 & Reserved (MBZ) \\
\hline
Answer & 0 & 36 & Reserved (MBZ) \\
\hline
\end{tabular}
\msgdef{DISCONNECT}
The Disconnect message is used to signal to the device that the driver will
stop using it. It gives an opportunity for the device to turn down.
This message is sent by the driver to the device and expects an answer from the
device.
\begin{tabular}{|l|l|l|l|}
\hline
Type & Offset & Size (bytes) & Content \\
\hline \hline
Request & 0 & 36 & Reserved (MBZ) \\
\hline
Answer & 0 & 36 & Reserved (MBZ) \\
\hline
\end{tabular}
\msgdef{GET_DEVICE_INFO}
The Get device information message is used by the driver to retrieve the device
version, device ID and vendor ID.
This message is sent by the driver to the device and expects an answer from the
device.
\begin{tabular}{|l|l|l|l|}
\hline
Type & Offset & Size (bytes) & Content \\
\hline \hline
Request & 0 & 36 & Reserved (MBZ) \\
\hline
Answer & 0 & 4 & Device version \\
& 4 & 4 & Device ID \\
& 8 & 4 & Vendor ID \\
& 12 & 24 & Reserved (MBZ) \\
\hline
\end{tabular}
\msgdef{GET_FEATURES}
The Get features message is used to retrieve 256 bits of feature information
from the device. The driver request features at an index and the device answers
with the features bits at 256*index.
TODO: How should a device signal that there are no features at the requested
index ? is it ok to just specify that 0 will be returned in that case ? can
we expect the driver to always know how much features a device has ?
This message is sent by the driver to the device and expects an answer from the
device.
\begin{tabular}{|l|l|l|l|}
\hline
Type & Offset & Size (bytes) & Content \\
\hline \hline
Request & 0 & 4 & Feature index \\
& 4 & 32 & Reserved (MBZ) \\
\hline
Answer & 0 & 4 & Feature index \\
& 4 & 32 & Feature data \\
\hline
\end{tabular}
\msgdef{SET_FEATURES}
The Set features message is used by the driver to configure the features of a
device. The driver configures 256 bits a time a given index. The device
provides in the answer the actual features value at the index after having
configured the bit requested giving an opportunity for the driver to detect if
some of the bits it tried to set were not accepted.
This message is sent by the driver to the device and expects an answer from the
device.
\begin{tabular}{|l|l|l|l|}
\hline
Type & Offset & Size (bytes) & Content \\
\hline \hline
Request & 0 & 4 & Feature index \\
& 4 & 32 & Feature data \\
\hline
Answer & 0 & 4 & Feature index \\
& 4 & 32 & Feature data \\
\hline
\end{tabular}
\msgdef{GET_CONFIG}
The Get configuration message is used by the driver to retrieve a part of the
configuration values of the device. The driver can request up to 256 bits at
a given offset in the device configuration space.
This message is sent by the driver to the device and expects an answer from the
device.
\begin{tabular}{|l|l|l|l|}
\hline
Type & Offset & Size (bytes) & Content \\
\hline \hline
Request & 0 & 3 & Configuration offset \\
& 3 & 1 & Number of bytes (1-32) \\
& 4 & 32 & Reserved (MBZ) \\
\hline
Answer & 0 & 3 & Configuration offset \\
& 3 & 1 & Number of bytes (1-32) \\
& 4 & 32 & Configuration data \\
\hline
\end{tabular}
\msgdef{SET_CONFIG}
The Set configuration message is used by the driver to modify a part of the
configuration values of the device. The driver can modify up to 256 bits at a
given offset in the device configuration. The device answers with the actual
configuration value at the offset after the modification to give a chance to the
driver to detect changes that have not been accepted by the device.
This message is sent by the driver to the device and expects an answer from the
device.
\begin{tabular}{|l|l|l|l|}
\hline
Type & Offset & Size (bytes) & Content \\
\hline \hline
Request & 0 & 3 & Configuration offset \\
& 3 & 1 & Number of bytes (1-32) \\
& 4 & 32 & Configuration data \\
\hline
Answer & 0 & 3 & Configuration offset \\
& 3 & 1 & Number of bytes (1-32) \\
& 4 & 32 & Configuration data \\
\hline
\end{tabular}
\msgdef{GET_CONFIG_GEN}
The Get configuration generation message is used by the driver to retrieve the
device configuration atomicity value.
TODO: need help to have a complete description here.
This message is sent by the driver to the device and expects an answer from the
device.
\begin{tabular}{|l|l|l|l|}
\hline
Type & Offset & Size (bytes) & Content \\
\hline \hline
Request & 0 & 36 & Reserved (MBZ) \\
\hline
Answer & 0 & 4 & Atomicity value \\
& 4 & 32 & Reserved (MBZ) \\
\hline
\end{tabular}
\msgdef{GET_DEVICE_STATUS}
The Get device status message is used by the driver to retrieve the device
status fields.
This message is sent by the driver to the device and expects an answer from the
device.
\begin{tabular}{|l|l|l|l|}
\hline
Type & Offset & Size (bytes) & Content \\
\hline \hline
Request & 0 & 36 & Reserved (MBZ) \\
\hline
Answer & 0 & 4 & Device status \\
& 4 & 32 & Reserved (MBZ) \\
\hline
\end{tabular}
\msgdef{SET_DEVICE_STATUS}
The Set device status message is used by the driver to modify the device status
fields. Writing a status of 0 triggers a device reset.
This message is sent by the driver to the device and expects an answer from the
device.
\begin{tabular}{|l|l|l|l|}
\hline
Type & Offset & Size (bytes) & Content \\
\hline \hline
Request & 0 & 4 & Device status \\
& 4 & 32 & Reserved (MBZ) \\
\hline
Answer & 0 & 36 & Reserved (MBZ) \\
\hline
\end{tabular}
\msgdef{GET_VQUEUE}
The Get vqueue message is used to retrieve the maximum virtqueue size and
information about the vqueue if it was already configured (all information are
0 if the virtqueue was not configured).
This message is sent by the driver to the device and expects an answer from the
device.
\begin{tabular}{|l|l|l|l|}
\hline
Type & Offset & Size (bytes) & Content \\
\hline \hline
Request & 0 & 4 & Virtqueue index \\
& 4 & 32 & Reserved (MBZ) \\
\hline
Answer & 0 & 4 & Virtqueue index \\
& 4 & 4 & Max virtqueue size \\
& 8 & 4 & Virtqueue size \\
& 12 & 8 & Descriptor address \\
& 20 & 8 & Driver address \\
& 28 & 8 & Device address \\
\hline
\end{tabular}
\msgdef{SET_VQUEUE}
The Set vqueue message is used to configure a virtqueue.
Setting the virtqueue size to 0 is disabling the virtqueue without modifying
the rest of the parameters (those should be ignored by the device).
If a driver needs to complete reset a virtqueue, the RESET\_VQUEUE message
should be used instead.
This message is sent by the driver to the device and expects an answer from the
device.
\begin{tabular}{|l|l|l|l|}
\hline
Type & Offset & Size (bytes) & Content \\
\hline \hline
Request & 0 & 4 & Virtqueue index \\
& 4 & 4 & Reserved (MBZ) \\
& 8 & 4 & Virtqueue size \\
& 12 & 8 & Descriptor address \\
& 20 & 8 & Driver address \\
& 28 & 8 & Device address \\
\hline
Answer & 0 & 4 & Virtqueue index \\
& 4 & 4 & Reserved (MBZ) \\
& 8 & 4 & Virtqueue size \\
& 12 & 8 & Descriptor address \\
& 20 & 8 & Driver address \\
& 28 & 8 & Device address \\
\hline
\end{tabular}
\msgdef{RESET_VQUEUE}
The Reset vqueue message is used to disable and reset a virtqueue.
This message is sent by the driver to the device and expects an answer from the
device.
\begin{tabular}{|l|l|l|l|}
\hline
Type & Offset & Size (bytes) & Content \\
\hline \hline
Request & 0 & 4 & Virtqueue index \\
& 4 & 32 & Reserved (MBZ) \\
\hline
Answer & 0 & 36 & Reserved (MBZ) \\
\hline
\end{tabular}
\msgdef{EVENT_CONFIG}
The Event config message is sent by the device to signal to the driver that one
or several values in the device configuration have changed. The message
contains the current device status (as encoded in the GET\_DEVICE\_STATUS
answer) and optionally the part of the configuration that has been modified. If
this is not provided, the driver will have to use the GET\_CONFIG to retrieve
the configuration and discover what has changed.
This message is sent by the device to the driver and does not expect any
answer.
\begin{tabular}{|l|l|l|l|}
\hline
Type & Offset & Size (bytes) & Content \\
\hline \hline
Request & 0 & 4 & Device status \\
& 4 & 3 & Configuration offset \\
& 7 & 1 & Number of bytes (1-16) \\
& 8 & 16 & Configuration data \\
& 24 & 12 & Reserved (MBZ) \\
\hline
\end{tabular}
\msgdef{EVENT_AVAIL}
The Event available message is sent by the driver to the device to signal that
some data are available to process in a virtqueue. If the NOTIFICATION\_DATA
was negotiated, the message can also include more details on what is actually
available.
This message is sent by the driver to the device and does not expect any
answer.
\begin{tabular}{|l|l|l|l|}
\hline
Type & Offset & Size (bytes) & Content \\
\hline \hline
Request & 0 & 4 & Virtqueue index \\
& 4 & 4 & Next offset \\
& 8 & 4 & Next wrap \\
& 12 & 24 & Reserved (MBZ) \\
\hline
\end{tabular}
\msgdef{EVENT_USED}
The event used message is sent by the device to the driver to signal that some
data is available or has been processed in the a virtqueue.
TODO: is there a case for offset/wrap in this one ?
This message is sent by the device to the driver and does not expect any
answer.
\begin{tabular}{|l|l|l|l|}
\hline
Type & Offset & Size (bytes) & Content \\
\hline \hline
Request & 0 & 4 & Virtqueue index \\
& 4 & 32 & Reserved (MBZ) \\
\hline
\end{tabular}