rtlp-lib — Rust TLP Parsing Library

A Rust crate for parsing PCI Express Transaction Layer Packets (TLPs).

Decode raw TLP byte streams into strongly-typed structs and trait objects. The library handles DW0 header decoding (format + type), per-type field extraction (requester ID, tag, address, operands, …), and validates format/type combinations according to the PCIe specification.

Supported TLP Types

For a detailed breakdown of every TLP encoding, header layout, parsed fields, and byte-level examples taken from the test suite, see tlp.md.

Quick Start

Add to your Cargo.toml:

[dependencies]
rtlp-lib = "0.5"

Usage

use rtlp_lib::{
    TlpPacket, TlpFmt, TlpType, TlpMode,
    new_mem_req, new_conf_req, new_cmpl_req, new_msg_req, new_atomic_req,
};

// Raw bytes captured from a PCIe trace (DW0 .. DWn)
let bytes = vec![
    0x00, 0x00, 0x20, 0x01,   // DW0: MemRead 3DW, length=1
    0x00, 0x00, 0x20, 0x0F,   // DW1: req_id=0x0000 tag=0x20 BE=0x0F
    0xF6, 0x20, 0x00, 0x0C,   // DW2: address32=0xF620000C
];
let packet = TlpPacket::new(bytes, TlpMode::NonFlit).unwrap();

// mode() tells you which parsing surface to use
match packet.mode() {
    TlpMode::NonFlit => {
        let tlp_type   = packet.tlp_type().unwrap();
        let tlp_format = packet.tlp_format().unwrap();

        match tlp_type {
            TlpType::MemReadReq | TlpType::MemWriteReq |
            TlpType::MemReadLockReq |
            TlpType::DeferrableMemWriteReq |
            TlpType::IOReadReq | TlpType::IOWriteReq => {
                // data() returns &[u8] — no extra allocation at this call site;
                // new_mem_req takes impl Into<Vec<u8>> and may allocate internally.
                let mr = new_mem_req(packet.data(), &tlp_format).unwrap();
                println!("req_id=0x{:04X}  tag=0x{:02X}  addr=0x{:X}",
                         mr.req_id(), mr.tag(), mr.address());
            }
            TlpType::FetchAddAtomicOpReq |
            TlpType::SwapAtomicOpReq |
            TlpType::CompareSwapAtomicOpReq => {
                let ar = new_atomic_req(&packet).unwrap();
                println!("atomic {:?} operand0=0x{:X}", ar.op(), ar.operand0());
            }
            TlpType::ConfType0ReadReq | TlpType::ConfType0WriteReq |
            TlpType::ConfType1ReadReq | TlpType::ConfType1WriteReq => {
                let cr = new_conf_req(packet.data()).unwrap();  // accepts &[u8] directly
                println!("config bus={} dev={} func={}",
                         cr.bus_nr(), cr.dev_nr(), cr.func_nr());
            }
            TlpType::Cpl | TlpType::CplData |
            TlpType::CplLocked | TlpType::CplDataLocked => {
                let cpl = new_cmpl_req(packet.data()).unwrap();
                println!("completion status={}", cpl.cmpl_stat());
            }
            TlpType::MsgReq | TlpType::MsgReqData => {
                let msg = new_msg_req(packet.data()).unwrap();
                println!("message code=0x{:02X}", msg.msg_code());
            }
            _ => println!("TLP type: {:?}", tlp_type),
        }
    }
    TlpMode::Flit => {
        // Use flit_type() for flit-mode packets
        println!("flit type: {:?}", packet.flit_type());
    }
    _ => {}
}

Non-Posted Semantics

The library exposes TlpType::is_non_posted() to distinguish requests that require a completion from posted writes:

use rtlp_lib::TlpType;

assert!( TlpType::MemReadReq.is_non_posted());
assert!( TlpType::DeferrableMemWriteReq.is_non_posted());
assert!(!TlpType::MemWriteReq.is_non_posted());   // posted

Public API Overview

Core Types (Non-Flit)

Key TlpPacket methods:

Other core types:

Flit Mode Types (PCIe 6.x)

use rtlp_lib::{TlpPacket, TlpMode, FlitStreamWalker, FlitTlpType};

// Parse a single flit TLP
let nop_bytes = vec![0x00u8, 0x00, 0x00, 0x00];
let pkt = TlpPacket::new(nop_bytes, TlpMode::Flit).unwrap();
assert_eq!(pkt.flit_type(), Some(FlitTlpType::Nop));
assert_eq!(pkt.mode(), TlpMode::Flit);  // explicit mode check

// Walk a packed stream of back-to-back flit TLPs
let stream: &[u8] = &[/* packed bytes */];
for result in FlitStreamWalker::new(stream) {
    let (offset, typ, size) = result.unwrap();
    println!("TLP at offset {}: {:?} ({} bytes)", offset, typ, size);
}

Request Traits and Constructors

Note: All bytes parameters accept impl Into<Vec<u8>> — you can pass pkt.data() (&[u8]) directly without calling .to_vec(). Only new_mem_req additionally requires &TlpFmt.

Atomic-Specific Types

Error Handling

Every decoding step returns Result<_, TlpError>:

Tests

The crate has 212 passing tests (0 ignored):

cargo test                        # run all 212 tests
cargo test --lib                  # unit tests only
cargo test --test non_flit_tests  # non-flit integration tests only
cargo test --test flit_mode_tests # flit mode tests (all tiers)
cargo test --doc                  # doc examples only

See TESTS.md for the full test structure and flit mode tier descriptions.

Documentation

• docs/api_guide.md — user-facing guide: parsing flow, mode dispatch, ownership/lifetimes, error handling, deprecated-API migration, and how to test your own code against the library.
• TESTS.md — test structure, tier descriptions, FM_* byte-vector constants reference, and running individual test suites.
• docs/tlp_reference.md — byte-level TLP examples for both non-flit (PCIe 1–5) and flit mode (PCIe 6.x), DW0 layout diagrams, and test inventory.
• tlp.md — supplementary PCIe TLP encoding reference.
• docs.rs — published rustdoc for the released version.
• cargo doc --open — rustdoc for the current local build.

License

Licensed under the 3-Clause BSD License — see LICENSE.