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

Category	TLP Types	Trait / Constructor
Memory Requests	MemRead (32/64), MemWrite (32/64), MemReadLock	MemRequest / new_mem_req()
IO Requests	IORead, IOWrite	MemRequest / new_mem_req()
Config Requests	Type 0 Read/Write, Type 1 Read/Write	ConfigurationRequest / new_conf_req()
Completions	Cpl, CplData, CplLocked, CplDataLocked	CompletionRequest / new_cmpl_req()
Messages	MsgReq, MsgReqData	MessageRequest / new_msg_req()
Atomic Ops	FetchAdd, Swap, CompareSwap (32/64-bit operands)	AtomicRequest / new_atomic_req()
DMWr	Deferrable Memory Write (32/64)	MemRequest / new_mem_req()

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.2"

Usage

use rtlp_lib::{
    TlpPacket, TlpFmt, TlpType,
    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);

let tlp_type   = packet.get_tlp_type().unwrap();
let tlp_format = packet.get_tlp_format().unwrap();

match tlp_type {
    TlpType::MemReadReq | TlpType::MemWriteReq |
    TlpType::MemReadLockReq |
    TlpType::DeferrableMemWriteReq |
    TlpType::IOReadReq | TlpType::IOWriteReq => {
        let mr = new_mem_req(packet.get_data(), &tlp_format);
        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.get_data(), &tlp_format);
        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.get_data(), &tlp_format);
        println!("completion status={}", cpl.cmpl_stat());
    }
    TlpType::MsgReq | TlpType::MsgReqData => {
        let msg = new_msg_req(packet.get_data(), &tlp_format);
        println!("message code=0x{:02X}", msg.msg_code());
    }
    _ => println!("TLP type: {:?}", tlp_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

Type	Description
TlpPacket	Full packet: DW0 header + remaining data bytes
TlpPacketHeader	DW0-only wrapper with accessor methods for every header field
TlpFmt	Format enum: NoDataHeader3DW, NoDataHeader4DW, WithDataHeader3DW, WithDataHeader4DW, TlpPrefix
TlpType	21-variant enum covering all decoded TLP types
TlpError	InvalidFormat, InvalidType, UnsupportedCombination, InvalidLength

Request Traits and Constructors

Trait	Fields	Constructor
MemRequest	address(), req_id(), tag(), ldwbe(), fdwbe()	new_mem_req(bytes, &fmt)
ConfigurationRequest	req_id(), tag(), bus_nr(), dev_nr(), func_nr(), ext_reg_nr(), reg_nr()	new_conf_req(bytes, &fmt)
CompletionRequest	cmpl_id(), cmpl_stat(), bcm(), byte_cnt(), req_id(), tag(), laddr()	new_cmpl_req(bytes, &fmt)
MessageRequest	req_id(), tag(), msg_code(), dw3(), dw4()	new_msg_req(bytes, &fmt)
AtomicRequest	op(), width(), req_id(), tag(), address(), operand0(), operand1()	new_atomic_req(&pkt)

Atomic-Specific Types

Type	Variants
AtomicOp	FetchAdd, Swap, CompareSwap
AtomicWidth	W32, W64

Error Handling

Every decoding step returns Result<_, TlpError>:

Error	Meaning
InvalidFormat	The 3-bit Fmt field does not match any known format
InvalidType	The 5-bit Type field does not match any known encoding
UnsupportedCombination	Valid Fmt + Type individually, but not a legal pair (e.g. DMWr with NoData)
InvalidLength	Byte slice is too short for the expected header + payload

Tests

The crate has 102 tests across four categories:

Category	File	Count
Unit tests	src/lib.rs	30
API contract tests	tests/api_tests.rs	50
Integration tests	tests/tlp_tests.rs	16
Doc tests	src/lib.rs	6

cargo test            # run all 102 tests
cargo test --lib      # unit tests only
cargo test --test tlp_tests   # integration tests only
cargo test --doc      # doc examples only

Documentation

The documentation of the released version is available on docs.rs. To generate current documentation locally: cargo doc --open

License

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