uefi: Add safe sync EFI_USB_IO_PROTOCOL bindings

Add safe wrapper functions that provide access to the sync versions of each
EFI_USB_IO_PROTOCOL transfer function.

Author: JarlEvanson

uefi/src/proto/usb/io.rs

@@ -2,8 +2,10 @@
 
 //! USB I/O protocol.
 
+use core::ffi;
+
 use uefi_macros::unsafe_protocol;
-use uefi_raw::protocol::usb::io::UsbIoProtocol;
+use uefi_raw::protocol::usb::io::{DataDirection, DeviceRequest, UsbIoProtocol, UsbTransferStatus};
 
 use crate::data_types::PoolString;
 use crate::{Char16, Result, StatusExt};
@@ -19,6 +21,194 @@ pub use uefi_raw::protocol::usb::io::{
 pub struct UsbIo(UsbIoProtocol);
 
 impl UsbIo {
+    /// Performs a USB Control transfer, allowing the driver to communicate with the USB device.
+    pub fn control_transfer(
+        &mut self,
+        request_type: u8,
+        request: u8,
+        value: u16,
+        index: u16,
+        transfer: ControlTransfer,
+        timeout: u32,
+    ) -> Result<(), UsbTransferStatus> {
+        let (direction, buffer_ptr, length) = match transfer {
+            ControlTransfer::None => (DataDirection::NO_DATA, core::ptr::null_mut(), 0),
+            ControlTransfer::DataIn(buffer) => (
+                DataDirection::DATA_IN,
+                buffer.as_ptr().cast_mut(),
+                buffer.len(),
+            ),
+            ControlTransfer::DataOut(buffer) => (
+                DataDirection::DATA_OUT,
+                buffer.as_ptr().cast_mut(),
+                buffer.len(),
+            ),
+        };
+
+        let mut device_request = DeviceRequest {
+            request_type,
+            request,
+            value,
+            index,
+            length: length as u16,
+        };
+        let mut status = UsbTransferStatus::default();
+
+        unsafe {
+            (self.0.control_transfer)(
+                &mut self.0,
+                &mut device_request,
+                direction,
+                timeout,
+                buffer_ptr.cast::<ffi::c_void>(),
+                length,
+                &mut status,
+            )
+        }
+        .to_result_with_err(|_| status)
+    }
+
+    /// Sends the provided buffer to a USB device over a bulk transfer pipe.
+    ///
+    /// Returns the number of bytes that were actually sent to the device.
+    pub fn sync_bulk_send(
+        &mut self,
+        endpoint: u8,
+        buffer: &[u8],
+        timeout: usize,
+    ) -> Result<usize, UsbTransferStatus> {
+        let mut status = UsbTransferStatus::default();
+        let mut length = buffer.len();
+
+        unsafe {
+            (self.0.bulk_transfer)(
+                &mut self.0,
+                endpoint & !0x80,
+                buffer.as_ptr().cast_mut().cast::<ffi::c_void>(),
+                &mut length,
+                timeout,
+                &mut status,
+            )
+        }
+        .to_result_with_err(|_| status)
+        .map(|()| length)
+    }
+
+    /// Fills the provided buffer with data from a USB device over a bulk transfer pipe.
+    ///
+    /// Returns the number of bytes that were actually received from the device.
+    pub fn sync_bulk_receive(
+        &mut self,
+        endpoint: u8,
+        buffer: &mut [u8],
+        timeout: usize,
+    ) -> Result<usize, UsbTransferStatus> {
+        let mut status = UsbTransferStatus::default();
+        let mut length = buffer.len();
+
+        unsafe {
+            (self.0.bulk_transfer)(
+                &mut self.0,
+                endpoint | 0x80,
+                buffer.as_ptr().cast_mut().cast::<ffi::c_void>(),
+                &mut length,
+                timeout,
+                &mut status,
+            )
+        }
+        .to_result_with_err(|_| status)
+        .map(|()| length)
+    }
+
+    /// Sends the provided buffer to a USB device through a synchronous interrupt transfer.
+    pub fn sync_interrupt_send(
+        &mut self,
+        endpoint: u8,
+        buffer: &[u8],
+        timeout: usize,
+    ) -> Result<usize, UsbTransferStatus> {
+        let mut status = UsbTransferStatus::default();
+        let mut length = buffer.len();
+
+        unsafe {
+            (self.0.sync_interrupt_transfer)(
+                &mut self.0,
+                endpoint & !0x80,
+                buffer.as_ptr().cast_mut().cast::<ffi::c_void>(),
+                &mut length,
+                timeout,
+                &mut status,
+            )
+        }
+        .to_result_with_err(|_| status)
+        .map(|()| length)
+    }
+
+    /// Fills the provided buffer with data from a USB device through a synchronous interrupt
+    /// transfer.
+    pub fn sync_interrupt_receive(
+        &mut self,
+        endpoint: u8,
+        buffer: &mut [u8],
+        timeout: usize,
+    ) -> Result<usize, UsbTransferStatus> {
+        let mut status = UsbTransferStatus::default();
+        let mut length = buffer.len();
+
+        unsafe {
+            (self.0.sync_interrupt_transfer)(
+                &mut self.0,
+                endpoint | 0x80,
+                buffer.as_ptr().cast_mut().cast::<ffi::c_void>(),
+                &mut length,
+                timeout,
+                &mut status,
+            )
+        }
+        .to_result_with_err(|_| status)
+        .map(|()| length)
+    }
+
+    /// Sends the provided buffer to a USB device over an isochronous transfer pipe.
+    pub fn sync_isochronous_send(
+        &mut self,
+        endpoint: u8,
+        buffer: &[u8],
+    ) -> Result<(), UsbTransferStatus> {
+        let mut status = UsbTransferStatus::default();
+
+        unsafe {
+            (self.0.isochronous_transfer)(
+                &mut self.0,
+                endpoint & !0x80,
+                buffer.as_ptr().cast_mut().cast::<ffi::c_void>(),
+                buffer.len(),
+                &mut status,
+            )
+        }
+        .to_result_with_err(|_| status)
+    }
+
+    /// Fills the provided buffer with data from a USB device over an isochronous transfer pipe.
+    pub fn sync_isochronous_receive(
+        &mut self,
+        endpoint: u8,
+        buffer: &mut [u8],
+    ) -> Result<(), UsbTransferStatus> {
+        let mut status = UsbTransferStatus::default();
+
+        unsafe {
+            (self.0.isochronous_transfer)(
+                &mut self.0,
+                endpoint | 0x80,
+                buffer.as_mut_ptr().cast::<ffi::c_void>(),
+                buffer.len(),
+                &mut status,
+            )
+        }
+        .to_result_with_err(|_| status)
+    }
+
     /// Returns information about USB devices, including the device's class, subclass, and number
     /// of configurations.
     pub fn device_descriptor(&mut self) -> Result<DeviceDescriptor> {
@@ -85,3 +275,14 @@ impl UsbIo {
         unsafe { (self.0.port_reset)(&mut self.0) }.to_result()
     }
 }
+
+/// Controls what type of USB control transfer operation should occur.
+#[derive(Debug)]
+pub enum ControlTransfer<'buffer> {
+    /// The USB control transfer has no data phase.
+    None,
+    /// The USB control transfer has an input data phase.
+    DataIn(&'buffer mut [u8]),
+    /// The USB control transfer has an output data phase.
+    DataOut(&'buffer [u8]),
+}