Merge pull request #42 from rcore-os/modules

Make modules public rather than re-exporting all their contents

examples/aarch64/src/main.rs

@@ -16,12 +16,15 @@ use hal::HalImpl;
 use log::{debug, error, info, trace, warn, LevelFilter};
 use psci::system_off;
 use virtio_drivers::{
-    pci::{
-        bus::{BarInfo, Cam, Command, DeviceFunction, MemoryBarType, PciRoot},
-        virtio_device_type, PciTransport,
+    device::{blk::VirtIOBlk, console::VirtIOConsole, gpu::VirtIOGpu, net::VirtIONet},
+    transport::{
+        mmio::{MmioTransport, VirtIOHeader},
+        pci::{
+            bus::{BarInfo, Cam, Command, DeviceFunction, MemoryBarType, PciRoot},
+            virtio_device_type, PciTransport,
+        },
+        DeviceType, Transport,
     },
-    DeviceType, MmioTransport, Transport, VirtIOBlk, VirtIOConsole, VirtIOGpu, VirtIOHeader,
-    VirtIONet,
 };
 
 #[no_mangle]

examples/riscv/src/main.rs

@@ -9,7 +9,13 @@ use alloc::vec;
 use core::ptr::NonNull;
 use fdt::{node::FdtNode, standard_nodes::Compatible, Fdt};
 use log::{info, warn, LevelFilter};
-use virtio_drivers::*;
+use virtio_drivers::{
+    device::{blk::VirtIOBlk, gpu::VirtIOGpu, input::VirtIOInput, net::VirtIONet},
+    transport::{
+        mmio::{MmioTransport, VirtIOHeader},
+        DeviceType, Transport,
+    },
+};
 use virtio_impl::HalImpl;
 
 mod virtio_impl;

src/blk.rs → src/device/blk.rs

@@ -1,9 +1,12 @@
-use super::*;
+//! Driver for VirtIO block devices.
+
+use crate::hal::Hal;
 use crate::queue::VirtQueue;
 use crate::transport::Transport;
 use crate::volatile::{volread, Volatile};
-use bitflags::*;
-use log::*;
+use crate::{Error, Result};
+use bitflags::bitflags;
+use log::info;
 use zerocopy::{AsBytes, FromBytes};
 
 const QUEUE: u16 = 0;
@@ -18,8 +21,10 @@ const QUEUE: u16 = 0;
 /// # Example
 ///
 /// ```
-/// # use virtio_drivers::{Error, Hal, Transport};
-/// use virtio_drivers::{VirtIOBlk, SECTOR_SIZE};
+/// # use virtio_drivers::{Error, Hal};
+/// # use virtio_drivers::transport::Transport;
+/// use virtio_drivers::device::blk::{VirtIOBlk, SECTOR_SIZE};
+///
 /// # fn example<HalImpl: Hal, T: Transport>(transport: T) -> Result<(), Error> {
 /// let mut disk = VirtIOBlk::<HalImpl, _>::new(transport)?;
 ///
@@ -136,7 +141,11 @@ impl<H: Hal, T: Transport> VirtIOBlk<H, T> {
     /// request. Once it has, the caller can then read the response and dispose of the buffers.
     ///
     /// ```
-    /// # use virtio_drivers::{BlkReq, BlkResp, Error, Hal, RespStatus, Transport, VirtIOBlk};
+    /// # use virtio_drivers::{Error, Hal};
+    /// # use virtio_drivers::device::blk::VirtIOBlk;
+    /// # use virtio_drivers::transport::Transport;
+    /// use virtio_drivers::device::blk::{BlkReq, BlkResp, RespStatus};
+    ///
     /// # fn example<H: Hal, T: Transport>(blk: &mut VirtIOBlk<H, T>) -> Result<(), Error> {
     /// let mut request = BlkReq::default();
     /// let mut buffer = [0; 512];
@@ -250,8 +259,9 @@ impl<H: Hal, T: Transport> VirtIOBlk<H, T> {
         self.queue.pop_used().map(|p| p.0)
     }
 
-    /// Return size of its VirtQueue.
-    /// It can be used to tell the caller how many channels he should monitor on.
+    /// Returns the size of the device's VirtQueue.
+    ///
+    /// This can be used to tell the caller how many channels to monitor on.
     pub fn virt_queue_size(&self) -> u16 {
         self.queue.size()
     }

src/console.rs → src/device/console.rs

@@ -1,10 +1,13 @@
-use super::*;
+//! Driver for VirtIO console devices.
+
+use crate::hal::{Dma, Hal};
 use crate::queue::VirtQueue;
 use crate::transport::Transport;
 use crate::volatile::{volread, ReadOnly, WriteOnly};
-use bitflags::*;
+use crate::Result;
+use bitflags::bitflags;
 use core::ptr::NonNull;
-use log::*;
+use log::info;
 
 const QUEUE_RECEIVEQ_PORT_0: u16 = 0;
 const QUEUE_TRANSMITQ_PORT_0: u16 = 1;
@@ -18,8 +21,8 @@ const QUEUE_SIZE: u16 = 2;
 /// # Example
 ///
 /// ```
-/// # use virtio_drivers::{Error, Hal, Transport};
-/// use virtio_drivers::VirtIOConsole;
+/// # use virtio_drivers::{Error, Hal, transport::Transport};
+/// use virtio_drivers::device::console::VirtIOConsole;
 /// # fn example<HalImpl: Hal, T: Transport>(transport: T) -> Result<(), Error> {
 /// let mut console = VirtIOConsole::<HalImpl, _>::new(transport)?;
 ///
@@ -51,8 +54,11 @@ pub struct VirtIOConsole<'a, H: Hal, T: Transport> {
 /// Information about a console device, read from its configuration space.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct ConsoleInfo {
+    /// The console height in characters.
     pub rows: u16,
+    /// The console width in characters.
     pub columns: u16,
+    /// The maxumum number of ports supported by the console device.
     pub max_ports: u32,
 }
 
@@ -213,7 +219,10 @@ mod tests {
     use super::*;
     use crate::{
         hal::fake::FakeHal,
-        transport::fake::{FakeTransport, QueueStatus, State},
+        transport::{
+            fake::{FakeTransport, QueueStatus, State},
+            DeviceStatus, DeviceType,
+        },
     };
     use alloc::{sync::Arc, vec};
     use core::ptr::NonNull;

src/gpu.rs → src/device/gpu.rs

@@ -1,9 +1,12 @@
-use super::*;
+//! Driver for VirtIO GPU devices.
+
+use crate::hal::{Dma, Hal};
 use crate::queue::VirtQueue;
 use crate::transport::Transport;
 use crate::volatile::{volread, ReadOnly, Volatile, WriteOnly};
-use bitflags::*;
-use log::*;
+use crate::{pages, Error, Result, PAGE_SIZE};
+use bitflags::bitflags;
+use log::info;
 
 /// A virtio based graphics adapter.
 ///

src/input.rs → src/device/input.rs

@@ -1,10 +1,14 @@
-use super::*;
+//! Driver for VirtIO input devices.
+
+use crate::hal::Hal;
+use crate::queue::VirtQueue;
 use crate::transport::Transport;
 use crate::volatile::{volread, volwrite, ReadOnly, WriteOnly};
+use crate::Result;
 use alloc::boxed::Box;
-use bitflags::*;
+use bitflags::bitflags;
 use core::ptr::NonNull;
-use log::*;
+use log::info;
 use zerocopy::{AsBytes, FromBytes};
 
 /// Virtual human interface devices such as keyboards, mice and tablets.

src/device/mod.rs

@@ -0,0 +1,8 @@
+//! Drivers for specific VirtIO devices.
+
+pub mod blk;
+pub mod console;
+pub mod gpu;
+#[cfg(feature = "alloc")]
+pub mod input;
+pub mod net;

src/net.rs → src/device/net.rs

@@ -1,10 +1,13 @@
-use core::mem::{size_of, MaybeUninit};
+//! Driver for VirtIO network devices.
 
-use super::*;
+use crate::hal::Hal;
+use crate::queue::VirtQueue;
 use crate::transport::Transport;
 use crate::volatile::{volread, ReadOnly};
-use bitflags::*;
-use log::*;
+use crate::Result;
+use bitflags::bitflags;
+use core::mem::{size_of, MaybeUninit};
+use log::{debug, info};
 use zerocopy::{AsBytes, FromBytes};
 
 /// The virtio network device is a virtual ethernet card.

src/hal.rs

@@ -1,7 +1,7 @@
 #[cfg(test)]
 pub mod fake;
 
-use super::*;
+use crate::{Error, Result, PAGE_SIZE};
 use core::marker::PhantomData;
 
 /// A virtual memory address in the address space of the program.

src/lib.rs

@@ -1,4 +1,43 @@
 //! VirtIO guest drivers.
+//!
+//! These drivers can be used by bare-metal code (such as a bootloader or OS kernel) running in a VM
+//! to interact with VirtIO devices provided by the VMM (such as QEMU or crosvm).
+//!
+//! # Usage
+//!
+//! You must first implement the [`Hal`] trait, to allocate DMA regions and translate between
+//! physical addresses (as seen by devices) and virtual addresses (as seen by your program). You can
+//! then construct the appropriate transport for the VirtIO device, e.g. for an MMIO device (perhaps
+//! discovered from the device tree):
+//!
+//! ```
+//! use core::ptr::NonNull;
+//! use virtio_drivers::transport::mmio::{MmioTransport, VirtIOHeader};
+//!
+//! # fn example(mmio_device_address: usize) {
+//! let header = NonNull::new(mmio_device_address as *mut VirtIOHeader).unwrap();
+//! let transport = unsafe { MmioTransport::new(header) }.unwrap();
+//! # }
+//! ```
+//!
+//! You can then check what kind of VirtIO device it is and construct the appropriate driver:
+//!
+//! ```
+//! # use virtio_drivers::Hal;
+//! use virtio_drivers::{
+//!     device::console::VirtIOConsole,
+//!     transport::{mmio::MmioTransport, DeviceType, Transport},
+//! };
+
+//!
+//! # fn example<HalImpl: Hal>(transport: MmioTransport) {
+//! if transport.device_type() == DeviceType::Console {
+//!     let mut console = VirtIOConsole::<HalImpl, _>::new(transport).unwrap();
+//!     // Send a byte to the console.
+//!     console.send(b'H').unwrap();
+//! }
+//! # }
+//! ```
 
 #![cfg_attr(not(test), no_std)]
 #![deny(unused_must_use, missing_docs)]
@@ -8,29 +47,13 @@
 #[cfg(any(feature = "alloc", test))]
 extern crate alloc;
 
-mod blk;
-mod console;
-mod gpu;
+pub mod device;
 mod hal;
-#[cfg(feature = "alloc")]
-mod input;
-mod net;
 mod queue;
-mod transport;
+pub mod transport;
 mod volatile;
 
-pub use self::blk::{BlkReq, BlkResp, RespStatus, VirtIOBlk, SECTOR_SIZE};
-pub use self::console::VirtIOConsole;
-pub use self::gpu::VirtIOGpu;
 pub use self::hal::{Hal, PhysAddr, VirtAddr};
-#[cfg(feature = "alloc")]
-pub use self::input::{InputConfigSelect, InputEvent, VirtIOInput};
-pub use self::net::VirtIONet;
-use self::queue::VirtQueue;
-pub use self::transport::mmio::{MmioError, MmioTransport, MmioVersion, VirtIOHeader};
-pub use self::transport::pci;
-pub use self::transport::{DeviceStatus, DeviceType, Transport};
-use hal::*;
 
 /// The page size in bytes supported by the library (4 KiB).
 pub const PAGE_SIZE: usize = 0x1000;

src/queue.rs

@@ -1,14 +1,16 @@
 #[cfg(test)]
+use crate::hal::VirtAddr;
+use crate::hal::{Dma, Hal};
+use crate::transport::Transport;
+use crate::{align_up, Error, Result, PAGE_SIZE};
+use bitflags::bitflags;
+#[cfg(test)]
 use core::cmp::min;
 use core::hint::spin_loop;
 use core::mem::size_of;
 use core::ptr::{self, addr_of_mut, NonNull};
 use core::sync::atomic::{fence, Ordering};
 
-use super::*;
-use crate::transport::Transport;
-use bitflags::*;
-
 /// The mechanism for bulk data transport on virtio devices.
 ///
 /// Each device can have zero or more virtqueues.
@@ -402,7 +404,10 @@ pub(crate) fn fake_write_to_queue(
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::{hal::fake::FakeHal, transport::mmio::MODERN_VERSION};
+    use crate::{
+        hal::fake::FakeHal,
+        transport::mmio::{MmioTransport, VirtIOHeader, MODERN_VERSION},
+    };
     use core::ptr::NonNull;
 
     #[test]

src/transport/fake.rs

@@ -1,7 +1,7 @@
-use super::{DeviceStatus, Transport};
+use super::{DeviceStatus, DeviceType, Transport};
 use crate::{
     queue::{fake_write_to_queue, Descriptor},
-    DeviceType, PhysAddr, Result,
+    PhysAddr, Result,
 };
 use alloc::{sync::Arc, vec::Vec};
 use core::{any::TypeId, ptr::NonNull};

src/transport/mmio.rs

@@ -1,3 +1,5 @@
+//! MMIO transport for VirtIO.
+
 use super::{DeviceStatus, DeviceType, Transport};
 use crate::{
     align_up,

src/transport/mod.rs

@@ -1,3 +1,5 @@
+//! VirtIO transports.
+
 #[cfg(test)]
 pub mod fake;
 pub mod mmio;