virtio_driver/common/
feature_bits.rs

1// Copyright 2026 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#[cfg(doc)]
6use super::device_status::DeviceStatus;
7
8#[cfg(doc)]
9use super::queue::abi::VirtioMemoryRangeFlags;
10
11use bitfield::bitfield;
12
13bitfield! {
14    /// Configures virtio device operation.
15    ///
16    /// Each bit represents an optional feature or an alternative mode for an
17    /// aspect of the virtio device's operation.
18    // @cite(virtio): sec="2.2" title="Feature Bits"
19    // @cite(virtio): sec="6" title="Reserved Feature Bits"
20    #[derive(Default, Copy, Clone, PartialEq, Eq)]
21    pub struct VirtioFeatureBits(u128);
22    impl Debug;
23
24    /// The device notifies when a virtqueue has no submitted buffers.
25    ///
26    /// If this feature is negotiated, the device issues a virtqueue
27    /// notification when it has completed all the commands submitted on the
28    /// virtqueue.
29    // @cite(virtio): sec="6" title="Reserved Feature Bits" bits=24
30    // @alias(virtio): theirs="VIRTIO_F_NOTIFY_ON_EMPTY"
31    pub bool, notify_on_empty_queue, set_notify_on_empty_queue: 24;
32
33    /// Remove virtio queue memory layout constraints in legacy mode.
34    ///
35    /// The feature is only meaningful if [`uses_virtio1_standard`] is not
36    /// negotiated. Flexible memory layout is required by the virtio 1.0+
37    /// standard.
38    ///
39    /// If this feature or [`uses_virtio1_standard`] is negotiated, the driver
40    /// does not need to support memory layout limitations in early virtio
41    /// device implementations.
42    ///
43    /// If neither feature is negotiated, the driver must meet the constraints
44    /// specified in the "Legacy Interface: Framing Requirements" sections of
45    /// the relevant device type specification.
46    ///
47    /// This driver only supports virtio 1.0+ devices, and does not attempt to
48    /// negotiate this feature.
49    // @cite(virtio): sec="6" title="Reserved Feature Bits" bits=27
50    // @alias(virtio): theirs="VIRTIO_F_ANY_LAYOUT"
51    pub bool, supports_flexible_memory_layout, set_supports_flexible_memory_layout: 27;
52
53    /// Indirect descriptors are supported.
54    ///
55    /// [`VirtioMemoryRangeFlags::is_indirect`] may be set to true iff
56    /// this feature is negotiated.
57    // @cite(virtio): sec="2.7.5.3" title="Indirect descriptors"
58    // @cite(virtio): sec="2.8.7" title="Indirect Flag: Scatter-Gather Support"
59    // @cite(virtio): sec="6" title="Reserved Feature Bits" bits=28
60    // @alias(virtio): theirs="VIRTIO_F_INDIRECT_DESC"
61    pub bool, supports_indirect_descriptors, set_supports_indirect_descriptors: 28;
62
63    /// Use selective virtqueue notifications.
64    // @cite(virtio): sec="2.7.7" title="Used Buffer Notification Suppression"
65    // @cite(virtio): sec="2.7.10" title="Available Buffer Notification Suppression"
66    // @cite(virtio): sec="6" title="Reserved Feature Bits" bits=29
67    // @alias(virtio): theirs="VIRTIO_F_EVENT_IDX"
68    pub bool, uses_virtqueue_notification_index, set_uses_virtqueue_notification_index: 29;
69
70    /// Workaround for bug in early QEMU implementations.
71    ///
72    /// This driver does not attempt to negotiate this feature.
73    // @cite(virtio): sec="6" title="Reserved Feature Bits" bits=30
74    // @alias(virtio): theirs="UNUSED"
75    pub bool, unused_qemu_experimental, set_unused_qemu_experimental: 30;
76
77    /// Use the virtio 1.0+ standard.
78    ///
79    /// Failing to negotiate this feature enables behaviors called "legacy" in
80    /// the specification.
81    ///
82    /// This driver only supports virtio 1.0+ devices, and fails to initialize
83    /// if the device does not offer this feature.
84    // @cite(virtio): sec="6" title="Reserved Feature Bits" bits=32
85    // @cite(virtio): sec="6.1" title="Driver Requirements: Reserved Feature Bits"
86    // @alias(virtio): theirs="VIRTIO_F_VERSION_1"
87    pub bool, uses_virtio1_standard, set_uses_virtio1_standard: 32;
88
89    /// Signals that the device's memory accesses are limited or translated.
90    ///
91    /// By default, the driver may assume that the virtio implementation can
92    /// access any physical memory address provided by the driver. If this
93    /// feature is negotiated, the device's memory accesses may be gated by an
94    /// IOMMU.
95    ///
96    /// This driver does not currently support this feature.
97    // @cite(virtio): sec="6" title="Reserved Feature Bits" bits=33
98    // @cite(virtio): sec="6.1" title="Driver Requirements: Reserved Feature Bits"
99    // @cite(virtio): sec="6.2" title="Device Requirements: Reserved Feature Bits"
100    // @alias(virtio): theirs="VIRTIO_F_ACCESS_PLATFORM"
101    pub bool, has_limited_memory_access, set_has_limited_memory_access: 33;
102
103    /// Use packed virtqueues, as opposed to split virtqueues.
104    ///
105    /// By default, virtqueues use split virtqueues. If this feature is negotiated,
106    /// virtqueues use packed virtqueues.
107    ///
108    /// This driver currently only supports split virtqueues, and does not attempt
109    /// to negotiate this feature.
110    // @cite(virtio): sec="2.7" title="Split Virtqueues"
111    // @cite(virtio): sec="2.8" title="Packed Virtqueues"
112    // @cite(virtio): sec="6" title="Reserved Feature Bits" bits=34
113    // @cite(virtio): sec="6.1" title="Driver Requirements: Reserved Feature Bits"
114    // @alias(virtio): theirs="VIRTIO_F_RING_PACKED"
115    pub bool, uses_packed_virtqueues, set_uses_packed_virtqueues: 34;
116
117    /// The device always returns virtqueue buffers in submission order.
118    ///
119    /// By default, virtio devices are free to return submitted virtqueue
120    /// buffers in any order. If this feature is negotiated, devices will follow
121    /// submission order when returning the buffers. So, negotiating this
122    /// feature can simplify the driver's buffer management, at the cost of
123    /// reducing performance optimization opportunities for the device.
124    ///
125    /// Only some devices offer this feature. For example, the virtio-gpu
126    /// implementation in QEMU and crosvm does not offer this feature.
127    // @cite(virtio): sec="6" title="Reserved Feature Bits" bits=35
128    // @alias(virtio): theirs="VIRTIO_F_IN_ORDER"
129    pub bool, returns_buffers_in_submission_order, set_returns_buffers_in_submission_order: 35;
130
131    /// Use the memory access ordering rules for device memory accesses.
132    ///
133    /// By default, the virtio device must behave as if it accesses memory
134    /// directly from one of the CPU cores, which entails access to coherent
135    /// caches.
136    ///
137    /// If this feature is negotiated, the virtio device may perform
138    /// optimizations that assume the driver issues the memory access barriers
139    /// needed for external hardware devices.
140    ///
141    /// This driver always issues the memory barriers required by the platform,
142    /// even if the feature is not negotiated.
143    // @cite(virtio): sec="6" title="Reserved Feature Bits" bits=36
144    // @cite(virtio): sec="6.1" title="Driver Requirements: Reserved Feature Bits"
145    // @cite(virtio): sec="6.2" title="Device Requirements: Reserved Feature Bits"
146    // @alias(virtio): theirs="VIRTIO_F_ORDER_PLATFORM"
147    pub bool, assumes_hardware_memory_barriers, set_assumes_hardware_memory_barriers: 36;
148
149    /// Enables device support for PCI Single Root I/O Virtualization (SR-IOV).
150    ///
151    /// If this feature is negotiated, the driver may use the PCI SR-IOV capability
152    /// structure to enable virtual functions.
153    ///
154    /// This driver does not use SR-IOV.
155    // @cite(virtio): sec="6" title="Reserved Feature Bits" bits=37
156    // @alias(virtio): theirs="VIRTIO_F_SR_IOV"
157    pub bool, supports_io_virtualization, set_supports_io_virtualization: 37;
158
159    /// Enables extra data in the driver's device notifications.
160    ///
161    /// By default, the notifications issued by the driver only identify a
162    /// target virtqueue. If this feature is negotiated, the notifications include
163    /// more data.
164    ///
165    /// This driver does not attempt to negotiate this feature. None of the
166    /// virtio implementations targeted by this driver take advantage of this
167    /// feature.
168    // @cite(virtio): sec="2.9" title="Driver Notifications"
169    // @cite(virtio): sec="4.1.5.2" title="Available Buffer Notifications"
170    // @cite(virtio): sec="6" title="Reserved Feature Bits" bits=38
171    // @alias(virtio): theirs="VIRTIO_F_NOTIFICATION_DATA"
172    pub bool, uses_extended_notification_data, set_uses_extended_notification_data: 38;
173
174    /// Enables custom virtqueue IDs in driver-issued notifications.
175    ///
176    /// By default, the driver identifies virtqueues using their index. If this
177    /// feature is negotiated, the notifications include a custom virtqueue ID
178    /// provided by the device.
179    ///
180    /// This driver does not attempt to negotiate this feature. The feature is
181    /// not implemented in any of the virtio implementations targeted by this
182    /// driver.
183    // @cite(virtio): sec="2.9" title="Driver Notifications"
184    // @cite(virtio): sec="4.1.5.2" title="Available Buffer Notifications"
185    // @cite(virtio): sec="6" title="Reserved Feature Bits" bits=39
186    // @alias(virtio): theirs="VIRTIO_F_NOTIF_CONFIG_DATA"
187    pub bool, uses_custom_virtqueue_ids, set_uses_custom_virtqueue_ids: 39;
188
189    /// Enables virtqueue-level reset.
190    ///
191    /// If this feature is not negotiated, the driver only has a device-level
192    /// reset mechanism.
193    // @cite(virtio): sec="6" title="Reserved Feature Bits" bits=40
194    // @alias(virtio): theirs="VIRTIO_F_RING_RESET"
195    pub bool, supports_queue_reset, set_supports_queue_reset: 40;
196
197    /// Enables driver usage of the device's administration virtqueues.
198    ///
199    /// If this feature is negotiated, the driver must configure the device's
200    /// administration virtqueues during device initialization.
201    ///
202    /// This driver does not support administration virtqueues.
203    // @cite(virtio): sec="2.13" title="Administration Virtqueues"
204    // @cite(virtio): sec="6" title="Reserved Feature Bits" bits=41
205    // @alias(virtio): theirs="VIRTIO_F_ADMIN_VQ"
206    pub bool, uses_admin_virtqueues, set_uses_admin_virtqueues: 41;
207
208    /// Enables the device's suspend functionality.
209    ///
210    /// If this feature is enabled [`DeviceStatus::suspended`] may be set.
211    // @cite(virtio): sec="6" title="Reserved Feature Bits" bits=43
212    // @alias(virtio): theirs="VIRTIO_F_SUSPEND"
213    pub bool, suspend_enabled, set_suspend_enabled: 43;
214}
virtio_driver/common/feature_bits.rs

virtio_driver/common/
feature_bits.rs
