uefi: Add safe protocol bindings for EFI_EXT_SCSI_PASS_THRU_PROTOCOL

Author: seijikun

Diff for: 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

Diff for: 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;

Diff for: uefi/src/proto/scsi/mod.rs

@@ -0,0 +1,366 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! SCSI Bus specific protocols.
+
+use crate::helpers::AlignedBuffer;
+use core::alloc::LayoutError;
+use core::error::Error;
+use core::ffi::c_void;
+use core::marker::PhantomData;
+use core::time::Duration;
+use core::{fmt, ptr};
+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;
+
+/// The `AlignmentError` is returned if a user-provided buffer doesn't fulfill alignment requirements.
+///
+/// This ensures that all buffers used in SCSI commands conform to the alignment requirements of the protocol.
+#[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")
+    }
+}
+
+/// 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)]
+#[repr(transparent)]
+pub struct ScsiRequestBuilder<'a> {
+    req: ScsiRequest<'a>,
+}
+impl<'a> ScsiRequestBuilder<'a> {
+    /// Creates a new `ScsiRequestBuilder` 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.
+    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(),
+            },
+        }
+    }
+
+    /// Creates a `ScsiRequestBuilder` 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.
+    pub fn read(io_align: u32) -> Self {
+        Self::new(ScsiIoDataDirection::READ, io_align)
+    }
+
+    /// Creates a `ScsiRequestBuilder` preconfigured for WRITE operations.
+    ///
+    /// Some examples of SCSI write commands are:
+    /// - WRITE
+    /// - MODE_SELECT
+    ///
+    /// # Parameters
+    /// - `io_align`: Specifies the required alignment for data buffers.
+    pub fn write(io_align: u32) -> Self {
+        Self::new(ScsiIoDataDirection::WRITE, io_align)
+    }
+
+    /// Creates a `ScsiRequestBuilder` preconfigured for BIDIRECTIONAL operations.
+    ///
+    /// Some examples of SCSI bidirectional commands are:
+    /// - SEND DIAGNOSTIC
+    ///
+    /// # Parameters
+    /// - `io_align`: Specifies the required alignment for data buffers.
+    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`].
+    pub 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() as *mut c_void;
+        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() as *mut c_void;
+        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() as *mut c_void;
+        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() as *mut c_void;
+        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() as *mut c_void;
+        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.
+    pub fn build(self) -> ScsiRequest<'a> {
+        self.req
+    }
+}
+impl<'a> ScsiRequestBuilder<'a> {
+    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<'a> ScsiResponse<'a> {
+    /// 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.
+    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.
+    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.
+    pub 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.
+    pub fn target_status(&self) -> ScsiIoTargetStatus {
+        self.0.packet.target_status
+    }
+}