uefi: Add safe protocol bindings for EFI_EXT_SCSI_PASS_THRU_PROTOCOL

Author: seijikun

uefi-raw/src/protocol/scsi.rs

@@ -84,7 +84,7 @@ pub struct ScsiIoScsiRequestPacket {
     ///
     /// A `timeout` value of 0 indicates that the function will wait indefinitely for
     /// the execution to complete. If the execution time exceeds the specified `timeout`
-    /// (greater than 0), the function will return `EFI_TIMEOUT`.
+    /// (greater than 0), the function will return [`Status::TIMEOUT`].
     pub timeout: u64,
 
     /// A pointer to the data buffer for reading from the device in read and bidirectional commands.

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,108 @@
+// 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();
+    assert_eq!(scsi_ctrl_handles.len(), 2);
+
+    let mut found_drive = false;
+
+    for handle in scsi_ctrl_handles {
+        let scsi_pt = uefi::boot::open_protocol_exclusive::<ExtScsiPassThru>(handle).unwrap();
+        for 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();
+    assert_eq!(scsi_ctrl_handles.len(), 2);
+
+    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 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

@@ -4,6 +4,7 @@
 - Added `boot::signal_event`.
 - 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::scsi::pass_thru::ExtScsiPassThru`.
 
 ## Changed
 - **Breaking:** Removed `BootPolicyError` as `BootPolicy` construction is no

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;

uefi/src/proto/scsi/mod.rs

@@ -0,0 +1,362 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! SCSI Bus specific protocols.
+
+use crate::helpers::{AlignedBuffer, AlignmentError};
+use core::alloc::LayoutError;
+use core::ffi::c_void;
+use core::marker::PhantomData;
+use core::ptr;
+use core::time::Duration;
+use uefi_raw::protocol::scsi::{
+    ScsiIoDataDirection, ScsiIoHostAdapterStatus, ScsiIoScsiRequestPacket, ScsiIoTargetStatus,
+};
+
+pub mod pass_thru;
+
+/// Represents the data direction for a SCSI request.
+///
+/// Used to specify whether the request involves reading, writing, or bidirectional data transfer.
+pub type ScsiRequestDirection = uefi_raw::protocol::scsi::ScsiIoDataDirection;
+
+/// Represents a SCSI request packet.
+///
+/// This structure encapsulates the necessary data for sending a command to a SCSI device.
+#[derive(Debug)]
+pub struct ScsiRequest<'a> {
+    packet: ScsiIoScsiRequestPacket,
+    io_align: u32,
+    in_data_buffer: Option<AlignedBuffer>,
+    out_data_buffer: Option<AlignedBuffer>,
+    sense_data_buffer: Option<AlignedBuffer>,
+    cdb_buffer: Option<AlignedBuffer>,
+    _phantom: PhantomData<&'a u8>,
+}
+
+/// A builder for constructing [`ScsiRequest`] instances.
+///
+/// Provides a safe and ergonomic interface for configuring SCSI request packets, including timeout,
+/// data buffers, and command descriptor blocks.
+#[derive(Debug)]
+pub struct ScsiRequestBuilder<'a> {
+    req: ScsiRequest<'a>,
+}
+impl ScsiRequestBuilder<'_> {
+    /// Creates a new instance with the specified data direction and alignment.
+    ///
+    /// # Parameters
+    /// - `direction`: Specifies the direction of data transfer (READ, WRITE, or BIDIRECTIONAL).
+    /// - `io_align`: Specifies the required alignment for data buffers. (SCSI Controller specific!)
+    #[must_use]
+    pub fn new(direction: ScsiRequestDirection, io_align: u32) -> Self {
+        Self {
+            req: ScsiRequest {
+                in_data_buffer: None,
+                out_data_buffer: None,
+                sense_data_buffer: None,
+                cdb_buffer: None,
+                packet: ScsiIoScsiRequestPacket {
+                    timeout: 0,
+                    in_data_buffer: ptr::null_mut(),
+                    out_data_buffer: ptr::null_mut(),
+                    sense_data: ptr::null_mut(),
+                    cdb: ptr::null_mut(),
+                    in_transfer_length: 0,
+                    out_transfer_length: 0,
+                    cdb_length: 0,
+                    data_direction: direction,
+                    host_adapter_status: ScsiIoHostAdapterStatus::default(),
+                    target_status: ScsiIoTargetStatus::default(),
+                    sense_data_length: 0,
+                },
+                io_align,
+                _phantom: Default::default(),
+            },
+        }
+    }
+
+    /// Starts a new builder preconfigured for READ operations.
+    ///
+    /// Some examples of SCSI read commands are:
+    /// - INQUIRY
+    /// - READ
+    /// - MODE_SENSE
+    ///
+    /// # Parameters
+    /// - `io_align`: Specifies the required alignment for data buffers.
+    #[must_use]
+    pub fn read(io_align: u32) -> Self {
+        Self::new(ScsiIoDataDirection::READ, io_align)
+    }
+
+    /// Starts a new builder preconfigured for WRITE operations.
+    ///
+    /// Some examples of SCSI write commands are:
+    /// - WRITE
+    /// - MODE_SELECT
+    ///
+    /// # Parameters
+    /// - `io_align`: Specifies the required alignment for data buffers.
+    #[must_use]
+    pub fn write(io_align: u32) -> Self {
+        Self::new(ScsiIoDataDirection::WRITE, io_align)
+    }
+
+    /// Starts a new builder preconfigured for BIDIRECTIONAL operations.
+    ///
+    /// Some examples of SCSI bidirectional commands are:
+    /// - SEND DIAGNOSTIC
+    ///
+    /// # Parameters
+    /// - `io_align`: Specifies the required alignment for data buffers.
+    #[must_use]
+    pub fn bidirectional(io_align: u32) -> Self {
+        Self::new(ScsiIoDataDirection::BIDIRECTIONAL, io_align)
+    }
+}
+
+impl<'a> ScsiRequestBuilder<'a> {
+    /// Sets a timeout for the SCSI request.
+    ///
+    /// # Parameters
+    /// - `timeout`: A [`Duration`] representing the maximum time allowed for the request.
+    ///   The value is converted to 100-nanosecond units.
+    ///
+    /// # Description
+    /// By default (without calling this method, or by calling with [`Duration::ZERO`]),
+    /// SCSI requests have no timeout.
+    /// Setting a timeout here will cause SCSI commands to potentially fail with [`crate::Status::TIMEOUT`].
+    #[must_use]
+    pub const fn with_timeout(mut self, timeout: Duration) -> Self {
+        self.req.packet.timeout = (timeout.as_nanos() / 100) as u64;
+        self
+    }
+
+    // # IN BUFFER
+    // ########################################################################################
+
+    /// Uses a user-supplied buffer for reading data from the device.
+    ///
+    /// # Parameters
+    /// - `bfr`: A mutable reference to an [`AlignedBuffer`] that will be used to store data read from the device.
+    ///
+    /// # Returns
+    /// `Result<Self, AlignmentError>` indicating success or an alignment issue with the provided buffer.
+    ///
+    /// # Description
+    /// This method checks the alignment of the buffer against the protocol's requirements and assigns it to
+    /// the `in_data_buffer` of the underlying `ScsiRequest`.
+    pub fn use_read_buffer(mut self, bfr: &'a mut AlignedBuffer) -> Result<Self, AlignmentError> {
+        // check alignment of externally supplied buffer
+        self.check_buffer_alignment(bfr.ptr())?;
+        self.req.in_data_buffer = None;
+        self.req.packet.in_data_buffer = bfr.ptr_mut().cast();
+        self.req.packet.in_transfer_length = bfr.len() as u32;
+        Ok(self)
+    }
+
+    /// Adds a newly allocated read buffer to the built SCSI request.
+    ///
+    /// # Parameters
+    /// - `len`: The size of the buffer (in bytes) to allocate for receiving data.
+    ///
+    /// # Returns
+    /// `Result<Self, LayoutError>` indicating success or a memory allocation error.
+    pub fn with_read_buffer(mut self, len: usize) -> Result<Self, LayoutError> {
+        let bfr = AlignedBuffer::alloc(len, self.req.io_align as usize)?;
+        self.req.packet.in_data_buffer = bfr.ptr() as *mut c_void;
+        self.req.packet.in_transfer_length = bfr.len() as u32;
+        self.req.in_data_buffer = Some(bfr);
+        Ok(self)
+    }
+
+    // # SENSE BUFFER
+    // ########################################################################################
+
+    /// Adds a newly allocated sense buffer to the built SCSI request.
+    ///
+    /// # Parameters
+    /// - `len`: The size of the buffer (in bytes) to allocate for receiving sense data.
+    ///
+    /// # Returns
+    /// `Result<Self, LayoutError>` indicating success or a memory allocation error.
+    pub fn with_sense_buffer(mut self, len: u8) -> Result<Self, LayoutError> {
+        let bfr = AlignedBuffer::alloc(len as usize, self.req.io_align as usize)?;
+        self.req.packet.sense_data = bfr.ptr() as *mut c_void;
+        self.req.packet.sense_data_length = len;
+        self.req.sense_data_buffer = Some(bfr);
+        Ok(self)
+    }
+
+    // # WRITE BUFFER
+    // ########################################################################################
+
+    /// Uses a user-supplied buffer for writing data to the device.
+    ///
+    /// # Parameters
+    /// - `bfr`: A mutable reference to an [`AlignedBuffer`] containing the data to be written to the device.
+    ///
+    /// # Returns
+    /// `Result<Self, AlignmentError>` indicating success or an alignment issue with the provided buffer.
+    ///
+    /// # Description
+    /// This method checks the alignment of the buffer against the protocol's requirements and assigns it to
+    /// the `out_data_buffer` of the underlying `ScsiRequest`.
+    pub fn use_write_buffer(mut self, bfr: &'a mut AlignedBuffer) -> Result<Self, AlignmentError> {
+        // check alignment of externally supplied buffer
+        self.check_buffer_alignment(bfr.ptr())?;
+        self.req.out_data_buffer = None;
+        self.req.packet.out_data_buffer = bfr.ptr_mut().cast();
+        self.req.packet.out_transfer_length = bfr.len() as u32;
+        Ok(self)
+    }
+
+    /// Adds a newly allocated write buffer to the built SCSI request that is filled from the
+    /// given data buffer. (Done for memory alignment and lifetime purposes)
+    ///
+    /// # Parameters
+    /// - `data`: A slice of bytes representing the data to be written.
+    ///
+    /// # Returns
+    /// `Result<Self, LayoutError>` indicating success or a memory allocation error.
+    pub fn with_write_data(mut self, data: &[u8]) -> Result<Self, LayoutError> {
+        let mut bfr = AlignedBuffer::alloc(data.len(), self.req.io_align as usize)?;
+        bfr.copy_from(data);
+        self.req.packet.out_data_buffer = bfr.ptr_mut().cast();
+        self.req.packet.out_transfer_length = bfr.len() as u32;
+        self.req.out_data_buffer = Some(bfr);
+        Ok(self)
+    }
+
+    // # COMMAND BUFFER
+    // ########################################################################################
+
+    /// Uses a user-supplied Command Data Block (CDB) buffer.
+    ///
+    /// # Parameters
+    /// - `data`: A mutable reference to an [`AlignedBuffer`] containing the CDB to be sent to the device.
+    ///
+    /// # Returns
+    /// `Result<Self, AlignmentError>` indicating success or an alignment issue with the provided buffer.
+    ///
+    /// # Notes
+    /// The maximum length of a CDB is 255 bytes.
+    pub fn use_command_buffer(
+        mut self,
+        data: &'a mut AlignedBuffer,
+    ) -> Result<Self, AlignmentError> {
+        assert!(data.len() <= 255);
+        // check alignment of externally supplied buffer
+        self.check_buffer_alignment(data.ptr())?;
+        self.req.cdb_buffer = None;
+        self.req.packet.cdb = data.ptr_mut().cast();
+        self.req.packet.cdb_length = data.len() as u8;
+        Ok(self)
+    }
+
+    /// Adds a newly allocated Command Data Block (CDB) buffer to the built SCSI request that is filled from the
+    /// given data buffer. (Done for memory alignment and lifetime purposes)
+    ///
+    /// # Parameters
+    /// - `data`: A slice of bytes representing the command to be sent.
+    ///
+    /// # Returns
+    /// `Result<Self, LayoutError>` indicating success or a memory allocation error.
+    ///
+    /// # Notes
+    /// The maximum length of a CDB is 255 bytes.
+    pub fn with_command_data(mut self, data: &[u8]) -> Result<Self, LayoutError> {
+        assert!(data.len() <= 255);
+        let mut bfr = AlignedBuffer::alloc(data.len(), self.req.io_align as usize)?;
+        bfr.copy_from(data);
+        self.req.packet.cdb = bfr.ptr_mut().cast();
+        self.req.packet.cdb_length = bfr.len() as u8;
+        self.req.cdb_buffer = Some(bfr);
+        Ok(self)
+    }
+
+    /// Build the final `ScsiRequest`.
+    ///
+    /// # Returns
+    /// A fully-configured [`ScsiRequest`] ready for execution.
+    #[must_use]
+    pub fn build(self) -> ScsiRequest<'a> {
+        self.req
+    }
+}
+impl ScsiRequestBuilder<'_> {
+    fn check_buffer_alignment(&self, bfr: *const u8) -> Result<(), AlignmentError> {
+        //TODO: use bfr.addr() when it's available
+        if (bfr as usize) % self.req.io_align as usize != 0 {
+            return Err(AlignmentError); //TODO: use >is_aligned_to< when it's available
+        }
+        Ok(())
+    }
+}
+
+/// Represents the response of a SCSI request.
+///
+/// This struct encapsulates the results of a SCSI operation, including data buffers
+/// for read and sense data, as well as status codes returned by the host adapter and target device.
+#[derive(Debug)]
+#[repr(transparent)]
+pub struct ScsiResponse<'a>(ScsiRequest<'a>);
+impl ScsiResponse<'_> {
+    /// Retrieves the buffer containing data read from the device (if any).
+    ///
+    /// # Returns
+    /// `Option<&[u8]>`: A slice of the data read from the device, or `None` if no read buffer was assigned.
+    ///
+    /// # Safety
+    /// - If the buffer pointer is `NULL`, the method returns `None` and avoids dereferencing it.
+    #[must_use]
+    pub fn read_buffer(&self) -> Option<&[u8]> {
+        if self.0.packet.in_data_buffer.is_null() {
+            return None;
+        }
+        unsafe {
+            Some(core::slice::from_raw_parts(
+                self.0.packet.in_data_buffer as *const u8,
+                self.0.packet.in_transfer_length as usize,
+            ))
+        }
+    }
+
+    /// Retrieves the buffer containing sense data returned by the device (if any).
+    ///
+    /// # Returns
+    /// `Option<&[u8]>`: A slice of the sense data, or `None` if no sense data buffer was assigned.
+    ///
+    /// # Safety
+    /// - If the buffer pointer is `NULL`, the method returns `None` and avoids dereferencing it.
+    #[must_use]
+    pub fn sense_data(&self) -> Option<&[u8]> {
+        if self.0.packet.sense_data.is_null() {
+            return None;
+        }
+        unsafe {
+            Some(core::slice::from_raw_parts(
+                self.0.packet.sense_data as *const u8,
+                self.0.packet.sense_data_length as usize,
+            ))
+        }
+    }
+
+    /// Retrieves the status of the host adapter after executing the SCSI request.
+    ///
+    /// # Returns
+    /// [`ScsiIoHostAdapterStatus`]: The status code indicating the result of the operation from the host adapter.
+    #[must_use]
+    pub const fn host_adapter_status(&self) -> ScsiIoHostAdapterStatus {
+        self.0.packet.host_adapter_status
+    }
+
+    /// Retrieves the status of the target device after executing the SCSI request.
+    ///
+    /// # Returns
+    /// [`ScsiIoTargetStatus`]: The status code returned by the target device.
+    #[must_use]
+    pub const fn target_status(&self) -> ScsiIoTargetStatus {
+        self.0.packet.target_status
+    }
+}

uefi/src/proto/scsi/pass_thru.rs

@@ -0,0 +1,239 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! Extended SCSI Pass Thru protocols.
+
+use super::{ScsiRequest, ScsiResponse};
+use crate::helpers::AlignedBuffer;
+use crate::proto::unsafe_protocol;
+use crate::StatusExt;
+use core::alloc::LayoutError;
+use core::ptr;
+use uefi_raw::protocol::scsi::{
+    ExtScsiPassThruMode, ExtScsiPassThruProtocol, SCSI_TARGET_MAX_BYTES,
+};
+use uefi_raw::Status;
+
+/// Structure representing a SCSI target address.
+pub type ScsiTarget = [u8; SCSI_TARGET_MAX_BYTES];
+
+/// Structure representing a fully-qualified device address, consisting of SCSI target and LUN.
+#[derive(Clone, Debug)]
+pub struct ScsiTargetLun(ScsiTarget, u64);
+impl Default for ScsiTargetLun {
+    fn default() -> Self {
+        Self([0xFF; SCSI_TARGET_MAX_BYTES], 0)
+    }
+}
+
+/// Enables interaction with SCSI devices using the Extended SCSI Pass Thru protocol.
+///
+/// This protocol allows communication with SCSI devices connected to the system,
+/// providing methods to send commands, reset devices, and enumerate SCSI targets.
+///
+/// # UEFI Spec Description
+/// Provides services that allow SCSI Pass Thru commands to be sent to SCSI devices attached to a SCSI channel. It also
+/// allows packet-based commands (ATAPI cmds) to be sent to ATAPI devices attached to a ATA controller.
+#[derive(Debug)]
+#[repr(transparent)]
+#[unsafe_protocol(ExtScsiPassThruProtocol::GUID)]
+pub struct ExtScsiPassThru(ExtScsiPassThruProtocol);
+
+impl ExtScsiPassThru {
+    /// Retrieves the mode structure for the Extended SCSI Pass Thru protocol.
+    ///
+    /// # Returns
+    /// The [`ExtScsiPassThruMode`] structure containing configuration details of the protocol.
+    #[must_use]
+    pub fn mode(&self) -> ExtScsiPassThruMode {
+        let mut mode = unsafe { (*self.0.passthru_mode).clone() };
+        mode.io_align = mode.io_align.max(1); // 0 and 1 is the same, says UEFI spec
+        mode
+    }
+
+    /// Retrieves the I/O buffer alignment required by this SCSI channel.
+    ///
+    /// # Returns
+    /// - A `u32` value representing the required I/O alignment.
+    #[must_use]
+    pub fn io_align(&self) -> u32 {
+        self.mode().io_align
+    }
+
+    /// Allocates an I/O buffer with the necessary alignment for this SCSI channel.
+    ///
+    /// You can alternatively do this yourself using the [`AlignedBuffer`] helper directly.
+    /// The Scsi api will validate that your buffers have the correct alignment and crash
+    /// if they don't.
+    ///
+    /// # Parameters
+    /// - `len`: The size (in bytes) of the buffer to allocate.
+    ///
+    /// # Returns
+    /// [`AlignedBuffer`] containing the allocated memory.
+    ///
+    /// # Errors
+    /// This method can fail due to alignment or memory allocation issues.
+    pub fn alloc_io_buffer(&self, len: usize) -> Result<AlignedBuffer, LayoutError> {
+        AlignedBuffer::alloc(len, self.io_align() as usize)
+    }
+
+    /// Iterate over all potential SCSI devices on this channel.
+    ///
+    /// # Warning
+    /// Depending on the UEFI implementation, this does not only return all actually available devices.
+    /// Most implementations instead return a list of all possible fully-qualified device addresses.
+    /// You have to probe for availability yourself, using [`ScsiDevice::execute_command`].
+    ///
+    /// # Returns
+    /// [`ScsiTargetLunIterator`] to iterate through connected SCSI devices.
+    #[must_use]
+    pub fn iter_devices(&self) -> ScsiTargetLunIterator<'_> {
+        ScsiTargetLunIterator {
+            proto: &self.0,
+            prev: ScsiTargetLun::default(),
+        }
+    }
+
+    /// Resets the SCSI channel associated with the protocol.
+    ///
+    /// The EFI_EXT_SCSI_PASS_THRU_PROTOCOL.ResetChannel() function resets a SCSI channel.
+    /// This operation resets all the SCSI devices connected to the SCSI channel.
+    ///
+    /// # Returns
+    /// [`Result<()>`] indicating the success or failure of the operation.
+    ///
+    /// # Errors
+    /// - [`Status::SUCCESS`] The SCSI channel was successfully reset.
+    /// - [`Status::UNSUPPORTED`] The SCSI channel does not support a channel reset operation.
+    /// - [`Status::DEVICE_ERROR`] A device error occurred while attempting to reset the SCSI channel.
+    /// - [`Status::TIMEOUT`] A timeout occurred while attempting to reset the SCSI channel.
+    pub fn reset_channel(&mut self) -> crate::Result<()> {
+        unsafe { (self.0.reset_channel)(&mut self.0).to_result() }
+    }
+}
+
+/// Structure representing a potential ScsiDevice.
+///
+/// In the UEFI Specification, this corresponds to a (SCSI target, LUN) tuple.
+///
+/// # Warning
+/// This does not actually have to correspond to an actual device!
+/// You have to probe for availability before doing anything meaningful with it.
+#[derive(Clone, Debug)]
+pub struct ScsiDevice<'a> {
+    proto: &'a ExtScsiPassThruProtocol,
+    target_lun: ScsiTargetLun,
+}
+impl ScsiDevice<'_> {
+    /// Returns the SCSI target address of the potential device.
+    #[must_use]
+    pub const fn target(&self) -> &ScsiTarget {
+        &self.target_lun.0
+    }
+
+    /// Returns the logical unit number (LUN) of the potential device.
+    #[must_use]
+    pub const fn lun(&self) -> u64 {
+        self.target_lun.1
+    }
+
+    /// Resets the potential SCSI device represented by this instance.
+    ///
+    /// The `EFI_EXT_SCSI_PASS_THRU_PROTOCOL.ResetTargetLun()` function resets the SCSI logical unit
+    /// specified by `Target` and `Lun`. This allows for recovering a device that may be in an error state
+    /// or requires reinitialization. The function behavior is dependent on the SCSI channel's capability
+    /// to perform target resets.
+    ///
+    /// # Returns
+    /// [`Result<()>`] indicating the success or failure of the operation.
+    ///
+    /// # Errors
+    /// - [`Status::SUCCESS`] The SCSI device specified by `Target` and `Lun` was reset.
+    /// - [`Status::UNSUPPORTED`] The SCSI channel does not support a target reset operation.
+    /// - [`Status::INVALID_PARAMETER`] The `Target` or `Lun` values are invalid.
+    /// - [`Status::DEVICE_ERROR`] A device error occurred while attempting to reset the SCSI device
+    ///   specified by `Target` and `Lun`.
+    /// - [`Status::TIMEOUT`] A timeout occurred while attempting to reset the SCSI device specified
+    ///   by `Target` and `Lun`.
+    pub fn reset(&self) -> crate::Result<()> {
+        unsafe {
+            (self.proto.reset_target_lun)(self.proto, self.target_lun.0.as_ptr(), self.lun())
+                .to_result()
+        }
+    }
+
+    /// Sends a SCSI command to the potential target device and retrieves the response.
+    ///
+    /// This method sends a SCSI Request Packet to a SCSI device attached to the SCSI channel.
+    /// It supports both blocking and nonblocking I/O. Blocking I/O is mandatory, while
+    /// nonblocking I/O is optional and dependent on the driver's implementation.
+    ///
+    /// # Parameters
+    /// - `scsi_req`: The [`ScsiRequest`] containing the command and data to send to the device.
+    ///
+    /// # Returns
+    /// [`ScsiResponse`] containing the results of the operation, such as data and status.
+    ///
+    /// # Errors
+    /// - [`Status::SUCCESS`] The SCSI Request Packet was successfully sent. For bi-directional
+    ///   commands, `InTransferLength` bytes were transferred from `InDataBuffer`. For write and
+    ///   bi-directional commands, `OutTransferLength` bytes were transferred by `OutDataBuffer`.
+    ///   Additional status information is available in `HostAdapterStatus`, `TargetStatus`,
+    ///   `SenseDataLength`, and `SenseData`.
+    /// - [`Status::BAD_BUFFER_SIZE`] The SCSI Request Packet was not executed because the data
+    ///   buffer size exceeded the allowed transfer size for a single command. The number of bytes
+    ///   that could be transferred is returned in `InTransferLength` or `OutTransferLength`.
+    /// - [`Status::NOT_READY`] The SCSI Request Packet could not be sent because too many packets
+    ///   are already queued. The caller may retry later.
+    /// - [`Status::DEVICE_ERROR`] A device error occurred while attempting to send the SCSI Request Packet.
+    ///   Additional status information is available in `HostAdapterStatus`, `TargetStatus`, `SenseDataLength`,
+    ///   and `SenseData`.
+    /// - [`Status::INVALID_PARAMETER`] The `Target`, `Lun`, or the contents of `ScsiRequestPacket` are invalid.
+    ///   The SCSI Request Packet was not sent, and no additional status information is available.
+    /// - [`Status::UNSUPPORTED`] The command described by the SCSI Request Packet is not supported by the
+    ///   host adapter, including unsupported bi-directional SCSI commands. The SCSI Request Packet was not
+    ///   sent, and no additional status information is available.
+    /// - [`Status::TIMEOUT`] A timeout occurred while executing the SCSI Request Packet. Additional status
+    ///   information is available in `HostAdapterStatus`, `TargetStatus`, `SenseDataLength`, and `SenseData`.
+    pub fn execute_command<'req>(
+        &self,
+        mut scsi_req: ScsiRequest<'req>,
+    ) -> crate::Result<ScsiResponse<'req>> {
+        unsafe {
+            (self.proto.pass_thru)(
+                self.proto,
+                self.target_lun.0.as_ptr(),
+                self.target_lun.1,
+                &mut scsi_req.packet,
+                ptr::null_mut(),
+            )
+            .to_result_with_val(|| ScsiResponse(scsi_req))
+        }
+    }
+}
+
+/// An iterator over SCSI devices available on the channel.
+#[derive(Debug)]
+pub struct ScsiTargetLunIterator<'a> {
+    proto: &'a ExtScsiPassThruProtocol,
+    prev: ScsiTargetLun,
+}
+impl<'a> Iterator for ScsiTargetLunIterator<'a> {
+    type Item = ScsiDevice<'a>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        // no idea why get_next_target_lun() takes a doubleptr ... makes no sense
+        let mut target: *mut u8 = self.prev.0.as_mut_ptr();
+        let result =
+            unsafe { (self.proto.get_next_target_lun)(self.proto, &mut target, &mut self.prev.1) };
+        let scsi_device = ScsiDevice {
+            proto: self.proto,
+            target_lun: self.prev.clone(),
+        };
+        match result {
+            Status::SUCCESS => Some(scsi_device),
+            Status::NOT_FOUND => None,
+            _ => panic!("Must not happen according to spec!"),
+        }
+    }
+}

xtask/src/qemu.rs

@@ -456,6 +456,10 @@ pub fn run_qemu(arch: UefiArch, opt: &QemuOpt) -> Result<()> {
     add_pflash_args(&mut cmd, &ovmf_paths.code, PflashMode::ReadOnly);
     add_pflash_args(&mut cmd, &ovmf_vars, PflashMode::ReadWrite);
 
+    // Configure SCSI Controller
+    cmd.arg("-device");
+    cmd.arg("virtio-scsi-pci,id=scsi");
+
     // Mount a local directory as a FAT partition.
     cmd.arg("-drive");
     let mut drive_arg = OsString::from("format=raw,file=fat:rw:");
@@ -471,9 +475,11 @@ pub fn run_qemu(arch: UefiArch, opt: &QemuOpt) -> Result<()> {
     create_mbr_test_disk(&test_disk)?;
 
     cmd.arg("-drive");
-    let mut drive_arg = OsString::from("format=raw,file=");
+    let mut drive_arg = OsString::from("if=none,id=disk1,format=raw,file=");
     drive_arg.push(test_disk.clone());
     cmd.arg(drive_arg);
+    cmd.arg("-device"); // attach disk to SCSI controller
+    cmd.arg("scsi-hd,drive=disk1,vendor=uefi-rs,product=ExtScsiPassThru");
 
     let qemu_monitor_pipe = Pipe::new(tmp_dir, "qemu-monitor")?;
     let serial_pipe = Pipe::new(tmp_dir, "serial")?;