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
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
|
Document: virtio-v1.0-csprd01
Number: 6
Date: Wed, 29 Jan 2014 21:36:30 +0100
Link to Mail: https://lists.oasis-open.org/archives/virtio-comment/201401/msg00055.html
Commenter name: Thomas Huth <thuth@linux.vnet.ibm.com>
Decision: 2014-02-11 minutes: Applied
Generic remark: Quite a lot of structures use a mixture of "u8"
and "char" types for bytes, e.g. struct virtio_blk_req. Is that
intended? If not, I'd suggest to always use "u8" here instead.
Page 38 / Device Types:
Is the information about other virtio devices like 9P documented
somewhere else? If yes, you might want to put a pointer to these
documents here.
Page 43 and page 44:
Some of the #defines are indented with an additional space.
That looks a little bit ugly, would be great if you could get rid
of the indentation here.
Page 43 / Setting MAC Address Filtering
ETH_ALEN is a Linux-internal #define only, which is not defined
in this spec, so I'd suggest to simply replace ETH_ALEN with 6 here.
Page 48 / Virtqueues
The initial numbered list names the second pair of console virtqueues
"port1" but the next sentence talks about "Port 2" ... that's confusing.
==> Maybe replace "Ports 2 onwards only exist ..." with something like
"All ports except the first one only exist ..." ?
Page 50:
The paragraph "5." says:
"If the device specified a port `name', a sysfs attribute is created with
the name filled in, so that udev rules can be written that can create a
symlink from the port's name to the char device for port discovery by
applications in the driver."
==> That's completely specific to Linux as far as I can tell, so I think
this should not go into a generic specification document, or at least it
should be marked as an example for Linux.
Also, this paragraph talks about the "name" which is not introduced before
paragraph "6.", so I think if you really want to keep this paragraph "5.",
it should be moved behind "6." instead.
Concerning paragraph "6.":
The console port change events are hardly documented ... I think this
paragraph needs some love. How does the "value" look like for the
various message types? For example, how is the size of the console
passed when the VIRTIO_CONSOLE_RESIZE event occured? Or the name? What
is the difference between VIRTIO_CONSOLE_PORT_ADD and
VIRTIO_CONSOLE_PORT_OPEN?
As a further remark, I also I wonder whether should be a way to signal
the terminal type (like "vt100") to the guest?
Page 55 / Device Operation: Request Queues
While reading this chapter, I first got a little bit confused about the
terms "read-only" and "write-only" since I read chapter 4.1.3.1.1
("Virtio Device Configuration Layout Detection") shortly before, where
the terms are used in the opposite way - since "read-only" and
"write-only" are dependend on the view, whether you talk about the device
or the driver.
So even it's clear when you read the various chapters twice and think
about everything logically, it might be more consisten and easier to
read if you always say something more explicit like "read-only for the
device" or "read-only for the driver" throughout the specification.
Proposal:
diff --git a/content.tex b/content.tex
index 7e77740..27a957d 100644
--- a/content.tex
+++ b/content.tex
@@ -286,7 +286,7 @@ struct vring {
struct vring_avail avail;
// Padding to the next PAGE_SIZE boundary.
- char pad[ Padding ];
+ u8 pad[ Padding ];
// A ring of used descriptor heads with free-running index.
struct vring_used used;
@@ -334,8 +334,11 @@ VIRTIO_F_ANY_LAYOUT feature is accepted.
The descriptor table refers to the buffers the driver is using for
the device. The addresses are physical addresses, and the buffers
can be chained via the next field. Each descriptor describes a
-buffer which is read-only or write-only, but a chain of
-descriptors can contain both read-only and write-only buffers.
+buffer which is read-only for the device (``device-readable'') or write-only for the device (``device-writable''), but a chain of
+descriptors can contain both device-readable and device-writable buffers.
+A device MUST NOT write to a device-readable buffer, and a device SHOULD NOT
+read a device-writable buffer (it might do so for debugging or diagnostic
+purposes).
The actual contents of the memory offered to the device depends on the
device type. Most common is to begin the data with a header
@@ -355,7 +358,7 @@ struct vring_desc {
/* This marks a buffer as continuing via the next field. */
#define VRING_DESC_F_NEXT 1
-/* This marks a buffer as write-only (otherwise read-only). */
+/* This marks a buffer as device write-only (otherwise device read-only). */
#define VRING_DESC_F_WRITE 2
/* This means the buffer contains a list of buffer descriptors. */
#define VRING_DESC_F_INDIRECT 4
@@ -401,7 +404,7 @@ chained by next field. An indirect descriptor without next field
An
indirect descriptor can not refer to another indirect descriptor
table (flags\&VRING_DESC_F_INDIRECT MUST be off). A single indirect descriptor
-table can include both read-only and write-only descriptors;
+table can include both device-readable and device-writable descriptors;
the device MUST ignore the write-only flag (flags\&VRING_DESC_F_WRITE) in the descriptor that refers to it.
\subsection{The Virtqueue Available Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Available Ring}
@@ -575,8 +578,8 @@ There are two parts to device operation: supplying new buffers to
the device, and processing used buffers from the device. As an
example, the simplest virtio network device has two virtqueues: the
transmit virtqueue and the receive virtqueue. The driver adds
-outgoing (read-only) packets to the transmit virtqueue, and then
-frees them after they are used. Similarly, incoming (write-only)
+outgoing (device-readable) packets to the transmit virtqueue, and then
+frees them after they are used. Similarly, incoming (device-writable)
buffers are added to the receive virtqueue, and processed after
they are used.
@@ -621,9 +624,9 @@ Here is a description of each stage in more detail.
\subsubsection{Placing Buffers Into The Descriptor Table}\label{sec:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Placing Buffers Into The Descriptor Table}
-A buffer consists of zero or more read-only physically-contiguous
+A buffer consists of zero or more device-readable physically-contiguous
elements followed by zero or more physically-contiguous
-write-only elements (it must have at least one element). This
+device-writable elements (it must have at least one element). This
algorithm maps it into the descriptor table to form a descriptor
chain:
@@ -633,7 +636,7 @@ for each buffer element, b:
\item Get the next free descriptor table entry, d
\item Set d.addr to the physical address of the start of b
\item Set d.len to the length of b.
-\item If b is write-only, set d.flags to VRING_DESC_F_WRITE,
+\item If b is device-writable, set d.flags to VRING_DESC_F_WRITE,
|
