Add virtio Admin Virtqueue specification
RFC PATCH 1/1 Add virtio Admin Virtqueue specification
Admin virtqueues will be used to send administrative commands to manipulate various features of the device which would not easily map into the configuration space.
The same Admin command format will be used for all virtio devices. The Admin command set will include 4 types of command classes:
1. The generic common class
2. The transport specific class
3. The device specific class
4. The vendor specific class
The above mechanism will enable adding various features to the virtio specification, e.g.:
1. Format virtio-blk devices in various configurations (512B block size, 512B + 8B T10-DIF, 4K block size, 4k + 8B T10-DIF, etc..).
2. Live migration management.
3. Encrypt/Decrypt descriptors.
4. Virtualization management.
5. Get device error logs.
6. Implement advanced vendor/device/transport specific features.
7. Run device health test.
8. More.
As virtio evolves beyond the para-virt/sw-emulated world, it's mandatory for the specification to become flexible and allow a wider feature set. The corrent ctrl virtq that is defined for some of the virtio devices is device specific and wasn't designed to be a generic virtq for admininistration.
--- admin-virtq.tex | 69 +++++++++++++++++++++++++++++++++++++++++++++++++ content.tex | 4 +++ 2 files changed, 73 insertions(+) create mode 100644 admin-virtq.tex
admin-virtq.tex new file +69 -0
@@ -0,0 +1,69 @@ +\section{Admin Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Admin Virtqueues} + +Admin virtqueues are used to send administrative commands to manipulate +various features of the device which would not easily map into the +configuration space. Admin virtqueues are also used to get advance +device properties. + +Use of Admin virtqueues is negotiated by the VIRTIO_F_ADMIN_VQ +feature bit. + +Admin virtqueue index may vary among different device types. + +All commands are of the following form: + +\begin{lstlisting} +struct virtio_admin_cmd { + /* Device-readable part */ + u8 class; + u8 command; + u8 command-specific-data[]; + + /* Device-writable part */ + u8 command-specific-result[]; + u8 status_type : 4; + u8 reserved : 4; + u8 status; +}; + +/* Status type values */ +#define VIRTIO_ADMIN_STATUS_TYPE_GENERIC 0 +#define VIRTIO_ADMIN_STATUS_TYPE_CLASS_SPECIFIC 1 +#define VIRTIO_ADMIN_STATUS_TYPE_COMMAND_SPECIFIC 2 +#define VIRTIO_ADMIN_STATUS_TYPE_TRANSPORT_SPECIFIC 3 +#define VIRTIO_ADMIN_STATUS_TYPE_DEVICE_SPECIFIC 4 +#define VIRTIO_ADMIN_STATUS_TYPE_VENDOR_SPECIFIC 5 + +/* Generic status values */ +#define VIRTIO_ADMIN_STATUS_GENERIC_OK 0 +#define VIRTIO_ADMIN_STATUS_GENERIC_ERR 1 +#define VIRTIO_ADMIN_STATUS_GENERIC_INVALID_CLASS 2 +#define VIRTIO_ADMIN_STATUS_GENERIC_INVALID_COMMAND 3 +#define VIRTIO_ADMIN_STATUS_GENERIC_DATA_TRANSFER_ERR 4 +#define VIRTIO_ADMIN_STATUS_GENERIC_DEVICE_INTERNAL_ERR 5 +\end{lstlisting} + +The \field{class}, \field{command} and \field{command-specific-data} are +set by the driver, and the device sets the \field{status_type}, the +\field{status} and the \field{command-specific-result}, if needed. + +The virtio Admin command class codes are divided in the following form: + +\begin{lstlisting} +/* class values that are transport, device and vendor independent */ +#define VIRTIO_ADMIN_COMMON_CLASS_START 0 +#define VIRTIO_ADMIN_COMMON_CLASS_END 63 + +/* class values that are transport specific */ +#define VIRTIO_ADMIN_TRANSPORT_CLASS_START 64 +#define VIRTIO_ADMIN_TRANSPORT_CLASS_END 127 + +/* class values that are device specific */ +#define VIRTIO_ADMIN_DEVICE_CLASS_START 128 +#define VIRTIO_ADMIN_DEVICE_CLASS_END 191 + +/* class values that are vendor specific */ +#define VIRTIO_ADMIN_VENDOR_CLASS_START 192 +#define VIRTIO_ADMIN_VENDOR_CLASS_END 255 +\end{lstlisting} +
content.tex +4 -0
@@ -407,6 +407,8 @@ \section{Exporting Objects}\label{sec:Basic Facilities of a Virtio Device / Expo types. It is RECOMMENDED that devices generate version 4 UUIDs as specified by \hyperref[intro:rfc4122]{[RFC4122]}. +\input{admin-virtq.tex} + \chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation} We start with an overview of device initialization, then expand on the
@@ -6671,6 +6673,8 @@ \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits} data to be provided in driver notification and the delivery method is transport specific. For more details about driver notifications over PCI see \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Available Buffer Notifications}. + \item[VIRTIO_F_ADMIN_VQ(40)] This feature indicates that + the device supports administration virtqueue negotiation. \end{description}
Signature · 18 lines
2.21.0 This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC. In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting. Subscribe: [email protected] Unsubscribe: [email protected] List help: [email protected] List archive: https://lists.oasis-open.org/archives/virtio-comment/ Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists Committee: https://www.oasis-open.org/committees/virtio/ Join OASIS: https://www.oasis-open.org/join/
Quoted 42 lines · Max Gurtovoy
Admin virtqueues will be used to send administrative commands to manipulate various features of the device which would not easily map into the configuration space.
The same Admin command format will be used for all virtio devices. The Admin command set will include 4 types of command classes:
1. The generic common class
2. The transport specific class
3. The device specific class
4. The vendor specific classThe above mechanism will enable adding various features to the virtio specification, e.g.:
1. Format virtio-blk devices in various configurations (512B block size, 512B + 8B T10-DIF, 4K block size, 4k + 8B T10-DIF, etc..).
2. Live migration management.
3. Encrypt/Decrypt descriptors.
4. Virtualization management.
5. Get device error logs.
6. Implement advanced vendor/device/transport specific features.
7. Run device health test.
8. More.As virtio evolves beyond the para-virt/sw-emulated world, it's mandatory for the specification to become flexible and allow a wider feature set. The corrent ctrl virtq that is defined for some of the virtio devices is device specific and wasn't designed to be a generic virtq for admininistration.
Signed-off-by Max Gurtovoy <[email protected]>--- admin-virtq.tex | 69 +++++++++++++++++++++++++++++++++++++++++++++++++ content.tex | 4 +++ 2 files changed, 73 insertions(+) create mode 100644 admin-virtq.texadmin-virtq.tex new file +0
-0
admin-virtq.tex line 6
Quoted 6 lines
admin-virtq.tex new file +6
-0@@ -0,0 +1,69 @@ +\section{Admin Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Admin Virtqueues} + +Admin virtqueues are used to send administrative commands to manipulate +various features of the device which would not easily map into the +configuration space. Admin virtqueues are also used to get advance +device properties.
What are "advance device properties"?
admin-virtq.tex line 11
Quoted 5 lines
admin-virtq.tex new file +5
-0+ +Use of Admin virtqueues is negotiated by the VIRTIO_F_ADMIN_VQ +feature bit. + +Admin virtqueue index may vary among different device types.
So, the idea is that every device type that supports this states something like: "If VIRTIO_F_ADMIN_VQ is negotiated, queue<i> is an admin virtqueue."?
Quoted 23 lines
admin-virtq.tex new file +23
-0+ +All commands are of the following form: + +\begin{lstlisting} +struct virtio_admin_cmd { + /* Device-readable part */ + u8 class; + u8 command; + u8 command-specific-data[]; + + /* Device-writable part */ + u8 command-specific-result[]; + u8 status_type : 4; + u8 reserved : 4; + u8 status; +}; + +/* Status type values */ +#define VIRTIO_ADMIN_STATUS_TYPE_GENERIC 0 +#define VIRTIO_ADMIN_STATUS_TYPE_CLASS_SPECIFIC 1 +#define VIRTIO_ADMIN_STATUS_TYPE_COMMAND_SPECIFIC 2 +#define VIRTIO_ADMIN_STATUS_TYPE_TRANSPORT_SPECIFIC 3 +#define VIRTIO_ADMIN_STATUS_TYPE_DEVICE_SPECIFIC 4
admin-virtq.tex line 44
Quoted 10 lines
admin-virtq.tex new file +10
-0+#define VIRTIO_ADMIN_STATUS_TYPE_VENDOR_SPECIFIC 5 + +/* Generic status values */ +#define VIRTIO_ADMIN_STATUS_GENERIC_OK 0 +#define VIRTIO_ADMIN_STATUS_GENERIC_ERR 1 +#define VIRTIO_ADMIN_STATUS_GENERIC_INVALID_CLASS 2 +#define VIRTIO_ADMIN_STATUS_GENERIC_INVALID_COMMAND 3 +#define VIRTIO_ADMIN_STATUS_GENERIC_DATA_TRANSFER_ERR 4 +#define VIRTIO_ADMIN_STATUS_GENERIC_DEVICE_INTERNAL_ERR 5 +\end{lstlisting}
I'd probably rather chop up the status namespace. I.e.
- first bit indicates ok or error
- next i bits indicate any generic errors
- next j bits indicate transport-specific errors
- next m bits indicate device type (class) specific errors
- next n bits indicate command-specific errors
(and ditch status_type/reserve, while making status u16)
Quoted 14 lines
admin-virtq.tex new file +14
-0+ +The \field{class}, \field{command} and \field{command-specific-data} are +set by the driver, and the device sets the \field{status_type}, the +\field{status} and the \field{command-specific-result}, if needed. + +The virtio Admin command class codes are divided in the following form: + +\begin{lstlisting} +/* class values that are transport, device and vendor independent */ +#define VIRTIO_ADMIN_COMMON_CLASS_START 0 +#define VIRTIO_ADMIN_COMMON_CLASS_END 63 + +/* class values that are transport specific */ +#define VIRTIO_ADMIN_TRANSPORT_CLASS_START 64
admin-virtq.tex line 68
Quoted 10 lines
admin-virtq.tex new file +10
-0+#define VIRTIO_ADMIN_TRANSPORT_CLASS_END 127 + +/* class values that are device specific */ +#define VIRTIO_ADMIN_DEVICE_CLASS_START 128 +#define VIRTIO_ADMIN_DEVICE_CLASS_END 191 + +/* class values that are vendor specific */ +#define VIRTIO_ADMIN_VENDOR_CLASS_START 192 +#define VIRTIO_ADMIN_VENDOR_CLASS_END 255 +\end{lstlisting}
I'd probably also make command a 16-bit value and divide up the namespace between the different cases (i.e. no separate setting of class and command.)
How can the driver find out which commands the device supports? Should we define a generic discovery command? Should it all be handled via feature bits?
This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.
Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
Quoted 52 lines · Cornelia Huck
Quoted 42 lines · Max Gurtovoy
Admin virtqueues will be used to send administrative commands to manipulate various features of the device which would not easily map into the configuration space.
The same Admin command format will be used for all virtio devices. The Admin command set will include 4 types of command classes:
1. The generic common class
2. The transport specific class
3. The device specific class
4. The vendor specific classThe above mechanism will enable adding various features to the virtio specification, e.g.:
1. Format virtio-blk devices in various configurations (512B block size,512B + 8B T10-DIF, 4K block size, 4k + 8B T10-DIF, etc..).2. Live migration management.
3. Encrypt/Decrypt descriptors.
4. Virtualization management.
5. Get device error logs.
6. Implement advanced vendor/device/transport specific features.
7. Run device health test.
8. More.As virtio evolves beyond the para-virt/sw-emulated world, it's mandatory for the specification to become flexible and allow a wider feature set. The corrent ctrl virtq that is defined for some of the virtio devices is device specific and wasn't designed to be a generic virtq for admininistration.
Signed-off-by Max Gurtovoy <[email protected]>--- admin-virtq.tex | 69 +++++++++++++++++++++++++++++++++++++++++++++++++ content.tex | 4 +++ 2 files changed, 73 insertions(+)create mode 100644 admin-virtq.tex
admin-virtq.tex new file +0
-0admin-virtq.tex line 6
Quoted 6 lines
admin-virtq.tex new file +6
-0@@ -0,0 +1,69 @@ +\section{Admin Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Admin Virtqueues} + +Admin virtqueues are used to send administrative commands to manipulate +various features of the device which would not easily map into the +configuration space. Admin virtqueues are also used to get advance +device properties.What are "advance device properties"?
Quoted 8 lines
admin-virtq.tex line 11
Quoted 5 lines
admin-virtq.tex new file +5
-0+ +Use of Admin virtqueues is negotiated by the VIRTIO_F_ADMIN_VQ +feature bit. + +Admin virtqueue index may vary among different device types.So, the idea is that every device type that supports this states something like: "If
VIRTIO_F_ADMIN_VQis negotiated, queue<i> is an admin virtqueue."?
Yes exactly.
Do you think we should add some example ? I can set it as queue_0
Quoted 40 lines
Quoted 23 lines
admin-virtq.tex new file +23
-0+ +All commands are of the following form: + +\begin{lstlisting} +struct virtio_admin_cmd { + /* Device-readable part */ + u8 class; + u8 command; + u8 command-specific-data[]; + + /* Device-writable part */ + u8 command-specific-result[]; + u8 status_type : 4; + u8 reserved : 4; + u8 status; +}; + +/* Status type values */ +#define VIRTIO_ADMIN_STATUS_TYPE_GENERIC 0 +#define VIRTIO_ADMIN_STATUS_TYPE_CLASS_SPECIFIC 1 +#define VIRTIO_ADMIN_STATUS_TYPE_COMMAND_SPECIFIC 2 +#define VIRTIO_ADMIN_STATUS_TYPE_TRANSPORT_SPECIFIC 3 +#define VIRTIO_ADMIN_STATUS_TYPE_DEVICE_SPECIFIC 4admin-virtq.tex line 44
Quoted 10 lines
admin-virtq.tex new file +10
-0+#define VIRTIO_ADMIN_STATUS_TYPE_VENDOR_SPECIFIC 5 + +/* Generic status values */ +#define VIRTIO_ADMIN_STATUS_GENERIC_OK 0 +#define VIRTIO_ADMIN_STATUS_GENERIC_ERR 1 +#define VIRTIO_ADMIN_STATUS_GENERIC_INVALID_CLASS 2 +#define VIRTIO_ADMIN_STATUS_GENERIC_INVALID_COMMAND 3 +#define VIRTIO_ADMIN_STATUS_GENERIC_DATA_TRANSFER_ERR 4 +#define VIRTIO_ADMIN_STATUS_GENERIC_DEVICE_INTERNAL_ERR 5 +\end{lstlisting}I'd probably rather chop up the status namespace. I.e.
- first bit indicates ok or error
- next i bits indicate any generic errors
- next j bits indicate transport-specific errors
- next m bits indicate device type (class) specific errors
- next n bits indicate command-specific errors
Quoted 1 line
(and ditch status_type/reserve, while making status u16)
Any reason it's preferred ?
seems like wasting bits.
Quoted 20 lines
Quoted 20 lines
admin-virtq.tex new file +19
-0+ +The \field{class}, \field{command} and \field{command-specific-data} are +set by the driver, and the device sets the \field{status_type}, the +\field{status} and the \field{command-specific-result}, if needed. + +The virtio Admin command class codes are divided in the following form: + +\begin{lstlisting} +/* class values that are transport, device and vendor independent */ +#define VIRTIO_ADMIN_COMMON_CLASS_START 0 +#define VIRTIO_ADMIN_COMMON_CLASS_END 63 + +/* class values that are transport specific */ +#define VIRTIO_ADMIN_TRANSPORT_CLASS_START 64 +#define VIRTIO_ADMIN_TRANSPORT_CLASS_END 127 + +/* class values that are device specific */ +#define VIRTIO_ADMIN_DEVICE_CLASS_START 128 +#define VIRTIO_ADMIN_DEVICE_CLASS_END 191
Quoted 8 lines
admin-virtq.tex line 68
Quoted 5 lines
admin-virtq.tex new file +5
-0+ +/* class values that are vendor specific */ +#define VIRTIO_ADMIN_VENDOR_CLASS_START 192 +#define VIRTIO_ADMIN_VENDOR_CLASS_END 255 +\end{lstlisting}I'd probably also make command a 16-bit value and divide up the namespace between the different cases (i.e. no separate setting of class and command.)
same here.
any reason to divide it ?
Quoted 4 lines
How can the driver find out which commands the device supports? Should we define a generic discovery command? Should it all be handled via feature bits?
Feature bit will be used for VIRTIO_F_ADMIN_VQ for now.
Admin command set should define some mandatory commands, such as:
#define VIRTIO_ADMIN_DISCOVER_DEVICE 0 // will return 4KB of output that will describe device properties
#define VIRTIO_ADMIN_DISCOVER_DEVICE_FEATURES 0
#define VIRTIO_ADMIN_DISCOVER_DEVICE_SUPPORTED_CLASSES 1
#define VIRTIO_ADMIN_DISCOVER_DEVICE_CLASS_COMMANDS 1 // will return 4KB of output that will describe device supported l data
#define VIRTIO_ADMIN_DISCOVER_DEVICE_CLASS_0_COMMANDS 0 // will return 4KB of output that will describe device supported commands for a given class 0 and some additional data #define VIRTIO_ADMIN_DISCOVER_DEVICE_CLASS_1_COMMANDS 1 // will return 4KB of output that will describe device supported commands for a given class 1 and some additional data #define VIRTIO_ADMIN_DISCOVER_DEVICE_CLASS_2_COMMANDS 2 // will return 4KB of output that will describe device supported commands for a given class 2 and some additional data
...
#define VIRTIO_ADMIN_DISCOVER_DEVICE_CLASS_255_COMMANDS 255 // will return 4KB of output that will describe device supported commands for a given class 255 and some additional data
Quoted 42 lines · Max Gurtovoy
Admin virtqueues will be used to send administrative commands to manipulate various features of the device which would not easily map into the configuration space.
The same Admin command format will be used for all virtio devices. The Admin command set will include 4 types of command classes:
1. The generic common class
2. The transport specific class
3. The device specific class
4. The vendor specific classThe above mechanism will enable adding various features to the virtio specification, e.g.:
1. Format virtio-blk devices in various configurations (512B block size, 512B + 8B T10-DIF, 4K block size, 4k + 8B T10-DIF, etc..).
2. Live migration management.
3. Encrypt/Decrypt descriptors.
4. Virtualization management.
5. Get device error logs.
6. Implement advanced vendor/device/transport specific features.
7. Run device health test.
8. More.As virtio evolves beyond the para-virt/sw-emulated world, it's mandatory for the specification to become flexible and allow a wider feature set. The corrent ctrl virtq that is defined for some of the virtio devices is device specific and wasn't designed to be a generic virtq for admininistration.
Signed-off-by Max Gurtovoy <[email protected]>--- admin-virtq.tex | 69 +++++++++++++++++++++++++++++++++++++++++++++++++ content.tex | 4 +++ 2 files changed, 73 insertions(+) create mode 100644 admin-virtq.texadmin-virtq.tex new file +0
-0
admin-virtq.tex line 5
Quoted 5 lines
admin-virtq.tex new file +5
-0@@ -0,0 +1,69 @@ +\section{Admin Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Admin Virtqueues} + +Admin virtqueues are used to send administrative commands to manipulate +various features of the device which would not easily map into the +configuration space. Admin virtqueues are also used to get advance
s/advance/advanced/
Quoted 33 lines
admin-virtq.tex new file +33
-0+device properties. + +Use of Admin virtqueues is negotiated by the VIRTIO_F_ADMIN_VQ +feature bit. + +Admin virtqueue index may vary among different device types. + +All commands are of the following form: + +\begin{lstlisting} +struct virtio_admin_cmd { + /* Device-readable part */ + u8 class; + u8 command; + u8 command-specific-data[]; + + /* Device-writable part */ + u8 command-specific-result[]; + u8 status_type : 4; + u8 reserved : 4; + u8 status; +}; + +/* Status type values */ +#define VIRTIO_ADMIN_STATUS_TYPE_GENERIC 0 +#define VIRTIO_ADMIN_STATUS_TYPE_CLASS_SPECIFIC 1 +#define VIRTIO_ADMIN_STATUS_TYPE_COMMAND_SPECIFIC 2 +#define VIRTIO_ADMIN_STATUS_TYPE_TRANSPORT_SPECIFIC 3 +#define VIRTIO_ADMIN_STATUS_TYPE_DEVICE_SPECIFIC 4 +#define VIRTIO_ADMIN_STATUS_TYPE_VENDOR_SPECIFIC 5 + +/* Generic status values */ +#define VIRTIO_ADMIN_STATUS_GENERIC_OK 0
admin-virtq.tex line 48
Quoted 10 lines
admin-virtq.tex new file +10
-0+#define VIRTIO_ADMIN_STATUS_GENERIC_ERR 1 +#define VIRTIO_ADMIN_STATUS_GENERIC_INVALID_CLASS 2 +#define VIRTIO_ADMIN_STATUS_GENERIC_INVALID_COMMAND 3 +#define VIRTIO_ADMIN_STATUS_GENERIC_DATA_TRANSFER_ERR 4 +#define VIRTIO_ADMIN_STATUS_GENERIC_DEVICE_INTERNAL_ERR 5 +\end{lstlisting} + +The \field{class}, \field{command} and \field{command-specific-data} are +set by the driver, and the device sets the \field{status_type}, the +\field{status} and the \field{command-specific-result}, if needed.
What are the semantics regarding:
- When can the admin virtqueue be used (only after the Device Initialization sequence is complete, while the device is active and performing I/O, etc)?
- Are commands executed in order?
- Can multiple commands execute concurrently (e.g. long-running commands like formatting a disk)?
Quoted 9 lines
admin-virtq.tex new file +9
-0+ +The virtio Admin command class codes are divided in the following form: + +\begin{lstlisting} +/* class values that are transport, device and vendor independent */ +#define VIRTIO_ADMIN_COMMON_CLASS_START 0 +#define VIRTIO_ADMIN_COMMON_CLASS_END 63 + +/* class values that are transport specific */
admin-virtq.tex line 67
Quoted 10 lines
admin-virtq.tex new file +10
-0+#define VIRTIO_ADMIN_TRANSPORT_CLASS_START 64 +#define VIRTIO_ADMIN_TRANSPORT_CLASS_END 127 + +/* class values that are device specific */ +#define VIRTIO_ADMIN_DEVICE_CLASS_START 128 +#define VIRTIO_ADMIN_DEVICE_CLASS_END 191 + +/* class values that are vendor specific */ +#define VIRTIO_ADMIN_VENDOR_CLASS_START 192 +#define VIRTIO_ADMIN_VENDOR_CLASS_END 255
How do vendor commands work? Will they be defined in the spec? If not, then how can vendors avoid namespace collisions? How does the availability of vendor commands interact with migration?
Is there a way to enumerate commands or does the driver simply try the command and handle VIRTIO_ADMIN_STATUS_GENERIC_INVALID_COMMAND in case the command is unavailable?
Stefan