콘텐츠로 이동

hyperaccel-smi

hyperaccel-smi는 드라이버가 /sys/class/ha/haN/ 아래에 공개하는 텔레메트리를 읽어 여러 카드 상태를 한 화면에 보여 주는 도구입니다. 디바이스 노드를 열지 않고 root 권한도 필요 없으므로, 워크로드 옆에서 모니터링이나 헬스체크로 실행할 수 있습니다. 이 페이지는 옵션, 출력 형식, 종료 코드를 정의합니다. 각 값의 의미는 sysfs 레퍼런스에 있습니다.


설치와 권한

경로 /usr/bin/hyperaccel-smi
배포 드라이버 deb 패키지(hyperdriver-dkms)에 들어 있습니다
요구 사항 Python 3. 표준 라이브러리만 쓰므로 추가 패키지가 필요 없습니다. deb 패키지는 python3를 의존성으로 요구합니다
권한 일반 사용자로 실행합니다. root가 필요 없습니다
도구 버전 1.0.0

도구는 /sys/class/ha/haN/ 아래의 읽기 전용 노드와 /sys/class/ha/haN/device 링크만 읽습니다. 이 노드들은 모든 사용자가 읽을 수 있습니다. /dev/haN을 열지 않으므로 워크로드와 디바이스를 두고 경쟁하지 않고, 디바이스가 연산 중에 멈춘 동안에도 응답합니다.

도구 버전과 드라이버 버전은 다릅니다

hyperaccel-smi -V는 도구 자신의 버전을 출력합니다. 기본 출력의 Driver 칸은 모듈 이름 ha를 표시할 뿐입니다. 적재된 드라이버 버전은 다음으로 확인합니다.

1
cat /sys/module/ha/version

시놉시스

1
2
3
hyperaccel-smi [-i N] [-q] [--json] [-l SEC] [--root PATH]
hyperaccel-smi -V
hyperaccel-smi -h

옵션 없이 실행하면 기본 출력을 한 번 출력합니다.


옵션

옵션 뜻
-i N, --id N 번호가 N인 카드(haN)만 보여 줍니다
-q, --query 카드마다 값을 항목별로 나열하는 상세 출력을 냅니다
--json JSON 출력을 냅니다. -q와 함께 주면 --json이 우선합니다
-l SEC, --loop SEC SEC초마다 다시 읽어 출력합니다. 소수 단위도 받습니다. 루프 모드를 보십시오
--root PATH 카드를 찾을 sysfs 클래스 경로입니다. 기본값은 환경 변수 HYPERACCEL_SYSFS_ROOT이고, 그것도 없으면 /sys/class/ha입니다
-V, --version hyperaccel-smi 1.0.0 형식으로 도구 버전을 출력합니다
-h, --help 도움말을 출력합니다

환경 변수

변수 뜻
HYPERACCEL_SYSFS_ROOT --root의 기본값입니다. 컨테이너에서 호스트의 sysfs를 다른 경로에 마운트했을 때 씁니다
HYPERACCEL_VISIBLE_DEVICES 보여 줄 카드 번호를 쉼표로 나열합니다(예: 0,2). 설정하지 않았거나 all이면 모든 카드를 보여 주고, none이거나 빈 값이면 아무 카드도 보여 주지 않습니다. 숫자가 아닌 항목은 무시하므로, 숫자 항목이 하나도 없으면 아무 카드도 보여 주지 않습니다. all과 none은 대소문자를 가리지 않습니다

HYPERACCEL_VISIBLE_DEVICES는 표시 범위만 정합니다

이 변수는 hyperaccel-smi가 출력할 카드를 고를 뿐입니다. 디바이스 접근 권한은 바꾸지 않습니다. 컨테이너에 노출할 디바이스는 컨테이너 지원에서 설명하는 방법으로 정하십시오.


카드를 찾는 방식

  1. 클래스 경로(--root) 아래에서 이름이 ha<숫자>인 항목을 찾아 번호 순으로 정렬합니다. 이 번호는 /dev/haN의 N과 같습니다.
  2. -i와 HYPERACCEL_VISIBLE_DEVICES로 거릅니다. 둘 다 주면 두 조건을 모두 만족하는 카드만 남습니다.
  3. 카드마다 device 링크가 가리키는 PCI 주소를 Bus-Id로 씁니다.

카드를 계속 같은 카드로 식별해야 할 때는 Bus-Id를 쓰십시오

haN 번호는 모듈을 다시 적재하거나 카드 구성이 바뀌면 달라질 수 있습니다. PCI 주소는 카드가 꽂힌 슬롯을 따릅니다. 인벤토리, 알림 규칙, ha-fw-update -d처럼 카드를 지정하는 곳에는 Bus-Id 값을 쓰십시오. serial이 unknown인 카드를 구별할 때도 PCI 주소를 씁니다.


기본 출력

옵션 없이 실행하면 카드 표, IP별 사용률, 스트림 요약의 세 블록을 출력합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
+-----------------------------------------------------------------------------------------+
| HYPERACCEL-SMI 1.0.0      Tue Oct 06 12:02:50 2026                                      |
| Firmware Version: 1.0.5        Driver: ha                                               |
+-------------------------------------------+-----------------------+---------------------+
| LPU  Name                 Serial          | Bus-Id                | Health              |
| Temp   Power        Util(core)            | Memory-Usage (DRAM)   | Fw-Err / Timeouts   |
+===========================================+=======================+=====================+
|   0  HyperAccel LPU   HA-1a2b3c4d-5e6…    | 0000:17:00.0          | OK                  |
| 52C    38.2 W      63.5 %                 | 24.00 / 128.00 GiB    | 0 / 0               |
+-------------------------------------------+-----------------------+---------------------+
|   1  HyperAccel LPU   HA-5f0e9d8c-7b6…    | 0000:65:00.0          | FAULTED             |
| N/A    N/A         N/A                    | 8.00 / 128.00 GiB     | 0 / 1               |
+-------------------------------------------+-----------------------+---------------------+
+-----------------------------------------------------------------------------------------+
| Per-IP Utilization (%)                                                                  |
| LPU  core   mpu    vpu    cdma   cgdma                                                  |
+-----------------------------------------------------------------------------------------+
|   0  63.5   41.2   18.0   22.4   12.7                                                   |
|   1  unknown (firmware not sampled / unprovisioned)                                     |
+-----------------------------------------------------------------------------------------+
+-----------------------------------------------------------------------------------------+
| Streams / Inflight                                                                      |
| LPU  Streams  Inflight                                                                  |
+-----------------------------------------------------------------------------------------+
|   0  3        2                                                                         |
|   1  0        0                                                                         |
+-----------------------------------------------------------------------------------------+

카드 표

카드마다 두 줄을 출력합니다.

칸 읽는 노드 표시
LPU 카드 이름 haN의 N 정수
Name 없음 항상 HyperAccel LPU
Serial serial 16자를 넘으면 앞 15자 뒤에 …를 붙입니다. 전체 값은 -q나 --json으로 봅니다
Bus-Id device 링크 PCI 주소(예: 0000:17:00.0)
Health health 아래 Health 칸
Temp temp 섭씨 정수(예: 52C)
Power power_mw W 단위, 소수 한 자리
Util(core) util의 core 줄 %, 소수 한 자리
Memory-Usage (DRAM) dram_used, dram_size <사용> / <전체> GiB, 소수 두 자리
Fw-Err / Timeouts devcmd_fw_errors, devcmd_timeouts 두 누적 카운터

머리글 두 줄은 다음과 같습니다.

  • 첫 줄: 도구 버전과 출력 시각.
  • 둘째 줄의 Firmware Version: 출력한 카드를 번호 순으로 보아 fw_version을 읽을 수 있는 첫 카드의 값입니다. 카드마다 펌웨어가 다를 수 있으므로 카드별 버전은 -q나 --json으로 확인하십시오. 출력할 카드가 없으면 N/A입니다.
  • 둘째 줄의 Driver: 항상 ha입니다.

Power는 보드 입력 전력이 아니라 감시하는 전원 레일의 전압×전류 합입니다. DMA 시간 초과(hdma_timeouts)는 이 표에 없고 -q와 --json에 나옵니다.

Health 칸

health 노드 값을 대문자로 바꿔 표시합니다.

표시 노드 값
OK ok
DEGRADED degraded
FAULTED faulted

health 노드를 읽을 수 없거나 값이 unknown이면 RAS 카운터 세 개(devcmd_fw_errors, devcmd_timeouts, hdma_timeouts)로 대신 판정합니다. 셋 다 읽을 수 없으면 UNKNOWN, 읽은 카운터 중 하나라도 0보다 크면 WARN, 그 밖에는 OK입니다.

각 값의 의미와 조치는 텔레메트리를 보십시오. DEGRADED는 지금 실패 중이라는 뜻이 아니라 누적 카운터 중 하나가 0보다 크다는 뜻입니다. 카운터는 줄지 않고, 드라이버가 카드를 다시 인식할 때(예: 모듈을 다시 적재하거나 ha-hotreset으로 카드를 다시 인식시킬 때)에만 0에서 다시 시작합니다. SDK의 리셋 기능으로 리셋해도 카운터는 그대로입니다. 그래서 한 번 DEGRADED가 된 카드는 그때까지 OK로 돌아가지 않습니다.

IP별 사용률

util 노드에서 core, mpu, vpu, cdma, cgdma 다섯 IP를 소수 한 자리 퍼센트로 표시합니다. util이 unknown이면 그 카드 줄에 unknown (firmware not sampled / unprovisioned)를 표시합니다. util 노드가 보고하는 나머지 IP는 --json에 들어 있습니다.

스트림 요약

카드마다 활성 스트림 수(stream_count)와 진행 중인 작업 수(inflight)를 표시합니다. 프로세스별로 나누어 보여 주지는 않습니다.


상세 출력

-q를 주면 카드마다 값을 항목 이름과 함께 나열합니다. 아래는 위 예의 1번 카드를 -q -i 1로 출력한 것입니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
==== hyperaccel-smi 1.0.0 ====

LPU 1:
    Bus-Id                    : 0000:65:00.0
    Serial                    : HA-5f0e9d8c-7b6a-5948-3726-150400000000
    Firmware Version          : 1.0.5
    HW Version (PCIe rev)     : 0x00
    Health                    : FAULTED
    Temperature
        Peak                  : N/A
        Average               : N/A
    Power
        Total (rail V*I)      : N/A
    Memory
        DRAM Used             : 8.00 GiB
        DRAM Total            : 128.00 GiB
        SRAM Used             : 256.00 KiB
        SRAM Total            : 4.00 MiB
    Utilization (%)
        (unknown - not sampled)
    RAS / Health
        Streams               : 0
        Inflight              : 0
        Devcmd FW Errors      : 0
        Devcmd Timeouts       : 1
        HDMA Timeouts         : 0
        Last Hang             : rc=- cmd_idx=- opcode=-
        Hang Verdict          : not-picked-up
        Batch Progress        : batch_seq=41->41 exec_index=none resq_tail=0
    dma-buf Export
        TW Window Size        : 64.00 MiB
        Windows               : 0 / 8  (pins 0 / 12)
항목 읽는 노드 표시
Bus-Id device 링크 PCI 주소
Serial serial 노드 값 그대로
Firmware Version fw_version 노드 값 그대로
HW Version (PCIe rev) hw_version 노드 값 그대로
Health health Health 칸과 같음
Temperature › Peak, Average temp, temp_avg 섭씨 정수
Temperature › 블록별 줄 temp_blocks 노드의 줄을 순서대로 나열합니다. 마지막 peak, avg 줄도 포함합니다. 노드가 unknown이면 생략합니다
Power › Total (rail V*I) power_mw W 단위, 소수 한 자리
Power › 레일별 줄 rails <레일> : <전압> mV <전류> mA. 노드가 none이거나 unknown이면 생략합니다. 노드가 값 뒤에 붙이는 읽기 오류 표시(V_ERR, I_ERR)는 출력하지 않으므로, 레일 값이 의심스러우면 rails 노드를 직접 확인하십시오
Memory dram_used, dram_size, sram_used, sram_size 1 KiB 미만은 B 단위 정수, 그 이상은 KiB, MiB, GiB 중 알맞은 단위로 소수 두 자리
Utilization (%) util 기본 출력과 같은 다섯 IP. unknown이면 (unknown - not sampled)
Streams, Inflight stream_count, inflight 정수
Devcmd FW Errors, Devcmd Timeouts, HDMA Timeouts devcmd_fw_errors, devcmd_timeouts, hdma_timeouts 누적 카운터
Last Hang last_hang의 rc, cmd_idx, opcode 노드 값 그대로. 노드를 읽을 수 없으면 none
Hang Verdict last_hang의 verdict 노드 값 그대로
Batch Progress last_hang의 batch_seq, exec_index, resq_tail 노드 값 그대로
dma-buf Export › TW Window Size tw_window_size Memory와 같은 단위
dma-buf Export › Windows dmabuf_exports의 첫 줄 <used> / <max> (pins <pins> / <pin_max>). 노드가 unknown이면 N/A
dma-buf Export › 창별 줄 dmabuf_exports의 창 줄 region <번호> ch<채널> : <da> <크기> <상태> pid <PID> (<comm>). <크기>는 Memory와 같은 단위이고, 노드의 pid가 -이면 owner hidden

Last Hang, Hang Verdict, Batch Progress의 의미는 hang 감지와 워치독과 sysfs 레퍼런스를 보십시오. dram_free와 sram_free는 -q에 나오지 않고 --json에 들어 있습니다.


JSON 출력

--json을 주면 카드마다 객체 하나를 담은 배열을 번호 순으로 출력합니다. 출력할 카드가 없으면 빈 배열 []입니다. 아래는 위 예의 1번 카드를 -i 1 --json으로 출력한 것입니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
[
  {
    "index": 1,
    "sysfs": "/sys/class/ha/ha1",
    "bdf": "0000:65:00.0",
    "fw_version": "1.0.5",
    "hw_version": "0x00",
    "serial": "HA-5f0e9d8c-7b6a-5948-3726-150400000000",
    "dram_size": 137438953472,
    "dram_used": 8589934592,
    "dram_free": 128849018880,
    "sram_size": 4194304,
    "sram_used": 262144,
    "sram_free": 3915776,
    "temp": null,
    "temp_avg": null,
    "temp_blocks": null,
    "power_mw": null,
    "rails": null,
    "util": null,
    "inflight": 0,
    "stream_count": 0,
    "devcmd_timeouts": 1,
    "devcmd_fw_errors": 0,
    "hdma_timeouts": 0,
    "last_hang": {
      "rc": "-",
      "cmd_idx": null,
      "opcode": "-",
      "batch_seq": "41->41",
      "exec_index": "none",
      "resq_tail": "0",
      "verdict": "not-picked-up"
    },
    "tw_window_size": 67108864,
    "dmabuf_exports": {
      "used": 0,
      "max": 8,
      "pins": 0,
      "pin_max": 12,
      "windows": []
    },
    "health_node": "faulted",
    "health": "FAULTED"
  }
]

필드

필드 타입 내용
index 정수 카드 번호(haN의 N)
sysfs 문자열 카드의 sysfs 경로
bdf 문자열 PCI 주소
fw_version, hw_version, serial 문자열 또는 null 같은 이름의 노드 값 그대로입니다. unknown도 문자열로 들어갑니다
dram_size, dram_used, dram_free, sram_size, sram_used, sram_free 정수 또는 null 바이트
temp, temp_avg 정수 또는 null 섭씨
temp_blocks 객체 또는 null {"<블록>": <섭씨>}. temp_blocks 노드의 모든 줄이며 peak, avg도 들어 있습니다
power_mw 정수 또는 null mW
rails 배열 또는 null [{"name": "<레일>", "mv": <mV>, "ma": <mA>}]. 노드가 none이면 빈 배열입니다. 읽기 오류 표시(V_ERR, I_ERR)는 들어 있지 않습니다
util 객체 또는 null {"<IP>": <퍼센트>}. 값은 실수이고, util 노드가 보고하는 모든 IP가 들어 있습니다
inflight, stream_count 정수 또는 null 진행 중인 작업 수, 활성 스트림 수
devcmd_timeouts, devcmd_fw_errors, hdma_timeouts 정수 또는 null 누적 카운터
last_hang 객체 또는 null 아래 표
tw_window_size 정수 또는 null 바이트
dmabuf_exports 객체 또는 null {"used", "max", "pins", "pin_max", "windows"}. windows는 창마다 {"region", "ch", "da", "size", "state", "pid", "comm"}이고, da는 문자열, size는 바이트 정수, pid와 comm은 노드에서 -이면 null입니다
health_node 문자열 또는 null health 노드 값 그대로(소문자)
health 문자열 Health 칸과 같은 값(대문자)

last_hang 객체는 last_hang 노드의 필드를 담습니다.

필드 타입 내용
rc, opcode 문자열 노드 값 그대로(0x… 또는 -)
cmd_idx 정수 또는 null 노드 값이 -이면 null
batch_seq, exec_index, resq_tail, verdict 문자열 노드 값 그대로

모니터링 시스템이 수집할 때는 health(또는 health_node)와 누적 카운터를 쓰십시오. 숫자 필드가 null일 수 있으므로 파서는 null을 정상 값으로 처리해야 합니다.


루프 모드

-l SEC를 주면 SEC초마다 모든 값을 다시 읽어 출력합니다.

  • 0.5초보다 짧은 값은 0.5초로 씁니다.
  • 터미널에 출력할 때는 매번 화면을 지우고 다시 그립니다. --json일 때는 화면을 지우지 않고 주기마다 JSON 배열을 하나씩 이어서 출력합니다.
  • 카드가 없어도 끝나지 않고 계속 돕니다.
  • Ctrl+C로 끝냅니다. 종료 코드는 130입니다.

수집기는 루프 모드 대신 한 번씩 호출하십시오

-l과 --json을 함께 쓰면 출력 전체가 하나의 JSON 문서가 아닙니다. 주기적으로 수집할 때는 수집기가 정한 주기마다 hyperaccel-smi --json을 한 번씩 실행하는 편이 다루기 쉽습니다.

화면 갱신 주기와 별개로, 온도·전력·사용률 값은 드라이버가 텔레메트리 폴링 주기마다 펌웨어에서 가져와 갱신합니다. 그보다 짧은 간격으로 다시 읽으면 같은 값이 나옵니다. 그 주기는 모듈 파라미터 ha_sysmon_poll_ms로 정합니다.


N/A, unknown, -

표시 뜻
N/A 숫자 값의 노드가 unknown이거나 노드를 읽을 수 없습니다. 표의 Serial 칸도 serial이 unknown이면 N/A입니다
unknown 드라이버가 값을 믿을 수 없어서 낸 값입니다. 문자열 값(-q의 Serial, Firmware Version, 머리글의 Firmware Version, JSON의 문자열 필드)은 노드 값을 그대로 보여 주므로 unknown이 그대로 나옵니다
- last_hang에서 기록된 적이 없거나 드라이버가 판정할 수 없어 비워 둔 값입니다. 0이 아닙니다
null JSON에서 N/A에 해당합니다

unknown이 나오는 조건(리셋 중, FATAL, 펌웨어 응답 없음 등)은 텔레메트리를 보십시오.


종료 코드

코드 뜻
0 카드를 하나 이상 출력했습니다. -V와 -h도 0으로 끝납니다
2 출력할 카드가 없습니다. 드라이버가 적재되지 않았거나, 카드가 없거나, -i나 HYPERACCEL_VISIBLE_DEVICES로 모두 걸러진 경우입니다. 명령행 옵션이 잘못된 경우에도 2로 끝나며, 이때는 표준 오류에 사용법이 출력됩니다
130 Ctrl+C로 중단했습니다

카드가 없을 때 기본 출력은 카드 표 자리에 No HyperAccel LPU found under로 시작하는 줄을 표시합니다.

종료 코드 0은 정상이라는 뜻이 아닙니다

종료 코드는 카드가 보이는지만 알려 줍니다. FAULTED인 카드가 있어도 0입니다. 상태는 health 값으로 판단하십시오.


사용 예

전체 상태를 한 번 봅니다.

1
hyperaccel-smi

카드 하나의 모든 값을 봅니다.

1
hyperaccel-smi -q -i 0

2초마다 갱신하며 지켜봅니다.

1
hyperaccel-smi -l 2

필요한 필드만 추출합니다.

1
2
3
4
hyperaccel-smi --json | python3 -c '
import json, sys
for d in json.load(sys.stdin):
    print(d["index"], d["bdf"], d["health"], d["temp"], d["power_mw"])'

헬스체크로 씁니다. 보이는 카드가 없거나 FAULTED인 카드가 있으면 1로 끝납니다.

1
2
3
4
hyperaccel-smi --json | python3 -c '
import json, sys
d = json.load(sys.stdin)
sys.exit(0 if d and all(x["health"] != "FAULTED" for x in d) else 1)'

이 예는 보이는 카드가 있는지와 health만 봅니다. 드라이버 적재, 카드 수, 카드마다의 fw_version까지 확인하고 주기적으로 실행하는 헬스체크는 카드 상태 헬스체크 만들기에, Prometheus로 수집하는 방법은 Prometheus로 텔레메트리 수집하기에 있습니다.

컨테이너 안에서 실행할 때는 컨테이너가 호스트의 /sys/class/ha를 읽을 수 있어야 합니다. 다른 경로에 마운트했다면 그 경로를 지정합니다.

1
HYPERACCEL_SYSFS_ROOT=/host/sys/class/ha hyperaccel-smi --json

함께 보기