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.

rtlp-lib 0.3.1