uefi: Add safe protocol wrapper for EFI_EXT_SCSI_PASS_THRU_PROTOCOL

uefi-raw/src/protocol/scsi.rs

@@ -128,7 +128,7 @@ pub struct ExtScsiPassThruMode {
 pub struct ExtScsiPassThruProtocol {
     pub passthru_mode: *const ExtScsiPassThruMode,
     pub pass_thru: unsafe extern "efiapi" fn(
-        this: *const Self,
+        this: *mut Self,
         target: *const u8,
         lun: u64,
         packet: *mut ScsiIoScsiRequestPacket,

uefi-test-runner/src/proto/mod.rs

@@ -25,6 +25,7 @@ pub fn test() {
     shell_params::test();
     string::test();
     misc::test();
+    scsi::test();
 
     #[cfg(any(
         target_arch = "x86",
@@ -73,6 +74,7 @@ mod misc;
 mod network;
 mod pi;
 mod rng;
+mod scsi;
 mod shell_params;
 #[cfg(any(
     target_arch = "x86",

uefi-test-runner/src/proto/scsi/mod.rs

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+mod pass_thru;
+
+pub fn test() {
+    pass_thru::test();
+}

uefi-test-runner/src/proto/scsi/pass_thru.rs

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+use uefi::proto::scsi::pass_thru::ExtScsiPassThru;
+use uefi::proto::scsi::ScsiRequestBuilder;
+
+pub fn test() {
+    info!("Running extended SCSI Pass Thru tests");
+    test_allocating_api();
+    test_reusing_buffer_api();
+}
+
+fn test_allocating_api() {
+    let scsi_ctrl_handles = uefi::boot::find_handles::<ExtScsiPassThru>().unwrap();
+
+    // On I440FX and Q35 (both x86 machines), Qemu configures an IDE and a SATA controller
+    // by default respectively. We manually configure an additional SCSI controller.
+    // Thus, we should see two controllers with support for EXT_SCSI_PASS_THRU on this platform
+    #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
+    assert_eq!(scsi_ctrl_handles.len(), 2);
+    #[cfg(any(target_arch = "arm", target_arch = "aarch64"))]
+    assert_eq!(scsi_ctrl_handles.len(), 1);
+
+    let mut found_drive = false;
+    for handle in scsi_ctrl_handles {
+        let scsi_pt = uefi::boot::open_protocol_exclusive::<ExtScsiPassThru>(handle).unwrap();
+        for mut device in scsi_pt.iter_devices() {
+            // see: https://www.seagate.com/files/staticfiles/support/docs/manual/Interface%20manuals/100293068j.pdf
+            // 3.6 INQUIRY command
+            let request = ScsiRequestBuilder::read(scsi_pt.io_align())
+                .with_timeout(core::time::Duration::from_millis(500))
+                .with_command_data(&[0x12, 0x00, 0x00, 0x00, 0xFF, 0x00])
+                .unwrap()
+                .with_read_buffer(255)
+                .unwrap()
+                .build();
+            let Ok(response) = device.execute_command(request) else {
+                continue; // no device
+            };
+            let bfr = response.read_buffer().unwrap();
+            // more no device checks
+            if bfr.len() < 32 {
+                continue;
+            }
+            if bfr[0] & 0b00011111 == 0x1F {
+                continue;
+            }
+
+            // found device
+            let vendor_id = core::str::from_utf8(&bfr[8..16]).unwrap().trim();
+            let product_id = core::str::from_utf8(&bfr[16..32]).unwrap().trim();
+            if vendor_id == "uefi-rs" && product_id == "ExtScsiPassThru" {
+                info!(
+                    "Found Testdisk at: {:?} | {}",
+                    device.target(),
+                    device.lun()
+                );
+                found_drive = true;
+            }
+        }
+    }
+
+    assert!(found_drive);
+}
+
+fn test_reusing_buffer_api() {
+    let scsi_ctrl_handles = uefi::boot::find_handles::<ExtScsiPassThru>().unwrap();
+
+    let mut found_drive = false;
+    for handle in scsi_ctrl_handles {
+        let scsi_pt = uefi::boot::open_protocol_exclusive::<ExtScsiPassThru>(handle).unwrap();
+        let mut cmd_bfr = scsi_pt.alloc_io_buffer(6).unwrap();
+        cmd_bfr.copy_from(&[0x12, 0x00, 0x00, 0x00, 0xFF, 0x00]);
+        let mut read_bfr = scsi_pt.alloc_io_buffer(255).unwrap();
+
+        for mut device in scsi_pt.iter_devices() {
+            // see: https://www.seagate.com/files/staticfiles/support/docs/manual/Interface%20manuals/100293068j.pdf
+            // 3.6 INQUIRY command
+            let request = ScsiRequestBuilder::read(scsi_pt.io_align())
+                .with_timeout(core::time::Duration::from_millis(500))
+                .use_command_buffer(&mut cmd_bfr)
+                .unwrap()
+                .use_read_buffer(&mut read_bfr)
+                .unwrap()
+                .build();
+            let Ok(response) = device.execute_command(request) else {
+                continue; // no device
+            };
+            let bfr = response.read_buffer().unwrap();
+            // more no device checks
+            if bfr.len() < 32 {
+                continue;
+            }
+            if bfr[0] & 0b00011111 == 0x1F {
+                continue;
+            }
+
+            // found device
+            let vendor_id = core::str::from_utf8(&bfr[8..16]).unwrap().trim();
+            let product_id = core::str::from_utf8(&bfr[16..32]).unwrap().trim();
+            if vendor_id == "uefi-rs" && product_id == "ExtScsiPassThru" {
+                info!(
+                    "Found Testdisk at: {:?} | {}",
+                    device.target(),
+                    device.lun()
+                );
+                found_drive = true;
+            }
+        }
+    }
+
+    assert!(found_drive);
+}

uefi/CHANGELOG.md

@@ -5,6 +5,7 @@
 - Added conversions between `proto::network::IpAddress` and `core::net` types.
 - Added conversions between `proto::network::MacAddress` and the `[u8; 6]` type that's more commonly used to represent MAC addresses.
 - Added `proto::media::disk_info::DiskInfo`.
+- Added `proto::scsi::pass_thru::ExtScsiPassThru`.
 
 ## Changed
 - **Breaking:** Removed `BootPolicyError` as `BootPolicy` construction is no

uefi/src/helpers/aligned_buffer.rs

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+use alloc::alloc::{alloc, dealloc, Layout, LayoutError};
+use core::error::Error;
+use core::fmt;
+
+/// Helper class to maintain the lifetime of a memory region allocated with a non-standard alignment.
+/// Facilitates RAII to properly deallocate when lifetime of the object ends.
+///
+/// Note: This uses the global Rust allocator under the hood.
+#[allow(clippy::len_without_is_empty)]
+#[derive(Debug)]
+pub struct AlignedBuffer {
+    ptr: *mut u8,
+    layout: Layout,
+}
+
+impl AlignedBuffer {
+    /// Allocate a new memory region with the requested len and alignment.
+    pub fn alloc(len: usize, alignment: usize) -> Result<Self, LayoutError> {
+        let layout = Layout::from_size_align(len, alignment)?;
+        let ptr = unsafe { alloc(layout) };
+        Ok(Self { ptr, layout })
+    }
+
+    /// Get a pointer to the aligned memory region managed by this instance.
+    #[must_use]
+    pub const fn ptr(&self) -> *const u8 {
+        self.ptr.cast_const()
+    }
+
+    /// Get a mutable pointer to the aligned memory region managed by this instance.
+    #[must_use]
+    pub fn ptr_mut(&mut self) -> *mut u8 {
+        self.ptr
+    }
+
+    /// Get the size of the aligned memory region managed by this instance.
+    #[must_use]
+    pub const fn len(&self) -> usize {
+        self.layout.size()
+    }
+
+    /// Fill the aligned memory region with data from the given buffer.
+    pub fn copy_from(&mut self, data: &[u8]) {
+        let len = data.len().min(self.len());
+        unsafe {
+            self.ptr.copy_from(data.as_ptr(), len);
+        }
+    }
+
+    /// Check the buffer's alignment against the `required_alignment`.
+    pub fn check_alignment(&self, required_alignment: usize) -> Result<(), AlignmentError> {
+        //TODO: use bfr.addr() when it's available
+        if (self.ptr as usize) % required_alignment != 0 {
+            return Err(AlignmentError); //TODO: use >is_aligned_to< when it's available
+        }
+        Ok(())
+    }
+}
+
+impl Drop for AlignedBuffer {
+    fn drop(&mut self) {
+        unsafe {
+            dealloc(self.ptr, self.layout);
+        }
+    }
+}
+
+/// The `AlignmentError` is returned if a user-provided buffer doesn't fulfill alignment requirements.
+#[derive(Clone, PartialEq, Eq, Debug)]
+pub struct AlignmentError;
+impl Error for AlignmentError {}
+impl fmt::Display for AlignmentError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str("invalid parameters to Layout::from_size_align")
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::AlignedBuffer;
+
+    #[test]
+    fn test_invalid_arguments() {
+        // invalid alignments, valid len
+        for request_alignment in [0, 3, 5, 7, 9] {
+            for request_len in [1, 32, 64, 128, 1024] {
+                assert!(AlignedBuffer::alloc(request_len, request_alignment).is_err());
+            }
+        }
+    }
+
+    #[test]
+    fn test_allocation_alignment() {
+        for request_alignment in [1, 2, 4, 8, 16, 32, 64, 128] {
+            for request_len in [1 as usize, 32, 64, 128, 1024] {
+                let buffer = AlignedBuffer::alloc(request_len, request_alignment).unwrap();
+                assert_eq!(buffer.ptr() as usize % request_alignment, 0);
+                assert_eq!(buffer.len(), request_len);
+            }
+        }
+    }
+}

uefi/src/helpers/mod.rs

@@ -24,6 +24,11 @@ use crate::Result;
 #[doc(hidden)]
 pub use println::_print;
 
+#[cfg(feature = "alloc")]
+mod aligned_buffer;
+#[cfg(feature = "alloc")]
+pub use aligned_buffer::{AlignedBuffer, AlignmentError};
+
 #[cfg(feature = "global_allocator")]
 mod global_allocator;
 #[cfg(feature = "logger")]

uefi/src/proto/mod.rs

@@ -20,6 +20,8 @@ pub mod misc;
 pub mod network;
 pub mod pi;
 pub mod rng;
+#[cfg(feature = "alloc")]
+pub mod scsi;
 pub mod security;
 pub mod shell_params;
 pub mod shim;