AtaPassThru: Add read_pio method for AtaRequestBuilder

uefi/CHANGELOG.md

@@ -1,6 +1,7 @@
 # uefi - [Unreleased]
 
 ## Added
+- Added `proto::ata::AtaRequestBuilder::read_pio()`.
 
 ## Changed
 

uefi/src/proto/ata/mod.rs

@@ -16,7 +16,12 @@ pub mod pass_thru;
 
 /// Represents the protocol for ATA Pass Thru command handling.
 ///
-/// This type defines the protocols supported for passing commands through the ATA controller.
+/// This type defines the protocols supported for passing ATA commands through to an
+/// ATA compliant controller. Over time, multiple possible transports for ATA commands
+/// have evolved. The UEFI spec generically abstracts all of these transports below
+/// this one protocol, so old PATA drives and controllers, as well as modern AHCI-only
+/// SATA controllers are supported with the same set of APIs.
+/// see: <https://uefi.org/specs/PI/1.8/V5_IDE_Controller.html>
 pub use uefi_raw::protocol::ata::AtaPassThruCommandProtocol;
 
 /// Represents an ATA request built for execution on an ATA controller.
@@ -87,6 +92,35 @@ impl<'a> AtaRequestBuilder<'a> {
         })
     }
 
+    // # PIO
+    // ########################################################################
+
+    /// Creates a builder for a PIO write operation.
+    ///
+    /// Since the ATA specification mandates the support for PIO mode for all
+    /// compliant drives and controllers, this is the protocol variant with the
+    /// highest compatibility in the field.
+    /// So probing, (sending ATA IDENTIFY commands to device ports to find out
+    /// whether there is actually a device connected to it) should probably be
+    /// done using this method most of the time.
+    /// If this errors with Status "UNSUPPORTED", try UDMA next.
+    ///
+    /// # Arguments
+    /// - `io_align`: The I/O buffer alignment required for the ATA controller.
+    /// - `command`: The ATA command byte specifying the write operation.
+    ///
+    /// # Returns
+    /// `Result<Self, LayoutError>` indicating success or memory allocation failure.
+    ///
+    /// # Errors
+    /// This method can fail due to alignment or memory allocation issues.
+    pub fn read_pio(io_align: u32, command: u8) -> Result<Self, LayoutError> {
+        Self::new(io_align, command, AtaPassThruCommandProtocol::PIO_DATA_IN)
+    }
+
+    // # UDMA
+    // ########################################################################
+
     /// Creates a builder for a UDMA read operation.
     ///
     /// # Arguments