diff options
| -rw-r--r-- | content.tex | 67 | ||||
| -rw-r--r-- | main.tex | 2 | ||||
| -rw-r--r-- | newdevice.tex | 66 |
3 files changed, 68 insertions, 67 deletions
diff --git a/content.tex b/content.tex index d66f89c..2aa3aac 100644 --- a/content.tex +++ b/content.tex @@ -4356,70 +4356,3 @@ Legacy or transitional devices may offer the following: for experimental early versions of virtio which did not perform correct feature negotiation, and should not be used. \end{description} - -\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). - -Devices must not assume that configuration fields over 32 bits wide -are atomically writable by the driver. - -\section{What Device Number?}\label{sec:Creating New Device Types / What Device Number?} - -Device numbers can be reserved by the OASIS committee: email -virtio-dev@lists.oasis-open.org 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. - - @@ -40,6 +40,8 @@ \input{headerfile.tex} +\input{newdevice.tex} + % acknowledgements \input{acknowledgements.tex} diff --git a/newdevice.tex b/newdevice.tex new file mode 100644 index 0000000..5e07b79 --- /dev/null +++ b/newdevice.tex @@ -0,0 +1,66 @@ +\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). + +Devices must not assume that configuration fields over 32 bits wide +are atomically writable by the driver. + +\section{What Device Number?}\label{sec:Creating New Device Types / What Device Number?} + +Device numbers can be reserved by the OASIS committee: email +virtio-dev@lists.oasis-open.org 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. + + |