uefi: document udp_read of PXE protocol + improve test

Author: phip1611

uefi-test-runner/src/proto/network/pxe.rs

@@ -76,10 +76,11 @@ pub fn test() {
 
         info!("Reading UDP packet from example service");
 
-        let mut src_ip = server_ip;
-        let mut src_port = EXAMPLE_SERVICE_PORT;
-        let mut dest_ip = base_code.mode().station_ip();
-        let mut dest_port = write_src_port;
+        // Used as buffers
+        let mut src_ip = IpAddress::new_v4([0; 4]);
+        let mut src_port = 0;
+        let mut dest_ip = IpAddress::new_v4([0; 4]);
+        let mut dest_port = 0;
         let mut header = [0; 1];
         let mut received = [0; 4];
 
@@ -88,7 +89,12 @@ pub fn test() {
         let mut read_result = Ok(0);
         for i in 0..5 {
             read_result = base_code.udp_read(
-                UdpOpFlags::USE_FILTER,
+                // We expect exactly one packet but accept all to catch
+                // unexpected network traffic.
+                UdpOpFlags::ANY_SRC_PORT
+                    | UdpOpFlags::ANY_SRC_IP
+                    | UdpOpFlags::ANY_DEST_PORT
+                    | UdpOpFlags::ANY_DEST_IP,
                 Some(&mut dest_ip),
                 Some(&mut dest_port),
                 Some(&mut src_ip),
@@ -104,6 +110,14 @@ pub fn test() {
         }
         read_result.unwrap();
 
+        // Check that we indeed received the expected packet.
+        assert_eq!(dest_ip, base_code.mode().station_ip());
+        assert_eq!(src_ip, server_ip);
+        assert_eq!(src_port, EXAMPLE_SERVICE_PORT);
+        // We don't know the dst port here, as it is dynamically handled
+        // by QEMU/the NIC.
+        debug!("dest UDP port: {dest_port}");
+
         // Check the header.
         assert_eq!(header[0] as usize, payload.len());
         // Check that we receive the reversed payload.

uefi/src/proto/network/pxe.rs

@@ -411,6 +411,27 @@ impl BaseCode {
     }
 
     /// Reads a UDP packet from the network interface.
+    ///
+    /// # Arguments
+    /// - `op_flags`: [`UdpOpFlags`] specifying the behavior of the function
+    /// - `dest_ip`: The behavior depends on whether
+    ///   [`UdpOpFlags::ANY_DEST_IP`] is set. If it not set, packets must match
+    ///   the specified IP. Otherwise, the corresponding IP is written into the
+    ///   provided buffer.
+    /// - `dest_port`: The behavior depends on whether
+    ///   [`UdpOpFlags::ANY_DEST_PORT`] is set. If it not set, packets must match
+    ///   the specified port. Otherwise, the corresponding port is written into
+    ///   the provided buffer.
+    /// - `src_ip`: The behavior depends on whether
+    ///   [`UdpOpFlags::ANY_SRC_IP`] is set. If it not set, packets must match
+    ///   the specified IP. Otherwise, the corresponding IP is written into the
+    ///   provided buffer.
+    /// - `src_port`: The behavior depends on whether
+    ///   [`UdpOpFlags::ANY_SRC_PORT`] is set. If it not set, packets must match
+    ///   the specified port. Otherwise, the corresponding port is written into
+    ///   the provided buffer.
+    /// - `header`: Optional header of the data inside `buffer`.
+    /// - `buffer`: Buffer for the UDP packet's content.
     #[allow(clippy::too_many_arguments)]
     pub fn udp_read(
         &mut self,