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 | |
시놉시스¶
1 2 3 | |
옵션 없이 실행하면 기본 출력을 한 번 출력합니다.
옵션¶
| 옵션 | 뜻 |
|---|---|
-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가 출력할 카드를 고를 뿐입니다. 디바이스 접근 권한은 바꾸지 않습니다. 컨테이너에 노출할 디바이스는 컨테이너 지원에서 설명하는 방법으로 정하십시오.
카드를 찾는 방식¶
- 클래스 경로(
--root) 아래에서 이름이ha<숫자>인 항목을 찾아 번호 순으로 정렬합니다. 이 번호는/dev/haN의 N과 같습니다. -i와HYPERACCEL_VISIBLE_DEVICES로 거릅니다. 둘 다 주면 두 조건을 모두 만족하는 카드만 남습니다.- 카드마다
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 | |
카드 표¶
카드마다 두 줄을 출력합니다.
| 칸 | 읽는 노드 | 표시 |
|---|---|---|
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 | |
| 항목 | 읽는 노드 | 표시 |
|---|---|---|
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 |
정수 | 카드 번호(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 | |
카드 하나의 모든 값을 봅니다.
1 | |
2초마다 갱신하며 지켜봅니다.
1 | |
필요한 필드만 추출합니다.
1 2 3 4 | |
헬스체크로 씁니다. 보이는 카드가 없거나 FAULTED인 카드가 있으면 1로 끝납니다.
1 2 3 4 | |
이 예는 보이는 카드가 있는지와 health만 봅니다. 드라이버 적재, 카드 수, 카드마다의 fw_version까지 확인하고 주기적으로 실행하는 헬스체크는 카드 상태 헬스체크 만들기에, Prometheus로 수집하는 방법은 Prometheus로 텔레메트리 수집하기에 있습니다.
컨테이너 안에서 실행할 때는 컨테이너가 호스트의 /sys/class/ha를 읽을 수 있어야 합니다. 다른 경로에 마운트했다면 그 경로를 지정합니다.
1 | |
함께 보기¶
- sysfs 레퍼런스 — 도구가 읽는 노드의 정의, 그리고 도구가 보여 주지 않는 노드(
peer_map,peer_route,peer_sram,abi_prefetch_stats,fw_update_progress, hwmon) - 텔레메트리 — 값의 갱신 방식,
unknown의 뜻,health판정 - hang 감지와 워치독 —
Last Hang과Hang Verdict읽는 법 - FATAL과 복구 —
FAULTED카드에 대한 조치 - 컨테이너 지원
- 파라미터 레퍼런스
- 설치 확인