README.md

# topo_tools

拓扑映射工具集，用于生成 DCU/GPU 与网卡（NIC）的 NUMA 亲和性拓扑映射文件。

## 文件结构

```
topo_tools/
├── generate_topo_mapping.py   # DCU-NIC 拓扑映射生成器（主要工具）
├── extract_slot_info.sh        # Slot/OAM 设备信息提取脚本
└── README.md                  # 本文档
```

## 功能说明

### 1. generate_topo_mapping.py

DCU-NIC 拓扑映射生成器，根据系统硬件信息自动生成符合 NCCL 规范的 topology mapping XML 文件。

**主要功能：**

- **自动获取系统信息**
  - CPU 架构和厂商（通过 `lscpu` 获取）
  - 网卡类型、NUMA 节点（通过 `/sys/class/infiniband/*` 获取）
  - 网卡速率和链路类型（通过 `ibstat` 获取）
  - DCU（GPU）的 NUMA 节点（通过 `hy-smi --showtopo` 获取）

- **自动生成 group name**
  - 格式：`GPU架构_GPU数量_CPU架构_CPU厂商_网卡前缀_网卡数_网卡类型_网卡速率列表_HyLink类型_HyLink分组关系`
  - 示例：`gfx936_8_x86_64_HygonGenuine_mlx5_11_InfiniBand_200-200-200-200-200-200-200-200-200-200_1_8_1`

- **NUMA 亲和性映射**
  - 支持 DCU 组合规则（DCU 0,1 使用同一 NUMA，DCU 2,3 使用同一 NUMA 等）
  - 支持 NUMA 分组规则（NUMA 0-3 为 Group 0，NUMA 4-7 为 Group 1）

- **灵活的配置选项**
  - 支持通过 `--nic-type` 参数指定网卡类型过滤（如 MT4129）
  - 支持通过 `--output` 参数指定输出文件路径

**使用示例：**

```bash
# 默认运行（过滤 MT4129 类型网卡）
python3 generate_topo_mapping.py

# 指定网卡类型
python3 generate_topo_mapping.py --nic-type MT4129

# 指定输出文件
python3 generate_topo_mapping.py --output /path/to/output.xml
```

**应用生成的拓扑映射：**

```bash
export NCCL_TOPO_MAPPING_FILE=/public/wkx/tools/topo_mapping_custom_new.xml
export NCCL_TOPO_FILE=/public/wkx/tools/topo_mapping_custom_new.xml
```

### 2. extract_slot_info.sh

Slot/OAM 设备信息提取脚本，用于从 dmidecode 获取交换板和 OAM 模块的硬件信息。

**主要功能：**

- 提取 Slot 设备信息（SW0_Slot1, SW1_Slot4, SW2_Slot5, SW3_Slot8）
- 提取 OAM 模块信息（SW1_OAM_0-7, SW2_OAM_0-7）
- 生成格式化的设备对照表

**使用示例：**

```bash
bash extract_slot_info.sh
```

## 限制条件

### generate_topo_mapping.py

1. **硬件依赖**
   - 需要 `hy-smi` 命令获取 DCU NUMA 信息
   - 需要 `ibstat` 命令获取网卡速率和链路类型
   - 需要 `/sys/class/infiniband/` 目录存在（InfiniBand 网卡）
   - 需要 root 权限或相应的硬件访问权限

2. **DCU/GPU 数量**
   - 默认支持 8 个 DCU（GPU 0-7）
   - 如需支持更多 DCU，需修改 `GPU_COUNT` 常量

3. **NUMA 节点**
   - 默认支持 8 个 NUMA 节点（0-7）
   - NUMA 分组规则：0-3 → Group 0，4-7 → Group 1

4. **DCU NUMA 规则**
   - DCU 0,1 使用 DCU 0 的 NUMA
   - DCU 2,3 使用 DCU 3 的 NUMA
   - DCU 4,5 使用 DCU 4 的 NUMA
   - DCU 6,7 使用 DCU 7 的 NUMA

5. **网卡过滤**
   - 默认过滤 MT4129 类型网卡（CX7）
   - 网卡数量和速率统计基于所有 mlx5_* 网卡
   - 网络类型（InfiniBand/Ethernet）基于指定类型的网卡

6. **错误处理**
   - 如果系统信息获取失败，group name 将默认为 "topo"
   - 建议用户检查并手动更新 group name

### extract_slot_info.sh

1. **权限要求**
   - 需要 root 权限运行 `dmidecode`

2. **硬件依赖**
   - 需要支持 dmidecode 的服务器硬件
   - 需要存在 SW*_Slot 和 SW*_OAM 类型的设备

3. **输出格式**
   - 输出结果包含 Slot1, Slot4, Slot5, Slot8(为插着网卡的位置，可以从BMC查看) 和 OAM_0 到 OAM_7
   - 其他 Slot 编号会被过滤忽略