콘텐츠로 이동

파라미터 설정과 사용법

ha.ko는 모듈 파라미터로 복구, hang 감지, 텔레메트리, 디바이스 간 경로, 성능 최적화의 동작을 정합니다. 이 페이지는 현재 값을 확인하고 값을 바꾸는 방법, 바꾼 값이 적용되는 시점, 자주 쓰는 설정을 다룹니다. 파라미터마다의 타입, 기본값, 유효 범위, 0의 뜻은 파라미터 레퍼런스에 있습니다.

ha 모듈의 파라미터입니다

이 값들은 ha 모듈의 파라미터입니다. 보통은 /etc/modprobe.d/의 옵션 파일로 정하며, 커널 명령행에 ha.<이름>=<값>으로 적어도 모듈을 적재할 때 그 값이 쓰입니다. 모든 파라미터는 장비의 모든 카드에 똑같이 적용되며, 카드마다 다른 값을 줄 수 없습니다.


분류

분류 파라미터 주로 바꾸는 경우
복구 ha_auto_reset, ha_aer_enable, ha_ready_timeout_ms 사람이 개입하지 않고 FATAL 디바이스를 복구하려 할 때, 커널 6.4 미만(RHEL 계열은 9.4 미만)에서 카드의 PCIe AER 오류 보고를 켜려 할 때, 리셋 뒤 펌웨어가 준비되는 데 더 오래 걸릴 때
hang 감지와 워치독 ha_devcmd_ceiling_ms, ha_wd_hang_ms, ha_wd_hdma_hang_ms, ha_wd_poll_ms, ha_wd_preempt 정상 작업이 hang으로 판정될 때, 멈춘 대기를 상한보다 빨리 끊으려 할 때
텔레메트리 ha_sysmon_poll_ms, ha_sysmon_fail_limit 센서 값의 갱신 주기나, 응답하지 않는 카드의 모니터링을 멈추는 기준을 바꾸려 할 때
디바이스 구성과 여러 디바이스 ha_tw_wide_access, ha_hdma_completion, ha_tw_pin_wait_ms, ha_host_mem_max_mb 하이퍼바이저가 BAR 접근을 가로챌 때, VM에서 DMA 복사가 모두 실패하거나 arm64 베어메탈 서버가 DMA 완료를 폴링할 때, 디바이스 간 복사가 한 카드로 몰릴 때, 카드가 직접 읽고 쓰는 호스트 메모리의 할당이 상한에 걸릴 때
성능 ha_abi_prefetch, ha_hdma_min_bytes, ha_hdma_cpu_latency_us 최적화 없이 동작이나 성능을 비교하려 할 때, 호스트와 디바이스 사이의 작은 복사를 DMA 엔진 대신 CPU 복사로 처리하려 할 때, 복사 중의 CPU 전력을 줄여야 할 때

대부분의 장비는 기본값으로 운영합니다. 기본값과 권한은 한눈에 보기에 있습니다.


현재 값 확인

파라미터 값은 /sys/module/ha/parameters/<이름>에 있고, 일반 사용자도 읽을 수 있습니다. bool 파라미터는 Y(1) 또는 N(0)으로 읽힙니다.

1
cat /sys/module/ha/parameters/ha_auto_reset

운영용 파라미터를 한 번에 봅니다.

1
2
3
4
5
cd /sys/module/ha/parameters && grep -H . ha_tw_wide_access ha_hdma_completion \
  ha_auto_reset ha_aer_enable ha_ready_timeout_ms \
  ha_devcmd_ceiling_ms ha_wd_hang_ms ha_wd_hdma_hang_ms ha_wd_poll_ms ha_wd_preempt \
  ha_sysmon_poll_ms ha_sysmon_fail_limit ha_tw_pin_wait_ms ha_host_mem_max_mb \
  ha_abi_prefetch ha_hdma_min_bytes ha_hdma_cpu_latency_us

이 디렉터리에는 이 문서에 없는 파라미터 파일도 있습니다. 개발과 시험에 쓰는 값이므로 HyperAccel의 안내 없이 바꾸지 마십시오.

파일은 적은 값을 그대로 보여 줍니다

범위 밖의 값을 적으면 파일에는 적은 값이 그대로 남고, 드라이버가 그 값을 쓸 때 유효 범위 안으로 맞춥니다. 예를 들어 ha_sysmon_poll_ms에 0을 적으면 파일은 0을 보여 주지만 실제 주기는 50 ms입니다.


바꾸는 방법

방법 적용 시점 재부팅한 뒤 바꿀 수 있는 파라미터
옵션 파일 다음에 모듈을 적재할 때 유지됩니다 전부
커널 명령행 명령행을 고치고 재부팅한 뒤 모듈을 적재할 때 명령행에 남아 있는 동안 유지됩니다 전부
modprobe 명령행 그 적재에만 사라집니다 전부
실행 중 쓰기 파라미터마다 다릅니다 사라집니다 권한이 0644인 것

적재할 때 위 표의 값을 읽는 세 곳(옵션 파일, 커널 명령행, modprobe 명령행) 가운데 한 곳에만 적으십시오. 어느 값이 쓰이고 있는지는 현재 값 확인처럼 /sys/module/ha/parameters/에서 봅니다.

옵션 파일로 정하기

/etc/modprobe.d/ 아래에 옵션 파일을 만듭니다. 파일 이름은 .conf로 끝나면 됩니다. 한 줄에 여러 파라미터를 적을 수 있습니다.

1
2
# /etc/modprobe.d/ha.conf
options ha ha_auto_reset=1 ha_wd_preempt=1

이 파일은 다음에 모듈을 적재할 때 적용됩니다. 재부팅하거나 모듈을 다시 적재합니다.

1
2
sudo modprobe -r ha
sudo modprobe ha

dracut으로 초기 램디스크를 만드는 배포판

RHEL 계열과 Fedora처럼 dracut이 호스트에 맞춘 초기 램디스크(initramfs)를 만드는 배포판에서는, 초기 램디스크를 다시 만들 때(커널 업데이트 등) ha 모듈과 그때의 /etc/modprobe.d/ 옵션 파일이 함께 들어갈 수 있습니다. 그러면 부팅할 때 초기 램디스크에 든 옵션으로 모듈이 적재되므로, 옵션 파일을 고친 뒤 재부팅으로 적용하려면 sudo dracut -f --regenerate-all로 초기 램디스크를 다시 만드십시오. 재부팅한 뒤에는 /sys/module/ha/parameters/에서 값을 확인하십시오.

설치 과정이 만드는 /etc/modules-load.d/ha.conf는 부팅할 때 모듈을 자동으로 적재하는 설정이고, 파라미터를 적는 파일이 아닙니다. 설치와 제거 절차는 /etc/modprobe.d/의 옵션 파일을 만들거나 지우지 않으므로, 드라이버를 업그레이드해도 설정이 그대로 남습니다.

옵션 파일이나 modprobe 명령행에 타입에 맞지 않거나 받지 않는 값을 적으면 모듈 적재가 실패하고, dmesg에 ha: `<값>' invalid for parameter `<이름>' 줄이 남습니다. 이름이 틀린 파라미터는 ha: unknown parameter '<이름>' ignored 경고만 남기고 무시됩니다. 옵션 파일을 고친 뒤에는 모듈을 다시 적재하고 /sys/module/ha/parameters/에서 값을 확인하십시오.

모듈을 다시 적재하면 모든 카드가 내려갑니다

modprobe -r ha는 장비의 모든 카드를 드라이버에서 떼어 냅니다. 디바이스를 연 프로세스가 하나라도 있으면 언로드가 실패합니다(Module ha is in use). 워크로드를 모두 멈춘 뒤에 하십시오.

권한이 0644인 파라미터는 다시 적재하지 않고 실행 중에 바꿀 수 있습니다. 카드 하나의 상태만 되돌리려는 것이라면 모듈을 다시 적재하지 말고 ha-hotreset을 쓰십시오.

커널 명령행에 적기

부트 로더의 커널 명령행에 ha.<파라미터>=<값>을 적으면, 모듈을 적재할 때(부팅할 때의 자동 적재와 modprobe ha) 그 값이 모듈 옵션으로 쓰입니다. 옵션 파일을 고치기 어려운 장비에서 씁니다.

1
ha.ha_auto_reset=1 ha.ha_sysmon_poll_ms=500
  • Ubuntu와 Debian: /etc/default/grub의 GRUB_CMDLINE_LINUX에 추가하고 sudo update-grub을 실행한 뒤 재부팅합니다.
  • RHEL 계열과 Fedora: sudo grubby --update-kernel=ALL --args="ha.ha_auto_reset=1"처럼 추가한 뒤 재부팅합니다.
  • 지금 커널의 명령행은 cat /proc/cmdline으로 확인합니다.
  • 커널 명령행의 값도 옵션 파일과 같이 검사합니다. 타입에 맞지 않는 값이 있으면 모듈이 적재되지 않고, 명령행은 재부팅해야 바뀌므로 그 부팅 동안에는 modprobe ha도 같은 이유로 실패합니다. 명령행을 고친 뒤 다시 부팅하십시오.
  • ha. 접두어가 없는 커널 명령행 옵션도 드라이버 동작에 영향을 줍니다. IOMMU 설정(예: iommu=pt)에 따라 카드 사이 데이터 경로의 주소 방식이 달라집니다. 지원하는 구성은 지원 환경에, 구성별 차이는 IOMMU 모드와 디바이스 간 경로에 있습니다. pci=nomsi로 MSI를 끄면 드라이버가 카드의 인터럽트를 설정하지 못해 카드를 인식하지 못합니다(probe를 멈추는 오류).

적재할 때 한 번만 지정하기

modprobe 명령행에 적은 값은 그 적재에만 적용됩니다.

1
sudo modprobe ha ha_auto_reset=1 ha_sysmon_poll_ms=500

모듈이 이미 적재되어 있으면 modprobe는 아무것도 하지 않고, 명령행에 적은 값도 적용되지 않습니다. 설치 과정이 부팅할 때 모듈을 적재하도록 설정하므로, 먼저 sudo modprobe -r ha로 모듈을 내립니다.

실행 중에 바꾸기

권한이 0644인 파라미터는 root가 바로 바꿀 수 있습니다. bool은 1/0이나 Y/N을 적습니다.

1
2
echo 1 | sudo tee /sys/module/ha/parameters/ha_auto_reset
echo 1000 | sudo tee /sys/module/ha/parameters/ha_sysmon_poll_ms
  • 실행 중에 바꾼 값은 모듈을 다시 적재하면 사라집니다. 계속 쓰려면 옵션 파일에도 적으십시오.
  • 권한이 0444인 ha_hdma_completion, ha_aer_enable, ha_hdma_cpu_latency_us는 실행 중에 바꿀 수 없습니다. 쓰기가 거부됩니다.
  • 타입에 맞지 않는 값(uint에 음수나 문자열)은 Invalid argument로 거부되고 값이 바뀌지 않습니다.

바꾼 값이 언제부터 쓰이는지는 파라미터마다 다르며, 파라미터 레퍼런스의 각 절 표에 있는 "적용 시점"을 보십시오.


자주 쓰는 설정

아래 예는 대부분 /etc/modprobe.d/ha.conf에 적는 형식입니다. 파일을 고친 뒤에는 모듈을 다시 적재하거나 재부팅해야 적용됩니다. 권한이 0644인 파라미터는 실행 중에 바꾸기처럼 바로 바꿀 수도 있습니다.

자동 복구 켜기

FATAL이 된 디바이스를 사람이 리셋하지 않아도 드라이버가 리셋하게 합니다.

1
2
# /etc/modprobe.d/ha.conf
options ha ha_auto_reset=1
  • 지금 바로 켜려면 echo 1 | sudo tee /sys/module/ha/parameters/ha_auto_reset을 실행합니다. 드라이버는 디바이스가 FATAL로 바뀌는 순간의 값을 쓰므로, 켜기 전에 이미 FATAL인 디바이스는 직접 리셋하십시오.
  • 자동 리셋을 시작하면 dmesg에 auto-TDR:로 시작하는 줄이 남습니다. 리셋된 디바이스를 쓰던 애플리케이션은 디바이스를 다시 열어야 합니다.
  • 펌웨어 업데이트가 진행 중이거나 업데이트의 응답을 확인하지 못한 디바이스는 자동으로 리셋하지 않습니다.

리셋 순서와 실패했을 때의 동작은 자동 리셋을 보십시오.

멈춘 대기를 빨리 끊고 복구하기

기본값에서 워치독은 멈춘 대기를 커널 로그에 보고만 합니다. 응답 대기 상한(기본 12초)보다 빨리 정리하고 자동으로 복구하려면 ha_wd_preempt를 ha_auto_reset과 함께 켭니다.

1
options ha ha_auto_reset=1 ha_wd_preempt=1
  • 디바이스 명령 대기는 상한(기본 12초) 대신 문턱(ha_wd_hang_ms, 기본 8초) 무렵에 끊기고, DMA 전송은 DMA 대기 문턱(ha_wd_hdma_hang_ms, 기본 4초) 무렵에 끊깁니다. 이렇게 끊긴 DMA 전송은 디바이스를 FATAL로 만듭니다. 기본값에서는 DMA 전송이 5초 안에 끝나지 않을 때 그 작업만 실패하고, 디바이스는 FATAL이 되지 않습니다.
  • 워치독은 경과 시간만 보므로 문턱을 넘는 정상 작업도 끊습니다. 상한 없이 오래 기다리는 작업을 돌리는 장비에서는 켜지 마십시오.
  • ha_auto_reset 없이 켜면 FATAL이 된 디바이스가 수동 리셋을 기다리고, dmesg에 watchdog: preempting without ha_auto_reset으로 시작하는 경고가 남습니다. 실행 중에 켤 때는 ha_auto_reset을 먼저 켭니다.
  • 문턱을 바꿀 때는 파라미터 사이의 관계를 지키십시오.

경우별 동작은 매달린 대기 끊기를 보십시오.

오래 걸리는 정상 작업을 hang으로 판정하지 않게 하기

드라이버는 디바이스 명령을 묶음(배치)으로 보내며, 응답 대기 상한은 묶음 하나의 응답을 기다리는 전체 시간에 걸립니다. 정상 워크로드의 묶음 하나를 처리하는 데 상한(기본 12초)보다 오래 걸려 Devcmd no response after 12000 ms (device hang)이 남고 디바이스가 FATAL이 되면, 상한을 그 작업의 소요 시간보다 넉넉하게 늘리고 워치독 문턱도 함께 늘립니다.

1
options ha ha_devcmd_ceiling_ms=30000 ha_wd_hang_ms=25000
  • 두 값 모두 실행 중에도 바꿀 수 있습니다. 상한은 바꾼 뒤에 시작하는 대기부터, 문턱은 다음 워치독 점검부터 적용됩니다.
  • 문턱을 그대로 두면 그 작업마다 워치독 경고가 남습니다. ha_wd_preempt=1인 장비에서는 워치독이 문턱(기본 8초)에서 그 대기를 끊어 디바이스가 FATAL이 되므로, 상한만 늘려서는 효과가 없습니다.
  • 펌웨어가 스스로 시간 초과를 보고해 FATAL이 된 경우(Firmware error 줄의 rc=0x7)는 이 두 값을 늘려도 달라지지 않습니다. 이때는 지원팀에 문의하십시오.
  • 늘린 만큼 실제로 응답하지 않는 디바이스를 hang으로 판정하는 시점이 늦어지고, 리셋할 때 펌웨어 재초기화의 응답을 기다리는 시간도 길어집니다.
  • 디바이스 메모리 채우기와 펌웨어 업데이트에는 드라이버가 추가 시간을 주므로 그 작업 때문에 늘릴 필요는 없습니다.
  • 두 값은 파라미터 사이의 관계를 지켜야 합니다(예: 25000 + 500 < 30000).

텔레메트리 갱신 주기 바꾸기

온도, 전력, 사용률을 펌웨어에서 가져오는 주기입니다. 기본값은 200 ms입니다.

1
options ha ha_sysmon_poll_ms=1000
  • 유효 범위는 50–2500 ms입니다. 범위 밖의 값은 가까운 끝값으로 쓰고, 0은 가장 짧은 주기(50 ms)입니다.
  • 주기를 늘리면 응답하지 않는 디바이스의 폴링을 멈추는 판정도 늦어집니다. 대략 ha_sysmon_fail_limit × 주기가 걸립니다.
  • 마지막 샘플이 5초보다 오래되면 값이 unknown이 됩니다. 주기를 길게 잡을수록 폴링이 한두 번 실패했을 때 unknown이 되기 쉽습니다.
  • 실행 중에도 바꿀 수 있습니다. 이미 예약된 폴링은 이전 주기를 쓰고, 그다음 폴링부터 새 주기를 씁니다.

카드의 PCIe AER 오류 보고 켜기

ha_aer_enable=1이면 커널 6.4 미만(RHEL 계열은 9.4 미만)에서 드라이버가 카드의 PCIe AER 오류 보고를 켭니다. 커널 6.4 이상과 RHEL 9.4 이상에서는 이 파라미터가 경고 한 줄을 남기는 것 말고는 아무것도 바꾸지 않습니다. 이 커널들에서는 커널과 플랫폼 구성이 오류 보고를 정하므로, ha_aer_enable=0이어도 카드의 오류가 보고되고 커널의 복구 절차가 진행될 수 있습니다.

1
options ha ha_aer_enable=1
  • 적재할 때만 정할 수 있습니다(0444). 켜려면 옵션 파일에 적고 모듈을 다시 적재합니다. 드라이버는 한 번 켠 오류 보고를 끄지 않으므로, 커널 6.4 미만(RHEL 계열은 9.4 미만)에서 다시 끄려면 옵션 파일에서 값을 0으로 바꾸거나 지운 뒤 호스트를 재부팅하십시오. 재부팅하지 않으려면 모듈을 다시 적재한 뒤 카드마다 ha-hotreset으로 리셋하십시오. 모듈을 다시 적재하는 것만으로는 카드의 오류 보고가 켜진 채로 남습니다.
  • AER로 보고된 치명적 오류를 복구할 때 커널은 부모 브리지에 SBR(Secondary Bus Reset, 브리지 아래 버스 전체의 리셋)을 겁니다. 경로의 포트에서 Surprise Down 오류(링크가 예고 없이 끊겼다는 오류)가 마스킹되어 있지 않으면 플랫폼이 호스트를 재부팅시킬 수 있으므로, 그 호스트에서 SBR이 안전하다는 것을 확인한 경우에만 켜십시오.

자세한 내용은 AER 보고와 ha_aer_enable과 SBR을 걸 수 있는 구성을 보십시오.

입력 복사 앞당기기 끄기

ha_abi_prefetch(기본 켜짐)는 같은 스트림에서 앞선 디바이스 커널이 실행되는 동안, 다음 디바이스 커널이 쓸 인자 블록을 미리 복사하는 성능 최적화입니다. 이 최적화 없이 동작이나 성능을 비교할 때 끕니다. 실행 중에 바꿀 수 있습니다.

1
echo 0 | sudo tee /sys/module/ha/parameters/ha_abi_prefetch
  • 끄면 모든 복사를 제출 순서대로 실행합니다. 켜 두어도 결과는 순서대로 실행한 것과 같습니다.
  • 앞당긴 횟수는 sysfs abi_prefetch_stats에서 봅니다. 다시 켜려면 1을 씁니다.

파라미터 사이의 관계

관계 지킬 조건 어기면
명령 대기 감시 ha_wd_hang_ms + ha_wd_poll_ms < ha_devcmd_ceiling_ms 명령 대기 감시가 발화할 수 없습니다
DMA 대기 감시 ha_wd_hdma_hang_ms + ha_wd_poll_ms < 5000 DMA 대기 감시가 발화할 수 없습니다
대기 끊기 ha_wd_preempt=1이면 ha_auto_reset=1 FATAL이 된 디바이스가 수동 리셋 전까지 그대로 남습니다
텔레메트리 중단 판정까지 대략 ha_sysmon_fail_limit × ha_sysmon_poll_ms 이상 주기를 늘리면 판정도 늦어집니다

기본값은 처음 두 조건을 만족합니다(8000 + 500 < 12000, 4000 + 500 < 5000). 문턱 값이 0인 감시는 꺼져 있으므로 검사하지 않습니다.

워치독 조건을 어기는 조합이면 드라이버는 값을 바꾸지 않고, 다음 워치독 점검에서 dmesg에 아래 경고를 남깁니다. 같은 값 조합에서는 한 번만 남기고, 값이 바뀐 뒤에도 조건을 어기면 다시 남깁니다.

1
watchdog: devcmd arm cannot fire with this configuration (hang=<ms> ms hdma_hang=<ms> ms poll=<ms> ms devcmd_ceiling=<ms> ms hdma_timeout=5000 ms); lower the threshold or the poll interval

devcmd 자리에는 발화할 수 없는 감시가 devcmd, hdma, devcmd+hdma 중 하나로 들어갑니다.


함께 보기