virtio_spec/
pci.rs

1//! Definitions for Virtio over PCI bus.
2
3use core::mem;
4
5use num_enum::{FromPrimitive, IntoPrimitive};
6use pci_types::capability::PciCapabilityAddress;
7use pci_types::ConfigRegionAccess;
8use volatile::access::{ReadOnly, ReadWrite, Readable, RestrictAccess};
9use volatile::VolatilePtr;
10use volatile_macro::VolatileFieldAccess;
11
12pub use crate::driver_notifications::NotificationData;
13use crate::volatile::WideVolatilePtr;
14use crate::{le16, le32, le64, DeviceConfigSpace, DeviceStatus, Le};
15
16/// PCI Capability
17///
18/// See [`CapData`] for reading additional fields.
19#[doc(alias = "virtio_pci_cap")]
20#[cfg_attr(
21    feature = "zerocopy",
22    derive(
23        zerocopy_derive::KnownLayout,
24        zerocopy_derive::Immutable,
25        zerocopy_derive::FromBytes,
26    )
27)]
28#[derive(Clone, Copy, Debug)]
29#[repr(C)]
30pub struct Cap {
31    /// Generic PCI field: `PCI_CAP_ID_VNDR`
32    ///
33    /// 0x09; Identifies a vendor-specific capability.
34    pub cap_vndr: u8,
35
36    /// Generic PCI field: next ptr.
37    ///
38    /// Link to next capability in the capability list in the PCI configuration space.
39    pub cap_next: u8,
40
41    /// Generic PCI field: capability length
42    ///
43    /// Length of this capability structure, including the whole of
44    /// struct virtio_pci_cap, and extra data if any.
45    /// This length MAY include padding, or fields unused by the driver.
46    pub cap_len: u8,
47
48    /// Identifies the structure.
49    ///
50    /// Each structure is detailed individually below.
51    ///
52    /// The device MAY offer more than one structure of any type - this makes it
53    /// possible for the device to expose multiple interfaces to drivers.  The order of
54    /// the capabilities in the capability list specifies the order of preference
55    /// suggested by the device.  A device may specify that this ordering mechanism be
56    /// overridden by the use of the `id` field.
57    ///
58    /// <div class="warning">
59    ///
60    /// For example, on some hypervisors, notifications using IO accesses are
61    /// faster than memory accesses. In this case, the device would expose two
62    /// capabilities with `cfg_type` set to VIRTIO_PCI_CAP_NOTIFY_CFG:
63    /// the first one addressing an I/O BAR, the second one addressing a memory BAR.
64    /// In this example, the driver would use the I/O BAR if I/O resources are available, and fall back on
65    /// memory BAR when I/O resources are unavailable.
66    ///
67    /// </div>
68    pub cfg_type: u8,
69
70    /// Where to find it.
71    ///
72    /// values 0x0 to 0x5 specify a Base Address register (BAR) belonging to
73    /// the function located beginning at 10h in PCI Configuration Space
74    /// and used to map the structure into Memory or I/O Space.
75    /// The BAR is permitted to be either 32-bit or 64-bit, it can map Memory Space
76    /// or I/O Space.
77    ///
78    /// Any other value is reserved for future use.
79    pub bar: u8,
80
81    /// Multiple capabilities of the same type
82    ///
83    /// Used by some device types to uniquely identify multiple capabilities
84    /// of a certain type. If the device type does not specify the meaning of
85    /// this field, its contents are undefined.
86    pub id: u8,
87
88    /// Pad to full dword.
89    pub padding: [u8; 2],
90
91    /// Offset within bar.
92    ///
93    /// indicates where the structure begins relative to the base address associated
94    /// with the BAR.  The alignment requirements of `offset` are indicated
95    /// in each structure-specific section below.
96    pub offset: le32,
97
98    /// Length of the structure, in bytes.
99    ///
100    /// indicates the length of the structure.
101    ///
102    /// `length` MAY include padding, or fields unused by the driver, or
103    /// future extensions.
104    ///
105    /// <div class="warning">
106    ///
107    /// For example, a future device might present a large structure size of several
108    /// MBytes.
109    /// As current devices never utilize structures larger than 4KBytes in size,
110    /// driver MAY limit the mapped structure size to e.g.
111    /// 4KBytes (thus ignoring parts of structure after the first
112    /// 4KBytes) to allow forward compatibility with such devices without loss of
113    /// functionality and without wasting resources.
114    ///
115    /// </div>
116    pub length: le32,
117}
118
119impl Cap {
120    pub fn read(addr: PciCapabilityAddress, access: impl ConfigRegionAccess) -> Option<Self> {
121        let data = unsafe { access.read(addr.address, addr.offset) };
122        let [cap_vndr, _cap_next, cap_len, _cfg_type] = data.to_ne_bytes();
123
124        if cap_vndr != 0x09 {
125            return None;
126        }
127
128        if cap_len < 16 {
129            return None;
130        }
131
132        let data = [
133            data,
134            unsafe { access.read(addr.address, addr.offset + 4) },
135            unsafe { access.read(addr.address, addr.offset + 8) },
136            unsafe { access.read(addr.address, addr.offset + 12) },
137        ];
138
139        let this = unsafe { mem::transmute::<[u32; 4], Self>(data) };
140
141        Some(this)
142    }
143}
144
145/// PCI Capability 64
146#[doc(alias = "virtio_pci_cap64")]
147#[cfg_attr(
148    feature = "zerocopy",
149    derive(
150        zerocopy_derive::KnownLayout,
151        zerocopy_derive::Immutable,
152        zerocopy_derive::FromBytes,
153    )
154)]
155#[derive(Clone, Copy, Debug)]
156#[repr(C)]
157pub struct Cap64 {
158    pub cap: Cap,
159    pub offset_hi: le32,
160    pub length_hi: le32,
161}
162
163/// PCI Notify Capability
164#[doc(alias = "virtio_pci_notify_cap")]
165#[cfg_attr(
166    feature = "zerocopy",
167    derive(
168        zerocopy_derive::KnownLayout,
169        zerocopy_derive::Immutable,
170        zerocopy_derive::FromBytes,
171    )
172)]
173#[derive(Clone, Copy, Debug)]
174#[repr(C)]
175pub struct NotifyCap {
176    pub cap: Cap,
177
178    /// Multiplier for queue_notify_off.
179    pub notify_off_multiplier: le32,
180}
181
182/// PCI Configuration Capability
183#[doc(alias = "virtio_pci_cfg_cap")]
184#[cfg_attr(
185    feature = "zerocopy",
186    derive(
187        zerocopy_derive::KnownLayout,
188        zerocopy_derive::Immutable,
189        zerocopy_derive::FromBytes,
190    )
191)]
192#[derive(Clone, Copy, Debug)]
193#[repr(C)]
194pub struct CfgCap {
195    pub cap: Cap,
196
197    /// Data for BAR access.
198    pub pci_cfg_data: [u8; 4],
199}
200
201/// PCI Capability Data
202#[derive(Clone, Copy, Debug)]
203pub struct CapData {
204    /// Identifies the structure.
205    pub cfg_type: CapCfgType,
206
207    /// Where to find it.
208    pub bar: u8,
209
210    /// Multiple capabilities of the same type
211    pub id: u8,
212
213    /// Offset within bar.
214    pub offset: le64,
215
216    /// Length of the structure, in bytes.
217    pub length: le64,
218
219    /// Multiplier for queue_notify_off.
220    pub notify_off_multiplier: Option<le32>,
221}
222
223impl CapData {
224    pub fn read(addr: PciCapabilityAddress, access: impl ConfigRegionAccess) -> Option<Self> {
225        let cap = Cap::read(addr, &access)?;
226        let cfg_type = CapCfgType::from(cap.cfg_type);
227
228        let (offset, length) = match cfg_type {
229            CapCfgType::SharedMemory => {
230                if cap.cap_len < 24 {
231                    return None;
232                }
233
234                let offset_hi = unsafe { access.read(addr.address, addr.offset + 16) };
235                let offset_hi = Le(offset_hi);
236                let offset = le64::from([cap.offset, offset_hi]);
237
238                let length_hi = unsafe { access.read(addr.address, addr.offset + 20) };
239                let length_hi = Le(length_hi);
240                let length = le64::from([cap.length, length_hi]);
241
242                (offset, length)
243            }
244            _ => (le64::from(cap.offset), le64::from(cap.length)),
245        };
246
247        let notify_off_multiplier = match cfg_type {
248            CapCfgType::Notify => {
249                if cap.cap_len < 20 {
250                    return None;
251                }
252
253                let notify_off_multiplier = unsafe { access.read(addr.address, addr.offset + 16) };
254                let notify_off_multiplier = Le(notify_off_multiplier);
255
256                Some(notify_off_multiplier)
257            }
258            _ => None,
259        };
260
261        Some(Self {
262            cfg_type,
263            bar: cap.bar,
264            id: cap.id,
265            offset,
266            length,
267            notify_off_multiplier,
268        })
269    }
270}
271
272/// PCI Capability Configuration Type
273#[doc(alias = "VIRTIO_PCI_CAP")]
274#[derive(IntoPrimitive, FromPrimitive, PartialEq, Eq, Clone, Copy, Debug)]
275#[non_exhaustive]
276#[repr(u8)]
277pub enum CapCfgType {
278    /// Common configuration
279    #[doc(alias = "VIRTIO_PCI_CAP_COMMON_CFG")]
280    Common = 1,
281
282    /// Notifications
283    #[doc(alias = "VIRTIO_PCI_CAP_NOTIFY_CFG")]
284    Notify = 2,
285
286    /// ISR Status
287    #[doc(alias = "VIRTIO_PCI_CAP_ISR_CFG")]
288    Isr = 3,
289
290    /// Device specific configuration
291    #[doc(alias = "VIRTIO_PCI_CAP_DEVICE_CFG")]
292    Device = 4,
293
294    /// PCI configuration access
295    #[doc(alias = "VIRTIO_PCI_CAP_PCI_CFG")]
296    Pci = 5,
297
298    /// Shared memory region
299    #[doc(alias = "VIRTIO_PCI_CAP_SHARED_MEMORY_CFG")]
300    SharedMemory = 8,
301
302    /// Vendor-specific data
303    #[doc(alias = "VIRTIO_PCI_CAP_VENDOR_CFG")]
304    Vendor = 9,
305
306    /// Unknown device
307    #[num_enum(catch_all)]
308    Unknown(u8),
309}
310
311/// Common configuration structure
312///
313/// The common configuration structure is found at the bar and offset within the [`VIRTIO_PCI_CAP_COMMON_CFG`] capability.
314///
315/// [`VIRTIO_PCI_CAP_COMMON_CFG`]: CapCfgType::Common
316///
317/// Use [`CommonCfgVolatileFieldAccess`] and [`CommonCfgVolatileWideFieldAccess`] to work with this struct.
318#[doc(alias = "virtio_pci_common_cfg")]
319#[cfg_attr(
320    feature = "zerocopy",
321    derive(
322        zerocopy_derive::KnownLayout,
323        zerocopy_derive::Immutable,
324        zerocopy_derive::FromBytes,
325    )
326)]
327#[derive(VolatileFieldAccess)]
328#[repr(C)]
329pub struct CommonCfg {
330    /// The driver uses this to select which feature bits `device_feature` shows.
331    /// Value 0x0 selects Feature Bits 0 to 31, 0x1 selects Feature Bits 32 to 63, etc.
332    device_feature_select: le32,
333
334    /// The device uses this to report which feature bits it is
335    /// offering to the driver: the driver writes to
336    /// `device_feature_select` to select which feature bits are presented.
337    #[access(ReadOnly)]
338    device_feature: le32,
339
340    /// The driver uses this to select which feature bits `driver_feature` shows.
341    /// Value 0x0 selects Feature Bits 0 to 31, 0x1 selects Feature Bits 32 to 63, etc.
342    driver_feature_select: le32,
343
344    /// The driver writes this to accept feature bits offered by the device.
345    /// Driver Feature Bits selected by `driver_feature_select`.
346    driver_feature: le32,
347
348    /// The driver sets the Configuration Vector for MSI-X.
349    config_msix_vector: le16,
350
351    /// The device specifies the maximum number of virtqueues supported here.
352    #[access(ReadOnly)]
353    num_queues: le16,
354
355    /// The driver writes the device status here (see [`DeviceStatus`]). Writing 0 into this
356    /// field resets the device.
357    device_status: DeviceStatus,
358
359    /// Configuration atomicity value.  The device changes this every time the
360    /// configuration noticeably changes.
361    #[access(ReadOnly)]
362    config_generation: u8,
363
364    /// Queue Select. The driver selects which virtqueue the following
365    /// fields refer to.
366    queue_select: le16,
367
368    /// Queue Size.  On reset, specifies the maximum queue size supported by
369    /// the device. This can be modified by the driver to reduce memory requirements.
370    /// A 0 means the queue is unavailable.
371    queue_size: le16,
372
373    /// The driver uses this to specify the queue vector for MSI-X.
374    queue_msix_vector: le16,
375
376    /// The driver uses this to selectively prevent the device from executing requests from this virtqueue.
377    /// 1 - enabled; 0 - disabled.
378    queue_enable: le16,
379
380    /// The driver reads this to calculate the offset from start of Notification structure at
381    /// which this virtqueue is located.
382    ///
383    /// <div class="warning">
384    ///
385    /// This is _not_ an offset in bytes.
386    /// See _Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability_ below.
387    ///
388    /// </div>
389    #[access(ReadOnly)]
390    queue_notify_off: le16,
391
392    /// The driver writes the physical address of Descriptor Area here.  See section _Basic Facilities of a Virtio Device / Virtqueues_.
393    queue_desc_low: le32,
394
395    /// The driver writes the physical address of Descriptor Area here.  See section _Basic Facilities of a Virtio Device / Virtqueues_.
396    queue_desc_high: le32,
397
398    /// The driver writes the physical address of Driver Area here.  See section _Basic Facilities of a Virtio Device / Virtqueues_.
399    queue_driver_low: le32,
400
401    /// The driver writes the physical address of Driver Area here.  See section _Basic Facilities of a Virtio Device / Virtqueues_.
402    queue_driver_high: le32,
403
404    /// The driver writes the physical address of Device Area here.  See section _Basic Facilities of a Virtio Device / Virtqueues_.
405    queue_device_low: le32,
406
407    /// The driver writes the physical address of Device Area here.  See section _Basic Facilities of a Virtio Device / Virtqueues_.
408    queue_device_high: le32,
409
410    /// This field exists only if [`VIRTIO_F_NOTIF_CONFIG_DATA`] has been negotiated.
411    /// The driver will use this value to put it in the 'virtqueue number' field
412    /// in the available buffer notification structure.
413    /// See section _Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Available Buffer Notifications_.
414    ///
415    /// <div class="warning">
416    ///
417    /// This field provides the device with flexibility to determine how virtqueues
418    /// will be referred to in available buffer notifications.
419    /// In a trivial case the device can set `queue_notify_data`=vqn. Some devices
420    /// may benefit from providing another value, for example an internal virtqueue
421    /// identifier, or an internal offset related to the virtqueue number.
422    ///
423    /// </div>
424    ///
425    /// [`VIRTIO_F_NOTIF_CONFIG_DATA`]: crate::F::NOTIF_CONFIG_DATA
426    #[access(ReadOnly)]
427    queue_notify_data: le16,
428
429    /// The driver uses this to selectively reset the queue.
430    /// This field exists only if [`VIRTIO_F_RING_RESET`] has been
431    /// negotiated. (see _Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset_).
432    ///
433    /// [`VIRTIO_F_RING_RESET`]: crate::F::RING_RESET
434    queue_reset: le16,
435}
436
437impl_wide_field_access! {
438    /// Common configuration structure
439    pub trait CommonCfgVolatileWideFieldAccess<'a, A>: CommonCfg {
440        /// The driver writes the physical address of Device Area here.  See section _Basic Facilities of a Virtio Device / Virtqueues_.
441        #[access(ReadWrite)]
442        queue_desc: queue_desc_low, queue_desc_high;
443
444        /// The driver writes the physical address of Device Area here.  See section _Basic Facilities of a Virtio Device / Virtqueues_.
445        #[access(ReadWrite)]
446        queue_driver: queue_driver_low, queue_driver_high;
447
448        /// The driver writes the physical address of Device Area here.  See section _Basic Facilities of a Virtio Device / Virtqueues_.
449        #[access(ReadWrite)]
450        queue_device: queue_device_low, queue_device_high;
451    }
452}
453
454impl<'a, A> DeviceConfigSpace for VolatilePtr<'a, CommonCfg, A>
455where
456    A: RestrictAccess<ReadOnly>,
457    A::Restricted: Readable,
458{
459    fn read_config_with<F, T>(self, f: F) -> T
460    where
461        F: FnMut() -> T,
462    {
463        let mut f = f;
464        loop {
465            let before = self.config_generation().read();
466            let read = f();
467            let after = self.config_generation().read();
468            if after == before {
469                break read;
470            }
471        }
472    }
473}
474
475virtio_bitflags! {
476    /// ISR Status
477    pub struct IsrStatus: u8 {
478        /// Queue Interrupt
479        const QUEUE_INTERRUPT = 1 << 0;
480
481        /// Device Configuration Interrupt
482        const DEVICE_CONFIGURATION_INTERRUPT = 1 << 1;
483    }
484}