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}