콘텐츠로 이동

ha-hotreset

ha-hotreset은 HyperAccel 카드 한 장을 PCIe 핫 리셋하는 호스트용 명령어입니다. 카드를 드라이버에서 제거하고, 부모 브리지에서 SBR(Secondary Bus Reset)을 건 뒤, 브리지를 다시 스캔해 드라이버가 카드를 다시 인식하게 합니다. ha 모듈은 적재된 채로 두며 요청하지 않은 카드는 건드리지 않습니다. 이 페이지는 설치 위치, 옵션, 사전 점검, 동작 순서, 출력, 종료 코드를 정의합니다. 언제 어떤 복구 수단을 쓰는지는 FATAL과 복구를 보십시오.


설치 위치

ha-hotreset은 드라이버 deb 패키지 hyperdriver-dkms가 /usr/bin/ha-hotreset에 설치합니다.

시놉시스

1
2
3
4
5
ha-hotreset [--bdf BDF] [--force] [--no-switch-link-drop]
ha-hotreset --all [--force] [--no-switch-link-drop]
ha-hotreset --check-mask[=SECONDS] [--bdf BDF | --all]
ha-hotreset --list [--no-switch-link-drop]
ha-hotreset --help

요구 사항

  • 호스트에서 root로 실행합니다. --help와 --list를 뺀 모든 동작은 root가 아니면 Run as root를 출력하고 끝납니다. --list는 root가 아니어도 실행되지만 부모 포트의 PCIe 설정을 읽으므로 가능하면 root로 실행하십시오.
  • pciutils의 setpci와 lspci가 필요합니다. 없으면 setpci not found (install pciutils) 또는 lspci not found (install pciutils)를 출력하고 끝납니다.
  • 리셋과 --check-mask에는 util-linux의 flock도 필요합니다. 없으면 flock not found (install util-linux)를 출력하고 끝납니다. 호스트 락을 보십시오.
  • 리셋할 카드의 디바이스 노드를 연 프로세스가 없어야 합니다. 사전 점검을 보십시오.
  • ha-hotreset은 ha 모듈을 내리거나 적재하지 않습니다. 카드를 다시 인식하는 것은 적재되어 있는 드라이버입니다.

옵션

옵션 설명
--bdf BDF, --bdf=BDF 리셋할 카드의 PCI 주소입니다(예: 0000:1a:00.0). 도메인을 뺀 1a:00.0은 그 주소가 모든 PCI 도메인에서 하나뿐일 때만 받습니다. 호스트에 카드가 한 장뿐이면 이 옵션을 생략할 수 있습니다
--all lspci가 찾은 vendor ID 20fb 카드를 모두 리셋합니다. 모든 카드의 사전 점검이 통과해야 시작합니다. --bdf와 함께 쓸 수 없습니다
--force 디바이스 노드가 열려 있어도 진행합니다. 다른 사전 점검은 넘기지 않습니다
--list lspci가 찾은 카드마다 부모 브리지와 SBR 판정을 출력하고 끝납니다. 아무것도 바꾸지 않습니다. --check-mask와 함께 쓸 수 없습니다
--no-switch-link-drop 부모 포트가 Surprise Down을 마스킹하지 않은 카드를 경로 마스킹으로 리셋하지 않고 거부합니다. --list에 함께 주면 그런 카드를 NOT resettable로 표시합니다. 경로 마스킹을 보십시오
--allow-switch-link-drop 호환을 위해 받습니다. 경로 마스킹이 기본 동작이므로 효과가 없습니다
--check-mask[=SECONDS] 경로 마스킹이 이 호스트에서 유지되는지만 확인합니다. 카드를 제거하지 않고 링크를 끊지 않습니다. SECONDS(기본 60)는 =로 붙여 씁니다. 마스킹 확인을 보십시오
-h, --help 사용법을 출력하고 끝납니다

--force로 리셋한 뒤

핸들을 열어 두었던 프로세스의 이후 SDK 호출은 실패합니다. 그 프로세스는 디바이스를 닫고 다시 열어야 하며, 그 사이 디바이스 메모리 매핑에 접근하면 SIGBUS가 발생할 수 있습니다. 펌웨어 업데이트 중인 카드에는 --force를 쓰지 마십시오. 업데이트 도구는 일반 리셋을 막으려고 디바이스를 열어 두며, 플래시를 쓰는 도중 리셋하면 카드가 부팅하지 못할 수 있습니다.

대상 카드

  • --bdf로 지정한 카드는 lspci 목록과 관계없이 대상으로 삼습니다. 주소는 /sys/bus/pci/devices 아래에서 찾습니다.
  • 도메인을 뺀 주소를 하나로 정하면 Resolved --bdf <입력> -> <BDF>를 출력합니다. 같은 주소가 여러 PCI 도메인에 있으면 후보를 출력하고 거부합니다.
  • --bdf와 --all을 모두 생략하면 lspci가 찾은 카드가 한 장일 때 그 카드를 고르고 Only one card present, selecting <BDF>를 출력합니다. 두 장 이상이면 목록을 출력하고 거부합니다. 한 장도 없으면 No PCIe EP with vendor 20fb found - pass --bdf explicitly를 출력합니다.
  • --all은 시작할 때 Targets (<개수>): <BDF 목록>을 출력합니다.

사전 점검

--list와 --check-mask를 뺀 모드는 카드를 건드리기 전에 모든 대상 카드를 점검합니다. 하나라도 실패하면 Pre-flight failed - nothing was touched.를 출력하고 아래 표의 종료 코드로 끝납니다. 카드마다 사유가 다르면 4, 3, 1 순서로 우선합니다.

점검 실패할 때 출력(첫 줄) --force로 넘김 종료 코드
카드의 PCI 노드가 있는가 <BDF>: missing sysfs node /sys/bus/pci/devices/<BDF> 아니요 1
vendor ID가 20fb인가 <BDF>: not a 20fb device (vendor=<값>) 아니요 1
SBR을 걸 수 있는 구성인가 <BDF>: <판정> - refusing SBR 아니요 4
경로를 마스킹해야 하면, 경로의 포트마다 마스킹할 레지스터를 읽을 수 있는가 <BDF>: cannot map the path to a root port - refusing SBR, <BDF>: cannot read <레지스터> on <포트> - the path cannot be masked, refusing SBR 아니요 4
부모 브리지 아래에 이 카드만 있는가 <BDF>: parent bridge <부모 BDF> has more than one device below it: 아니요 4
디바이스 노드를 연 프로세스가 없는가 <BDF>: /dev/haN still open by PID(s) <PID 목록> 예 3
  • vendor ID를 0xffff로 읽거나 읽지 못한 카드는 거부하지 않고 already unresponsive 경고만 출력합니다. 응답하지 않는 카드는 리셋할 대상이기 때문입니다.
  • SBR 판정은 --list와 같습니다. 목록 출력을 보십시오.
  • 사전 점검을 통과해도 리셋 직전에 경로 마스킹이 적용되지 않을 수 있습니다. 이때 그 카드는 건드리지 않지만, --all이면 앞의 카드들은 이미 리셋된 상태로 끝납니다. 처음 쓰는 호스트에서는 마스킹 확인으로 먼저 확인하십시오.
  • 부모 브리지 아래의 디바이스를 셀 때 같은 카드의 PCI function들은 하나로 셉니다.
  • 열린 핸들은 /proc/<PID>/fd에서 그 카드의 /dev/haN을 연 프로세스를 찾아 판단합니다. 열린 핸들을 찾으면 그 카드의 sysfs inflight와 stream_count 값을 (inflight=<n> streams=<n> - informational only; …) 줄로 참고로 함께 출력합니다. 진행 중인 작업이 없어도 핸들이 열려 있으면 거부합니다. 드라이버에 바인드되지 않아 /dev/haN이 없는 카드는 이 점검을 건너뜁니다.
  • 펌웨어 업데이트 상태는 점검하지 않습니다. 업데이트 도구가 끝난 뒤에는 카드를 연 프로세스가 없으므로, 마지막 ha-fw-update 실행이 종료 코드 4로 끝났거나 종료 코드를 알리지 못하고 끝난 카드도 리셋합니다. 이런 카드는 일부만 기록된 플래시로 부팅해 올라오지 못할 수 있으므로, 먼저 응답을 받지 못했을 때의 안내대로 펌웨어의 응답을 기다려 업데이트를 마치십시오. 펌웨어가 끝내 응답하지 않을 때 남는 모듈 재적재, 이 도구, 전원 재인가는 일부만 기록된 플래시로 부팅할 위험이 있으므로 HyperAccel과 상의한 뒤에만 쓰십시오.

동작 순서

카드마다 다음 순서로 진행합니다. --all이면 카드를 하나씩 차례로 리셋하며, 한 장이 실패하면 거기서 멈추고 남은 카드는 리셋하지 않습니다. 리셋은 끝났는데 ha 드라이버가 바인드하지 않은 카드는 예외입니다. 이때는 남은 카드를 마저 리셋하고, 마지막에 바인드되지 않은 카드의 목록을 출력한 뒤 종료 코드 1로 끝납니다.

  1. 부모 포트가 root port가 아니고 Surprise Down을 마스킹하지 않았으면, 부모 포트부터 root port까지 경로를 마스킹합니다(경로 마스킹). 실패하면 그 카드를 건드리지 않고 끝납니다. 아직 리셋한 카드가 없으면 Nothing was touched.를 출력하고 종료 코드 4로, --all에서 앞선 카드를 이미 리셋했으면 종료 코드 1로 끝납니다. 마스킹에 성공하면 직접 되돌리는 setpci 명령을 미리 출력합니다.
  2. 카드의 AER 레지스터(Uncorrectable Error Mask, Correctable Error Mask, Uncorrectable Error Severity)를 읽어 둡니다.
  3. remove <BDF>를 출력하고 카드를 PCI에서 제거합니다(/sys/bus/pci/devices/<BDF>/remove). 드라이버가 카드를 내립니다.
  4. 부모 브리지의 Bridge Control 레지스터에서 Secondary Bus Reset 비트를 켰다가 끕니다.
  5. 부모 포트가 링크 활성 상태를 보고할 때까지 최대 30초 기다립니다. 보고하지 않아도 다음 단계로 넘어갑니다.
  6. 부모 브리지를 다시 스캔하며 카드가 다시 열거될 때까지 기다립니다(최대 100회, 0.1초 간격). 카드의 PCI 노드가 다시 생기지 않으면 실패합니다.
  7. 카드의 AER 레지스터를 2단계의 값과 비교해 바뀌었으면 되돌리고, 카드의 AER 상태를 출력합니다.
  8. 리셋 전에 /dev/haN이 있던 카드는 드라이버가 카드를 다시 인식해 같은 노드가 나타날 때까지 최대 약 12초 기다립니다. 나타나지 않으면 did not reappear - check dmesg for probe failure를 출력하고 실패합니다. 리셋 전에 /dev/haN이 없던 카드는 ha 드라이버가 카드를 바인드할 때까지 같은 시간 기다립니다. 바인드되지 않으면 9단계를 마친 뒤 the card was reset but the ha driver did not bind it와 다시 바인드하는 명령을 출력하고 종료 코드 1로 끝납니다. ha 모듈이 적재되지 않았거나, 커널의 자동 probe가 꺼져 있거나, 카드가 다른 드라이버용으로 잡혀 있으면(리셋 전에 다른 드라이버에 바인드되어 있었거나 driver_override가 지정됨) 이 확인을 하지 않습니다.
  9. 1단계에서 경로를 마스킹했으면 카드가 응답하는지 확인한 뒤 경로의 마스킹을 되돌립니다.
  10. Hot reset OK: <BDF>를 출력합니다.

중단되거나 실패할 때

  • 카드를 제거하기 전에 실패하거나 SIGINT, SIGTERM, SIGHUP으로 중단되면, 경로의 마스킹만 되돌리고 끝납니다.
  • 카드를 제거한 뒤에 실패하거나 중단되면, 부모 브리지의 Secondary Bus Reset 비트를 끄고 5~9단계를 성공할 때와 같이 마저 진행한 뒤 끝납니다. 카드가 다시 열거되고 응답할 때만 마스킹을 되돌리고, 그렇지 않으면 일부러 남깁니다(경로 마스킹 4단계).
  • 신호로 중단되면 정리를 마친 뒤 종료 코드 129(SIGHUP), 130(SIGINT), 143(SIGTERM)으로 끝납니다. 정리하는 동안 오는 신호는 무시합니다.
  • SIGKILL은 이 정리를 건너뛰므로 카드가 열거되지 않은 채 남거나 마스킹이 남을 수 있습니다. 쓰지 마십시오. 경로를 마스킹했다면 1단계에서 출력한 setpci 명령으로 되돌릴 수 있습니다.

Hot reset OK는 카드가 PCI에 다시 열거되었고, 리셋 전에 /dev/haN이 있던 카드라면 그 노드가 다시 나타났으며, 노드가 없던 카드라면 ha 드라이버가 카드를 바인드했다는 뜻입니다. 펌웨어 상태는 hyperaccel-smi나 sysfs health로 확인하십시오.

경로 마스킹

부모 포트가 root port가 아니고 Surprise Down을 마스킹하지 않았으면, SBR이 링크를 끊을 때 부모 포트가 Surprise Down 오류를 보고합니다. PCIe 오류를 플랫폼 펌웨어가 처리하는 서버에서는 이 오류가 호스트 전체의 재시작으로 이어질 수 있습니다. 그래서 ha-hotreset은 이런 카드를 리셋하는 동안, 부모 포트부터 root port까지 경로의 포트들이 오류를 보고하지 않게 막습니다(경로 마스킹). 이것이 기본 동작이며, --no-switch-link-drop을 주면 마스킹하지 않고 그런 카드를 거부합니다. 부모 포트가 root port이거나 Surprise Down을 이미 마스킹한 카드는 마스킹하지 않습니다.

마스킹된 오류는 보고되지 않으므로 플랫폼 펌웨어에 닿지 않습니다. 다만 플랫폼 펌웨어가 포트의 오류 상태 레지스터를 직접 읽는 등 다른 방법으로 링크 끊김을 감지하는 서버에서는, 마스킹해도 호스트 재시작을 막지 못할 수 있습니다. 처음 쓰는 호스트에서는 마스킹 확인으로 먼저 확인하십시오.

  1. 부모 포트에서 root port까지 경로의 포트마다 AER Uncorrectable Error Mask와 Correctable Error Mask의 마스킹 비트를 켜고, root port에서는 Root Control의 System Error 보고 비트 세 개를 끕니다. root port부터 아래로 진행하며 쓴 값을 모두 다시 읽어 확인합니다. 한 포트라도 확인되지 않으면 바꾼 포트를 모두 되돌리고 SBR을 걸지 않습니다.
  2. 마스킹은 카드가 다시 열거되고 드라이버가 카드를 인식할 때까지 유지합니다.
  3. 카드의 sysfs temp 노드(없으면 util)가 unknown이 아닌 값을 낼 때까지 최대 5초 기다립니다. 둘 다 없으면 no sysmon node under <경로> - falling back to a plain wait를 출력하고 5초를 기다립니다. 카드가 응답하면 경로와 카드의 AER 상태 비트를 지우고 마스킹을 되돌린 뒤 다시 읽어 확인합니다. 되돌린 값이 맞지 않으면 직접 되돌리는 setpci 명령을 출력합니다.
  4. 카드가 다시 열거되지 않거나, 디바이스 노드가 돌아오지 않거나, 응답하지 않으면 마스킹을 일부러 남겨 두고(the mask is LEFT IN PLACE on purpose), 되돌리는 setpci 명령을 출력한 뒤 실패로 끝납니다. 응답하지 않는 카드 위에서 마스킹을 풀면 그 카드의 오류가 플랫폼에 닿을 수 있기 때문입니다. 마스킹이 남아 있으면 그 경로의 실제 링크 오류도 보고되지 않으므로, 카드 문제를 처리한 뒤 출력된 명령으로 되돌리십시오.

호스트 락

마스킹하는 포트(switch upstream port, root port)는 그 아래의 모든 카드가 함께 씁니다. 두 실행이 겹치면 한쪽이 마스킹을 되돌리는 순간 다른 쪽의 리셋이 보호 없이 진행될 수 있습니다. 그래서 리셋과 --check-mask는 호스트에서 한 번에 하나만 실행됩니다(/run/ha-hotreset.lock). 다른 ha-hotreset이 실행 중이면 another ha-hotreset is running on this host - waiting up to 600s를 출력하고 최대 600초 기다립니다. 그 안에 끝나지 않으면 the other ha-hotreset did not finish in 600s - nothing was touched를 출력하고 종료 코드 3으로 끝납니다. --list는 읽기만 하므로 기다리지 않습니다.

마스킹 확인

--check-mask[=SECONDS]는 경로 마스킹이 이 호스트에서 동작할 수 있는지 확인합니다. 카드를 제거하지 않고 링크를 끊지 않으며, 사전 점검을 하지 않으므로 사용 중인 카드에도 실행할 수 있습니다. root 권한이 필요하고, 대상은 리셋과 같은 방법으로 --bdf를 이용해 지정합니다.

  1. 경로의 포트마다 현재 설정을 출력합니다(before:).
  2. 경로 마스킹과 같은 방법으로 경로를 마스킹하고 다시 읽어 확인합니다.
  3. SECONDS초 동안 기다린 뒤 마스킹이 그대로인지 확인합니다.
  4. 판정을 출력하고, 경로 포트의 AER 상태 비트를 지운 뒤 마스킹을 되돌립니다.
판정 뜻
VERDICT: the path could NOT be masked 어떤 포트가 마스킹을 받아들이지 않았습니다. 이 호스트에서는 부모 포트가 Surprise Down을 마스킹하지 않은 카드를 리셋할 수 없습니다
VERDICT: the platform CLEARED the mask on: <포트> 기다리는 동안 플랫폼이 마스킹을 되돌렸습니다. 이 호스트에서는 부모 포트가 Surprise Down을 마스킹하지 않은 카드를 리셋할 수 없습니다
VERDICT: the whole path masks and holds. 경로 전체가 마스킹되고 유지됩니다. 마스킹 쓰기에는 문제가 없다는 뜻이며, 리셋이 안전하다는 보장은 아닙니다
  • 기다리는 동안 경로의 포트가 검출한 오류는 보고되지 않고, root port는 받은 오류 메시지를 System Error로 올리지 않습니다.
  • 모든 대상의 판정이 the whole path masks and holds이면 종료 코드 0, 아니면 1입니다.

출력

진행 상황은 표준 출력(stdout)에, 경고와 거부 사유는 표준 오류(stderr)에 출력합니다.

목록 출력

--list는 카드마다 한 줄을 출력합니다.

1
2
<카드 BDF>  (parent <부모 BDF>, <판정>)
<카드 BDF>  (parent <부모 BDF>, <판정> - NOT resettable)
판정 리셋
parent is a root port 가능
parent is a <포트 종류>, Surprise Down Error masked there 가능
parent is a <포트 종류> with Surprise Down Error unmasked; the path is masked for the reset 가능. 경로 마스킹으로 리셋합니다
parent is a <포트 종류> with Surprise Down Error unmasked --no-switch-link-drop을 주었을 때 표시됩니다. 불가(NOT resettable)
parent is a <포트 종류> whose Surprise Down mask cannot be read (no AER capability) 불가(NOT resettable)
parent has no PCIe capability 불가(NOT resettable)

<포트 종류>는 switch upstream port, switch downstream port, PCIe-to-PCI bridge, PCI-to-PCIe bridge, port type <N> 가운데 하나입니다.

1
2
0000:1a:00.0  (parent 0000:19:00.0, parent is a root port)
0000:5e:00.0  (parent 0000:5d:00.0, parent is a switch downstream port with Surprise Down Error unmasked; the path is masked for the reset)

--list는 SBR 판정만 보여 줍니다. 열린 핸들, 부모 브리지 아래의 다른 디바이스, 경로의 레지스터를 읽을 수 있는지는 리셋할 때 사전 점검에서 확인합니다.

리셋 출력

카드 한 장의 리셋은 다음 줄들을 차례로 출력합니다. 그 사이에 카드와 경로의 AER 레지스터 값과 상태가 함께 출력됩니다.

1
2
3
4
5
6
7
8
9
=== <BDF> (parent <부모 BDF>, /dev/haN) ===
remove <BDF>
BRIDGE_CONTROL: <원래 값> -> <SBR 켠 값> (SBR=1) -> <SBR 끈 값> (SBR=0)
Waiting for PCIe link to retrain...
PCIe link is active.
Waiting for EP to be enumerated...
Endpoint fully enumerated.
Waiting for /dev/haN...
Hot reset OK: <BDF>

경로를 마스킹하는 카드는 remove 앞에 masking <포트 수> ports: <포트 목록>과 직접 되돌리는 setpci 명령을, Hot reset OK 앞에 Checking the card answers before unmasking (up to 5s)...와 device answering (<노드>=<값>) - safe to unmask를 더 출력합니다.

remove <BDF> 줄이 없으면 카드를 건드리지 않은 것입니다.

종료 코드

코드 뜻
0 성공했습니다. 대상 카드를 모두 리셋했거나, --list나 --help를 출력했거나, --check-mask의 판정이 모두 통과했습니다
1 실패했습니다. root가 아니거나, pciutils나 flock이 없거나, 카드를 찾지 못했거나, 카드가 20fb 디바이스가 아니거나, 리셋 단계가 실패했거나, 리셋한 뒤 ha 드라이버가 카드를 바인드하지 않았거나, --check-mask 판정이 통과하지 못했습니다. 신호 없이 도중에 실패한 리셋도 여기에 듭니다
2 사용법 오류입니다. 알 수 없는 인자, 함께 쓸 수 없는 옵션, 숫자가 아닌 --check-mask 값, 값이 없거나 형식이 틀린 --bdf 값, 도메인을 뺀 --bdf 값과 일치하는 디바이스가 없거나 둘 이상인 경우, 카드가 여러 장인데 --bdf나 --all을 주지 않은 경우입니다
3 거부했고 아무것도 건드리지 않았습니다. 디바이스 노드가 열려 있거나(--force로 넘길 수 있음), 다른 ha-hotreset 실행이 600초 안에 끝나지 않았습니다(호스트 락). 나중에 다시 실행합니다
4 거부했고 아무것도 건드리지 않았습니다. 이 카드의 PCIe 위치에서는 SBR이 안전하지 않습니다. 부모의 Surprise Down 마스크를 읽을 수 없거나, 경로를 마스킹할 수 없거나 마스킹이 적용되지 않았거나, --no-switch-link-drop에서 부모가 마스킹하지 않았거나, 부모 브리지 아래에 다른 디바이스가 있습니다
129, 130, 143 리셋이나 마스킹 확인 도중 SIGHUP, SIGINT, SIGTERM으로 중단되었습니다. 정리 단계를 실행한 뒤 끝냅니다

--all에서 사유가 여럿이면 4가 3보다, 3이 1보다 앞섭니다. 실패 판정은 1인지가 아니라 0이 아닌지로 하십시오.

리셋 뒤

  • SBR을 받은 카드는 플래시의 펌웨어로 다시 부팅합니다. 펌웨어 업데이트 뒤 새 펌웨어를 적용할 때 이 도구를 쓰는 이유입니다.
  • 드라이버가 카드를 새로 인식하므로 드라이버가 모은 RAS 카운터와 last_hang이 초기화됩니다.
  • 카드는 보통 리셋 전과 같은 /dev/haN 번호로 나타납니다.
  • 다른 카드는 리셋되지 않습니다. 다만 다른 카드에서 이 카드의 메모리를 대상으로 하던 디바이스 간 복사는 실패합니다.

함께 보기