Document driver modes. (#3217)

* WIP

* Explain Async a bit better

* Update esp-hal/src/lib.rs

Co-authored-by: Scott Mabin <[email protected]>

* Improve consistency

* Disallow constructing driver modes

---------

Co-authored-by: Scott Mabin <[email protected]>

Author: bugadani

esp-hal/src/lib.rs

@@ -312,15 +312,51 @@ WARNING: use --release
   peripherals and/or devices.
 "}
 
-/// A marker trait for initializing drivers in a specific mode.
+/// A marker trait for driver modes.
+///
+/// Different driver modes offer different features and different API. Using
+/// this trait as a generic parameter ensures that the driver is initialized in
+/// the correct mode.
 pub trait DriverMode: crate::private::Sealed {}
 
-/// Driver initialized in blocking mode.
+/// Marker type signalling that a driver is initialized in blocking mode.
+///
+/// Drivers are constructed in blocking mode by default. To learn about the
+/// differences between blocking and async drivers, see the [`Async`] mode
+/// documentation.
 #[derive(Debug)]
+#[non_exhaustive]
 pub struct Blocking;
 
-/// Driver initialized in async mode.
+/// Marker type signalling that a driver is initialized in async mode.
+///
+/// Drivers are constructed in blocking mode by default. To set up an async
+/// driver, a [`Blocking`] driver must be converted to an `Async` driver using
+/// the `into_async` method. Drivers can be converted back to blocking mode
+/// using the `into_blocking` method.
+///
+/// Async mode drivers offer most of the same features as blocking drivers, but
+/// with the addition of async APIs. Interrupt-related functions are not
+/// available in async mode, as they are handled by the driver's interrupt
+/// handlers.
+///
+/// Note that async functions usually take up more space than their blocking
+/// counterparts, and they are generally slower. This is because async functions
+/// are implemented using a state machine that is driven by interrupts and is
+/// polled by a runtime. For short operations, the overhead of the state machine
+/// can be significant. Consider using the blocking functions on the async
+/// driver for small transfers.
+///
+/// When initializing an async driver, the driver disables user-specified
+/// interrupt handlers, and sets up internal interrupt handlers that drive the
+/// driver's async API. The driver's interrupt handlers run on the same core as
+/// the driver was initialized on. This means that the driver can not be sent
+/// across threads, to prevent incorrect concurrent access to the peripheral.
+///
+/// Switching back to blocking mode will disable the interrupt handlers and
+/// return the driver to a state where it can be sent across threads.
 #[derive(Debug)]
+#[non_exhaustive]
 pub struct Async(PhantomData<*const ()>);
 
 unsafe impl Sync for Async {}