forked from oasis-tcs/virtio-spec
-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathnewdevice.tex
90 lines (71 loc) · 4.7 KB
/
newdevice.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
\chapter{Creating New Device Types}\label{sec:Creating New Device Types}
Various considerations are necessary when creating a new device
type.
\section{How Many Virtqueues?}\label{sec:Creating New Device Types / How Many Virtqueues?}
It is possible that a very simple device will operate entirely
through its device configuration space, but most will need at least one
virtqueue in which it will place requests. A device with both
input and output (eg. console and network devices described here)
need two queues: one which the driver fills with buffers to
receive input, and one which the driver places buffers to
transmit output.
\section{What Device Configuration Space Layout?}\label{sec:Creating New Device Types / What Device Configuration Space Layout?}
Device configuration space should only be used for initialization-time
parameters. It is a limited resource with no synchronization between
field written by the driver, so for most uses it is better to use a virtqueue to update
configuration information (the network device does this for filtering,
otherwise the table in the config space could potentially be very
large).
Remember that configuration fields over 32 bits wide might not be atomically
writable by the driver. Therefore, no writeable field which triggers an
action ought to be wider than 32 bits.
\section{What Device Number?}\label{sec:Creating New Device Types / What Device Number?}
Device numbers can be reserved by the OASIS committee: email
[email protected] (after subscribing through
[email protected]) to secure a unique one.
Meanwhile for experimental drivers, use 65535 and work backwards.
\section{How many MSI-X vectors? (for PCI)}\label{sec:Creating New Device Types / How many MSI-X vectors? (for PCI)}
Using the optional MSI-X capability devices can speed up
interrupt processing by removing the need to read ISR Status
register by guest driver (which might be an expensive operation),
reducing interrupt sharing between devices and queues within the
device, and handling interrupts from multiple CPUs. However, some
systems impose a limit (which might be as low as 256) on the
total number of MSI-X vectors that can be allocated to all
devices. Devices and/or drivers should take this into
account, limiting the number of vectors used unless the device is
expected to cause a high volume of interrupts. Devices can
control the number of vectors used by limiting the MSI-X Table
Size or not presenting MSI-X capability in PCI configuration
space. Drivers can control this by mapping events to as small
number of vectors as possible, or disabling MSI-X capability
altogether.
\section{Device Improvements}\label{sec:Creating New Device Types / Device Improvements}
Any change to device configuration space, or new virtqueues, or
behavioural changes, should be indicated by negotiation of a new
feature bit. This establishes clarity\footnote{Even if it does mean documenting design or implementation
mistakes!
} and avoids future expansion problems.
Clusters of functionality which are always implemented together
can use a single bit, but if one feature makes sense without the
others they should not be gratuitously grouped together to
conserve feature bits.
\section{How to define a new device part?}\label{sec:Creating New Device Types or Extending the Device / How to define a new device part?}
Few considerations are necessary when creating new device part or
when extending the device part structure.
If the new field is generic for all the device types or most of the device types,
a new device part should be defined as common device part by claiming a new \field{type} value.
If the new field is unique to a device type, a new device specific device part should
be added.
range.
\section{When to define a new device part?}\label{sec:Creating New Device Types or Extending the Device / When to define a new device part?}
When the device part for a specific field does not exists, one should
define a new device part.
\section{How to avoid device part duplication with existing structure?}\label{sec:Creating New Device Types or Extending the Device / How to avoid device part duplication with existing structure?}
Each device should reuse any existing field definition that may exists as part
of device control virtqueue or any other existing structure definition.
\section{How to extend the existing device part definition?}\label{sec:Creating New Device Types or Extending the Device / How to extend the existing device part definition?}
When a field is missing in already defined device part, a new field should be added at
the end of the existing device part. New field MUST not be added at beginning or in
the middle of the device part structure. Any field which is already present MUST NOT
be removed.