### Manage Devices via CLI

Source: https://context7.com/intel/tbtools/llms.txt

Examples of using tbtools command-line utilities to target specific hardware components using domain, route, and adapter addressing schemes.

```bash
# Router targeting
tbauth -d 0 -r 301
# Retimer targeting
tbmargin -d 0 -r 0 -a 3 -i 1
# Adapter register access
tbdump -d 0 -r 0 -a 1 -N 10 0
# Field access
tbget -d 0 -r 0 ROUTER_CS_4.USB4\ Version
```

--------------------------------

### Build and Install tbtools

Source: https://context7.com/intel/tbtools/llms.txt

Commands to build the project from source using Cargo, including options for selective compilation and installation to the system path.

```bash
cargo build --release
cargo build --release --bin tblist --bin tbdump
cargo install --path .
cargo test
```

--------------------------------

### Install tbtools globally

Source: https://github.com/intel/tbtools/blob/main/README.md

Installs the compiled binaries into the default Cargo installation directory for system-wide access.

```shell
cargo install --path .
```

--------------------------------

### Address Thunderbolt/USB4 devices

Source: https://github.com/intel/tbtools/blob/main/README.md

Examples of how to target specific routers and retimers using domain, route, adapter, and index parameters.

```shell
# Authorize a router
tbauth -d 0 -r 301

# Run margin on a retimer
tbmargin -d 0 -r 0 -a 3 -i 1

# Dump adapter configuration space
tbdump -d 0 -r 0 -a 1 -N 10 0
```

--------------------------------

### Write to Thunderbolt Register Fields with tbset

Source: https://github.com/intel/tbtools/blob/main/README.md

The `tbset` command enables writing to specific fields within Thunderbolt registers. It allows modification of register values by specifying the register and field name, followed by the desired value. This example shows how to set the 'DPR' field in 'PORT_CS_19' to 1.

```bash
# tbset -r 0 -a 1 PORT_CS_19.DPR=1
```

--------------------------------

### Read Thunderbolt Register with tbdump

Source: https://github.com/intel/tbtools/blob/main/README.md

The `tbdump` command is used to read and display the contents of Thunderbolt registers. It supports various options for controlling the output format and verbosity. This example shows how to read register PORT_CS_18 with specific flags.

```bash
# tbdump -r 0 -N 1 -a 3 PORT_CS_18 -vv
0x00a2 0x00000410 0b00000000 00000000 00000100 00010000 PORT_CS_18
  [00:07]       0x10 Cable USB4 Version
  [08:08]        0x0 Bonding Enabled (BE)
  [09:09]        0x0 TBT3-Compatible Mode (TCM)
  [10:10]        0x1 CLx Protocol Support (CPS)
  [11:11]        0x0 RS-FEC Enabled (Gen 2) (RE2)
  [12:12]        0x0 RS-FEC Enabled (Gen 3) (RE3)
  [13:13]        0x0 Router Detected (RD)
  [16:16]        0x0 Wake on Connect Status
  [17:17]        0x0 Wake on Disconnect Status
  [18:18]        0x0 Wake on USB4 Wake Status
  [19:19]        0x0 Wake on Inter-Domain Status
  [20:20]        0x0 Cable Gen 3 Support (CG3)
  [21:21]        0x0 Cable Gen 4 Support (CG4)
  [22:22]        0x0 Cable Asymmetric Support (CSA)
  [23:23]        0x0 Cable CLx Support (CSC)
  [24:24]        0x0 AsymmetricTransitionInProgress (TIP)
```

--------------------------------

### Access Single Register Fields with tbget

Source: https://github.com/intel/tbtools/blob/main/README.md

The `tbget` command allows for reading specific fields within Thunderbolt registers using either their long or short names. This is useful for isolating and checking the value of a particular setting. The examples demonstrate reading 'Cable Asymmetric Support' using its full name and its short name 'CSA'.

```bash
# tbget -r 0 -a 1 "PORT_CS_18.Cable Asymmetric Support"
0x0
# tbget -r 0 -a 1 PORT_CS_18.CSA
0x0
```

--------------------------------

### Generate Project Documentation

Source: https://github.com/intel/tbtools/blob/main/README.md

Command to generate local HTML documentation for the library using cargo.

```bash
$ cargo doc
```

--------------------------------

### Discover Thunderbolt/USB4 Devices with Rust

Source: https://context7.com/intel/tbtools/llms.txt

Demonstrates how to enumerate all devices on the bus or target specific routers and retimers using the tbtools library. It utilizes the Address enum to specify device paths and retrieves metadata such as vendor, generation, and NVM version.

```rust
use std::io;
use tbtools::{Address, Device, Kind, find_devices, find_device};

fn main() -> io::Result<()> {
	for device in find_devices(None)? {
		println!("Found: {} ({:04x}:{:04x})", device.name(), device.vendor(), device.device());
	}

	let address = Address::Router { domain: 0, route: 0x301 };
	if let Some(device) = find_device(&address)? {
		println!("Device: {}", device.name());
	}

	let retimer_addr = Address::Retimer { domain: 0, route: 0, adapter: 3, index: 1 };
	if let Some(retimer) = find_device(&retimer_addr)? {
		println!("Retimer: {:04x}:{:04x}", retimer.vendor(), retimer.device());
	}

	Ok(())
}
```

--------------------------------

### Dump Adapter Path Configuration

Source: https://github.com/intel/tbtools/wiki/Useful-Commands

Displays the path configuration space for a specific adapter, useful for debugging PCIe downstream connections.

```bash
# tbdump -r 0 -a 9 -p -vv
```

--------------------------------

### Scripting Output in CSV Format

Source: https://github.com/intel/tbtools/blob/main/README.md

Tools like `tblist` and `tbadapters` support a `-S` option to output data in CSV format, which is suitable for scripting and automated parsing. The output includes fields like domain, route, adapter, vendor, and device information. The field order is guaranteed, though new fields may be added in the future.

```bash
# tblist -S
domain,route,adapter,index,vendor,device,vendor_name,device_name,type
0,0,,,7eb2,8087,Intel,Gen14,Router
0,1,,,1234,8087,Intel Thunderbolt generic vendor name,Intel Thunderbolt generic model name,Router
1,0,,,7eb2,8087,Intel,Gen14,Router
```

--------------------------------

### Run Rust Development Workflow Commands

Source: https://github.com/intel/tbtools/blob/main/README.md

Standard commands to ensure code quality before submitting patches. These include formatting, running tests, and executing clippy for linting.

```bash
$ cargo fmt
$ cargo test
$ cargo clippy
```

--------------------------------

### Dump Lane Adapter Capabilities

Source: https://github.com/intel/tbtools/wiki/Useful-Commands

Dumps the configuration space for a specific lane adapter to inspect link status, speeds, and power management states.

```bash
# tbdump -r 0 -a 3 -N 2 -vv LANE_ADP_CS_0
```

--------------------------------

### Generate HTML Trace Report

Source: https://github.com/intel/tbtools/wiki/Useful-Commands

Exports Thunderbolt trace data into an HTML file for visualization in a web browser.

```bash
# tbtrace dump -H -vv > trace.html
```

--------------------------------

### List Thunderbolt Devices with tblist

Source: https://github.com/intel/tbtools/wiki/Useful-Commands

Lists Thunderbolt devices, including routers and other hosts. The -v flag provides verbose output with details like UUID and NVM version. The -A flag lists all devices, including adapters and retimers.

```bash
# tblist -v
Domain 0 Route 0: 8087:7eb2 Intel Gen14
  Type: Router
  UUID: 844d8780-80c9-2c2e-ffff-ffffffffffff
  Generation: USB4

Domain 0 Route 3: 005a:de40 Other World Computing Thunderbolt Hub
  Type: Router
  Speed (Rx/Tx): 40/40 Gb/s
  Authorized: No
  UUID: d9178780-0055-a9a8-ffff-ffffffffffff
  Generation: USB4
  NVM version: 27.0
```

```bash
# tblist -A
Domain 0
Domain 0 Route 0: 8087:7eb2 Intel Gen14
Domain 0 Route 0 Adapter 3 Index 1: 8087:0d9c
Domain 0 Route 3: 005a:de40 Other World Computing Thunderbolt Hub
Domain 0 Route 3 Adapter 1 Index 3: 8087:0d9c
```

--------------------------------

### Build tbtools with Cargo

Source: https://github.com/intel/tbtools/blob/main/README.md

Compiles the entire suite of Thunderbolt/USB4 debugging tools using the Rust Cargo build system.

```shell
cargo build
```

--------------------------------

### Access Configuration Space Registers in Rust

Source: https://context7.com/intel/tbtools/llms.txt

Shows how to read and parse configuration space registers for routers and adapters. It highlights the use of field metadata to extract specific values like Vendor ID or link speed.

```rust
use std::io;
use tbtools::{Address, find_device};
use tbtools::debugfs::BitFields;

fn main() -> io::Result<()> {
	let address = Address::Router { domain: 0, route: 0 };
	let mut device = find_device(&address)?.expect("Device not found");
	device.read_registers()?;

	if let Some(reg) = device.register_by_name("ROUTER_CS_0") {
		println!("Vendor ID: 0x{:04x}", reg.field("Vendor ID"));
	}

	device.read_adapters()?;
	if let Some(adapter) = device.adapter(3) {
		if let Some(reg) = adapter.register_by_name("LANE_ADP_CS_1") {
			println!("Link: Gen{} x{}", reg.field("Current Link Speed"), reg.field("Negotiated Link Width"));
		}
	}
	Ok(())
}
```

--------------------------------

### Build specific tbtools binaries

Source: https://github.com/intel/tbtools/blob/main/README.md

Compiles only selected tools from the suite to reduce build time and binary size.

```shell
cargo build --bin tblist --bin tbdump
```

--------------------------------

### Generate TBTools Library Documentation

Source: https://context7.com/intel/tbtools/llms.txt

Uses the Rust cargo tool to generate and open the local library documentation in a web browser. This is useful for developers looking to integrate TBTools into custom automation scripts.

```shell
cargo doc --open
```

--------------------------------

### Enabling Kernel Debug Logging

Source: https://github.com/intel/tbtools/blob/main/README.md

Kernel driver logs can provide valuable debugging information. Debug logging can be enabled either by passing `thunderbolt.dyndbg=+p` to the kernel command line or by runtime modification of the dynamic debug control file. The logs can then be viewed using the `dmesg` command. This requires `CONFIG_DYNAMIC_DEBUG=y` to be set in the kernel configuration.

```bash
# echo -n 'module thunderbolt =p' > /sys/kernel/debug/dynamic_debug/control
```

--------------------------------

### List Thunderbolt/USB4 Devices - tblist

Source: https://context7.com/intel/tbtools/llms.txt

Lists all Thunderbolt/USB4 devices, including routers, retimers, and XDomain connections. Supports verbose, CSV, and tree formats for detailed device information and scripting.

```bash
$ tblist
Domain 0 Route 0: 8087:7eb2 Intel Gen14
Domain 0 Route 3: 005a:de40 Other World Computing Thunderbolt Hub

$ tblist -Av
Domain 0
  Type: Domain
  Security Level: User
  Deauthorization: Yes
  IOMMU DMA protection: Yes

Domain 0 Route 0: 8087:7eb2 Intel Gen14
  Type: Router
  UUID: 844d8780-80c9-2c2e-ffff-ffffffffffff
  Generation: USB4
  NVM version: 27.0

Domain 0 Route 0 Adapter 3 Index 1: 8087:0d9c
  Type: Retimer
  NVM version: 1.0

$ tblist -S
domain,route,adapter,index,vendor,device,vendor_name,device_name,type
0,0,,,7eb2,8087,Intel,Gen14,Router
0,1,,,1234,8087,Intel,Thunderbolt Hub,Router

$ tblist -t
/:  Domain 0
    Domain 0 Route 0: 8087:7eb2 Intel Gen14
        Domain 0 Route 3: 005a:de40 Other World Computing Thunderbolt Hub
```

--------------------------------

### Merge Kernel and Trace Logs

Source: https://github.com/intel/tbtools/wiki/Useful-Commands

Captures system logs and Thunderbolt traces, then uses a Python script to merge them into a single chronological output file for easier debugging.

```bash
# tbtrace disable
# tbtrace dump -vv > trace.out
# dmesg > dmesg.out
$ scripts/merge-logs.py dmesg.out trace.out > merged.out
```

--------------------------------

### Run Lane Margining

Source: https://github.com/intel/tbtools/wiki/Useful-Commands

Executes software-based voltage and time margining on a specified router port to verify signal integrity.

```bash
# tbmargin -r 0 -a 3
```

--------------------------------

### Vendor Defined Registers Configuration

Source: https://github.com/intel/tbtools/blob/main/README.md

The Thunderbolt tools support vendor-specific registers (VSC and VSEC) through an optional JSON configuration file (`VENDOR-registers.json`). This file can amend existing register metadata or add new ones, associating them with specific vendor IDs. The format mirrors `registers.json` but includes a `vendor_id` field.

```json
{"offset": 0, "vendor_id": [32902, 32903], "cap_id": 5, "vs_cap_id": 1, "name": "VENDOR_REG_0"},
{"offset": 1, "vendor_id": [32902, 32903], "cap_id": 5, "vs_cap_id": 1, "name": "VENDOR_REG_1"}
```

--------------------------------

### Capture Transport Layer Packet Traces in Rust

Source: https://context7.com/intel/tbtools/llms.txt

Provides a workflow for enabling, reading, and clearing the transport layer packet trace buffer. It includes logic to verify tracing support and parse individual packets from the live buffer.

```rust
use std::io;
use tbtools::trace;

fn main() -> io::Result<()> {
	trace::mount()?;
	if !trace::supported() { return Ok(()); }
	trace::enable()?;
	trace::disable()?;

	for entry in trace::live_buffer()? {
		println!("{} Domain {} Route {:x}", entry.function(), entry.domain_index(), entry.route());
	}

	trace::clear()?;
	Ok(())
}
```

--------------------------------

### List Thunderbolt Tunnels with tbtunnels

Source: https://github.com/intel/tbtools/wiki/Useful-Commands

Lists all active Thunderbolt tunnels within a specified domain. The -d option selects the domain.

```bash
# tbtunnels -d 0
Domain 0 Route 0 Adapter 5 ⇔  Domain 0 Route 303 Adapter 13: DisplayPort
Domain 0 Route 0 Adapter 7 ⇔  Domain 0 Route 303 Adapter 5: DMA
Domain 0 Route 0 Adapter 9 ⇔  Domain 0 Route 3 Adapter 9: PCIe
Domain 0 Route 0 Adapter 13 ⇔  Domain 0 Route 3 Adapter 20: USB 3
Domain 0 Route 3 Adapter 10 ⇔  Domain 0 Route 303 Adapter 9: PCIe
Domain 0 Route 3 Adapter 21 ⇔  Domain 0 Route 303 Adapter 16: USB 3
```

--------------------------------

### DisplayPort Tunnel Bandwidth Status Script

Source: https://github.com/intel/tbtools/wiki/Useful-Commands

A helper script to extract and display bandwidth information for DisplayPort tunnels. It shows tunnel status, bandwidth modes, group, estimated, requested, allocated bandwidth, link rate, and lane count.

```bash
# /usr/share/tbtools/scripts/tb-bandwidth.sh 
[Thunderbolt/USB4 Info]:
TBHost0:
	Adapter:DP IN-5
		Tunnel    : active
		DPBWMode  : enabled
		Group     : 0x1
		Estimated : 34.50 Gb/s
		Requested : 4.50 Gb/s
		Allocated : 4.50 Gb/s
		Link Rate : RBR(1.62 Gb/s)
		Lane Count: 4
	Adapter:DP IN-6
		Tunnel    : inactive

[Display Info]:
	CONNECTOR:260:DP-2: connected
		Resolution: 1920x1080
		BPP       : 30
		Frequency : 60Hz
		Encoder   : [ENCODER:259:DDITC1/PHYTC1]
```

--------------------------------

### Manage Kernel Driver Tracing with tbtrace

Source: https://github.com/intel/tbtools/blob/main/README.md

Commands to enable, disable, and dump trace buffers for the transport layer control packets. The dump command supports verbose output for detailed register access analysis.

```bash
# tbtrace enable
# tbtrace disable
# tbtrace dump -vv
```

--------------------------------

### Dump USB4 Router Version

Source: https://github.com/intel/tbtools/wiki/Useful-Commands

Retrieves the USB4 version identifier from a specific Thunderbolt router using the tbget utility.

```bash
# tbget -r 0 ROUTER_CS_4.USB4\ Version
```

--------------------------------

### Write Thunderbolt/USB4 Registers - tbset

Source: https://context7.com/intel/tbtools/llms.txt

Writes values to registers or register fields by name or offset. Requires kernel configuration `CONFIG_USB4_DEBUGFS_WRITE=y`.

```bash
# Write a register field by name
$ tbset -r 0 -a 1 PORT_CS_19.DPR=1

# Write full register value by offset
$ tbset -r 0 0x05=0x12345678
```

--------------------------------

### Dump Router DROM with tbdump

Source: https://github.com/intel/tbtools/wiki/Useful-Commands

Dumps the DROM (Device ROM) of a Thunderbolt router. This requires kernel support for exposing DROM through debugfs. The -r option specifies the router, -R enables DROM dumping, and -vv provides verbose output.

```bash
# ./tbdump -r 1 -R -vv
0x0000 0x24 0x00 0xf1 0x91 0xf0 0x94 0xf3 0x3d $......=
0x0008 0x00 0x41 0x3b 0x61 0xa5 0x01 0x5e 0x00 .A;a..^.
0x0010 0x3d 0x00 0x15 0x00 0x01 0x01           =.....
  CRC8: 0x24 ✔
  UUID: 0x3df394f091f100
  CRC32: 0xa5613b41 ✔
  Version: 1 (Thunderbolt 3 Compatible)
0x0016 0x08 0x81 0x80 0x02 0x80 0x00 0x00 0x00 ........
```

--------------------------------

### Authorize/Deauthorize Thunderbolt Tunnels with tbauth

Source: https://github.com/intel/tbtools/wiki/Useful-Commands

Authorizes or deauthorizes Thunderbolt tunnels. The -r option specifies the route, and -D enables deauthorization. Deauthorization support can be verified using `tblist -Av`.

```bash
# tbauth -r 3
```

```bash
# tbauth -r 3 -D
```

```bash
# tblist -Av
Domain 0
  Type: Domain
  Security Level: User
  Deauthorization: Yes
  IOMMU DMA protection: Yes
  ...
```

--------------------------------

### Authorize Thunderbolt/USB4 Devices - tbauth

Source: https://context7.com/intel/tbtools/llms.txt

Authorizes or de-authorizes Thunderbolt/USB4 devices for PCIe tunneling, necessary for user or secure security levels. Supports authorization, de-authorization, and secure key operations.

```bash
# Authorize a device (enables PCIe tunnel)
$ tbauth -d 0 -r 3

# De-authorize a device (disables PCIe tunnel, software CM only)
$ tbauth -d 0 -r 3 -D

# Authorize with secure key (generates and saves key)
$ tbauth -d 0 -r 3 -A /path/to/keyfile

# Challenge with existing secure key
$ tbauth -d 0 -r 3 -C /path/to/keyfile
```

--------------------------------

### Read Thunderbolt/USB4 Registers - tbget

Source: https://context7.com/intel/tbtools/llms.txt

Reads specific registers or fields by name or offset, designed for scripting with flexible output formats (binary, decimal). Supports querying register names and fields.

```bash
# Read USB4 version field from router
$ tbget -r 0 ROUTER_CS_4.USB4\ Version
0x20

# Read a field using short name
$ tbget -r 0 -a 1 PORT_CS_18.CSA
0x0

# Read by absolute offset (hex)
$ tbget -r 0 0x04
0x12345678

# Output in binary format
$ tbget -r 0 -B ROUTER_CS_0.Vendor\ ID
0b1000000010000111

# Output in decimal format
$ tbget -r 0 -D ROUTER_CS_1.Max\ Adapter
13

# Query available register names matching pattern
$ tbget -r 0 -Q ROUTER
ROUTER_CS_0
ROUTER_CS_1
ROUTER_CS_2
...

# Query all fields of a register
$ tbget -r 0 -Q TMU_RTR. -v
TMU_RTR_CS_0.UCAP 0x0028 [00:00]
TMU_RTR_CS_0.DCAP 0x0028 [01:01]
```

--------------------------------

### Dump Thunderbolt/USB4 Registers - tbdump

Source: https://context7.com/intel/tbtools/llms.txt

Reads and displays registers from various configuration spaces (router, adapter, path, counters). Supports named registers with detailed field information and verbose output.

```bash
# Dump first 10 router registers of host router
$ tbdump -d 0 -r 0 -N 10 0

# Dump adapter config space for adapter 3 with verbose output
$ tbdump -r 0 -a 3 -vv 0
0x0000 0x0001043e 0b00000000 00000001 00000100 00111110 .... ADP_CS_0
  [00:07]      0x3e Next Capability Pointer
  [08:15]        0x4 Capability ID
  [16:16]        0x1 Port Enable (PE)

# Dump named register with full field details
$ tbdump -r 0 -N 1 -a 3 PORT_CS_18 -vv
0x00a2 0x00000410 0b00000000 00000000 00000100 00010000 PORT_CS_18
  [00:07]       0x10 Cable USB4 Version
  [08:08]        0x0 Bonding Enabled (BE)
  [10:10]        0x1 CLx Protocol Support (CPS)
  [13:13]        0x0 Router Detected (RD)

# Dump path config space of adapter 9
$ tbdump -r 0 -a 9 -p -vv
0x0010 0x800e180d PATH_CS_0
  [00:06]        0xd Output HopID
  [11:16]        0x3 Output Adapter
  [31:31]        0x1 Valid

# Dump router DROM with detailed entries
$ tbdump -r 1 -R -vv
0x0000 0x24 0x00 0xf1 0x91...
  CRC8: 0x24 Valid
  UUID: 0x3df394f091f100
  Vendor: CalDigit, Inc.
  Model: TB3-MiniDock-HM

# Dump specific capability by ID
$ tbdump -r 0 -C 5 -vv 0
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.