# fstree

**Repository Path**: lasimu/fstree

## Basic Information

- **Project Name**: fstree
- **Description**: A CLI tool and library for browsing and querying FST/VCD waveform files with interactive exploration capabilities.
一个用于浏览和查询 FST/VCD 波形文件的 CLI 工具和库，支持交互式探索。

- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-14
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# fstree

一个用于浏览和查询 FST/VCD 波形文件的 CLI 工具和库，支持交互式探索。

## 特性

- **层级导航**：像文件系统一样浏览信号层级，支持 Tab 补全
- **信号搜索**：通过名称模式查找信号（支持 glob）
- **时间管理**：跟踪和导航仿真时间
- **值查询**：获取特定时刻的信号值，自动格式化显示
- **边沿导航**：查找并导航到信号跳变
- **值搜索**：跨信号搜索特定值（支持 glob 模式）
- **输出重定向**：将命令输出保存到文件
- **数据导出**：导出信号数据到 CSV/JSON

## 安装

```bash
cargo install --path .
```

## 使用方法

fstree 支持两种模式：**交互模式**和**命令行模式**。

### 交互模式

交互模式加载波形文件一次，提供类似 REPL 的环境来探索层级结构：

```bash
# 进入交互模式（默认模式，不指定子命令时）
fstree -f waveform.fst
fstree -f waveform.fst interactive

# 在交互模式中：
/> help                    # 显示可用命令
/> ls                      # 列出当前路径下的信号和模块
/> ls -s                   # 仅列出信号（不包含模块）
/> cd sys/nodes            # 导航到不同路径
/> pwd                     # 打印当前路径
/> tree                    # 显示当前路径的树形视图
/> search "clk*"           # 搜索信号
/> search "clk*" -d 3      # 带深度限制的搜索
/> info /sys/nodes/cpu0/clk  # 显示信号详情
/> time                    # 显示当前时间和时间范围
/> time 100ns              # 设置当前时间
/> get /sys/nodes/cpu0/clk # 获取当前时间的值
/> get /sys/nodes/cpu0/clk 100ns  # 获取特定时间的值
/> next /sys/nodes/cpu0/clk       # 查找当前时间之后的下一个边沿
/> find */clk 1            # 在匹配的信号中搜索值（支持 glob）
/> find /sys/clk 1 0 1us   # 带时间范围的搜索
/> save output.txt ls /sys # 保存命令输出到文件
/> ls > output.txt         # 重定向输出到文件（覆盖）
/> ls >> output.txt        # 重定向输出到文件（追加）
/> quit                    # 退出交互模式
```

交互模式在命令之间维护状态（当前路径、当前时间、加载的文件），非常适合探索性使用。

#### Tab 补全

交互模式支持路径的 Tab 补全：
- 输入部分路径后按 Tab 键补全
- 支持绝对路径和相对路径
- 同时补全模块和信号

#### 输出重定向

将命令输出保存到文件：
```bash
# 使用 save 命令（适用于所有命令）
/> save output.txt find */clk 1

# 使用 shell 风格重定向（适用于简单命令）
/> help > help.txt
/> time >> log.txt
```

### 命令行模式

命令行模式执行单个命令后退出：

```bash
# 列出根目录下的信号和模块
fstree -f waveform.fst ls

# 列出特定路径下仅信号
fstree -f waveform.fst ls /top/cpu0/ -s

# 显示树形视图
fstree -f waveform.fst tree /top/
fstree -f waveform.fst tree /top/ --depth 2

# 搜索信号
fstree -f waveform.fst search "clk*"
fstree -f waveform.fst search "*reset*" --depth 3

# 获取特定时间的信号值
fstree -f waveform.fst get /top/cpu0/clk --time 100ns

# 查找信号为特定值的时间点
fstree -f waveform.fst when /top/cpu0/reset --value 1
```

命令行模式适合脚本编写和自动化。

### 导出数据

```bash
# 导出到 CSV
fstree -f waveform.fst export "/top/cpu0/*" --start 0 --end 1us -o signals.csv

# 导出到 JSON
fstree -f waveform.fst export "/top/cpu0/clk" --start 0 -o data.json --format json
```

## 交互命令参考

### 导航
- `ls [path] [-s]` - 列出信号和模块（使用 `-s` 仅显示信号）
- `cd [path]` - 更改当前路径
- `pwd` - 打印当前路径
- `tree [path]` - 显示树形视图

### 搜索
- `search <pattern> [-d <depth>]` - 按模式搜索信号（深度限制）
- `find <path> <value> [start] [end]` - 搜索值（路径支持 glob）

### 时间与值
- `time [time]` - 显示或设置当前时间
- `get <path> [time]` - 获取信号值（默认：当前时间）
- `next <path> [time]` - 查找时间之后的下一个边沿
- `info <path>` - 显示信号详情

### 输出
- `save <file> <command> [args]` - 保存命令输出到文件
- `command > file` - 重定向输出（覆盖）
- `command >> file` - 重定向输出（追加）

### 帮助
- `help` - 显示可用命令
- `quit` - 退出交互模式

## 库使用示例

```rust
use fstree::FstReader;

let mut reader = FstReader::open("waveform.fst")?;

// 列出信号
let signals = reader.list_signals("/top/cpu0/")?;
for sig in signals {
    println!("{}: {} bits", sig.name, sig.width);
}

// 获取特定时间的值
let value = reader.get_value("/top/cpu0/clk", 100_000_000)?; // 100ns，单位为 fs
println!("clk @ 100ns = {}", value);

// 查找下一个边沿
if let Some((time, value)) = reader.find_next_edge("/top/cpu0/clk", 0)? {
    println!("下一个边沿在 {}: {}", time, value);
}

// 搜索值
let results = reader.search_value("/top/cpu0/clk", "1", 0, 1_000_000_000)?;
for (time, value) in results {
    println!("在 {} 找到 {}", time, value);
}
```

## 时间格式

时间值可以带单位指定：
- `100` 或 `100fs` - 飞秒
- `100ps` - 皮秒
- `1ns` - 纳秒
- `1us` - 微秒
- `1ms` - 毫秒
- `1s` - 秒

## 信号值格式

信号值根据位宽自动格式化：
- 1-8 位：`0x00` - `0xff`
- 9-16 位：`0x0000` - `0xffff`
- 17-32 位：`0x00000000` - `0xffffffff`
- 33-64 位：`0x0000000000000000` - `0xffffffffffffffff`
- >64 位：`[N bits]`

## 开发

```bash
# 构建
cargo build

# 运行测试
cargo test

# 使用测试文件运行
cargo run -- -f lasimu.fst ls
```

## 许可证

MIT