Skip to content

Commit dcb0ba3

Browse files
yeahdongcnyeahdongcn
authored
Merge pull request #7 from ChenyuJia-MT/add_user_manual
Add user manual and usage examples
2 parents e238abc + 77cb497 commit dcb0ba3

15 files changed

Lines changed: 2119 additions & 0 deletions

‎MANUAL.md‎

Lines changed: 1020 additions & 0 deletions
Large diffs are not rendered by default.

‎examples/01_library_basics.py‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
"""
2+
示例 01: 库基础操作
3+
演示 MTML 库的初始化、版本查询、设备枚举、关闭等基础操作，
4+
以及多次 init/shutdown 循环调用。
5+
"""
6+
7+
from pymtml import *
8+
9+
print("=" * 60)
10+
print(" 示例 01: 库基础操作")
11+
print("=" * 60)
12+
13+
# 1. 初始化
14+
mtmlLibraryInit()
15+
print("[1] 库初始化成功")
16+
17+
# 2. 查询库版本
18+
version = mtmlLibraryGetVersion()
19+
print(f"[2] MTML 库版本: {version}")
20+
21+
# 3. 查询驱动版本
22+
system = mtmlLibraryInitSystem()
23+
driver_ver = mtmlSystemGetDriverVersion(system)
24+
print(f"[3] 驱动版本: {driver_ver}")
25+
mtmlLibraryFreeSystem(system)
26+
27+
# 4. 枚举设备
28+
device_count = mtmlLibraryCountDevice()
29+
print(f"[4] 检测到 {device_count} 个 GPU 设备")
30+
31+
for i in range(device_count):
32+
device = mtmlLibraryInitDeviceByIndex(i)
33+
name = mtmlDeviceGetName(device)
34+
uuid = mtmlDeviceGetUUID(device)
35+
print(f" 设备 {i}: {name} (UUID: {uuid})")
36+
37+
# 5. 按 UUID 获取设备
38+
if device_count > 0:
39+
device = mtmlLibraryInitDeviceByIndex(0)
40+
uuid = mtmlDeviceGetUUID(device)
41+
device_by_uuid = mtmlLibraryInitDeviceByUuid(uuid)
42+
print(f"[5] 按 UUID 获取设备: {mtmlDeviceGetName(device_by_uuid)}")
43+
44+
# 6. 按 PCI SBDF 获取设备
45+
if device_count > 0:
46+
pci = mtmlDeviceGetPciInfo(mtmlLibraryInitDeviceByIndex(0))
47+
device_by_pci = mtmlLibraryInitDeviceByPciSbdf(pci.sbdf)
48+
print(f"[6] 按 PCI SBDF ({pci.sbdf}) 获取设备: {mtmlDeviceGetName(device_by_pci)}")
49+
50+
# 7. 关闭
51+
mtmlLibraryShutDown()
52+
print("[7] 库关闭成功")
53+
54+
# 8. 多次 init/shutdown 循环
55+
print("[8] 测试多次 init/shutdown 循环:")
56+
for cycle in range(3):
57+
mtmlLibraryInit()
58+
count = mtmlLibraryCountDevice()
59+
mtmlLibraryShutDown()
60+
print(f" 第 {cycle + 1} 次循环: 检测到 {count} 个设备 ✓")
61+
62+
print("\n完成!")

‎examples/02_device_info.py‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
"""
2+
示例 02: 设备信息查询
3+
演示如何查询 GPU 设备的基本属性信息。
4+
"""
5+
6+
from pymtml import *
7+
8+
print("=" * 60)
9+
print(" 示例 02: 设备信息查询")
10+
print("=" * 60)
11+
12+
mtmlLibraryInit()
13+
14+
for i in range(mtmlLibraryCountDevice()):
15+
device = mtmlLibraryInitDeviceByIndex(i)
16+
17+
print(f"\n--- 设备 {i} ---")
18+
print(f" 名称: {mtmlDeviceGetName(device)}")
19+
print(f" 索引: {mtmlDeviceGetIndex(device)}")
20+
print(f" UUID: {mtmlDeviceGetUUID(device)}")
21+
print(f" 品牌: {'MTT' if mtmlDeviceGetBrand(device) == MTML_BRAND_MTT else 'Unknown'}")
22+
23+
try:
24+
print(f" 序列号: {mtmlDeviceGetSerialNumber(device)}")
25+
except MTMLError as e:
26+
print(f" 序列号: [不可用: {e}]")
27+
28+
print(f" VBIOS 版本: {mtmlDeviceGetVbiosVersion(device)}")
29+
30+
try:
31+
print(f" MtBIOS 版本: {mtmlDeviceGetMtBiosVersion(device)}")
32+
except MTMLError as e:
33+
print(f" MtBIOS 版本: [不可用: {e}]")
34+
35+
print(f" GPU 核心数: {mtmlDeviceCountGpuCores(device)}")
36+
print(f" 功耗: {mtmlDeviceGetPowerUsage(device)} mW "
37+
f"({mtmlDeviceGetPowerUsage(device) / 1000:.1f} W)")
38+
39+
# PCI 信息
40+
pci = mtmlDeviceGetPciInfo(device)
41+
print(f" PCI SBDF: {pci.sbdf}")
42+
print(f" PCI Bus ID: {pci.busId}")
43+
print(f" PCI 设备ID: {pci.pciDeviceId:#010x}")
44+
print(f" PCIe 代数: 当前 Gen{pci.pciCurGen} / 最大 Gen{pci.pciMaxGen}")
45+
print(f" PCIe 宽度: 当前 x{pci.pciCurWidth} / 最大 x{pci.pciMaxWidth}")
46+
print(f" PCIe 速率: 当前 {pci.pciCurSpeed:.1f} GT/s / 最大 {pci.pciMaxSpeed:.1f} GT/s")
47+
48+
# PCIe 插槽信息
49+
try:
50+
slot = mtmlDeviceGetPcieSlotInfo(device)
51+
print(f" PCIe 插槽: {slot.slotName} (type={slot.slotType})")
52+
except MTMLError as e:
53+
print(f" PCIe 插槽: [不可用: {e}]")
54+
55+
# 设备属性
56+
prop = mtmlDeviceGetProperty(device)
57+
virt_cap = "支持" if prop.virtCapability == MTML_DEVICE_SUPPORT_VIRTUALIZATION else "不支持"
58+
mpc_cap = "支持" if prop.mpcCapability == MTML_DEVICE_SUPPORT_MPC else "不支持"
59+
print(f" 虚拟化: {virt_cap}")
60+
print(f" MPC: {mpc_cap}")
61+
62+
mtmlLibraryShutDown()
63+
print("\n完成!")

‎examples/03_gpu_monitoring.py‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
"""
2+
示例 03: GPU 监控
3+
演示如何查询 GPU 利用率、温度、时钟频率及各引擎利用率。
4+
"""
5+
6+
from pymtml import *
7+
8+
print("=" * 60)
9+
print(" 示例 03: GPU 监控")
10+
print("=" * 60)
11+
12+
mtmlLibraryInit()
13+
14+
engine_names = {
15+
MTML_GPU_ENGINE_GEOMETRY: "几何引擎",
16+
MTML_GPU_ENGINE_2D: "2D 引擎",
17+
MTML_GPU_ENGINE_3D: "3D 引擎",
18+
MTML_GPU_ENGINE_COMPUTE: "计算引擎",
19+
}
20+
21+
for i in range(mtmlLibraryCountDevice()):
22+
device = mtmlLibraryInitDeviceByIndex(i)
23+
name = mtmlDeviceGetName(device)
24+
print(f"\n--- 设备 {i}: {name} ---")
25+
26+
with mtmlGpuContext(device) as gpu:
27+
# 基本指标
28+
util = mtmlGpuGetUtilization(gpu)
29+
temp = mtmlGpuGetTemperature(gpu)
30+
clock = mtmlGpuGetClock(gpu)
31+
max_clock = mtmlGpuGetMaxClock(gpu)
32+
33+
print(f" GPU 利用率: {util}%")
34+
print(f" GPU 温度: {temp}°C")
35+
print(f" GPU 时钟: {clock} / {max_clock} MHz")
36+
37+
# 各引擎利用率
38+
print(f" 引擎利用率:")
39+
for engine_id, engine_name in engine_names.items():
40+
try:
41+
engine_util = mtmlGpuGetEngineUtilization(gpu, engine_id)
42+
print(f" {engine_name}: {engine_util}%")
43+
except MTMLError as e:
44+
print(f" {engine_name}: [不可用: {e}]")
45+
46+
mtmlLibraryShutDown()
47+
print("\n完成!")

‎examples/04_memory_monitoring.py‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
"""
2+
示例 04: 显存监控
3+
演示如何查询显存使用情况、带宽、时钟等信息。
4+
"""
5+
6+
from pymtml import *
7+
8+
print("=" * 60)
9+
print(" 示例 04: 显存监控")
10+
print("=" * 60)
11+
12+
mtmlLibraryInit()
13+
14+
for i in range(mtmlLibraryCountDevice()):
15+
device = mtmlLibraryInitDeviceByIndex(i)
16+
name = mtmlDeviceGetName(device)
17+
print(f"\n--- 设备 {i}: {name} ---")
18+
19+
with mtmlMemoryContext(device) as memory:
20+
total = mtmlMemoryGetTotal(memory)
21+
used = mtmlMemoryGetUsed(memory)
22+
free = total - used
23+
util = mtmlMemoryGetUtilization(memory)
24+
25+
print(f" 显存总量: {total / 1024**3:.2f} GB ({total / 1024**2:.0f} MB)")
26+
print(f" 已用显存: {used / 1024**3:.2f} GB ({used / 1024**2:.0f} MB)")
27+
print(f" 空闲显存: {free / 1024**3:.2f} GB ({free / 1024**2:.0f} MB)")
28+
print(f" 显存利用率: {util}%")
29+
30+
# 时钟
31+
clock = mtmlMemoryGetClock(memory)
32+
max_clock = mtmlMemoryGetMaxClock(memory)
33+
print(f" 显存时钟: {clock} / {max_clock} MHz")
34+
35+
# 带宽和总线
36+
bus_width = mtmlMemoryGetBusWidth(memory)
37+
bandwidth = mtmlMemoryGetBandwidth(memory)
38+
speed = mtmlMemoryGetSpeed(memory)
39+
print(f" 总线宽度: {bus_width} bits")
40+
print(f" 显存带宽: {bandwidth} GB/s")
41+
print(f" 显存速率: {speed} Mbps")
42+
43+
# 类型和供应商
44+
mem_type = mtmlMemoryGetType(memory)
45+
type_names = {MTML_MEM_TYPE_LPDDR4: "LPDDR4", MTML_MEM_TYPE_GDDR6: "GDDR6"}
46+
print(f" 显存类型: {type_names.get(mem_type, f'Unknown({mem_type})')}")
47+
48+
try:
49+
vendor = mtmlMemoryGetVendor(memory)
50+
print(f" 显存供应商: {vendor}")
51+
except MTMLError as e:
52+
print(f" 显存供应商: [不可用: {e}]")
53+
54+
# 系统使用量
55+
try:
56+
sys_used = mtmlMemoryGetUsedSystem(memory)
57+
print(f" 系统占用显存: {sys_used / 1024**2:.2f} MB")
58+
except MTMLError as e:
59+
print(f" 系统占用显存: [不可用: {e}]")
60+
61+
mtmlLibraryShutDown()
62+
print("\n完成!")

‎examples/05_vpu_monitoring.py‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
"""
2+
示例 05: VPU (视频处理单元) 监控
3+
演示如何查询 VPU 时钟、编解码利用率和容量信息。
4+
"""
5+
6+
from pymtml import *
7+
8+
print("=" * 60)
9+
print(" 示例 05: VPU 监控")
10+
print("=" * 60)
11+
12+
mtmlLibraryInit()
13+
14+
for i in range(mtmlLibraryCountDevice()):
15+
device = mtmlLibraryInitDeviceByIndex(i)
16+
name = mtmlDeviceGetName(device)
17+
print(f"\n--- 设备 {i}: {name} ---")
18+
19+
try:
20+
with mtmlVpuContext(device) as vpu:
21+
# 时钟
22+
clock = mtmlVpuGetClock(vpu)
23+
max_clock = mtmlVpuGetMaxClock(vpu)
24+
print(f" VPU 时钟: {clock} / {max_clock} MHz")
25+
26+
# 编解码利用率
27+
util = mtmlVpuGetUtilization(vpu)
28+
print(f" 编码利用率: {util.encodeUtil}%")
29+
print(f" 解码利用率: {util.decodeUtil}%")
30+
31+
# 编解码容量
32+
enc_cap, dec_cap = mtmlVpuGetCodecCapacity(vpu)
33+
print(f" 编码容量: {enc_cap}")
34+
print(f" 解码容量: {dec_cap}")
35+
36+
# 编码器会话状态
37+
try:
38+
enc_states = mtmlVpuGetEncoderSessionStates(vpu, 8)
39+
active_enc = sum(1 for s in enc_states if s.state == MTML_CODEC_SESSION_STATE_ACTIVE)
40+
print(f" 活跃编码会话: {active_enc}")
41+
for s in enc_states:
42+
if s.state == MTML_CODEC_SESSION_STATE_ACTIVE:
43+
metrics = mtmlVpuGetEncoderSessionMetrics(vpu, s.sessionId)
44+
print(f" 编码会话 {s.sessionId}: {metrics.width}x{metrics.height}, "
45+
f"codec={metrics.codecType}, fps={metrics.fps}")
46+
break
47+
except MTMLError:
48+
print(f" 活跃编码会话: [不可用]")
49+
50+
# 解码器会话状态
51+
try:
52+
dec_states = mtmlVpuGetDecoderSessionStates(vpu, 8)
53+
active_dec = sum(1 for s in dec_states if s.state == MTML_CODEC_SESSION_STATE_ACTIVE)
54+
print(f" 活跃解码会话: {active_dec}")
55+
for s in dec_states:
56+
if s.state == MTML_CODEC_SESSION_STATE_ACTIVE:
57+
metrics = mtmlVpuGetDecoderSessionMetrics(vpu, s.sessionId)
58+
print(f" 解码会话 {s.sessionId}: {metrics.width}x{metrics.height}, "
59+
f"codec={metrics.codecType}, fps={metrics.fps}")
60+
break
61+
except MTMLError:
62+
print(f" 活跃解码会话: [不可用]")
63+
64+
except MTMLError as e:
65+
print(f" VPU 不可用: {e}")
66+
67+
mtmlLibraryShutDown()
68+
print("\n完成!")

‎examples/06_fan_and_power.py‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
"""
2+
示例 06: 风扇与功耗监控
3+
演示如何查询风扇转速和设备功耗。
4+
"""
5+
6+
from pymtml import *
7+
8+
print("=" * 60)
9+
print(" 示例 06: 风扇与功耗监控")
10+
print("=" * 60)
11+
12+
mtmlLibraryInit()
13+
14+
for i in range(mtmlLibraryCountDevice()):
15+
device = mtmlLibraryInitDeviceByIndex(i)
16+
name = mtmlDeviceGetName(device)
17+
print(f"\n--- 设备 {i}: {name} ---")
18+
19+
# 功耗
20+
power_mw = mtmlDeviceGetPowerUsage(device)
21+
print(f" 当前功耗: {power_mw} mW ({power_mw / 1000:.1f} W)")
22+
23+
# 风扇
24+
try:
25+
fan_count = mtmlDeviceCountFan(device)
26+
print(f" 风扇数量: {fan_count}")
27+
28+
for f in range(fan_count):
29+
try:
30+
speed = mtmlDeviceGetFanSpeed(device, f)
31+
print(f" 风扇 {f} 转速: {speed}%")
32+
except MTMLError as e:
33+
print(f" 风扇 {f} 转速: [不可用: {e}]")
34+
35+
try:
36+
rpm = mtmlDeviceGetFanRpm(device, f)
37+
print(f" 风扇 {f} RPM: {rpm}")
38+
except MTMLError as e:
39+
print(f" 风扇 {f} RPM: [不可用: {e}]")
40+
except MTMLError as e:
41+
print(f" 风扇信息: [不可用: {e}]")
42+
43+
mtmlLibraryShutDown()
44+
print("\n完成!")

0 commit comments

Comments
 (0)