Use more specific [u8; 8] type for SETUP packets

Also, a minor change to return WouldBlock when read() encounters a SETUP
packet, rather than InvalidState, which cleans up control logic.

Author: ianrrees

src/bus.rs

@@ -93,6 +93,9 @@ pub trait UsbBus: Sized {
     /// * [`WouldBlock`](crate::UsbError::WouldBlock) - There is no packet to be read. Note that
     ///   this is different from a received zero-length packet, which is valid in USB. A zero-length
     ///   packet will return `Ok(0)`.
+    ///
+    ///   `WouldBlock` is also returned when the endpoint received a SETUP transaction, which can be
+    ///   read through [`read_setup()`](UsbBus::read_setup()).
     /// * [`BufferOverflow`](crate::UsbError::BufferOverflow) - The received packet is too long to
     ///   fit in `buf`. This is generally an error in the class implementation, because the class
     ///   should use a buffer that is large enough for the `max_packet_size` it specified when
@@ -114,14 +117,8 @@ pub trait UsbBus: Sized {
     ///
     /// * [`InvalidEndpoint`](crate::UsbError::InvalidEndpoint) - The `ep_addr` does not point to a
     ///   valid endpoint that was previously allocated with [`UsbBus::alloc_ep`].
-    /// * [`WouldBlock`](crate::UsbError::WouldBlock) - There is no SETUP packet to be read. Note
-    ///   that this is different from a received zero-length packet, which is valid in USB. A
-    ///   zero-length packet will return `Ok(0)`.
-    /// * [`BufferOverflow`](crate::UsbError::BufferOverflow) - The received packet is too long to
-    ///   fit in `buf`. This is generally an error in the class implementation, because the class
-    ///   should use a buffer that is large enough for the `max_packet_size` it specified when
-    ///   allocating the endpoint.
-    fn read_setup(&self, ep_addr: EndpointAddress, buf: &mut [u8]) -> Result<usize>;
+    /// * [`WouldBlock`](crate::UsbError::WouldBlock) - There is no SETUP packet to be read.
+    fn read_setup(&self, ep_addr: EndpointAddress) -> Result<[u8; 8]>;
 
     /// Sets or clears the STALL condition for an endpoint. If the endpoint is an OUT endpoint, it
     /// should be prepared to receive data again.

src/control_pipe.rs

@@ -65,18 +65,18 @@ impl<B: UsbBus> ControlPipe<'_, B> {
     }
 
     pub fn handle_setup(&mut self) -> Option<Request> {
-        let count = match self.ep_out.read_setup(&mut self.buf[..]) {
-            Ok(count) => {
-                usb_trace!("Read {} bytes on EP0-OUT: {:?}", count, &self.buf[..count]);
-                count
+        let packet = match self.ep_out.read_setup() {
+            Ok(packet) => {
+                usb_trace!("Read SETUP packet on EP0-OUT: {:?}", packet);
+                packet
             }
             Err(UsbError::WouldBlock) => return None,
             Err(_) => {
                 return None;
             }
         };
 
-        let req = match Request::parse(&self.buf[0..count]) {
+        let req = match Request::parse(&packet) {
             Ok(req) => req,
             Err(_) => {
                 // Failed to parse SETUP packet. We are supposed to silently ignore this.
@@ -167,7 +167,7 @@ impl<B: UsbBus> ControlPipe<'_, B> {
                 );
                 match self.ep_out.read(&mut []) {
                     Ok(_) => {}
-                    Err(UsbError::InvalidState) => {
+                    Err(UsbError::WouldBlock) => {
                         // Host sent a new SETUP transaction, which may have overwritten the ZLP
                     }
                     Err(err) => {

src/dummy.rs

@@ -59,8 +59,7 @@ impl UsbBus for DummyUsbBus {
     fn read_setup(
         &self,
         ep_addr: crate::class_prelude::EndpointAddress,
-        buf: &mut [u8],
-    ) -> crate::Result<usize> {
+    ) -> crate::Result<[u8; 8]> {
         unimplemented!()
     }
 

src/endpoint.rs

@@ -199,49 +199,56 @@ impl<B: UsbBus> Endpoint<'_, B, In> {
 impl<B: UsbBus> Endpoint<'_, B, Out> {
     /// Reads a single packet of data and returns the length of the packet
     ///
-    /// The buffer should be large enough to fit at least as many bytes as the `max_packet_size`
-    /// specified when allocating the endpoint.
+    /// The buffer should be large enough to fit at least as many bytes as the
+    /// `max_packet_size` specified when allocating the endpoint.
     ///
     /// # Errors
     ///
-    /// Note: USB bus implementation errors are directly passed through, so be prepared to handle
-    /// other errors as well.
+    /// Note: USB bus implementation errors are directly passed through, so be
+    /// prepared to handle other errors as well.
     ///
-    /// * [`WouldBlock`](crate::UsbError::WouldBlock) - There is no packet to be read. Note that
-    ///   this is different from a received zero-length packet, which is valid and significant in
-    ///   USB. A zero-length packet will return `Ok(0)`.
-    /// * [`BufferOverflow`](crate::UsbError::BufferOverflow) - The received packet is too long to
-    ///   fit in `data`. This is generally an error in the class implementation.
-    /// * [`InvalidState`](crate::UsbError::InvalidState) - The received packet is a SETUP
-    ///   transaction, and needs to be read through [`read_setup()`](Endpoint::read_setup())
-    ///   instead.
+    /// * [`WouldBlock`](crate::UsbError::WouldBlock) - There is no OUT packet
+    ///   to be read. Note that this is different from a received zero-length
+    ///   packet, which is valid and significant in USB. A zero-length packet
+    ///   will return `Ok(0)`.
+    ///
+    ///   `WouldBlock` is also returned when the endpoint received a SETUP
+    ///   transaction, which can be read through
+    ///   [`read_setup()`](Endpoint::read_setup()).
+    /// * [`BufferOverflow`](crate::UsbError::BufferOverflow) - The received
+    ///   packet is too long to fit in `data`. This is generally an error in the
+    ///   class implementation.
     pub fn read(&self, data: &mut [u8]) -> Result<usize> {
         self.bus().read(self.address, data)
     }
 
-    /// Reads a single packet of SETUP data and returns the length of the packet
+    /// Reads a single packet of SETUP data and returns it
+    ///
+    /// USB Spec 2.0 5.5.3 Control Transfer Packet Size Constraints: "A Setup
+    /// packet is always eight bytes."
     ///
-    /// The buffer should be large enough to fit at least as many bytes as the `max_packet_size`
-    /// specified when allocating the endpoint.  See [`UsbBus::read_setup()`] for rationale for two
-    /// distinct read methods.
+    /// See [`UsbBus::read_setup()`] for rationale for two distinct read
+    /// methods.
     ///
     /// # Errors
     ///
-    /// Note: USB bus implementation errors are directly passed through, so be prepared to handle
-    /// other errors as well.
+    /// Note: USB bus implementation errors are directly passed through, so be
+    /// prepared to handle other errors as well.
     ///
-    /// * [`WouldBlock`](crate::UsbError::WouldBlock) - There is no packet to be read. Note that
-    ///   this is different from a received zero-length packet, which is valid and significant in
-    ///   USB. A zero-length packet will return `Ok(0)`.
-    /// * [`BufferOverflow`](crate::UsbError::BufferOverflow) - The received packet is too long to
-    ///   fit in `data`. This is generally an error in the class implementation.
-    pub fn read_setup(&self, data: &mut [u8]) -> Result<usize> {
+    /// * [`WouldBlock`](crate::UsbError::WouldBlock) - There is no packet to be
+    ///   read. Note that this is different from a received zero-length packet,
+    ///   which is valid and significant in USB. A zero-length packet will
+    ///   return `Ok(0)`.
+    /// * [`InvalidEndpoint`](crate::UsbError::InvalidEndpoint) - SETUP packets
+    ///   can only be read from Control endpoints, this error is returned if the
+    ///   method is called on any other type endpoint.
+    pub fn read_setup(&self) -> Result<[u8; 8]> {
         // SETUP transactions can only occur on control endpoints
         if self.ep_type != EndpointType::Control {
-            Err(UsbError::InvalidEndpoint)
-        } else {
-            self.bus().read_setup(self.address, data)
+            return Err(UsbError::InvalidEndpoint);
         }
+
+        self.bus().read_setup(self.address)
     }
 }
 

src/lib.rs

@@ -258,7 +258,7 @@ fn _ensure_sync() {
             Err(UsbError::InvalidEndpoint)
         }
 
-        fn read_setup(&self, _ep_addr: EndpointAddress, _buf: &mut [u8]) -> Result<usize> {
+        fn read_setup(&self, _ep_addr: EndpointAddress) -> Result<[u8; 8]> {
             Err(UsbError::InvalidEndpoint)
         }