Add doc examples (#17)

Author: Jake-Shadle

CHANGELOG.md

@@ -11,13 +11,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - [PR#16](https://github.com/Jake-Shadle/xdp/pull/16) changed `RxRing` and `TxRing` to use the new `slab::Slab` trait.
 - [PR#16](https://github.com/Jake-Shadle/xdp/pull/16) moved `HeapSlab` to the new `slab` module, and made it implement `slab::Slab`, changing it so that items are always pushed to the front and popped from the back, unlike the previous implementation which allowed both.
+- [PR#17](https://github.com/Jake-Shadle/xdp/pull/17) changed `CsumOffload::Request(xdp::libc::xdp::xsk_tx_request)` -> `CsumOffload::Request { start: u16, offset: u16 }`
 
 ### Added
 - [PR#16](https://github.com/Jake-Shadle/xdp/pull/16) added a new `slab::StackSlab<N>` fixed size ring buffer that implements `slab::Slab`.
+- [PR#17](https://github.com/Jake-Shadle/xdp/pull/17) added various doc examples.
 
 ### Fixed
 - [PR#16](https://github.com/Jake-Shadle/xdp/pull/16) fixed some undefined behavior in the netlink code used to query NIC capabilities.
 - [PR#16](https://github.com/Jake-Shadle/xdp/pull/16) fixed a bug where TX metadata would not be added and would return an error if the packet headroom was not large enough for the metadata, this is irrelevant.
+- [PR#17](https://github.com/Jake-Shadle/xdp/pull/17) fixed the exceptional case where a UDP checksum is calculated to be 0, in which case it is set to `0xffff` instead.
 
 ## [0.5.0] - 2025-02-27
 ### Changed

crates/integ/tests/tx_checksum.rs

@@ -9,18 +9,9 @@ use xdp::{
 
 /// Validates that we can offload (most of) the layer 4 checksum calculation to
 /// hardware when the hardware + driver supports the `XDP_TXMD_FLAGS_CHECKSUM`
-/// flag
+/// flag. Note that this will fail if the kernel version is too low.
 #[test]
 fn offloads_tx_checksum() {
-    if std::env::var_os("CI").is_some() {
-        println!(
-            "::notice file={},line={}::Skipping TX offload test with sofware checksum, Ubunut kernel version is too old",
-            file!(),
-            line!()
-        );
-        return;
-    }
-
     let vpair = test_utils::veth_pair!("tx_off", 0);
 
     do_checksum_test(true, &vpair);

src/packet.rs

@@ -100,7 +100,12 @@ pub unsafe trait Pod: Sized {
 /// Configures TX checksum offload when setting TX metadata via [`Packet::set_tx_metadata`]
 pub enum CsumOffload {
     /// Requests checksum offload
-    Request(libc::xdp::xsk_tx_request),
+    Request {
+        /// The offset from the start of the packet where the checksum calculation should start
+        start: u16,
+        /// The offset from `start` where the checksum should be stored
+        offset: u16,
+    },
     /// Offload is not requested
     None,
 }
@@ -169,12 +174,34 @@ impl Packet {
     }
 
     /// The number of initialized/valid bytes in the packet
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # let mut buf = [0u8; 2 * 1024];
+    /// # let mut packet = xdp::Packet::testing_new(&mut buf);
+    ///
+    /// assert_eq!(0, packet.len());
+    /// packet.insert(0, &[2; 21]).expect("failed to insert slice");
+    /// assert_eq!(21, packet.len());
+    /// ```
     #[inline]
     pub fn len(&self) -> usize {
         self.tail - self.head
     }
 
     /// True if the packet is empty
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # let mut buf = [0u8; 2 * 1024];
+    /// # let mut packet = xdp::Packet::testing_new(&mut buf);
+    ///
+    /// assert!(packet.is_empty());
+    /// packet.insert(0, &[1]).expect("failed to insert slice");
+    /// assert!(!packet.is_empty());
+    /// ```
     #[inline]
     pub fn is_empty(&self) -> bool {
         self.head == self.tail
@@ -184,29 +211,54 @@ impl Packet {
     ///
     /// Note that this never includes the [`libc::xdp::XDP_PACKET_HEADROOM`]
     /// part of every packet
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let mut umem = xdp::Umem::map(
+    ///     xdp::umem::UmemCfgBuilder::default().build().unwrap()
+    /// ).expect("failed to map Umem");
+    ///
+    /// unsafe {
+    ///     let packet = umem.alloc().expect("failed to allocate packet");
+    ///     // The default size is 4k (page size)
+    ///     assert_eq!(packet.capacity(), 4 * 1024 - xdp::libc::xdp::XDP_PACKET_HEADROOM as usize);
+    /// }
+    /// ```
     #[inline]
     pub fn capacity(&self) -> usize {
         self.capacity
     }
 
     /// Resets the tail of this packet, causing it to become empty
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # let mut buf = [0u8; 2 * 1024];
+    /// # let mut packet = xdp::Packet::testing_new(&mut buf);
+    ///
+    /// assert!(packet.is_empty());
+    /// packet.insert(0, &[2; 21]).expect("failed to insert slice");
+    /// packet.clear();
+    /// assert!(packet.is_empty());
+    /// ```
     #[inline]
     pub fn clear(&mut self) {
         self.tail = self.head;
     }
 
-    /// If true, this packet is partial, and the next packet in the RX continues
-    /// this packet, until this returns fals
+    /// If true, this packet is fragmented, and the next packet in the queue
+    /// continues this packet, until this returns `false`
     #[inline]
     pub fn is_continued(&self) -> bool {
         (self.options & libc::xdp::XdpPktOptions::XDP_PKT_CONTD) != 0
     }
 
+    // TODO: Create a different type to indicate checksum since it's not going
+    // to change so the user can choose at init time whether they want checksum
+    // offload or not
     /// Checks if the NIC this packet is being sent on supports tx checksum offload
-    ///
-    /// TODO: Create a different type to indicate checksum since it's not going
-    /// to change so the user can choose at init time whether they want checksum
-    /// offload or not
     #[inline]
     pub fn can_offload_checksum(&self) -> bool {
         (self.options & libc::InternalXdpFlags::SUPPORTS_CHECKSUM_OFFLOAD) != 0
@@ -219,6 +271,38 @@ impl Packet {
     /// to copy the entirety of the packet data up or down.
     ///
     /// Adjusting the head down requires that headroom was configured for the [`crate::Umem`]
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let mut umem = xdp::Umem::map(
+    ///     xdp::umem::UmemCfgBuilder {
+    ///         head_room: 20,
+    ///         ..Default::default()
+    ///     }.build().unwrap()
+    /// ).expect("failed to map Umem");
+    ///
+    /// unsafe {
+    ///     let mut packet = umem.alloc().expect("failed to allocate packet");
+    ///
+    ///     // We can't extend the head past the tail, so first insert some data
+    ///     packet.insert(0, &[0xff; 33]).unwrap();
+    ///     assert_eq!(33, packet.len());
+    ///
+    ///     // Adjust the head up to match the tail, making the packet empty
+    ///     packet.adjust_head(33).unwrap();
+    ///     assert!(packet.is_empty());
+    ///
+    ///     // When using alloc, the head is already adjust to the headroom, the
+    ///     // same as the kernel would do when receiving a packet, so we can
+    ///     // adjust the head down further
+    ///     packet.adjust_head(-53).unwrap();
+    ///     assert_eq!(53, packet.len());
+    ///
+    ///     // ...but no further
+    ///     assert!(packet.adjust_head(-1).is_err());
+    /// }
+    /// ```
     #[inline]
     pub fn adjust_head(&mut self, diff: i32) -> Result<(), PacketError> {
         if diff < 0 {
@@ -247,6 +331,32 @@ impl Packet {
     ///
     /// This method is the equivalent of [`bpf_xdp_adjust_tail`](https://docs.ebpf.io/linux/helper-function/bpf_xdp_adjust_tail/),
     /// and allows extending or truncating the data portion of a packet
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let mut umem = xdp::Umem::map(
+    ///     xdp::umem::UmemCfgBuilder {
+    ///         head_room: 20,
+    ///         ..Default::default()
+    ///     }.build().unwrap()
+    /// ).expect("failed to map Umem");
+    ///
+    /// unsafe {
+    ///     let mut packet = umem.alloc().expect("failed to allocate packet");
+    ///     packet.insert(0, &[0xff; 10]).unwrap();
+    ///     assert_eq!(10, packet.len());
+    ///
+    ///     for _ in 0..10 {
+    ///         packet.adjust_tail(-1).expect("failed to reduce tail");
+    ///     }
+    ///
+    ///     assert!(packet.is_empty());
+    ///     
+    ///     packet.adjust_tail(10).expect("failed to extend the tail");
+    ///     assert_eq!(&packet[..10], &[0xff; 10]);
+    /// }
+    /// ```
     #[inline]
     pub fn adjust_tail(&mut self, diff: i32) -> Result<(), PacketError> {
         if diff < 0 {
@@ -277,6 +387,40 @@ impl Packet {
     ///
     /// - The offset is not within bounds
     /// - The offset + size of `T` is not within bounds
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use xdp::packet::net_types;
+    /// use std::net::Ipv4Addr;
+    /// # use xdp::packet::Pod;
+    /// # let mut umem = xdp::Umem::map(
+    /// #    xdp::umem::UmemCfgBuilder {
+    /// #        head_room: 20,
+    /// #        ..Default::default()
+    /// #    }.build().unwrap()
+    /// # ).expect("failed to map Umem");
+    /// # let mut packet = unsafe {
+    /// #    let mut packet = umem.alloc().expect("failed to allocate packet");
+    /// #    packet.adjust_tail(34).unwrap();
+    /// #    packet.write(0, net_types::EthHdr {
+    /// #        source: net_types::MacAddress([1; 6]),
+    /// #        destination: net_types::MacAddress([2; 6]),
+    /// #        ether_type: net_types::EtherType::Ipv4 }
+    /// #    ).unwrap();
+    /// #    let mut ip = net_types::Ipv4Hdr::zeroed();
+    /// #    ip.reset(64, net_types::IpProto::Udp);
+    /// #    ip.source = u32::from_be_bytes([100, 1, 2, 100]).into();
+    /// #    ip.destination = u32::from_be_bytes([200, 2, 1, 200]).into();
+    /// #    packet.write(net_types::EthHdr::LEN, ip).unwrap();
+    /// #    assert_eq!(packet.len(), net_types::EthHdr::LEN + net_types::Ipv4Hdr::LEN);
+    /// #    packet
+    /// # };
+    /// // Read an Ipv4 header, which directly follows an Ethernet II header
+    /// let ip_hdr = packet.read::<net_types::Ipv4Hdr>(net_types::EthHdr::LEN).unwrap();
+    /// assert_eq!(ip_hdr.source.host(), Ipv4Addr::new(100, 1, 2, 100).to_bits());
+    /// assert_eq!(ip_hdr.destination.host(), Ipv4Addr::new(200, 2, 1, 200).to_bits());
+    /// ```
     #[inline]
     pub fn read<T: Pod>(&self, offset: usize) -> Result<T, PacketError> {
         let start = self.head + offset;
@@ -309,6 +453,50 @@ impl Packet {
     ///
     /// - The offset is not within bounds
     /// - The offset + size of `T` is not within bounds
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use xdp::packet::net_types;
+    /// use std::net::Ipv4Addr;
+    /// # use xdp::packet::Pod;
+    /// # let mut umem = xdp::Umem::map(
+    /// #    xdp::umem::UmemCfgBuilder {
+    /// #        head_room: 0,
+    /// #        ..Default::default()
+    /// #    }.build().unwrap()
+    /// # ).expect("failed to map Umem");
+    /// # let mut packet = unsafe {
+    /// #    umem.alloc().expect("failed to allocate packet")
+    /// # };
+    /// // Extend the tail so we have enough space for the writes
+    /// packet.adjust_tail(42).unwrap();
+    ///
+    /// packet.write(0, net_types::EthHdr {
+    ///     source: net_types::MacAddress([1; 6]),
+    ///     destination: net_types::MacAddress([2; 6]),
+    ///     ether_type: net_types::EtherType::Ipv4 }
+    /// ).expect("failed to write ethhdr");
+    ///
+    /// let mut ip = net_types::Ipv4Hdr::zeroed();
+    /// ip.reset(64, net_types::IpProto::Udp);
+    /// ip.source = u32::from_be_bytes([100, 1, 2, 100]).into();
+    /// ip.destination = u32::from_be_bytes([200, 2, 1, 200]).into();
+    /// ip.total_length = ((net_types::Ipv4Hdr::LEN + net_types::UdpHdr::LEN + 5) as u16).into();
+    /// packet.write(net_types::EthHdr::LEN, ip).expect("failed to write ip hdr");
+    ///
+    /// packet.write(net_types::EthHdr::LEN + net_types::Ipv4Hdr::LEN, net_types::UdpHdr {
+    ///     source: 50000.into(),
+    ///     destination: 80.into(),
+    ///     length: ((net_types::UdpHdr::LEN + 5) as u16).into(),
+    ///     check: 0,
+    /// }).expect("failed to write ip hdr");
+    ///
+    /// packet.insert(
+    ///     net_types::EthHdr::LEN + net_types::Ipv4Hdr::LEN + net_types::UdpHdr::LEN,
+    ///     &[0xf0; 5]
+    /// ).unwrap();
+    /// ```
     #[inline]
     pub fn write<T: Pod>(&mut self, offset: usize, item: T) -> Result<(), PacketError> {
         let start = self.head + offset;
@@ -344,6 +532,28 @@ impl Packet {
     ///
     /// - The offset is not within bounds
     /// - The offset + `N` is not within bounds
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use xdp::packet::Pod;
+    /// # let mut umem = xdp::Umem::map(
+    /// #    xdp::umem::UmemCfgBuilder {
+    /// #        head_room: 0,
+    /// #        ..Default::default()
+    /// #    }.build().unwrap()
+    /// # ).expect("failed to map Umem");
+    /// # let mut packet = unsafe {
+    /// #    umem.alloc().expect("failed to allocate packet")
+    /// # };
+    /// // Insert a u32
+    /// packet.insert(0, &0xaabbccddu32.to_ne_bytes()).unwrap();
+    ///
+    /// let mut bytes = [0u8; 4];
+    /// packet.array_at_offset(0, &mut bytes).unwrap();
+    ///
+    /// assert_eq!(u32::from_ne_bytes(bytes), 0xaabbccddu32);
+    /// ```
     #[inline]
     pub fn array_at_offset<const N: usize>(
         &self,
@@ -377,6 +587,36 @@ impl Packet {
     ///
     /// - The offset is not within bounds
     /// - The offset + `slice.len()` would exceed the capacity
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use xdp::packet::Pod;
+    /// # let mut umem = xdp::Umem::map(
+    /// #    xdp::umem::UmemCfgBuilder {
+    /// #        head_room: 0,
+    /// #        ..Default::default()
+    /// #    }.build().unwrap()
+    /// # ).expect("failed to map Umem");
+    /// # let mut packet = unsafe {
+    /// #    umem.alloc().expect("failed to allocate packet")
+    /// # };
+    /// // Insert a u32
+    /// packet.insert(0, &0xf0f1f2f3u32.to_ne_bytes()).unwrap();
+    ///
+    /// // Insert a u64
+    /// packet.insert(0, &u64::MAX.to_ne_bytes()).unwrap();
+    ///
+    /// let mut bytes = [0u8; 8];
+    /// packet.array_at_offset(0, &mut bytes).unwrap();
+    ///
+    /// assert_eq!(u64::from_ne_bytes(bytes), u64::MAX);
+    ///
+    /// let mut bytes = [0u8; 4];
+    /// packet.array_at_offset(8, &mut bytes).unwrap();
+    ///
+    /// assert_eq!(u32::from_ne_bytes(bytes), 0xf0f1f2f3);
+    /// ```
     #[inline]
     pub fn insert(&mut self, offset: usize, slice: &[u8]) -> Result<(), PacketError> {
         if self.tail + slice.len() > self.capacity {
@@ -454,9 +694,12 @@ impl Packet {
         unsafe {
             let mut tx_meta = std::mem::zeroed::<xdp::xsk_tx_metadata>();
 
-            if let CsumOffload::Request(csum_req) = csum {
+            if let CsumOffload::Request { start, offset } = csum {
                 tx_meta.flags |= xdp::XdpTxFlags::XDP_TXMD_FLAGS_CHECKSUM;
-                tx_meta.offload.request = csum_req;
+                tx_meta.offload.request = xdp::xsk_tx_request {
+                    csum_start: start,
+                    csum_offset: offset,
+                };
             }
 
             if request_timestamp {