콘텐츠로 이동

설치 확인

드라이버를 설치한 뒤, 드라이버가 모든 카드를 인식했는지와 정상적으로 동작할 준비가 되었는지 확인하는 순서입니다. 1단계부터 차례로 확인하고, 기대와 다른 결과가 나오면 그 단계에서 원인을 찾으십시오. 상태를 읽는 명령(lspci, dmesg, cat, hyperaccel-smi)은 워크로드가 동작하는 중에도 실행할 수 있습니다.


1. 카드가 PCI 버스에 보이는지 확인

1
lspci -D -k -d 20fb:

20fb는 카드의 PCI 벤더 ID입니다. 카드마다 PCI 주소(예: 0000:01:00.0)로 시작하는 항목이 하나씩 나와야 하고, 드라이버가 정상적으로 설치되어 있는 상태라면 각 카드마다 Kernel driver in use: ha가 함께 출력됩니다.

  • 항목이 하나도 없으면 호스트가 카드를 찾지 못한 것입니다. 카드의 장착, 전원, BIOS 설정을 확인하십시오. 이 상태에서는 드라이버도 카드를 인식할 수 없습니다.
  • Kernel driver in use: ha가 없으면 드라이버가 적재되지 않았거나 그 카드를 인식하지 못한 것입니다. 2단계와 3단계에서 원인을 찾으십시오.
  • Kernel driver in use에 다른 드라이버가 나오면 그 드라이버가 카드를 쓰고 있는 것입니다.

2. 모듈이 적재되었는지 확인

1
2
3
lsmod | grep '^ha '
cat /sys/module/ha/version
modinfo -F version ha
  • lsmod에 ha로 시작하는 줄이 있어야 합니다.
  • /sys/module/ha/version은 지금 적재된 드라이버의 버전이고, modinfo -F version ha는 실행 중인 커널에 설치된 모듈 파일의 버전입니다. 새로 설치했다면 둘 다 설치한 버전과 같아야 합니다.
  • 두 버전이 다르면 이전 드라이버가 아직 적재되어 있는 것입니다. 업그레이드와 제거를 보십시오.

실행 중인 커널용 모듈이 DKMS로 설치되었는지도 확인합니다.

1
2
uname -r
dkms status | grep '^ha'

uname -r과 같은 커널 버전의 항목이 installed로 나와야 합니다.

모듈이 적재되어 있지 않으면 직접 적재하고 커널 로그를 봅니다.

1
2
sudo modprobe ha
sudo dmesg | tail -n 30

Secure Boot가 켜진 호스트에서 적재가 거부되면 설치를 보십시오.

재부팅 뒤 자동 적재

설치 과정은 /etc/modules-load.d/ha.conf를 만들어 부팅할 때 모듈이 적재되게 합니다. 처음 설치한 호스트라면 한 번 재부팅한 뒤 이 단계를 다시 확인하십시오.

3. 커널 로그에서 인식 결과 확인

드라이버가 남긴 메시지만 골라 봅니다.

1
sudo dmesg | grep -E '(^|\] )ha[ :]'

카드를 정상으로 인식했는지는 아래 메시지로 판단합니다.

1
sudo dmesg -t | grep -E 'firmware ready after|ABI protocol|Probe successful|Module initialized'

출력 예(카드 한 장):

1
2
3
4
ha 0000:01:00.0: firmware ready after 0 ms
ha 0000:01:00.0: ABI protocol v8 (driver v9, min v6)
ha 0000:01:00.0: Probe successful: /dev/ha0 created
ha: Module initialized
메시지 뜻
firmware ready after <N> ms 카드의 펌웨어가 준비를 마쳤습니다
ABI protocol v<N> (driver v<N>, min v<N>) 펌웨어의 명령 프로토콜 버전이 드라이버가 요구하는 최소 버전 이상입니다
Probe successful: /dev/haN created 드라이버가 카드를 인식하고 디바이스 노드 /dev/haN을 만들었습니다
ha: Module initialized 모듈 적재가 끝났습니다

카드마다 앞의 세 메시지가 하나씩 있어야 합니다. 경고나 오류가 함께 있으면 커널 로그 메시지에서 뜻을 확인하십시오. 펌웨어가 준비되지 않았을 때 남는 메시지는 8단계에 있습니다.

적재한 지 오래되어 dmesg에서 이 메시지가 밀려났다면 sudo journalctl -k -b의 출력에서 같은 메시지를 찾으십시오.

4. 디바이스 노드 확인

1
ls -l /dev/ha*

카드마다 /dev/haN 노드가 하나씩 있어야 합니다. 기본 udev 규칙이 적용되었다면 권한이 crw-rw-rw-(0666)입니다.

1
crw-rw-rw- 1 root root 239, 0 Oct 16 09:12 /dev/ha0

장치 번호와 시각은 시스템마다 다릅니다.

결과 뜻과 조치
노드가 없음 드라이버가 카드를 인식하지 못했습니다. 3단계의 커널 로그를 보십시오
노드 수가 카드 수보다 적음 일부 카드를 인식하지 못했습니다. 7단계를 보십시오
권한이 crw-rw-rw-가 아님 udev 규칙을 직접 바꾸지 않았다면 규칙이 적용되지 않은 것입니다. 아래 명령으로 다시 적용하십시오
1
2
sudo udevadm control --reload-rules
sudo udevadm trigger --subsystem-match=ha

기본 권한 0666에서는 호스트의 모든 로컬 사용자가 카드를 쓸 수 있습니다. 접근을 제한하는 규칙은 접근 제한하기를 보십시오.

5. sysfs 상태 확인

드라이버는 카드마다 /sys/class/ha/haN/ 아래에 상태 노드를 둡니다. 모든 사용자가 읽을 수 있으므로 root 권한이 필요 없습니다.

1
2
3
4
ls /sys/class/ha/
cat /sys/class/ha/ha0/health
cat /sys/class/ha/ha0/fw_version
cat /sys/class/ha/ha0/serial
노드 정상일 때 다른 값일 때
health ok degraded나 faulted면 텔레메트리에서 뜻을, 문제 해결에서 조치를 확인하십시오
fw_version <major>.<minor>.<patch> 형식의 펌웨어 버전 unknown이면 펌웨어가 준비되지 않았습니다. 8단계를 보십시오
serial HA-로 시작하는 카드 고유 ID 펌웨어가 준비되지 않았으면 unknown입니다. fw_version이 버전을 보여 주는데도 unknown이면 이 카드나 펌웨어가 ID를 제공하지 않는 것이며, 디바이스 사용에는 영향이 없습니다

펌웨어 준비 여부는 fw_version으로 확인합니다

health는 드라이버가 관측한 오류와 FATAL 상태로 정해집니다. 펌웨어가 아직 준비되지 않은 카드도 오류가 없으면 ok입니다.

다른 노드의 정의는 sysfs를 보십시오.

6. hyperaccel-smi로 확인

1
hyperaccel-smi

출력의 첫 부분입니다. 값은 예시입니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
+-----------------------------------------------------------------------------------------+
| HYPERACCEL-SMI 1.0.0      Tue Oct 06 11:58:59 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-0a1b2c3d-000…    | 0000:01:00.0          | OK                  |
| 38C    21.5 W      0.0 %                  | 0.00 / 128.00 GiB     | 0 / 0               |
+-------------------------------------------+-----------------------+---------------------+
  • 맨 위 Firmware Version에 펌웨어 버전이 나와야 합니다. 이 값은 번호가 가장 작은 카드의 버전이므로, 카드별 버전은 hyperaccel-smi -q로 봅니다.
  • 카드마다 두 줄짜리 행이 있어야 하고, Bus-Id는 1단계에서 본 PCI 주소와 같아야 합니다.
  • Health가 OK여야 합니다.

hyperaccel-smi는 Python 3로 실행됩니다. 카드가 하나도 보이지 않으면 종료 코드 2로 끝나므로, 스크립트에서 설치를 확인할 때 쓸 수 있습니다.

1
hyperaccel-smi > /dev/null; echo $?

0이면 카드가 하나 이상 보이는 것입니다. 옵션과 출력 항목은 hyperaccel-smi를 보십시오.

7. 여러 카드 확인

카드가 여러 장이면 PCI 버스에 보이는 카드 수와 드라이버가 만든 디바이스 수가 같은지 봅니다.

1
2
lspci -D -d 20fb: | wc -l
ls -d /sys/class/ha/ha* | wc -l

카드마다 디바이스 번호, PCI 주소, health, fw_version을 한 줄씩 봅니다.

1
2
3
for d in /sys/class/ha/ha*; do
  echo "$(basename "$d") $(basename "$(readlink -f "$d/device")") $(cat "$d/health") $(cat "$d/fw_version")"
done
1
2
ha0 0000:01:00.0 ok 1.0.5
ha1 0000:02:00.0 ok 1.0.5

모든 카드가 ok이고 펌웨어 버전이 나와야 합니다. hyperaccel-smi의 LPU 번호와 Bus-Id도 같은 대응을 보여 줍니다.

  • 드라이버는 한 호스트에서 카드를 8장까지 인식합니다.
  • 노드가 없는 카드가 있으면 그 카드의 PCI 주소로 커널 로그를 찾으십시오. 예: sudo dmesg | grep 0000:02:00.0
  • 번호가 정해지는 방식은 여러 디바이스를 보십시오.

8. 펌웨어가 준비되지 않았을 때

드라이버는 카드를 인식할 때 펌웨어가 준비되기를 몇 초 기다립니다. 그 안에 준비되지 않아도 카드를 인식하고 /dev/haN을 만들지만, 펌웨어가 준비되기 전에는 다음과 같이 보입니다.

  • 커널 로그에 firmware boot sentinel not seen within이나 firmware never reported ready로 시작하는 경고가 남습니다.
  • fw_version과 serial이 unknown입니다. 온도와 전력처럼 펌웨어가 보내 주는 값도 펌웨어가 보내기 시작할 때까지 unknown입니다. health는 ok일 수 있습니다.
  • hyperaccel-smi의 그 카드 행에서 Serial이 N/A이고, hyperaccel-smi -q에서 그 카드의 Firmware Version과 Serial이 unknown입니다. 온도와 전력이 unknown이면 Temp와 Power도 N/A입니다.
  • 애플리케이션이 디바이스를 사용하려 하면 디바이스가 준비되지 않았다는 오류가 반환됩니다.
  • 몇 초 뒤 커널 로그(dmesg)에 sys_mon: no response for로 시작하는 오류가 남을 수 있습니다. 온도, 전력, 사용률 정보를 읽는 폴링을 멈췄다는 뜻이며, 펌웨어가 준비된 뒤 fw_version을 읽으면 폴링이 다시 시작되고 sys_mon: resuming telemetry polling이 남습니다.

펌웨어가 나중에 준비를 마치면 드라이버를 다시 적재할 필요가 없습니다. 잠시 뒤 fw_version을 다시 읽어 버전이 나오면 그때부터 디바이스를 쓸 수 있습니다. 이때 커널 로그에 firmware booted after probe gave up; CSR-derived telemetry refreshed가 남습니다.

fw_version이 계속 unknown이면 문제 해결과 FATAL과 복구를 보십시오.


결과가 기대와 다를 때

증상 확인할 것
lspci에 카드가 없음 카드의 장착, 전원, BIOS 설정
모듈이 적재되지 않음 sudo modprobe ha의 오류 메시지와 커널 로그, Secure Boot 설정
카드는 보이는데 /dev/haN이 없음 커널 로그에서 그 카드의 PCI 주소를 찾습니다. ABI protocol mismatch가 있으면 펌웨어와 드라이버의 버전 조합이 맞지 않는 것입니다. 지원 환경을 보십시오
노드 권한이 crw-rw-rw-가 아님 4단계의 udev 규칙 재적용
fw_version이 계속 unknown 8단계
health가 ok가 아님 문제 해결
적재된 버전과 설치된 버전이 다름 업그레이드와 제거

지원을 요청할 때는 문제 상황의 진단 정보 모으기로 진단 정보를 저장해 함께 보내십시오. 함께 알려 줄 내용은 지원 요청에 있습니다.


함께 보기