p4rs/

lib.rs

// Copyright 2026 Oxide Computer Company

//! This is the runtime support create for `x4c` generated programs.
//!
//! The main abstraction in this crate is the [`Pipeline`] trait. Rust code that
//! is generated by `x4c` implements this trait. A `main_pipeline` struct is
//! exported by the generated code that implements [`Pipeline`]. Users can wrap
//! the `main_pipeline` object in harness code to provide higher level
//! interfaces for table manipulation and packet i/o.
//!
//! ```rust
//! use p4rs::{ packet_in, packet_out, Pipeline };
//! use std::net::Ipv6Addr;
//!
//! struct Handler {
//!     pipe: Box<dyn Pipeline>
//! }
//!
//! impl Handler {
//!     /// Create a new pipeline handler.
//!     fn new(pipe: Box<dyn Pipeline>) -> Self {
//!         Self{ pipe }
//!     }
//!
//!     /// Handle a packet from the specified port. If the pipeline produces
//!     /// an output result, send the processed packet to the output port
//!     /// returned by the pipeline.
//!     fn handle_packet(&mut self, port: u16, pkt: &[u8]) {
//!
//!         let mut input = packet_in::new(pkt);
//!
//!         let output =  self.pipe.process_packet(port, &mut input);
//!         for (out_pkt, out_port) in &output {
//!             let mut out = out_pkt.header_data.clone();
//!             out.extend_from_slice(out_pkt.payload_data);
//!             self.send_packet(*out_port, &out);
//!         }
//!
//!     }
//!
//!     /// Add a routing table entry. Packets for the provided destination will
//!     /// be sent out the specified port.
//!     fn add_router_entry(&mut self, dest: Ipv6Addr, port: u16) {
//!         self.pipe.add_table_entry(
//!             "ingress.router.ipv6_routes", // qualified name of the table
//!             "forward_out_port",           // action to invoke on a hit
//!             &dest.octets(),
//!             &port.to_le_bytes(),
//!             0,
//!         );
//!     }
//!
//!     /// Send a packet out the specified port.
//!     fn send_packet(&self, port: u16, pkt: &[u8]) {
//!         // send the packet ...
//!     }
//! }
//! ```
//!
#![allow(incomplete_features)]
#![allow(non_camel_case_types)]

use std::fmt;
use std::net::IpAddr;

pub use error::TryFromSliceError;
use serde::{Deserialize, Serialize};

use bitvec::prelude::*;

pub mod error;
//pub mod hicuts;
//pub mod rice;
pub mod bitmath;
pub mod checksum;
pub mod externs;
pub mod table;

#[usdt::provider]
mod p4rs_provider {
    fn match_miss(_: &str) {}
}

#[derive(Debug)]
pub struct Bit<'a, const N: usize>(pub &'a [u8]);

impl<'a, const N: usize> Bit<'a, N> {
    //TODO measure the weight of returning TryFromSlice error versus just
    //dropping and incrementing a counter. Relying on dtrace for more detailed
    //debugging.
    pub fn new(data: &'a [u8]) -> Result<Self, TryFromSliceError> {
        let required_bytes = if N & 7 > 0 { (N >> 3) + 1 } else { N >> 3 };
        if data.len() < required_bytes {
            return Err(TryFromSliceError(N));
        }
        Ok(Self(&data[..required_bytes]))
    }
}

impl<const N: usize> fmt::LowerHex for Bit<'_, N> {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        for x in self.0 {
            fmt::LowerHex::fmt(&x, f)?;
        }
        Ok(())
    }
}

// TODO more of these for other sizes
impl<'a> From<Bit<'a, 16>> for u16 {
    fn from(b: Bit<'a, 16>) -> u16 {
        u16::from_be_bytes([b.0[0], b.0[1]])
    }
}

// TODO more of these for other sizes
impl std::hash::Hash for Bit<'_, 8> {
    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
        self.0[0].hash(state);
    }
}

impl std::cmp::PartialEq for Bit<'_, 8> {
    fn eq(&self, other: &Self) -> bool {
        self.0[0] == other.0[0]
    }
}

impl std::cmp::Eq for Bit<'_, 8> {}

/// Every packet that goes through a P4 pipeline is represented as a `packet_in`
/// instance. `packet_in` objects wrap an underlying mutable data reference that
/// is ultimately rooted in a memory mapped region containing a ring of packets.
#[derive(Debug)]
pub struct packet_in<'a> {
    /// The underlying data. Owned by an external, memory-mapped packet ring.
    pub data: &'a [u8],

    /// Extraction index. Everything before `index` has been extracted already.
    /// Only data after `index` is eligble for extraction. Extraction is always
    /// for contiguous segments of the underlying packet ring data.
    pub index: usize,
}

#[derive(Debug)]
pub struct packet_out<'a> {
    pub header_data: Vec<u8>,
    pub payload_data: &'a [u8],
}

#[derive(Debug, Serialize, Deserialize)]
pub struct TableEntry {
    pub action_id: String,
    pub keyset_data: Vec<u8>,
    pub parameter_data: Vec<u8>,
}

pub trait Pipeline: Send {
    /// Process an input packet and produce a set of output packets.
    fn process_packet<'a>(
        &mut self,
        port: u16,
        pkt: &mut packet_in<'a>,
    ) -> Vec<(packet_out<'a>, u16)>;

    //TODO use struct TableEntry?
    /// Add an entry to a table identified by table_id.
    fn add_table_entry(
        &mut self,
        table_id: &str,
        action_id: &str,
        keyset_data: &[u8],
        parameter_data: &[u8],
        priority: u32,
    );

    /// Remove an entry from a table identified by table_id.
    fn remove_table_entry(&mut self, table_id: &str, keyset_data: &[u8]);

    /// Remove all entries from a table identified by table_id.
    ///
    /// Returns `true` if the table was cleared, or `false` if `table_id` maps
    /// to no table in this pipeline. This return type distinguishes an unknown
    /// table from an already-empty one, like [`Pipeline::get_table_entries`]
    /// does with `None`.
    // NOTE: This maps to dendrite's SoftNPU `TableOps::clear` implementation,
    // which is the analogue of `bf_rt_table_clear` on Tofino, for example.
    fn clear_table_entries(&mut self, table_id: &str) -> bool;

    /// Get all the entries in a table.
    fn get_table_entries(&self, table_id: &str) -> Option<Vec<TableEntry>>;

    /// Get a list of table ids
    fn get_table_ids(&self) -> Vec<&str>;
}

/// A fixed length header trait.
pub trait Header {
    fn new() -> Self;
    fn size() -> usize;
    fn set(&mut self, buf: &[u8]) -> Result<(), TryFromSliceError>;
    fn set_valid(&mut self);
    fn set_invalid(&mut self);
    fn is_valid(&self) -> bool;
    fn to_bitvec(&self) -> BitVec<u8, Msb0>;
}

impl<'a> packet_in<'a> {
    pub fn new(data: &'a [u8]) -> Self {
        Self { data, index: 0 }
    }

    // TODO: this function signature is a bit unforunate in the sense that the
    // p4 compiler generates call sites based on a p4 `packet_in` extern
    // definition. But based on that definition, there is no way for the
    // compiler to know that this function returns a result that needs to be
    // interrogated. In fact, the signature for packet_in::extract from the p4
    // standard library requires the return type to be `void`, so this signature
    // cannot return a result without the compiler having special knowledge of
    // functions that happen to be called "extract".
    pub fn extract<H: Header>(&mut self, h: &mut H) {
        //TODO what if a header does not end on a byte boundary?
        let n = H::size();
        let start = if self.index > 0 { self.index >> 3 } else { 0 };
        match h.set(&self.data[start..start + (n >> 3)]) {
            Ok(_) => {}
            Err(e) => {
                //TODO better than this
                println!("packet extraction failed: {}", e);
            }
        }
        self.index += n;
        h.set_valid();
    }

    // This is the same as extract except we return a new header instead of
    // modifying an existing one.
    pub fn extract_new<H: Header>(&mut self) -> Result<H, TryFromSliceError> {
        let n = H::size();
        let start = if self.index > 0 { self.index >> 3 } else { 0 };
        self.index += n;
        let mut x = H::new();
        x.set(&self.data[start..start + (n >> 3)])?;
        Ok(x)
    }
}

//XXX: remove once classifier defined in terms of bitvecs
pub fn bitvec_to_biguint(bv: &BitVec<u8, Msb0>) -> table::BigUintKey {
    table::BigUintKey {
        value: if bv.is_empty() {
            num::BigUint::default()
        } else {
            bv.load_le::<u128>().into()
        },
        width: bv.len().div_ceil(8),
    }
}

pub fn bitvec_to_ip6addr(bv: &BitVec<u8, Msb0>) -> std::net::IpAddr {
    let mut arr: [u8; 16] = bv.as_raw_slice().try_into().unwrap();
    arr.reverse();
    std::net::IpAddr::V6(std::net::Ipv6Addr::from(arr))
}

#[repr(C, align(16))]
pub struct AlignedU128(pub u128);

pub fn int_to_bitvec(x: i128) -> BitVec<u8, Msb0> {
    //let mut bv = BitVec::<u8, Msb0>::new();
    let mut bv = bitvec![mut u8, Msb0; 0; 128];
    bv.store(x);
    bv
}

/// Resize `x` to 16 bits, zero-extending or truncating its value.
pub fn bitvec_to_bitvec16(x: BitVec<u8, Msb0>) -> BitVec<u8, Msb0> {
    bitvec_resize(x, 16)
}

/// Resize `x` to `width` bits.
///
/// Any added high-order bits are zero.
///
/// This backs x4c's implicit `bit<W>` to `bit<V>` widening, which P4-16
/// expresses as an explicit cast ([8.11.1]).
///
/// [8.11.1]: https://p4.org/wp-content/uploads/sites/53/2024/10/P4-16-spec-v1.2.5.html#sec-explicit-casts
pub fn bitvec_resize(x: BitVec<u8, Msb0>, width: usize) -> BitVec<u8, Msb0> {
    let value: u128 = if x.is_empty() { 0 } else { x.load_le() };
    let mut resized = bitvec![u8, Msb0; 0; width];
    if width > 0 {
        resized.store_le(value);
    }
    resized
}

pub fn dump_bv(x: &BitVec<u8, Msb0>) -> String {
    if x.is_empty() {
        "∅".into()
    } else {
        let v: u128 = x.load_le();
        format!("{:x}", v)
    }
}

pub fn extract_exact_key(
    keyset_data: &[u8],
    offset: usize,
    len: usize,
) -> table::Key {
    table::Key::Exact(table::BigUintKey {
        value: num::BigUint::from_bytes_le(&keyset_data[offset..offset + len]),
        width: len,
    })
}

pub fn extract_range_key(
    keyset_data: &[u8],
    offset: usize,
    len: usize,
) -> table::Key {
    table::Key::Range(
        table::BigUintKey {
            value: num::BigUint::from_bytes_le(
                &keyset_data[offset..offset + len],
            ),
            width: len,
        },
        table::BigUintKey {
            value: num::BigUint::from_bytes_le(
                &keyset_data[offset + len..offset + len + len],
            ),
            width: len,
        },
    )
}

/// Extract a ternary key from the provided keyset data. Ternary keys come in
/// two parts. The first part is a leading bit that indicates whether we care
/// about the value. If that leading bit is non-zero, the trailing bits of the
/// key are interpreted as a binary value. If the leading bit is zero, the
/// trailing bits are ignored and a Ternary::DontCare key is returned.
pub fn extract_ternary_key(
    keyset_data: &[u8],
    offset: usize,
    len: usize,
) -> table::Key {
    let care = keyset_data[offset];
    if care != 0 {
        table::Key::Ternary(table::Ternary::Value(table::BigUintKey {
            value: num::BigUint::from_bytes_le(
                &keyset_data[offset + 1..offset + 1 + len],
            ),
            width: len,
        }))
    } else {
        table::Key::Ternary(table::Ternary::DontCare)
    }
}

pub fn extract_lpm_key(
    keyset_data: &[u8],
    offset: usize,
    len: usize,
) -> table::Key {
    let (addr, prefix_len) = match len {
        // IPv4
        4 => {
            let data: [u8; 4] =
                keyset_data[offset..offset + 4].try_into().unwrap();
            (IpAddr::from(data), keyset_data[offset + 4])
        }
        // IPv6
        16 => {
            let data: [u8; 16] =
                keyset_data[offset..offset + 16].try_into().unwrap();
            (IpAddr::from(data), keyset_data[offset + 16])
        }
        x => {
            panic!("lpm: data len must be 4 (ipv4) or 16 (ipv6) found {}", x);
        }
    };

    table::Key::Lpm(table::Prefix {
        addr,
        len: prefix_len,
    })
}

pub fn extract_bool_action_parameter(
    parameter_data: &[u8],
    offset: usize,
) -> bool {
    parameter_data[offset] == 1
}

/// Extract a `bit<size>` action parameter from the control-plane action data.
///
/// Action data lays out each parameter in declaration order as
/// `size.div_ceil(8)` little-endian bytes, starting at `offset`. x4c keeps
/// every numeric value little-endian inside a program (header fields are
/// byte-reversed on parse and once again on deparse), so the control plane
/// passes these values into this representation with no conversion necessary;
/// the same is true for `exact` and `range` keys.
///
/// The returned vector has the same layout as [`bitvec_resize`] output and
/// header fields of the same width, so `load_le` recovers the value whenever
/// the width fits the target integer (up to 128 bits for `u128`).
pub fn extract_bit_action_parameter(
    parameter_data: &[u8],
    offset: usize,
    size: usize,
) -> BitVec<u8, Msb0> {
    let byte_size = size.div_ceil(8);
    let mut bytes = parameter_data[offset..offset + byte_size].to_vec();
    let rem = size % 8;
    // Msb0 keeps a partial last byte in its high bits, so the value's top
    // `rem` bits move up before the vector is truncated to `size`.
    if rem != 0 {
        bytes[byte_size - 1] <<= 8 - rem;
    }
    let mut bv = BitVec::<u8, Msb0>::from_vec(bytes);
    bv.resize(size, false);
    bv
}

/// Collect output ports from a bitmap, excluding the ingress port.
///
/// Bits at or above `radix` are ignored, which means that a bitmap cannot
/// address a port outside the pipeline.
///
/// The bitmap is interpreted as a little-endian integer: bit N
/// (i.e., the bit with numeric value 2^N) corresponds to port N.
/// This matches the encoding used by P4 arithmetic (`128w1 << port`)
/// via [`bitmath::shl_le`].
pub fn bitmap_to_port_list(
    bitmap: &BitVec<u8, Msb0>,
    ingress_port: u16,
    radix: u16,
) -> Vec<u16> {
    if bitmap.is_empty() {
        return Vec::new();
    }
    let val: u128 = bitmap.load_le();
    (0..radix.min(128))
        .filter(|&p| val & (1u128 << p) != 0 && p != ingress_port)
        .collect()
}

#[cfg(test)]
mod tests {
    use super::*;
    use num::bigint::BigUint;

    #[test]
    fn bitvec_resize_preserves_value() {
        for (source_width, target_width, value) in [
            (4, 8, 1u128),
            (4, 16, 0xf),
            (8, 12, 0xab),
            (12, 16, 0xabc),
            (12, 24, 0xabc),
            (16, 128, 0xbeef),
            (128, 128, u128::MAX),
        ] {
            let mut input = bitvec![u8, Msb0; 0; source_width];
            input.store_le(value);

            let out = bitvec_resize(input, target_width);

            assert_eq!(out.len(), target_width);
            assert_eq!(
                out.load_le::<u128>(),
                value,
                "{source_width} -> {target_width}",
            );
        }
    }

    #[test]
    fn extract_bit_action_parameter_sub_byte_widths() {
        for (width, value) in [
            (12, 100u16),
            (12, 256),
            (12, 300),
            (12, 4094),
            (4, 0xa),
            (9, 0x1ab),
            (10, 0x2ab),
            (11, 0x5ab),
            (13, 0x1abc),
            (14, 0x2abc),
            (15, 0x5abc),
            (16, 0xbeef),
        ] {
            let mut data = vec![0xffu8];
            data.extend_from_slice(&value.to_le_bytes());

            let out = extract_bit_action_parameter(&data, 1, width);

            assert_eq!(out.len(), width);
            assert_eq!(out.load_le::<u16>(), value, "bit<{width}> = {value}");

            let mut expected = bitvec![u8, Msb0; 0; width];
            expected.store_le(value);
            assert_eq!(out, expected, "bit<{width}> layout");
        }
    }

    #[test]
    fn extract_bit_action_parameter_wide_unaligned() {
        let mut data = vec![0xa5u8; 16];
        data.push(0x0f);

        let out = extract_bit_action_parameter(&data, 0, 132);

        assert_eq!(out.len(), 132);
        let mut expected = vec![0xa5u8; 16];
        expected.push(0xf0);
        assert_eq!(out.as_raw_slice(), expected.as_slice());
    }

    #[test]
    fn bitvec_resize_empty_values() {
        let out = bitvec_resize(BitVec::new(), 8);
        assert_eq!(out.len(), 8);
        assert_eq!(out.load_le::<u8>(), 0);
        assert!(bitvec_resize(BitVec::new(), 0).is_empty());
    }

    #[test]
    fn bitvec_resize_aligns_slices() {
        for offset in 0..8 {
            for (source_width, target_width, value) in [
                (4, 8, 0xbu128),
                (8, 16, 0xab),
                (12, 16, 0xabc),
                (16, 24, 0xbeef),
                (128, 128, u128::MAX),
            ] {
                let storage = bitvec![u8, Msb0; 0; offset + source_width];
                let mut input = storage[offset..].to_bitvec();
                input.store_le(value);

                let out = bitvec_resize(input, target_width);
                let mut expected = bitvec![u8, Msb0; 0; target_width];
                expected.store_le(value);

                assert_eq!(
                    out, expected,
                    "offset {offset}: {source_width} -> {target_width}",
                );
            }
        }
    }

    /// Checks [`bitvec_to_biguint`] is semantically equivalent to `load_le`,
    /// even with non-byte-aligned widths.
    #[test]
    fn bitvec_to_biguint_non_byte_aligned() {
        for width in 1..=16 {
            let mut bv = bitvec![u8, Msb0; 0; width];
            bv.store_le(0xbeefu16);

            assert_eq!(
                bitvec_to_biguint(&bv).value,
                BigUint::from(bv.load_le::<u16>()),
            );
        }
    }

    #[test]
    fn bitvec_to_biguint_parsed_ihl() {
        let data = [0x45u8];
        let ihl = data.view_bits::<Msb0>()[4..8].to_bitvec();
        let key = bitvec_to_biguint(&ihl);

        assert_eq!(key.value, BigUint::from(5u8));
        assert_eq!(key.width, 1);
    }

    #[test]
    fn bitvec_to_biguint_storage_offsets() {
        for offset in 0..8 {
            for width in 1..=128 {
                let storage = bitvec![u8, Msb0; 1; offset + width];
                let mut bv = storage[offset..].to_bitvec();
                let expected = u128::MAX >> (128 - width);
                bv.store_le(expected);
                bv.set_uninitialized(true);
                let key = bitvec_to_biguint(&bv);

                assert_eq!(key.value, BigUint::from(expected));
                assert_eq!(key.width, width.div_ceil(8));
            }
        }
    }

    #[test]
    fn bitvec_to_biguint_empty() {
        let key = bitvec_to_biguint(&BitVec::new());

        assert_eq!(key.value, BigUint::default());
        assert_eq!(key.width, 0);
    }

    #[test]
    fn replication_radix_is_bounded_by_bitmap_width() {
        let mut bitmap = bitvec![u8, Msb0; 0; 128];
        bitmap.store_le(1u128 << 127);

        assert_eq!(bitmap_to_port_list(&bitmap, 0, u16::MAX), vec![127]);
    }

    #[test]
    fn replication_of_empty_bitmap_yields_no_ports() {
        let bitmap: BitVec<u8, Msb0> = BitVec::new();

        assert_eq!(bitmap_to_port_list(&bitmap, 0, 4), Vec::<u16>::new());
    }
}