USER_MANUAL.md

# DCU Profile Tools 用户手册

## 概述

DCU Profile Tools 是一个针对 DCU 环境的综合性能分析工具。该工具整合了现有的环境检查脚本功能，使用户能够便捷地执行性能分析、收集相关日志，并生成可执行的报告。

## 功能特性

### 核心功能
- **系统信息收集**: CPU、内存、操作系统版本等基础信息
- **PCIe设备检查**: DCU设备识别、PCIe链路状态分析
- **驱动状态检查**: 内核模块加载状态、驱动文件完整性
- **系统日志收集**: dmesg、系统日志文件分析
- **硬件信息检查**: 主板、BIOS、IPMI信息收集
- **性能指标监控**: CPU、内存、磁盘使用率实时监控

### 高级特性
- **模块化检查**: 可选择性运行特定检查模块
- **并行处理**: 多线程并发执行检查任务
- **详细日志**: 完整的操作记录和错误追踪
- **报告生成**: JSON和文本格式的分析报告
- **数据打包**: 一键导出所有分析结果
- **跨平台支持**: 独立可执行文件，无需Python环境

## 安装和使用

### 系统要求
- 操作系统: Linux (推荐 Kylin、CentOS、Ubuntu)
- 架构: x86_64
- 权限: 建议使用root权限运行以获得完整信息

### 安装步骤
1. 下载可执行文件 `dcu_analyzer`
2. 赋予执行权限: `chmod +x dcu_analyzer`
3. 运行工具: `./dcu_analyzer`

### 基本用法

#### 运行所有检查
```bash
./dcu_analyzer
```

#### 运行指定检查模块
```bash
./dcu_analyzer -c system pcie driver
```

#### 指定输出目录
```bash
./dcu_analyzer -o /tmp/my_analysis
```

#### 调试模式
```bash
./dcu_analyzer -d
```

#### 静默模式（仅显示错误）
```bash
./dcu_analyzer -q
```

## 命令行选项

```
用法: dcu_analyzer [选项]

可选参数:
  -h, --help            显示帮助信息并退出
  -c {system,pcie,driver,logs,hardware,performance} [{...}]
                        指定要运行的检查模块
  -o OUTPUT, --output OUTPUT
                        指定输出目录
  -t LOG_AGE, --log-age LOG_AGE
                        收集日志的时间范围(小时) (默认: 24)
  -s LOG_SIZE, --log-size LOG_SIZE
                        日志文件大小限制(MB) (默认: 10)                        
  --auto-install-pkg    自动安装缺失的软件包
  -d, --debug           启用调试模式
  -q, --quiet           静默模式（仅显示错误）
  -v, --version         显示版本号并退出
```

## 检查模块说明

### system (系统信息)
收集系统基础信息，包括：
- CPU型号和核心数
- 内存容量和使用情况
- 操作系统版本和内核信息
- Python环境信息

### pcie (PCIe设备)
检查PCIe设备状态，包括：
- DCU设备识别
- PCIe链路速度和宽度
- 设备拓扑结构
- BAR地址分配状态

### driver (驱动状态)
验证驱动程序状态，包括：
- 内核模块加载状态
- 驱动文件完整性
- IOMMU配置
- 固件文件检查

### logs (系统日志)
收集和分析系统日志，包括：
- dmesg内核日志
- 系统日志文件
- 最近一小时的日志记录
- 错误和警告信息

### hardware (硬件信息)
收集硬件详细信息，包括：
- 主板型号和序列号
- BIOS版本和配置
- IPMI管理信息（如可用）
- 硬件兼容性检查

### performance (性能指标)
实时性能监控，包括：
- CPU使用率
- 内存使用率
- 磁盘空间使用率
- 系统负载平均值

## 输出文件说明

### 目录结构
```
dcu_analysis/
├── logs/
│   └── analysis.log          # 详细日志文件
├── data/
|   ├── pcie_info             # pcie设备信息
│   ├── cpu_info.txt          # CPU信息
│   ├── memory_info.txt       # 内存信息
│   ├── os_info.txt           # OS系统信息
│   ├── dmesg.log             # 内核日志
│   ├── hardware.txt          # 硬件信息
|   ├── hy_smi_info.txt       # DCU状态信息
|   ├── pcie_dcu.log          # DCU拓扑信息
└── reports/
    ├── analysis_report.json  # JSON格式报告
    └── analysis_summary.txt  # 文本格式摘要
```

### 报告文件格式

#### JSON报告 (`analysis_report.json`)
包含完整的检查结果、元数据和统计数据，便于程序化处理。

#### 文本摘要 (`analysis_summary.txt`)
提供人类可读的检查摘要，包括：
- 检查统计信息
- 各模块状态
- 执行时间
- 整体评估结果

## 结果解读

### 状态说明
- **PASS**: 检查通过，未发现问题
- **FAIL**: 检查失败，发现严重问题
- **WARNING**: 检查完成，发现潜在问题
- **INFO**: 信息收集，无状态判断

### 常见问题处理

#### PCIe设备未识别
- 检查物理连接
- 验证供电是否正常
- 检查BIOS PCIe配置

#### 驱动加载失败
- 确认驱动文件完整性
- 检查内核版本兼容性
- 验证IOMMU配置

#### 性能指标异常
- CPU使用率过高：检查后台进程
- 内存使用率过高：优化应用程序
- 磁盘空间不足：清理无用文件

## 故障排除

### 权限问题
如果遇到权限错误，请使用root权限运行：
```bash
sudo ./dcu_analyzer
```

### 命令执行失败
- 检查系统命令是否可用
- 验证PATH环境变量
- 查看详细日志获取错误信息

### 输出目录权限
确保对输出目录有写入权限，或使用 `-o` 指定有权限的目录。

## 技术支持

如遇到问题，请提供以下信息：
1. 工具版本号 (`./dcu_analyzer -v`)
2. 操作系统版本
3. 完整的错误日志
4. 复现步骤

## 版本历史

### v1.0.0 (2026-02-25)
- 初始版本发布
- 集成6个核心检查模块
- 支持命令行界面
- 提供JSON和文本报告
- 支持数据打包导出