Add some crate-level documentation and an example.

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)]