Add user manual and usage examples

examples/01_library_basics.py

@@ -0,0 +1,62 @@
+"""
+示例 01: 库基础操作
+演示 MTML 库的初始化、版本查询、设备枚举、关闭等基础操作，
+以及多次 init/shutdown 循环调用。
+"""
+
+from pymtml import *
+
+print("=" * 60)
+print(" 示例 01: 库基础操作")
+print("=" * 60)
+
+# 1. 初始化
+mtmlLibraryInit()
+print("[1] 库初始化成功")
+
+# 2. 查询库版本
+version = mtmlLibraryGetVersion()
+print(f"[2] MTML 库版本: {version}")
+
+# 3. 查询驱动版本
+system = mtmlLibraryInitSystem()
+driver_ver = mtmlSystemGetDriverVersion(system)
+print(f"[3] 驱动版本: {driver_ver}")
+mtmlLibraryFreeSystem(system)
+
+# 4. 枚举设备
+device_count = mtmlLibraryCountDevice()
+print(f"[4] 检测到 {device_count} 个 GPU 设备")
+
+for i in range(device_count):
+    device = mtmlLibraryInitDeviceByIndex(i)
+    name = mtmlDeviceGetName(device)
+    uuid = mtmlDeviceGetUUID(device)
+    print(f"    设备 {i}: {name} (UUID: {uuid})")
+
+# 5. 按 UUID 获取设备
+if device_count > 0:
+    device = mtmlLibraryInitDeviceByIndex(0)
+    uuid = mtmlDeviceGetUUID(device)
+    device_by_uuid = mtmlLibraryInitDeviceByUuid(uuid)
+    print(f"[5] 按 UUID 获取设备: {mtmlDeviceGetName(device_by_uuid)}")
+
+# 6. 按 PCI SBDF 获取设备
+if device_count > 0:
+    pci = mtmlDeviceGetPciInfo(mtmlLibraryInitDeviceByIndex(0))
+    device_by_pci = mtmlLibraryInitDeviceByPciSbdf(pci.sbdf)
+    print(f"[6] 按 PCI SBDF ({pci.sbdf}) 获取设备: {mtmlDeviceGetName(device_by_pci)}")
+
+# 7. 关闭
+mtmlLibraryShutDown()
+print("[7] 库关闭成功")
+
+# 8. 多次 init/shutdown 循环
+print("[8] 测试多次 init/shutdown 循环:")
+for cycle in range(3):
+    mtmlLibraryInit()
+    count = mtmlLibraryCountDevice()
+    mtmlLibraryShutDown()
+    print(f"    第 {cycle + 1} 次循环: 检测到 {count} 个设备 ✓")
+
+print("\n完成!")

examples/02_device_info.py

@@ -0,0 +1,63 @@
+"""
+示例 02: 设备信息查询
+演示如何查询 GPU 设备的基本属性信息。
+"""
+
+from pymtml import *
+
+print("=" * 60)
+print(" 示例 02: 设备信息查询")
+print("=" * 60)
+
+mtmlLibraryInit()
+
+for i in range(mtmlLibraryCountDevice()):
+    device = mtmlLibraryInitDeviceByIndex(i)
+
+    print(f"\n--- 设备 {i} ---")
+    print(f"  名称:       {mtmlDeviceGetName(device)}")
+    print(f"  索引:       {mtmlDeviceGetIndex(device)}")
+    print(f"  UUID:       {mtmlDeviceGetUUID(device)}")
+    print(f"  品牌:       {'MTT' if mtmlDeviceGetBrand(device) == MTML_BRAND_MTT else 'Unknown'}")
+
+    try:
+        print(f"  序列号:     {mtmlDeviceGetSerialNumber(device)}")
+    except MTMLError as e:
+        print(f"  序列号:     [不可用: {e}]")
+
+    print(f"  VBIOS 版本: {mtmlDeviceGetVbiosVersion(device)}")
+
+    try:
+        print(f"  MtBIOS 版本: {mtmlDeviceGetMtBiosVersion(device)}")
+    except MTMLError as e:
+        print(f"  MtBIOS 版本: [不可用: {e}]")
+
+    print(f"  GPU 核心数: {mtmlDeviceCountGpuCores(device)}")
+    print(f"  功耗:       {mtmlDeviceGetPowerUsage(device)} mW "
+          f"({mtmlDeviceGetPowerUsage(device) / 1000:.1f} W)")
+
+    # PCI 信息
+    pci = mtmlDeviceGetPciInfo(device)
+    print(f"  PCI SBDF:   {pci.sbdf}")
+    print(f"  PCI Bus ID: {pci.busId}")
+    print(f"  PCI 设备ID: {pci.pciDeviceId:#010x}")
+    print(f"  PCIe 代数:  当前 Gen{pci.pciCurGen} / 最大 Gen{pci.pciMaxGen}")
+    print(f"  PCIe 宽度:  当前 x{pci.pciCurWidth} / 最大 x{pci.pciMaxWidth}")
+    print(f"  PCIe 速率:  当前 {pci.pciCurSpeed:.1f} GT/s / 最大 {pci.pciMaxSpeed:.1f} GT/s")
+
+    # PCIe 插槽信息
+    try:
+        slot = mtmlDeviceGetPcieSlotInfo(device)
+        print(f"  PCIe 插槽:  {slot.slotName} (type={slot.slotType})")
+    except MTMLError as e:
+        print(f"  PCIe 插槽:  [不可用: {e}]")
+
+    # 设备属性
+    prop = mtmlDeviceGetProperty(device)
+    virt_cap = "支持" if prop.virtCapability == MTML_DEVICE_SUPPORT_VIRTUALIZATION else "不支持"
+    mpc_cap = "支持" if prop.mpcCapability == MTML_DEVICE_SUPPORT_MPC else "不支持"
+    print(f"  虚拟化:     {virt_cap}")
+    print(f"  MPC:        {mpc_cap}")
+
+mtmlLibraryShutDown()
+print("\n完成!")

examples/03_gpu_monitoring.py

@@ -0,0 +1,47 @@
+"""
+示例 03: GPU 监控
+演示如何查询 GPU 利用率、温度、时钟频率及各引擎利用率。
+"""
+
+from pymtml import *
+
+print("=" * 60)
+print(" 示例 03: GPU 监控")
+print("=" * 60)
+
+mtmlLibraryInit()
+
+engine_names = {
+    MTML_GPU_ENGINE_GEOMETRY: "几何引擎",
+    MTML_GPU_ENGINE_2D: "2D 引擎",
+    MTML_GPU_ENGINE_3D: "3D 引擎",
+    MTML_GPU_ENGINE_COMPUTE: "计算引擎",
+}
+
+for i in range(mtmlLibraryCountDevice()):
+    device = mtmlLibraryInitDeviceByIndex(i)
+    name = mtmlDeviceGetName(device)
+    print(f"\n--- 设备 {i}: {name} ---")
+
+    with mtmlGpuContext(device) as gpu:
+        # 基本指标
+        util = mtmlGpuGetUtilization(gpu)
+        temp = mtmlGpuGetTemperature(gpu)
+        clock = mtmlGpuGetClock(gpu)
+        max_clock = mtmlGpuGetMaxClock(gpu)
+
+        print(f"  GPU 利用率:   {util}%")
+        print(f"  GPU 温度:     {temp}°C")
+        print(f"  GPU 时钟:     {clock} / {max_clock} MHz")
+
+        # 各引擎利用率
+        print(f"  引擎利用率:")
+        for engine_id, engine_name in engine_names.items():
+            try:
+                engine_util = mtmlGpuGetEngineUtilization(gpu, engine_id)
+                print(f"    {engine_name}: {engine_util}%")
+            except MTMLError as e:
+                print(f"    {engine_name}: [不可用: {e}]")
+
+mtmlLibraryShutDown()
+print("\n完成!")

examples/04_memory_monitoring.py

@@ -0,0 +1,62 @@
+"""
+示例 04: 显存监控
+演示如何查询显存使用情况、带宽、时钟等信息。
+"""
+
+from pymtml import *
+
+print("=" * 60)
+print(" 示例 04: 显存监控")
+print("=" * 60)
+
+mtmlLibraryInit()
+
+for i in range(mtmlLibraryCountDevice()):
+    device = mtmlLibraryInitDeviceByIndex(i)
+    name = mtmlDeviceGetName(device)
+    print(f"\n--- 设备 {i}: {name} ---")
+
+    with mtmlMemoryContext(device) as memory:
+        total = mtmlMemoryGetTotal(memory)
+        used = mtmlMemoryGetUsed(memory)
+        free = total - used
+        util = mtmlMemoryGetUtilization(memory)
+
+        print(f"  显存总量:     {total / 1024**3:.2f} GB ({total / 1024**2:.0f} MB)")
+        print(f"  已用显存:     {used / 1024**3:.2f} GB ({used / 1024**2:.0f} MB)")
+        print(f"  空闲显存:     {free / 1024**3:.2f} GB ({free / 1024**2:.0f} MB)")
+        print(f"  显存利用率:   {util}%")
+
+        # 时钟
+        clock = mtmlMemoryGetClock(memory)
+        max_clock = mtmlMemoryGetMaxClock(memory)
+        print(f"  显存时钟:     {clock} / {max_clock} MHz")
+
+        # 带宽和总线
+        bus_width = mtmlMemoryGetBusWidth(memory)
+        bandwidth = mtmlMemoryGetBandwidth(memory)
+        speed = mtmlMemoryGetSpeed(memory)
+        print(f"  总线宽度:     {bus_width} bits")
+        print(f"  显存带宽:     {bandwidth} GB/s")
+        print(f"  显存速率:     {speed} Mbps")
+
+        # 类型和供应商
+        mem_type = mtmlMemoryGetType(memory)
+        type_names = {MTML_MEM_TYPE_LPDDR4: "LPDDR4", MTML_MEM_TYPE_GDDR6: "GDDR6"}
+        print(f"  显存类型:     {type_names.get(mem_type, f'Unknown({mem_type})')}")
+
+        try:
+            vendor = mtmlMemoryGetVendor(memory)
+            print(f"  显存供应商:   {vendor}")
+        except MTMLError as e:
+            print(f"  显存供应商:   [不可用: {e}]")
+
+        # 系统使用量
+        try:
+            sys_used = mtmlMemoryGetUsedSystem(memory)
+            print(f"  系统占用显存: {sys_used / 1024**2:.2f} MB")
+        except MTMLError as e:
+            print(f"  系统占用显存: [不可用: {e}]")
+
+mtmlLibraryShutDown()
+print("\n完成!")

examples/05_vpu_monitoring.py

@@ -0,0 +1,68 @@
+"""
+示例 05: VPU (视频处理单元) 监控
+演示如何查询 VPU 时钟、编解码利用率和容量信息。
+"""
+
+from pymtml import *
+
+print("=" * 60)
+print(" 示例 05: VPU 监控")
+print("=" * 60)
+
+mtmlLibraryInit()
+
+for i in range(mtmlLibraryCountDevice()):
+    device = mtmlLibraryInitDeviceByIndex(i)
+    name = mtmlDeviceGetName(device)
+    print(f"\n--- 设备 {i}: {name} ---")
+
+    try:
+        with mtmlVpuContext(device) as vpu:
+            # 时钟
+            clock = mtmlVpuGetClock(vpu)
+            max_clock = mtmlVpuGetMaxClock(vpu)
+            print(f"  VPU 时钟:     {clock} / {max_clock} MHz")
+
+            # 编解码利用率
+            util = mtmlVpuGetUtilization(vpu)
+            print(f"  编码利用率:   {util.encodeUtil}%")
+            print(f"  解码利用率:   {util.decodeUtil}%")
+
+            # 编解码容量
+            enc_cap, dec_cap = mtmlVpuGetCodecCapacity(vpu)
+            print(f"  编码容量:     {enc_cap}")
+            print(f"  解码容量:     {dec_cap}")
+
+            # 编码器会话状态
+            try:
+                enc_states = mtmlVpuGetEncoderSessionStates(vpu, 8)
+                active_enc = sum(1 for s in enc_states if s.state == MTML_CODEC_SESSION_STATE_ACTIVE)
+                print(f"  活跃编码会话: {active_enc}")
+                for s in enc_states:
+                    if s.state == MTML_CODEC_SESSION_STATE_ACTIVE:
+                        metrics = mtmlVpuGetEncoderSessionMetrics(vpu, s.sessionId)
+                        print(f"    编码会话 {s.sessionId}: {metrics.width}x{metrics.height}, "
+                              f"codec={metrics.codecType}, fps={metrics.fps}")
+                        break
+            except MTMLError:
+                print(f"  活跃编码会话: [不可用]")
+
+            # 解码器会话状态
+            try:
+                dec_states = mtmlVpuGetDecoderSessionStates(vpu, 8)
+                active_dec = sum(1 for s in dec_states if s.state == MTML_CODEC_SESSION_STATE_ACTIVE)
+                print(f"  活跃解码会话: {active_dec}")
+                for s in dec_states:
+                    if s.state == MTML_CODEC_SESSION_STATE_ACTIVE:
+                        metrics = mtmlVpuGetDecoderSessionMetrics(vpu, s.sessionId)
+                        print(f"    解码会话 {s.sessionId}: {metrics.width}x{metrics.height}, "
+                              f"codec={metrics.codecType}, fps={metrics.fps}")
+                        break
+            except MTMLError:
+                print(f"  活跃解码会话: [不可用]")
+
+    except MTMLError as e:
+        print(f"  VPU 不可用: {e}")
+
+mtmlLibraryShutDown()
+print("\n完成!")

examples/06_fan_and_power.py

@@ -0,0 +1,44 @@
+"""
+示例 06: 风扇与功耗监控
+演示如何查询风扇转速和设备功耗。
+"""
+
+from pymtml import *
+
+print("=" * 60)
+print(" 示例 06: 风扇与功耗监控")
+print("=" * 60)
+
+mtmlLibraryInit()
+
+for i in range(mtmlLibraryCountDevice()):
+    device = mtmlLibraryInitDeviceByIndex(i)
+    name = mtmlDeviceGetName(device)
+    print(f"\n--- 设备 {i}: {name} ---")
+
+    # 功耗
+    power_mw = mtmlDeviceGetPowerUsage(device)
+    print(f"  当前功耗: {power_mw} mW ({power_mw / 1000:.1f} W)")
+
+    # 风扇
+    try:
+        fan_count = mtmlDeviceCountFan(device)
+        print(f"  风扇数量: {fan_count}")
+
+        for f in range(fan_count):
+            try:
+                speed = mtmlDeviceGetFanSpeed(device, f)
+                print(f"  风扇 {f} 转速: {speed}%")
+            except MTMLError as e:
+                print(f"  风扇 {f} 转速: [不可用: {e}]")
+
+            try:
+                rpm = mtmlDeviceGetFanRpm(device, f)
+                print(f"  风扇 {f} RPM:  {rpm}")
+            except MTMLError as e:
+                print(f"  风扇 {f} RPM:  [不可用: {e}]")
+    except MTMLError as e:
+        print(f"  风扇信息: [不可用: {e}]")
+
+mtmlLibraryShutDown()
+print("\n完成!")