Skip to main content

shadow_rs/network/
packet.rs

1use std::io::Write;
2use std::mem::MaybeUninit;
3use std::net::{IpAddr, SocketAddrV4};
4use std::sync::Arc;
5
6use crate::host::network::interface::FifoPacketPriority;
7use crate::utility::ObjectCounter;
8use crate::utility::pcap_writer::PacketDisplay;
9
10use atomic_refcell::AtomicRefCell;
11use bytes::Bytes;
12use shadow_shim_helper_rs::HostId;
13
14/// Represents different checkpoints that a packet reaches as it is being moved around in Shadow.
15#[derive(Copy, Clone, Debug)]
16pub enum PacketStatus {
17    SndCreated,
18    SndTcpEnqueueThrottled,
19    SndTcpEnqueueRetransmit,
20    SndTcpDequeueRetransmit,
21    SndTcpRetransmitted,
22    SndSocketBuffered,
23    SndInterfaceSent,
24    InetSent,
25    InetDropped,
26    RouterEnqueued,
27    RouterDequeued,
28    RouterDropped,
29    RcvInterfaceReceived,
30    RcvInterfaceDropped,
31    RcvSocketProcessed,
32    RcvSocketDropped,
33    RcvTcpEnqueueUnordered,
34    RcvSocketBuffered,
35    RcvSocketDelivered,
36    Destroyed,
37    RelayCached,
38    RelayForwarded,
39}
40
41/// Official IANA-assigned protocols supported in our packets.
42#[derive(Copy, Clone, Debug, Eq, Hash, PartialEq)]
43pub enum IanaProtocol {
44    Tcp,
45    Udp,
46}
47
48impl IanaProtocol {
49    /// The IANA-assigned protocol number. This value is guaranteed to be unique for distinct
50    /// protocol variants.
51    pub fn number(&self) -> u8 {
52        // The specific values assigned here should not be changed since they are used to produce
53        // correctly formatted pcap files.
54        // https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml
55        match self {
56            IanaProtocol::Tcp => 6,
57            IanaProtocol::Udp => 17,
58        }
59    }
60}
61
62/// A packet's type of service (TOS) indicates its desired queuing priority. This may be used by
63/// Shadow's interface qdisc to prioritize packets that it sends out to the network. For example,
64/// in the `pfifo_fast` qdisc, packets in lower priority bands would be sent ahead of others.
65// https://lartc.org/howto/lartc.qdisc.classless.html
66#[derive(Copy, Clone, Debug, PartialEq)]
67pub enum TypeOfService {
68    /// Corresponds to "Best Effort" priority (band 1).
69    Normal,
70    /// Corresponds to "Interactive" priority (band 0).
71    MinimizeDelay,
72    /// Corresponds to "Best Effort" priority (band 1).
73    MaximizeReliability,
74    /// Corresponds to "Bulk" priority (band 2).
75    MaximizeThroughput,
76}
77
78/// A thread-safe shared reference to a `Packet`.
79///
80/// Although a `PacketRc` is thread-safe, a panic may occur if multiple threads concurrently write
81/// `PacketStatus` metadata on the inner `Packet`. Thus, use `new_copy_inner()` to copy the inner
82/// `Packet` and send the copy to the other thread rather than sharing it between threads.
83///
84/// A `PacketRc` is a wrapper around a `Packet` and allows us to support reference counting on
85/// `Packet`s while safely sharing them across threads. A clone of a `PacketRc`s increments the
86/// reference count of the shared `Packet` while dropping the `PacketRc` decrements the reference
87/// count. The shared inner `Packet` is only dropped when all `PacketRc`s referring to it are also
88/// dropped (i.e., the reference count reaches zero).
89///
90/// The `PartialEq` implementation on `PacketRc` compares the pointer values of the wrapped
91/// `Packet`.
92///
93/// `PacketRc` implements the `Deref` trait so that all non-associated functions on `Packet` can be
94/// accessed from instances of `PacketRc` too.
95#[derive(Clone, Debug)]
96pub struct PacketRc {
97    inner: Arc<Packet>,
98}
99
100impl PacketRc {
101    /// Creates a thread-safe shared reference to a new `Packet` using the provided information.
102    /// Additional references to the `Packet` can be cheaply obtained by cloning the returned
103    /// `PacketRc`. The `Packet` is dropped when its last `PacketRc` reference is dropped.
104    ///
105    /// See `Packet::new_ipv4_tcp()` for more details.
106    pub fn new_ipv4_tcp(
107        header: tcp::TcpHeader,
108        payload: tcp::Payload,
109        priority: FifoPacketPriority,
110    ) -> Self {
111        Self::from(Packet::new_ipv4_tcp(header, payload, priority))
112    }
113
114    /// Creates a thread-safe shared reference to a new `Packet` using the provided information.
115    /// Additional references to the `Packet` can be cheaply obtained by cloning the returned
116    /// `PacketRc`. The `Packet` is dropped when its last `PacketRc` reference is dropped.
117    ///
118    /// See `Packet::new_ipv4_udp()` for more details.
119    pub fn new_ipv4_udp(
120        src: SocketAddrV4,
121        dst: SocketAddrV4,
122        payload: Bytes,
123        priority: FifoPacketPriority,
124    ) -> Self {
125        Self::from(Packet::new_ipv4_udp(src, dst, payload, priority))
126    }
127
128    /// Creates a new IPv4 UDP packet for unit tests with unspecified source and destination
129    /// addresses and header information and a payload of 1_000 bytes.
130    /// Additional references to the `Packet` can be cheaply obtained by cloning the returned
131    /// `PacketRc`. The `Packet` is dropped when its last `PacketRc` reference is dropped.
132    ///
133    /// See `Packet::new_ipv4_udp_mock()` for more details.
134    #[cfg(test)]
135    pub fn new_ipv4_udp_mock() -> Self {
136        let unspec = SocketAddrV4::new(std::net::Ipv4Addr::UNSPECIFIED, 0);
137        Self::new_ipv4_udp_mock_with(unspec, unspec, 1_000)
138    }
139
140    /// Creates a thread-safe shared reference to a new `Packet` using the provided information.
141    /// Additional references to the `Packet` can be cheaply obtained by cloning the returned
142    /// `PacketRc`. The `Packet` is dropped when its last `PacketRc` reference is dropped.
143    ///
144    /// See `Packet::new_ipv4_udp_mock()` for more details.
145    #[cfg(test)]
146    pub fn new_ipv4_udp_mock_with(
147        src: SocketAddrV4,
148        dst: SocketAddrV4,
149        payload_len: usize,
150    ) -> Self {
151        Self::from(Packet::new_ipv4_udp_mock(src, dst, payload_len))
152    }
153
154    /// Creates a thread-safe shared reference to a new `Packet` that is created by performing a
155    /// copy of the provided referenced `Packet`. This function copies all packet data _except_ the
156    /// packet payload, which is shared by incrementing its reference count. Additional references
157    /// to the `Packet` can be cheaply obtained by cloning the returned `PacketRc`. The `Packet` is
158    /// dropped when its last `PacketRc` reference is dropped.
159    pub fn new_copy_inner(&self) -> Self {
160        // We want a copy of the inner packet, since cloning the `Arc` wrapper would just increase
161        // the reference count.
162        Self::from(self.inner.as_ref().clone())
163    }
164
165    /// Transfers ownership of the given packet_ptr reference into a new `PacketRc` object. The provided
166    /// pointer must have been obtained from a call to the Rust function `PacketRc::into_raw()` or
167    /// the C function `packet_new_tcp()`.
168    ///
169    /// Use `PacketRc::into_raw()` if the returned reference is to be handed back to C code.
170    ///
171    /// # Panics
172    ///
173    /// This function panics if the supplied packet pointer is NULL.
174    ///
175    /// # Deprecation
176    ///
177    /// This function provides compatibility with the legacy C TCP stack and should be considered
178    /// deprecated and removed when the legacy C TCP stack is removed.
179    pub fn from_raw(packet_ptr: *mut Packet) -> Self {
180        assert!(!packet_ptr.is_null());
181        Self {
182            inner: unsafe { Arc::from_raw(packet_ptr) },
183        }
184    }
185
186    /// Transfers ownership of the inner Arc reference to the caller while dropping the `PacketRc`.
187    ///
188    /// To avoid a memory leak, the returned pointer must be either reconstituted into a `PacketRc`
189    /// using the Rust function `PacketRc::from_raw()`, or dropped using the C function
190    /// `packet_unref()`.
191    ///
192    /// Although this returns a `*mut Packet` pointer, the packet is not actually mutuable. We
193    /// return a `*mut Packet` pointer only to avoid having to change the instnaces of the pointers
194    /// to const instances in the C network code.
195    ///
196    /// # Deprecation
197    ///
198    /// This function provides compatibility with the legacy C TCP stack and should be considered
199    /// deprecated and removed when the legacy C TCP stack is removed.
200    pub fn into_raw(self) -> *mut Packet {
201        Arc::into_raw(self.inner).cast_mut()
202    }
203
204    /// Borrow a reference that is owned by the C code so that we can temporarily operate on the
205    /// packet in a Rust context. The reference count of the underlying `Packet` will be the same
206    /// after the returned `PacketRc` is dropped as it was before calling this function. The C code
207    /// that owns the reference is still responsible for dropping it.
208    ///
209    /// # Panics
210    ///
211    /// This function panics if the supplied packet pointer is NULL.
212    ///
213    /// # Deprecation
214    ///
215    /// This function provides compatibility with the legacy C TCP stack and should be considered
216    /// deprecated and removed when the legacy C TCP stack is removed.
217    fn borrow_raw(packet_ptr: *const Packet) -> Self {
218        assert!(!packet_ptr.is_null());
219        unsafe { Arc::increment_strong_count(packet_ptr) };
220        PacketRc::from_raw(packet_ptr.cast_mut())
221    }
222
223    /// The same as `PacketRc::borrow_raw()` but this version handles a `*mut` packet pointer.
224    ///
225    /// # Panics
226    ///
227    /// This function panics if the supplied packet pointer is NULL.
228    ///
229    /// # Deprecation
230    ///
231    /// This function provides compatibility with the legacy C TCP stack and should be considered
232    /// deprecated and removed when the legacy C TCP stack is removed.
233    fn borrow_raw_mut(packet_ptr: *mut Packet) -> Self {
234        Self::borrow_raw(packet_ptr.cast_const())
235    }
236}
237
238impl PartialEq for PacketRc {
239    /// Compares the pointer rather than the value of the inner `Arc<Packet>` object.
240    fn eq(&self, other: &Self) -> bool {
241        // Two `PacketRc`s are considered equal if they point to the same shared `Packet`.
242        Arc::ptr_eq(&self.inner, &other.inner)
243    }
244}
245
246impl Eq for PacketRc {}
247
248impl From<Packet> for PacketRc {
249    fn from(packet: Packet) -> Self {
250        Self {
251            inner: Arc::new(packet),
252        }
253    }
254}
255
256// Non-associated functions on `Packet` can be accessed from instances of `PacketRc`.
257impl std::ops::Deref for PacketRc {
258    type Target = Packet;
259    fn deref(&self) -> &Self::Target {
260        self.inner.as_ref()
261    }
262}
263
264/// Holds networking information and payload data that assists in sending managed-process bytes
265/// between different sockets and hosts over the simulation network.
266///
267/// The `Packet` is designed to separate the IP layer header from the transport layer data, to make
268/// it easier to support new transport protocols in the future. Thus, the `Packet` has a `Header` to
269/// store IP header information, and a `Data` to store transport-specific data (e.g., A TCP header
270/// and payload for TCP, or a UDP header and payload for UDP).
271///
272/// The `Packet` is designed to be read-only after creation to simplify implementation and to reduce
273/// the need for mutable borrows.
274///
275/// # Deprecation
276///
277/// As an exception to the read-only design, some legacy TCP data is mutable to support the legacy C
278/// TCP stack. When the legacy TCP stack and the `Packet`'s C interface is removed, mutability will
279/// also be removed.
280#[derive(Clone, Debug)]
281pub struct Packet {
282    header: Header,
283    data: Data,
284    meta: Metadata,
285    _counter: ObjectCounter,
286}
287
288impl Packet {
289    /// Creates a new `Packet` with the pre-constructed objects.
290    ///
291    /// This function is private because we do not expose the inner `Packet` structures.
292    fn new(header: Header, data: Data, meta: Metadata) -> Self {
293        Self {
294            header,
295            data,
296            meta,
297            _counter: ObjectCounter::new("Packet"),
298        }
299    }
300
301    /// Creates a new IPv4 TCP packet using the provided data.
302    pub fn new_ipv4_tcp(
303        header: tcp::TcpHeader,
304        payload: tcp::Payload,
305        priority: FifoPacketPriority,
306    ) -> Self {
307        let hdr = header;
308        let header = Header::new(IpAddr::V4(hdr.ip.src), IpAddr::V4(hdr.ip.dst));
309
310        let tcp_packet = TcpData::new(TcpHeader::from(hdr), payload.0);
311        let data = Data::from(tcp_packet);
312
313        let meta = Metadata::new(priority);
314
315        Self::new(header, data, meta)
316    }
317
318    /// Creates a new IPv4 UDP packet using the provided data.
319    pub fn new_ipv4_udp(
320        src: SocketAddrV4,
321        dst: SocketAddrV4,
322        payload: Bytes,
323        priority: FifoPacketPriority,
324    ) -> Self {
325        let header = Header::new(IpAddr::V4(*src.ip()), IpAddr::V4(*dst.ip()));
326
327        let udp_header = UdpHeader::new(src.port(), dst.port());
328        let udp_packet = UdpData::new(udp_header, payload);
329        let data = Data::from(udp_packet);
330
331        let meta = Metadata::new(priority);
332
333        Self::new(header, data, meta)
334    }
335
336    /// Creates a new IPv4 UDP packet for unit tests with given `src` and `dst`
337    /// addresses and a payload of `size` bytes.
338    #[cfg(test)]
339    pub fn new_ipv4_udp_mock(src: SocketAddrV4, dst: SocketAddrV4, payload_len: usize) -> Self {
340        // Some of our tests require packets with payloads.
341        Self::new_ipv4_udp(src, dst, Bytes::from(vec![0u8; payload_len]), 0)
342    }
343
344    /// If the packet is an IPv4 TCP packet, returns a copy of the TCP header in a format defined by
345    /// the Rust TCP stack. Otherwise, returns `None`.
346    ///
347    /// Panics
348    ///
349    /// This function panics if the packet was created with `packet_new_tcp()` in the legacy C API.
350    pub fn ipv4_tcp_header(&self) -> Option<tcp::TcpHeader> {
351        let hdr = &self.header;
352
353        let IpAddr::V4(src) = hdr.src else {
354            return None;
355        };
356        let IpAddr::V4(dst) = hdr.dst else {
357            return None;
358        };
359
360        let tcp_hdr = match &self.data {
361            // The legacy TCP header is obtained with `packet_getTCPHeader()` in the legacy C API.
362            Data::LegacyTcp(_) => unimplemented!(),
363            Data::Tcp(tcp) => tcp.header.clone(),
364            Data::Udp(_) => return None,
365        };
366
367        Some(tcp::TcpHeader {
368            ip: tcp::Ipv4Header { src, dst },
369            flags: tcp_hdr.flags,
370            src_port: tcp_hdr.src_port,
371            dst_port: tcp_hdr.dst_port,
372            seq: tcp_hdr.sequence,
373            ack: tcp_hdr.acknowledgement,
374            window_size: tcp_hdr.window_size,
375            selective_acks: tcp_hdr.selective_acks.map(|x| x.into()),
376            window_scale: tcp_hdr.window_scale,
377            timestamp: tcp_hdr.timestamp,
378            timestamp_echo: tcp_hdr.timestamp_echo,
379        })
380    }
381
382    /// Returns the packet's payload that was provided at packet creation time. This function
383    /// allocates a new `Vec`, but is zero-copy with respect to the payload `Bytes`.
384    ///
385    /// This function may return a non-empty vector of zero-length `Bytes` object(s) if zero-length
386    /// `Bytes` object(s) were provided at creation time. Thus, it may be helpful to check if the
387    /// packet has useful payload using `payload_len()` before calling this function.
388    //
389    // TODO: after we remove the legacy C TCP stack, then all packet creation functions will require
390    // a pre-set payload, and we do not add more bytes later. Thus, we can then store them as a
391    // slice of `Bytes` rather than a `Vec<Bytes>`.
392    pub fn payload(&self) -> Vec<Bytes> {
393        match &self.data {
394            Data::LegacyTcp(tcp_rc) => tcp_rc.borrow().payload.clone(),
395            Data::Tcp(tcp) => tcp.payload.clone(),
396            Data::Udp(udp) => vec![udp.payload.clone()],
397        }
398    }
399
400    /// Returns the total simulated length of the packet, which is the sum of the emulated IP and
401    /// transport header lengths and the payload length.
402    #[allow(clippy::len_without_is_empty)]
403    pub fn len(&self) -> usize {
404        self.header.len().checked_add(self.data.len()).unwrap()
405    }
406
407    /// Returns the total number of payload bytes stored in the packet, which excludes IP and
408    /// transport header lengths.
409    pub fn payload_len(&self) -> usize {
410        self.data.payload_len()
411    }
412
413    /// Appends the provided packet status to the list of the packet's status checkpoints.
414    ///
415    /// This function has no effect unless `log::Level::Trace` is enabled.
416    pub fn add_status(&self, status: PacketStatus) {
417        if log::log_enabled!(log::Level::Trace) {
418            if let Some(vec) = self.meta.statuses.as_ref() {
419                vec.borrow_mut().push(status);
420            }
421            log::trace!("[{status:?}] {self:?}");
422        }
423    }
424
425    /// Returns the packet's IPv4 source address and source port.
426    ///
427    /// Panics
428    ///
429    /// This function panics if the source address is not an IPv4 address.
430    pub fn src_ipv4_address(&self) -> SocketAddrV4 {
431        let IpAddr::V4(addr) = self.header.src else {
432            unimplemented!()
433        };
434
435        let port = match &self.data {
436            Data::LegacyTcp(tcp_rc) => tcp_rc.borrow().header.src_port,
437            Data::Tcp(tcp) => tcp.header.src_port,
438            Data::Udp(udp) => udp.header.src_port,
439        };
440
441        SocketAddrV4::new(addr, port)
442    }
443
444    /// Returns the packet's IPv4 destination address and destination port.
445    ///
446    /// Panics
447    ///
448    /// This function panics if the destination address is not an IPv4 address.
449    pub fn dst_ipv4_address(&self) -> SocketAddrV4 {
450        let IpAddr::V4(addr) = self.header.dst else {
451            unimplemented!()
452        };
453
454        let port = match &self.data {
455            Data::LegacyTcp(tcp_rc) => tcp_rc.borrow().header.dst_port,
456            Data::Tcp(tcp) => tcp.header.dst_port,
457            Data::Udp(udp) => udp.header.dst_port,
458        };
459
460        SocketAddrV4::new(addr, port)
461    }
462
463    /// Returns the priority set at packet creation time.
464    pub fn priority(&self) -> FifoPacketPriority {
465        self.meta.priority
466    }
467
468    /// Returns the packet's iana-assigned protocol type.
469    pub fn iana_protocol(&self) -> IanaProtocol {
470        self.data.iana_protocol()
471    }
472}
473
474/// Stores the IP header information.
475#[derive(Clone, Debug)]
476struct Header {
477    src: IpAddr,
478    dst: IpAddr,
479    _tos: TypeOfService,
480}
481
482impl Header {
483    pub fn new(src: IpAddr, dst: IpAddr) -> Self {
484        // TODO: make TOS configurable, then the network queue can do pfifo properly.
485        Self {
486            src,
487            dst,
488            _tos: TypeOfService::Normal,
489        }
490    }
491
492    pub fn len(&self) -> usize {
493        match &self.dst {
494            // 20 bytes without options: https://en.wikipedia.org/wiki/IPv4
495            IpAddr::V4(_) => 20usize,
496            // 40 bytes: https://en.wikipedia.org/wiki/IPv6
497            IpAddr::V6(_) => 40usize,
498        }
499    }
500}
501
502/// Stores the data part of an IP packet. The data segment varies depending on the protocol being
503/// carried by the packet.
504#[derive(Clone, Debug)]
505enum Data {
506    // We need a mutable TCP packet to support the legacy TCP stack, which writes some header and
507    // payload data after the packet was created.
508    LegacyTcp(AtomicRefCell<TcpData>),
509    Tcp(TcpData),
510    Udp(UdpData),
511}
512
513impl Data {
514    pub fn len(&self) -> usize {
515        match self {
516            Data::LegacyTcp(tcp_ref) => tcp_ref.borrow().len(),
517            Data::Tcp(tcp) => tcp.len(),
518            Data::Udp(udp) => udp.len(),
519        }
520    }
521
522    pub fn payload_len(&self) -> usize {
523        match self {
524            Data::LegacyTcp(tcp_ref) => tcp_ref.borrow().payload_len(),
525            Data::Tcp(tcp) => tcp.payload_len(),
526            Data::Udp(udp) => udp.payload_len(),
527        }
528    }
529
530    pub fn iana_protocol(&self) -> IanaProtocol {
531        match self {
532            Data::LegacyTcp(tcp_ref) => tcp_ref.borrow().iana_protocol(),
533            Data::Tcp(tcp) => tcp.iana_protocol(),
534            Data::Udp(udp) => udp.iana_protocol(),
535        }
536    }
537}
538
539impl From<UdpData> for Data {
540    fn from(packet: UdpData) -> Self {
541        Self::Udp(packet)
542    }
543}
544
545impl From<TcpData> for Data {
546    fn from(packet: TcpData) -> Self {
547        Self::Tcp(packet)
548    }
549}
550
551/// The data portion of an IP packet that contains TCP protocol information, including a TCP header
552/// and payload.
553#[derive(Clone, Debug)]
554struct TcpData {
555    // We don't use `tcp::TcpHeader` here because it includes non-transport layer data (IP headers).
556    header: TcpHeader,
557    // A vector allows us to store the payload in multiple separate chunks.
558    // Consider using `SmallVec` instead. I'm not sure what the improvement would be, and it if is
559    // worth adding in the extra dependency on the `SmallVec` code here.
560    payload: Vec<Bytes>,
561}
562
563impl TcpData {
564    pub fn new(header: TcpHeader, payload: Vec<Bytes>) -> Self {
565        Self { header, payload }
566    }
567
568    pub fn len(&self) -> usize {
569        self.header.len().checked_add(self.payload_len()).unwrap()
570    }
571
572    pub fn payload_len(&self) -> usize {
573        self.payload
574            .iter()
575            // `fold` rather than `sum` so that we always panic on overflow
576            .fold(0usize, |acc, x| acc.checked_add(x.len()).unwrap())
577    }
578
579    pub fn iana_protocol(&self) -> IanaProtocol {
580        IanaProtocol::Tcp
581    }
582}
583
584/// A TCP header contains protocol information including ports, sequence numbers, and other
585/// protocol-specific information.
586#[derive(Clone, Debug, PartialEq)]
587struct TcpHeader {
588    src_port: u16,
589    dst_port: u16,
590    flags: tcp::TcpFlags,
591    sequence: u32,
592    acknowledgement: u32,
593    window_size: u16,
594    selective_acks: Option<TcpSelectiveAcks>,
595    window_scale: Option<u8>,
596    timestamp: Option<u32>,
597    timestamp_echo: Option<u32>,
598}
599
600impl TcpHeader {
601    // Unused now, but want to allow its use in the future.
602    #[allow(dead_code)]
603    pub fn new(
604        src_port: u16,
605        dst_port: u16,
606        flags: tcp::TcpFlags,
607        sequence: u32,
608        acknowledgement: u32,
609        window_size: u16,
610        selective_acks: Option<TcpSelectiveAcks>,
611        window_scale: Option<u8>,
612        timestamp: Option<u32>,
613        timestamp_echo: Option<u32>,
614    ) -> Self {
615        Self {
616            src_port,
617            dst_port,
618            sequence,
619            flags,
620            acknowledgement,
621            window_size,
622            selective_acks,
623            window_scale,
624            timestamp,
625            timestamp_echo,
626        }
627    }
628
629    // This function must be kept in sync with `display_bytes()`.
630    // TODO: is there a better way of keeping this logic in sync with similar logic in
631    // `display_bytes()`?
632    pub fn len(&self) -> usize {
633        // Base is 20 bytes: https://en.wikipedia.org/wiki/Transmission_Control_Protocol
634        let mut len = 20usize;
635
636        // TCP options use additional bytes.
637        if self.window_scale.is_some() {
638            // Window scale option is 3 bytes.
639            len += 3;
640        }
641
642        // TODO: should we consider the length of the selective acks, if any exist?
643
644        // Add padding bytes if needed.
645        if !len.is_multiple_of(4) {
646            len += 4 - (len % 4);
647        }
648
649        len
650    }
651}
652
653impl From<tcp::TcpHeader> for TcpHeader {
654    fn from(hdr: tcp::TcpHeader) -> Self {
655        TcpHeader {
656            src_port: hdr.src_port,
657            dst_port: hdr.dst_port,
658            flags: hdr.flags,
659            sequence: hdr.seq,
660            acknowledgement: hdr.ack,
661            window_size: hdr.window_size,
662            selective_acks: hdr.selective_acks.map(|x| x.into()),
663            window_scale: hdr.window_scale,
664            timestamp: hdr.timestamp,
665            timestamp_echo: hdr.timestamp_echo,
666        }
667    }
668}
669
670#[derive(Clone, Copy, Debug, Default)]
671struct TcpSelectiveAcks {
672    len: u8,
673    // A TCP packet can only hold at most 4 selective ack blocks.
674    ranges: [(u32, u32); 4],
675}
676
677impl From<tcp::util::SmallArrayBackedSlice<4, (u32, u32)>> for TcpSelectiveAcks {
678    fn from(array: tcp::util::SmallArrayBackedSlice<4, (u32, u32)>) -> Self {
679        let mut selective_acks = Self::default();
680
681        for (i, sack) in array.as_ref().iter().enumerate() {
682            selective_acks.ranges[i] = (sack.0, sack.1);
683            selective_acks.len += 1;
684            if selective_acks.len >= 4 {
685                break;
686            }
687        }
688
689        selective_acks
690    }
691}
692
693impl From<TcpSelectiveAcks> for tcp::util::SmallArrayBackedSlice<4, (u32, u32)> {
694    fn from(selective_acks: TcpSelectiveAcks) -> Self {
695        assert!(selective_acks.len <= 4);
696        Self::new(&selective_acks.ranges[0..(selective_acks.len as usize)]).unwrap()
697    }
698}
699
700impl PartialEq for TcpSelectiveAcks {
701    fn eq(&self, other: &Self) -> bool {
702        if self.len != other.len {
703            return false;
704        }
705        for i in 0..self.len as usize {
706            if self.ranges[i] != other.ranges[i] {
707                return false;
708            }
709        }
710        true
711    }
712}
713
714/// The data portion of an IP packet that contains UDP protocol information, including a UDP header
715/// and payload.
716#[derive(Clone, Debug)]
717struct UdpData {
718    header: UdpHeader,
719    payload: Bytes,
720}
721
722impl UdpData {
723    pub fn new(header: UdpHeader, payload: Bytes) -> Self {
724        Self { header, payload }
725    }
726
727    pub fn len(&self) -> usize {
728        self.header.len().checked_add(self.payload_len()).unwrap()
729    }
730
731    pub fn payload_len(&self) -> usize {
732        self.payload.len()
733    }
734
735    pub fn iana_protocol(&self) -> IanaProtocol {
736        IanaProtocol::Udp
737    }
738}
739
740/// A UDP header consists of source and destination port information.
741#[derive(Clone, Debug, PartialEq)]
742struct UdpHeader {
743    src_port: u16,
744    dst_port: u16,
745}
746
747impl UdpHeader {
748    pub fn new(src_port: u16, dst_port: u16) -> Self {
749        Self { src_port, dst_port }
750    }
751
752    pub fn len(&self) -> usize {
753        // 8 bytes: https://en.wikipedia.org/wiki/User_Datagram_Protocol
754        8usize
755    }
756}
757
758#[derive(Clone, Debug)]
759struct Metadata {
760    /// Tracks application priority so we flush packets from the interface to the wire in the order
761    /// intended by the application. This is used in the default FIFO network interface scheduling
762    /// discipline. Smaller values have greater priority.
763    // TODO: this can be removed once we support the TOS field in the `Header` struct.
764    priority: FifoPacketPriority,
765    /// Tracks the sequence of operations that happen on this packet as is transits Shadow's
766    /// network.
767    statuses: Option<AtomicRefCell<Vec<PacketStatus>>>,
768    /// The id of the host that created the packet.
769    ///
770    /// # Deprecation
771    ///
772    /// This is currently set by the legacy C TCP stack to help uniquely identify a packet while
773    /// debugging. It can be removed when the legacy TCP stack and our C packet API is removed.
774    _host_id: Option<HostId>,
775    /// The id of the packet.
776    ///
777    /// # Deprecation
778    ///
779    /// This is currently set by the legacy C TCP stack to help uniquely identify a packet while
780    /// debugging. It can be removed when the legacy TCP stack and our C packet API is removed.
781    _packet_id: Option<u64>,
782}
783
784impl Metadata {
785    pub fn new(priority: FifoPacketPriority) -> Self {
786        Self {
787            priority,
788            _host_id: None,
789            _packet_id: None,
790            // For efficiency, we only store statuses when tracing is enabled because they are
791            // logged at trace level and won't be displayed at other levels anyway.
792            statuses: log::log_enabled!(log::Level::Trace).then(AtomicRefCell::default),
793        }
794    }
795
796    /// Supports creation of legacy TCP stack metadata.
797    ///
798    /// # Deprecation
799    ///
800    /// This is currently used by the legacy C TCP stack and can be removed when the legacy TCP
801    /// stack and our C packet API is removed.
802    fn new_legacy(priority: FifoPacketPriority, host_id: HostId, packet_id: u64) -> Self {
803        Self {
804            priority,
805            _host_id: Some(host_id),
806            _packet_id: Some(packet_id),
807            // For efficiency, we only store statuses when tracing is enabled because they are
808            // logged at trace level and won't be displayed at other levels anyway.
809            statuses: log::log_enabled!(log::Level::Trace).then(AtomicRefCell::default),
810        }
811    }
812}
813
814impl PacketDisplay for Packet {
815    fn display_bytes(&self, mut writer: impl Write) -> std::io::Result<()> {
816        // write the IP header
817
818        let version_and_header_length: u8 = 0x45;
819        let fields: u8 = 0x0;
820        let total_length: u16 = self.len().try_into().unwrap();
821        let identification: u16 = 0x0;
822        let flags_and_fragment: u16 = 0x4000;
823        let time_to_live: u8 = 64;
824        let iana_protocol: u8 = self.data.iana_protocol().number();
825        let header_checksum: u16 = 0x0;
826        let source_ip: [u8; 4] = self.src_ipv4_address().ip().to_bits().to_be_bytes();
827        let dest_ip: [u8; 4] = self.dst_ipv4_address().ip().to_bits().to_be_bytes();
828
829        // version and header length: 1 byte
830        // DSCP + ECN: 1 byte
831        writer.write_all(&[version_and_header_length, fields])?;
832        // total length: 2 bytes
833        writer.write_all(&total_length.to_be_bytes())?;
834        // identification: 2 bytes
835        writer.write_all(&identification.to_be_bytes())?;
836        // flags + fragment offset: 2 bytes
837        writer.write_all(&flags_and_fragment.to_be_bytes())?;
838        // ttl: 1 byte
839        // protocol: 1 byte
840        writer.write_all(&[time_to_live, iana_protocol])?;
841        // header checksum: 2 bytes
842        writer.write_all(&header_checksum.to_be_bytes())?;
843        // source IP: 4 bytes
844        writer.write_all(&source_ip)?;
845        // destination IP: 4 bytes
846        writer.write_all(&dest_ip)?;
847
848        // write protocol-specific data
849
850        match &self.data {
851            Data::LegacyTcp(tcp_ref) => write_tcpdata_bytes(&tcp_ref.borrow(), writer),
852            Data::Tcp(tcp) => write_tcpdata_bytes(tcp, writer),
853            Data::Udp(udp) => write_udpdata_bytes(udp, writer),
854        }?;
855
856        Ok(())
857    }
858}
859
860fn write_tcpdata_bytes(data: &TcpData, mut writer: impl Write) -> std::io::Result<()> {
861    // process TCP options
862
863    let tcp_hdr = &data.header;
864
865    // options can be a max of 40 bytes
866    let mut options = [0u8; 40];
867    let mut options_len = 0;
868
869    if let Some(window_scale) = tcp_hdr.window_scale {
870        // option-kind = 3, option-len = 3, option-data = window-scale
871        options[options_len..][..3].copy_from_slice(&[3, 3, window_scale]);
872        options_len += 3;
873    }
874
875    // TODO: do we want to include selective acks or timestamp options?
876
877    if options_len % 4 != 0 {
878        // need to add padding (our options array was already initialized with zeroes)
879        let padding = 4 - (options_len % 4);
880        options_len += padding;
881    }
882
883    let options = &options[..options_len];
884
885    // process the TCP header
886
887    let mut tcp_flags = tcp_hdr.flags;
888
889    // Header length in bytes. This must be kept in sync with `header().len()`.
890    let header_len: usize = 20usize.checked_add(options.len()).unwrap();
891    assert_eq!(header_len, tcp_hdr.len());
892
893    // Ultimately, TCP header len is represented in 32-bit words, so we divide by 4. The
894    // left-shift of 4 is because the header len is represented in the top 4 bits.
895    let mut header_len = u8::try_from(header_len).unwrap();
896    header_len /= 4;
897    header_len <<= 4;
898
899    // Filter these two bits because we stuff non-TCP legacy flags here on legacy packets.
900    // TODO: remove this filter when the C TCP stack and Data::LegacyTCP packets are removed.
901    tcp_flags.remove(tcp::TcpFlags::ECE);
902    tcp_flags.remove(tcp::TcpFlags::CWR);
903
904    // write the header data
905
906    // source port: 2 bytes
907    writer.write_all(&tcp_hdr.src_port.to_be_bytes())?;
908    // destination port: 2 bytes
909    writer.write_all(&tcp_hdr.dst_port.to_be_bytes())?;
910    // sequence number: 4 bytes
911    writer.write_all(&tcp_hdr.sequence.to_be_bytes())?;
912    // acknowledgement number: 4 bytes
913    writer.write_all(&tcp_hdr.acknowledgement.to_be_bytes())?;
914    // data offset + reserved + NS: 1 byte
915    // flags: 1 byte
916    writer.write_all(&[header_len, tcp_flags.bits()])?;
917    // window size: 2 bytes
918    writer.write_all(&tcp_hdr.window_size.to_be_bytes())?;
919    // checksum: 2 bytes
920    let checksum: u16 = 0u16;
921    writer.write_all(&checksum.to_be_bytes())?;
922    // urgent: 2 bytes
923    let urgent_pointer: u16 = 0u16;
924    writer.write_all(&urgent_pointer.to_be_bytes())?;
925
926    writer.write_all(options)?;
927
928    // write payload data
929
930    for bytes in &data.payload {
931        writer.write_all(bytes)?;
932    }
933
934    Ok(())
935}
936
937fn write_udpdata_bytes(data: &UdpData, mut writer: impl Write) -> std::io::Result<()> {
938    // write the UDP header
939
940    // source port: 2 bytes
941    writer.write_all(&data.header.src_port.to_be_bytes())?;
942    // destination port: 2 bytes
943    writer.write_all(&data.header.dst_port.to_be_bytes())?;
944    // length: 2 bytes
945    let udp_len: u16 = u16::try_from(data.len()).unwrap();
946    writer.write_all(&udp_len.to_be_bytes())?;
947    // checksum: 2 bytes
948    let checksum: u16 = 0x0;
949    writer.write_all(&checksum.to_be_bytes())?;
950
951    // write payload data
952
953    writer.write_all(&data.payload)?;
954
955    Ok(())
956}
957
958#[cfg(test)]
959mod tests {
960    use std::net::Ipv4Addr;
961
962    use super::*;
963
964    #[test]
965    fn ipv4_udp() {
966        let src = SocketAddrV4::new(Ipv4Addr::new(192, 168, 1, 1), 10_000);
967        let dst = SocketAddrV4::new(Ipv4Addr::new(192, 168, 1, 2), 80);
968        let payload = Bytes::from_static(b"Hello World!");
969        let priority = 123;
970
971        let packetrc = PacketRc::new_ipv4_udp(src, dst, payload.clone(), priority);
972
973        assert_eq!(src, packetrc.src_ipv4_address());
974        assert_eq!(dst, packetrc.dst_ipv4_address());
975        assert_eq!(priority, packetrc.priority());
976        assert_eq!(IanaProtocol::Udp, packetrc.iana_protocol());
977
978        assert_eq!(payload.len(), packetrc.payload_len());
979        let chunks = packetrc.payload();
980        assert_eq!(1, chunks.len());
981        assert_eq!(payload, chunks.first().unwrap());
982    }
983
984    #[test]
985    fn ipv4_udp_empty() {
986        let src = SocketAddrV4::new(Ipv4Addr::new(192, 168, 1, 1), 10_000);
987        let dst = SocketAddrV4::new(Ipv4Addr::new(192, 168, 1, 2), 80);
988        let priority = 123;
989
990        // Bytes object with no data inside.
991
992        let payload = Bytes::new();
993        let packetrc = PacketRc::new_ipv4_udp(src, dst, payload.clone(), priority);
994
995        assert_eq!(0, packetrc.payload_len());
996        assert_eq!(payload.len(), packetrc.payload_len());
997        let chunks = packetrc.payload();
998        assert_eq!(1, chunks.len());
999        assert_eq!(0, chunks.first().unwrap().len());
1000    }
1001
1002    fn make_tcp_header(src: SocketAddrV4, dst: SocketAddrV4) -> tcp::TcpHeader {
1003        // Selective acks with two ranges: [1-3) and [5-6).
1004        let sel_acks =
1005            tcp::util::SmallArrayBackedSlice::<4, (u32, u32)>::new(&[(1, 3), (5, 6)]).unwrap();
1006
1007        tcp::TcpHeader {
1008            ip: tcp::Ipv4Header {
1009                src: *src.ip(),
1010                dst: *dst.ip(),
1011            },
1012            flags: tcp::TcpFlags::SYN,
1013            src_port: src.port(),
1014            dst_port: dst.port(),
1015            seq: 10,
1016            ack: 3,
1017            window_size: 25,
1018            selective_acks: Some(sel_acks),
1019            window_scale: Some(2),
1020            timestamp: Some(123456),
1021            timestamp_echo: Some(123450),
1022        }
1023    }
1024
1025    #[test]
1026    fn ipv4_tcp() {
1027        let src = SocketAddrV4::new(Ipv4Addr::new(192, 168, 1, 1), 10_000);
1028        let dst = SocketAddrV4::new(Ipv4Addr::new(192, 168, 1, 2), 80);
1029        let priority = 123;
1030        let tcp_hdr = make_tcp_header(src, dst);
1031        let payload = tcp::Payload(vec![
1032            Bytes::from_static(b"Hello"),
1033            Bytes::from_static(b" World!"),
1034        ]);
1035
1036        let packetrc = PacketRc::new_ipv4_tcp(tcp_hdr, payload.clone(), priority);
1037
1038        assert_eq!(src, packetrc.src_ipv4_address());
1039        assert_eq!(dst, packetrc.dst_ipv4_address());
1040        assert_eq!(priority, packetrc.priority());
1041        assert_eq!(IanaProtocol::Tcp, packetrc.iana_protocol());
1042        assert_eq!(
1043            TcpHeader::from(tcp_hdr),
1044            TcpHeader::from(packetrc.ipv4_tcp_header().unwrap())
1045        );
1046
1047        assert_eq!(payload.len() as usize, packetrc.payload_len());
1048        let chunks = packetrc.payload();
1049        assert_eq!(2, chunks.len());
1050
1051        for (i, bytes) in chunks.iter().enumerate() {
1052            assert_eq!(payload.0[i], bytes);
1053        }
1054    }
1055
1056    #[test]
1057    fn ipv4_tcp_empty() {
1058        let src = SocketAddrV4::new(Ipv4Addr::new(192, 168, 1, 1), 10_000);
1059        let dst = SocketAddrV4::new(Ipv4Addr::new(192, 168, 1, 2), 80);
1060        let priority = 123;
1061        let tcp_hdr = make_tcp_header(src, dst);
1062
1063        // Empty chunks vec.
1064
1065        let payload = tcp::Payload(vec![]);
1066        let packetrc = PacketRc::new_ipv4_tcp(tcp_hdr, payload, priority);
1067
1068        assert_eq!(0, packetrc.payload_len());
1069        let chunks = packetrc.payload();
1070        assert_eq!(0, chunks.len());
1071
1072        // Non-empty chunks vec with empty bytes objects.
1073
1074        let payload = tcp::Payload(vec![Bytes::new(), Bytes::new()]);
1075        let packetrc = PacketRc::new_ipv4_tcp(tcp_hdr, payload, priority);
1076
1077        assert_eq!(0, packetrc.payload_len());
1078        let chunks = packetrc.payload();
1079        assert_eq!(2, chunks.len());
1080        assert_eq!(0, chunks.first().unwrap().len());
1081        assert_eq!(0, chunks.last().unwrap().len());
1082    }
1083}
1084
1085/// This module provides a C API to create and operate on packets.
1086///
1087/// # Deprecation
1088///
1089/// This module provides compatibility with the legacy C TCP stack and should be considered
1090/// deprecated and removed when the legacy C TCP stack is removed.
1091mod export {
1092    use std::cmp::Ordering;
1093    use std::io::Write;
1094
1095    use shadow_shim_helper_rs::simulation_time::SimulationTime;
1096    use shadow_shim_helper_rs::syscall_types::UntypedForeignPtr;
1097
1098    use crate::cshadow as c;
1099    use crate::host::memory_manager::MemoryManager;
1100    use crate::host::syscall::types::ForeignArrayPtr;
1101
1102    use super::*;
1103
1104    #[unsafe(no_mangle)]
1105    pub extern "C-unwind" fn packet_new_tcp(
1106        host_id: HostId,
1107        packet_id: u64,
1108        flags: c::ProtocolTCPFlags,
1109        src_ip: libc::in_addr_t,
1110        src_port: libc::in_port_t,
1111        dst_ip: libc::in_addr_t,
1112        dst_port: libc::in_port_t,
1113        seq: u32,
1114        priority: u64,
1115    ) -> *mut Packet {
1116        // First construct the internet-level header.
1117        let header = Header::new(
1118            IpAddr::V4(u32::from_be(src_ip).into()),
1119            IpAddr::V4(u32::from_be(dst_ip).into()),
1120        );
1121
1122        // The transport header and payload are defined within the data field.
1123        let data = Data::LegacyTcp(AtomicRefCell::new(TcpData {
1124            header: TcpHeader {
1125                src_port: u16::from_be(src_port),
1126                dst_port: u16::from_be(dst_port),
1127                flags: legacy_flags_to_tcp_flags(flags),
1128                sequence: seq,
1129                acknowledgement: 0,
1130                window_size: 0,
1131                selective_acks: None,
1132                window_scale: None,
1133                timestamp: None,
1134                timestamp_echo: None,
1135            },
1136            payload: vec![],
1137        }));
1138
1139        let meta = Metadata::new_legacy(priority, host_id, packet_id);
1140        let packet = Packet::new(header, data, meta);
1141
1142        // Move ownership of the inner Arc reference to C (for now).
1143        PacketRc::from(packet).into_raw()
1144    }
1145
1146    #[unsafe(no_mangle)]
1147    pub extern "C-unwind" fn packet_ref(packet_ptr: *mut Packet) {
1148        assert!(!packet_ptr.is_null());
1149        unsafe { Arc::increment_strong_count(packet_ptr) };
1150    }
1151
1152    #[unsafe(no_mangle)]
1153    pub extern "C-unwind" fn packet_unref(packet_ptr: *mut Packet) {
1154        assert!(!packet_ptr.is_null());
1155        unsafe { Arc::decrement_strong_count(packet_ptr) };
1156    }
1157
1158    #[unsafe(no_mangle)]
1159    pub extern "C-unwind" fn packet_updateTCP(
1160        packet_ptr: *mut Packet,
1161        ack: libc::c_uint,
1162        sel_acks: c::PacketSelectiveAcks,
1163        window_size: libc::c_uint,
1164        window_scale: libc::c_uchar,
1165        window_scale_set: bool,
1166        ts_val: c::CSimulationTime,
1167        ts_echo: c::CSimulationTime,
1168    ) {
1169        let packet = PacketRc::borrow_raw_mut(packet_ptr);
1170
1171        let Data::LegacyTcp(tcp) = &packet.data else {
1172            unimplemented!()
1173        };
1174
1175        let mut tcp = tcp.borrow_mut();
1176
1177        tcp.header.acknowledgement = ack;
1178        tcp.header.selective_acks = Some(TcpSelectiveAcks::from(sel_acks));
1179
1180        tcp.header.window_size = u16::try_from(window_size).unwrap_or(u16::MAX);
1181        if window_scale_set {
1182            tcp.header.window_scale = Some(window_scale);
1183        } else {
1184            tcp.header.window_scale = None;
1185        }
1186
1187        // The TCP header supports 32-bit timestamps; since these are used for network latency
1188        // calculations, which are usually on the order of milliseconds, we trade off some precision
1189        // here for supporting longer simulations.
1190        tcp.header.timestamp = from_legacy_timestamp(ts_val);
1191        tcp.header.timestamp_echo = from_legacy_timestamp(ts_echo);
1192    }
1193
1194    #[unsafe(no_mangle)]
1195    pub extern "C-unwind" fn packet_getTCPHeader(packet_ptr: *const Packet) -> c::PacketTCPHeader {
1196        let packet = PacketRc::borrow_raw(packet_ptr);
1197
1198        let IpAddr::V4(src_ip) = packet.header.src else {
1199            unimplemented!()
1200        };
1201        let IpAddr::V4(dst_ip) = packet.header.dst else {
1202            unimplemented!()
1203        };
1204        let Data::LegacyTcp(tcp_rc) = &packet.data else {
1205            unimplemented!()
1206        };
1207        let tcp = tcp_rc.borrow();
1208
1209        let mut c_hdr: c::PacketTCPHeader = unsafe { MaybeUninit::zeroed().assume_init() };
1210
1211        c_hdr.flags = tcp_flags_to_legacy_flags(tcp.header.flags);
1212        c_hdr.sourceIP = u32::from(src_ip).to_be();
1213        c_hdr.sourcePort = tcp.header.src_port.to_be();
1214        c_hdr.destinationIP = u32::from(dst_ip).to_be();
1215        c_hdr.destinationPort = tcp.header.dst_port.to_be();
1216        c_hdr.sequence = tcp.header.sequence;
1217        c_hdr.acknowledgment = tcp.header.acknowledgement;
1218        c_hdr.selectiveACKs = to_legacy_sel_acks(tcp.header.selective_acks);
1219        c_hdr.window = u32::from(tcp.header.window_size);
1220        if let Some(scale) = tcp.header.window_scale {
1221            c_hdr.windowScale = scale;
1222            c_hdr.windowScaleSet = true;
1223        }
1224        c_hdr.timestampValue = to_legacy_timestamp(tcp.header.timestamp);
1225        c_hdr.timestampEcho = to_legacy_timestamp(tcp.header.timestamp_echo);
1226
1227        c_hdr
1228    }
1229
1230    #[unsafe(no_mangle)]
1231    pub extern "C-unwind" fn packet_appendPayloadWithMemoryManager(
1232        packet_ptr: *mut Packet,
1233        src: UntypedForeignPtr,
1234        src_len: u64,
1235        mem: *const MemoryManager,
1236    ) {
1237        // Read data from the managed process into the packet's payload buffer.
1238        let packet = PacketRc::borrow_raw_mut(packet_ptr);
1239        let mem = unsafe { mem.as_ref() }.unwrap();
1240
1241        let Data::LegacyTcp(tcp) = &packet.data else {
1242            unimplemented!()
1243        };
1244
1245        let len = usize::try_from(src_len).unwrap();
1246        let src = ForeignArrayPtr::new(src.cast::<MaybeUninit<u8>>(), len);
1247
1248        // We want the dst buf on the heap so we don't have to copy it later. Uses
1249        // `new_uninit_slice` to avoid zero-filling the bytes in dst buffer that we are going to
1250        // copy over with the memory manager below anyway.
1251        let mut dst = Box::<[u8]>::new_uninit_slice(len);
1252
1253        log::trace!(
1254            "Requested to read payload of len {len} from the managed process into the packet's \
1255            payload buffer",
1256        );
1257
1258        // Copy from the managed process directly into the heap buffer. We want this to be the only
1259        // copy of the payload that occurs until the receiver host later copies it into their
1260        // managed process.
1261        if let Err(e) = mem.copy_from_ptr(&mut dst[..], src) {
1262            // Panic because the packet data will be corrupt (not what the application wrote).
1263            panic!(
1264                "Couldn't read managed process memory at {src:?} into packet payload at {dst:?}: {e:?}"
1265            );
1266        }
1267
1268        let dst = unsafe { dst.assume_init() };
1269
1270        log::trace!(
1271            "We read {} bytes from the managed process into the packet's payload",
1272            dst.len()
1273        );
1274
1275        // Move the payload into the packet. Use Bytes (not BytesMut) to avoid copying the payload.
1276        tcp.borrow_mut().payload.push(Bytes::from(dst));
1277    }
1278
1279    #[unsafe(no_mangle)]
1280    pub extern "C-unwind" fn packet_copyPayloadWithMemoryManager(
1281        packet_ptr: *const Packet,
1282        payload_offset: u64,
1283        dst: UntypedForeignPtr,
1284        dst_len: u64,
1285        mem: *mut MemoryManager,
1286    ) -> i64 {
1287        // Write the payload data from the packet into the managed process memory.
1288        let packet = PacketRc::borrow_raw(packet_ptr);
1289        let mem = unsafe { mem.as_mut() }.unwrap();
1290
1291        let Data::LegacyTcp(tcp) = &packet.data else {
1292            unimplemented!()
1293        };
1294
1295        if dst_len == 0 {
1296            return 0;
1297        }
1298
1299        log::trace!(
1300            "Requested to write payload of len {} from offset {payload_offset} into managed \
1301            process buffer of len {dst_len}",
1302            packet.payload_len()
1303        );
1304
1305        let dst_len = usize::try_from(dst_len).unwrap_or(usize::MAX);
1306        let dst = ForeignArrayPtr::new(dst.cast::<u8>(), dst_len);
1307
1308        let mut dst_writer = mem.writer(dst);
1309        let mut dst_space = dst_len;
1310        let mut src_offset = usize::try_from(payload_offset).unwrap_or(usize::MAX);
1311
1312        for bytes in &tcp.borrow().payload {
1313            // This also skips over empty Bytes objects.
1314            if src_offset >= bytes.len() {
1315                src_offset = src_offset.saturating_sub(bytes.len());
1316                continue;
1317            }
1318
1319            let start = src_offset;
1320            let len = bytes.len().saturating_sub(start).min(dst_space);
1321            let end = start + len;
1322            assert!(start <= end);
1323
1324            if len == 0 {
1325                break;
1326            }
1327
1328            log::trace!("Writing {len} bytes into managed process");
1329
1330            if let Err(e) = dst_writer.write_all(&bytes[start..end]) {
1331                log::warn!(
1332                    "Couldn't write managed process memory at {dst:?} from packet payload: {e:?}"
1333                );
1334                // TODO: can we get memmgr errno here like we can with `copy_from_ptr()`?
1335                return linux_api::errno::Errno::EFAULT.to_negated_i64();
1336            }
1337
1338            dst_space = dst_space.saturating_sub(len);
1339            src_offset = 0;
1340        }
1341
1342        let tot_written = dst_len.saturating_sub(dst_space);
1343
1344        if tot_written > 0
1345            && let Err(e) = dst_writer.flush()
1346        {
1347            log::warn!("Couldn't flush managed process writes from packet payload: {e:?}");
1348            // TODO: can we get memmgr errno here like we can with `copy_from_ptr()`?
1349            return linux_api::errno::Errno::EFAULT.to_negated_i64();
1350        }
1351
1352        log::trace!("We wrote {tot_written} bytes into managed process buffer of len {dst_len}");
1353
1354        i64::try_from(tot_written).unwrap()
1355    }
1356
1357    #[unsafe(no_mangle)]
1358    pub extern "C-unwind" fn packet_getPriority(packet_ptr: *const Packet) -> u64 {
1359        let packet = PacketRc::borrow_raw(packet_ptr);
1360        packet.priority()
1361    }
1362
1363    #[unsafe(no_mangle)]
1364    pub extern "C-unwind" fn packet_getPayloadSize(packet_ptr: *const Packet) -> u64 {
1365        let packet = PacketRc::borrow_raw(packet_ptr);
1366        packet.payload_len().try_into().unwrap()
1367    }
1368
1369    #[unsafe(no_mangle)]
1370    pub extern "C-unwind" fn packet_getDestinationIP(packet_ptr: *const Packet) -> libc::in_addr_t {
1371        let packet = PacketRc::borrow_raw(packet_ptr);
1372        u32::to_be((*packet.dst_ipv4_address().ip()).into())
1373    }
1374
1375    #[unsafe(no_mangle)]
1376    pub extern "C-unwind" fn packet_getDestinationPort(
1377        packet_ptr: *const Packet,
1378    ) -> libc::in_port_t {
1379        let packet = PacketRc::borrow_raw(packet_ptr);
1380        u16::to_be(packet.dst_ipv4_address().port())
1381    }
1382
1383    #[unsafe(no_mangle)]
1384    pub extern "C-unwind" fn packet_getSourceIP(packet_ptr: *const Packet) -> libc::in_addr_t {
1385        let packet = PacketRc::borrow_raw(packet_ptr);
1386        u32::to_be((*packet.src_ipv4_address().ip()).into())
1387    }
1388
1389    #[unsafe(no_mangle)]
1390    pub extern "C-unwind" fn packet_getSourcePort(packet_ptr: *const Packet) -> libc::in_port_t {
1391        let packet = PacketRc::borrow_raw(packet_ptr);
1392        u16::to_be(packet.src_ipv4_address().port())
1393    }
1394
1395    #[unsafe(no_mangle)]
1396    pub extern "C-unwind" fn packet_addDeliveryStatus(
1397        packet_ptr: *mut Packet,
1398        status: c::PacketDeliveryStatusFlags,
1399    ) {
1400        let packet = PacketRc::borrow_raw_mut(packet_ptr);
1401        packet.add_status(PacketStatus::from(status));
1402    }
1403
1404    #[unsafe(no_mangle)]
1405    pub extern "C-unwind" fn packet_compareTCPSequence(
1406        packet_ptr1: *mut Packet,
1407        packet_ptr2: *mut Packet,
1408        _ptr: *mut libc::c_void,
1409    ) -> libc::c_int {
1410        let packet1 = PacketRc::borrow_raw_mut(packet_ptr1);
1411        let packet2 = PacketRc::borrow_raw_mut(packet_ptr2);
1412
1413        let seq1 = get_sequence_number(&packet1);
1414        let seq2 = get_sequence_number(&packet2);
1415
1416        // Translated from the C packet impl.
1417        match seq1.cmp(&seq2) {
1418            Ordering::Less => -1,
1419            Ordering::Equal => 0,
1420            Ordering::Greater => 1,
1421        }
1422    }
1423
1424    fn get_sequence_number(packet: &PacketRc) -> u32 {
1425        let Data::LegacyTcp(tcp_ref) = &packet.data else {
1426            unimplemented!()
1427        };
1428        tcp_ref.borrow().header.sequence
1429    }
1430
1431    fn legacy_flags_to_tcp_flags(legacy_flags: c::ProtocolTCPFlags) -> tcp::TcpFlags {
1432        // The legacy flags use the first 7 bits of an i32. We could just do:
1433        // `u8::try_from(flags).expect("Legacy TCP flags use < 8 bits")` but we have to map the
1434        // values to support PCAP correctly.
1435        let mut tcp_flags = tcp::TcpFlags::empty();
1436
1437        if legacy_flags & c::_ProtocolTCPFlags_PTCP_FIN != 0 {
1438            tcp_flags.insert(tcp::TcpFlags::FIN);
1439        }
1440        if legacy_flags & c::_ProtocolTCPFlags_PTCP_SYN != 0 {
1441            tcp_flags.insert(tcp::TcpFlags::SYN);
1442        }
1443        if legacy_flags & c::_ProtocolTCPFlags_PTCP_RST != 0 {
1444            tcp_flags.insert(tcp::TcpFlags::RST);
1445        }
1446        if legacy_flags & c::_ProtocolTCPFlags_PTCP_ACK != 0 {
1447            tcp_flags.insert(tcp::TcpFlags::ACK);
1448        }
1449        // These legacy flags don't exist as real TCP flags, so we overload the two bits that are
1450        // not shown in the PCAP output.
1451        if legacy_flags & c::_ProtocolTCPFlags_PTCP_SACK != 0 {
1452            tcp_flags.insert(tcp::TcpFlags::ECE);
1453        }
1454        if legacy_flags & c::_ProtocolTCPFlags_PTCP_DUPACK != 0 {
1455            tcp_flags.insert(tcp::TcpFlags::CWR);
1456        }
1457
1458        tcp_flags
1459    }
1460
1461    fn tcp_flags_to_legacy_flags(tcp_flags: tcp::TcpFlags) -> c::ProtocolTCPFlags {
1462        // The u8 header flags fit within the legacy flags which are represented by an i32. We could
1463        // just do: `bits as c::ProtocolTCPFlags` but we have to map the values to support PCAP
1464        // correctly.
1465        let mut legacy_flags = c::_ProtocolTCPFlags_PTCP_NONE;
1466
1467        if tcp_flags.contains(tcp::TcpFlags::FIN) {
1468            legacy_flags |= c::_ProtocolTCPFlags_PTCP_FIN;
1469        }
1470        if tcp_flags.contains(tcp::TcpFlags::SYN) {
1471            legacy_flags |= c::_ProtocolTCPFlags_PTCP_SYN;
1472        }
1473        if tcp_flags.contains(tcp::TcpFlags::RST) {
1474            legacy_flags |= c::_ProtocolTCPFlags_PTCP_RST;
1475        }
1476        if tcp_flags.contains(tcp::TcpFlags::ACK) {
1477            legacy_flags |= c::_ProtocolTCPFlags_PTCP_ACK;
1478        }
1479        // Extract these from the encoding used in `legacy_flags_to_tcp_flags()`.
1480        if tcp_flags.contains(tcp::TcpFlags::ECE) {
1481            legacy_flags |= c::_ProtocolTCPFlags_PTCP_SACK;
1482        }
1483        if tcp_flags.contains(tcp::TcpFlags::CWR) {
1484            legacy_flags |= c::_ProtocolTCPFlags_PTCP_DUPACK;
1485        }
1486
1487        legacy_flags
1488    }
1489
1490    fn from_legacy_timestamp(ts: c::CSimulationTime) -> Option<u32> {
1491        SimulationTime::from_c_simtime(ts).map(|x| u32::try_from(x.as_millis()).unwrap_or(u32::MAX))
1492    }
1493
1494    fn to_legacy_timestamp(val: Option<u32>) -> c::CSimulationTime {
1495        SimulationTime::to_c_simtime(val.map(|x| SimulationTime::from_millis(x as u64)))
1496    }
1497
1498    impl From<c::PacketSelectiveAcks> for TcpSelectiveAcks {
1499        fn from(c_sel_acks: c::PacketSelectiveAcks) -> Self {
1500            let mut selective_acks = TcpSelectiveAcks::default();
1501
1502            assert!(c_sel_acks.len <= 4);
1503
1504            for i in 0..(c_sel_acks.len as usize) {
1505                let start: u32 = c_sel_acks.ranges[i].start;
1506                let end: u32 = c_sel_acks.ranges[i].end;
1507                selective_acks.ranges[i] = (start, end);
1508                selective_acks.len += 1;
1509            }
1510
1511            selective_acks
1512        }
1513    }
1514
1515    fn to_legacy_sel_acks(selective_acks: Option<TcpSelectiveAcks>) -> c::PacketSelectiveAcks {
1516        let mut c_sel_acks: c::PacketSelectiveAcks = unsafe { MaybeUninit::zeroed().assume_init() };
1517
1518        let Some(selective_acks) = selective_acks else {
1519            return c_sel_acks;
1520        };
1521
1522        assert!(selective_acks.len <= 4);
1523
1524        for i in 0..(selective_acks.len as usize) {
1525            let (start, end) = selective_acks.ranges[i];
1526            c_sel_acks.ranges[i].start = start;
1527            c_sel_acks.ranges[i].end = end;
1528            c_sel_acks.len += 1;
1529        }
1530
1531        c_sel_acks
1532    }
1533
1534    impl From<c::ProtocolType> for IanaProtocol {
1535        fn from(value: c::ProtocolType) -> Self {
1536            match value {
1537                c::_ProtocolType_PTCP => IanaProtocol::Tcp,
1538                c::_ProtocolType_PUDP => IanaProtocol::Udp,
1539                _ => panic!("Unexpected protocol type {value}"),
1540            }
1541        }
1542    }
1543
1544    impl From<c::PacketDeliveryStatusFlags> for PacketStatus {
1545        fn from(legacy_status: c::PacketDeliveryStatusFlags) -> Self {
1546            match legacy_status {
1547                c::_PacketDeliveryStatusFlags_PDS_SND_CREATED => PacketStatus::SndCreated,
1548                c::_PacketDeliveryStatusFlags_PDS_SND_TCP_ENQUEUE_THROTTLED => {
1549                    PacketStatus::SndTcpEnqueueThrottled
1550                }
1551                c::_PacketDeliveryStatusFlags_PDS_SND_TCP_ENQUEUE_RETRANSMIT => {
1552                    PacketStatus::SndTcpEnqueueRetransmit
1553                }
1554                c::_PacketDeliveryStatusFlags_PDS_SND_TCP_DEQUEUE_RETRANSMIT => {
1555                    PacketStatus::SndTcpDequeueRetransmit
1556                }
1557                c::_PacketDeliveryStatusFlags_PDS_SND_TCP_RETRANSMITTED => {
1558                    PacketStatus::SndTcpRetransmitted
1559                }
1560                c::_PacketDeliveryStatusFlags_PDS_SND_SOCKET_BUFFERED => {
1561                    PacketStatus::SndSocketBuffered
1562                }
1563                c::_PacketDeliveryStatusFlags_PDS_SND_INTERFACE_SENT => {
1564                    PacketStatus::SndInterfaceSent
1565                }
1566                c::_PacketDeliveryStatusFlags_PDS_INET_SENT => PacketStatus::InetSent,
1567                c::_PacketDeliveryStatusFlags_PDS_INET_DROPPED => PacketStatus::InetDropped,
1568                c::_PacketDeliveryStatusFlags_PDS_ROUTER_ENQUEUED => PacketStatus::RouterEnqueued,
1569                c::_PacketDeliveryStatusFlags_PDS_ROUTER_DEQUEUED => PacketStatus::RouterDequeued,
1570                c::_PacketDeliveryStatusFlags_PDS_ROUTER_DROPPED => PacketStatus::RouterDropped,
1571                c::_PacketDeliveryStatusFlags_PDS_RCV_INTERFACE_RECEIVED => {
1572                    PacketStatus::RcvInterfaceReceived
1573                }
1574                c::_PacketDeliveryStatusFlags_PDS_RCV_INTERFACE_DROPPED => {
1575                    PacketStatus::RcvInterfaceDropped
1576                }
1577                c::_PacketDeliveryStatusFlags_PDS_RCV_SOCKET_PROCESSED => {
1578                    PacketStatus::RcvSocketProcessed
1579                }
1580                c::_PacketDeliveryStatusFlags_PDS_RCV_SOCKET_DROPPED => {
1581                    PacketStatus::RcvSocketDropped
1582                }
1583                c::_PacketDeliveryStatusFlags_PDS_RCV_TCP_ENQUEUE_UNORDERED => {
1584                    PacketStatus::RcvTcpEnqueueUnordered
1585                }
1586                c::_PacketDeliveryStatusFlags_PDS_RCV_SOCKET_BUFFERED => {
1587                    PacketStatus::RcvSocketBuffered
1588                }
1589                c::_PacketDeliveryStatusFlags_PDS_RCV_SOCKET_DELIVERED => {
1590                    PacketStatus::RcvSocketDelivered
1591                }
1592                c::_PacketDeliveryStatusFlags_PDS_DESTROYED => PacketStatus::Destroyed,
1593                c::_PacketDeliveryStatusFlags_PDS_RELAY_CACHED => PacketStatus::RelayCached,
1594                c::_PacketDeliveryStatusFlags_PDS_RELAY_FORWARDED => PacketStatus::RelayForwarded,
1595                _ => unimplemented!(),
1596            }
1597        }
1598    }
1599}